From 72915b6ed7aa9ec87cbeeb6731aa4a3b151c358a Mon Sep 17 00:00:00 2001
From: Melissa Henderson <57110301+melissahenderson@users.noreply.github.com>
Date: Tue, 3 Jun 2025 09:19:31 -0400
Subject: [PATCH] docs: fixes #53

A number of people have pointed out that the updates made to this site in 2020 don't mention anything about the Interledger protocol and that all references lead to Open Payments, which isn't entirely accurate. This PR attempts to fix these issues.
---
 astro.config.mjs                              |  15 +-
 src/content/docs/about.md                     |  22 ++-
 .../docs/examples/ilp-implementation.md       |  80 ++++++++
 src/content/docs/goals.md                     |  21 --
 src/content/docs/how-it-works.md              | 182 ++++++++++++++++++
 src/content/docs/iana.md                      |   2 +-
 src/content/docs/index.md                     | 179 ++---------------
 src/content/docs/{flow.md => overview.md}     |  68 +++----
 src/content/docs/security.md                  |  29 ++-
 src/content/docs/syntax.md                    |  49 ++---
 10 files changed, 369 insertions(+), 278 deletions(-)
 create mode 100644 src/content/docs/examples/ilp-implementation.md
 delete mode 100644 src/content/docs/goals.md
 create mode 100644 src/content/docs/how-it-works.md
 rename src/content/docs/{flow.md => overview.md} (53%)

diff --git a/astro.config.mjs b/astro.config.mjs
index 54d72b5..62e921c 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -8,6 +8,9 @@ export default defineConfig({
   integrations: [
     starlight({
       title: "Payment Pointers",
+      customCss: [
+        './src/styles/custom.css'
+      ],
       description:
         "Payment Pointers are a standardized identifier for payment accounts. In the same way that an email address provides an identifier for a mailbox in the email ecosystem a payment pointer is used by an account holder to share the details of their account with a counter-party.",
         head: [
@@ -40,12 +43,12 @@ export default defineConfig({
         github: "https://github.com/interledger/paymentpointers.org",
       },
       sidebar: [
-        { label: "Explainer", link: "/" },
-        { label: "Design Goals", link: "/goals" },
-        { label: "Flow", link: "/flow" },
-        { label: "Syntax and Resolution", link: "/syntax" },
-        { label: "IANA Considerations", link: "/iana" },
-        { label: "Security Considerations", link: "/security" },
+        { label: "Overview", link: "overview" },
+        { label: "How it works", link: "how-it-works" },
+        { label: "Syntax and resolution", link: "/syntax" },
+        { label: "Security considerations", link: "/security" },
+        { label: "Example implementation - Interledger", link: "/examples/ilp-implementation" },
+        { label: "IANA considerations", link: "/iana" },
         { label: "About", link: "/about" },
       ],
     }),
diff --git a/src/content/docs/about.md b/src/content/docs/about.md
index fefcdb4..257f47f 100644
--- a/src/content/docs/about.md
+++ b/src/content/docs/about.md
@@ -2,4 +2,24 @@
 title: About
 ---
 
-The **Payment Pointers** specification is published by the [Interledger Community Group](https://interledger.org) at [W3C](https://w3.org).
+This payment pointers specification is published by the <a href="https://interledger.org" target="_blank">Interledger Community Group</a> at <a href="https://w3.org" target="_blank">W3C</a>.
+
+## Design goals
+
+Payment pointers are designed with very specific goals in mind.
+
+### Unique and easily recognizable
+
+Various standardized and defacto-standardized identifiers are widely used on the Internet today, such as email addresses and social media handles. Payment pointers must be obviously unique so that they aren't confused with another type of identifier and also so that other identifiers aren't assumed to be payment pointers.
+
+### Simple transcription
+
+It should be easy for someone to exchange their payment pointer with a counterparty by saying it, writing it down, or sending it in a digital message.
+
+### Flexible
+
+Payment pointers shouldn't be tightly coupled to a specific payment service. It should be possible for any new payment service to leverage payment pointers by implementing Interledger's <a href="https://interledger.org/developers/rfcs/simple-payment-setup-protocol/" target="_blank">Simple Payment Setup Protocol</a>.
+
+### Widely usable
+
+It should be simple for individuals or small companies to host their own payment service endpoints at a URL that can resolve via a simple and easily recognizable payment pointer. Likewise, it should be possible for a payment services provider to host payment service endpoints for multiple entities without the risk of hosting them at endpoint URLs that conflict with their other services. To that end, the provider should have the option of hosting different endpoints under the same domain and a different path or at a different sub-domain for each user.
diff --git a/src/content/docs/examples/ilp-implementation.md b/src/content/docs/examples/ilp-implementation.md
new file mode 100644
index 0000000..1ddc584
--- /dev/null
+++ b/src/content/docs/examples/ilp-implementation.md
@@ -0,0 +1,80 @@
+---
+title: 'Example implementation - Interledger'
+---
+
+This page provides a high-level description of how the <a href="https://interledger.org/developers/get-started/" target="_blank">Interledger Protocol (ILP)</a> has implemented payment pointers. ILP is an open suite of protocols for transferring packets of value across different payment networks and ledgers.
+
+## Interledger's Simple Payment Setup Protocol (SPSP)
+
+Interledger's <a href="https://interledger.org/developers/rfcs/simple-payment-setup-protocol/" target="_blank">SPSP</a> is a protocol used by clients, such as mobile and web apps, to obtain the destination account and shared secret details required to set up an Interledger payment.
+
+The details are obtained via an HTTPS request to an SPSP server endpoint. Interledger uses payment pointers as a user-friendly way to express the endpoint URLs.
+
+### Example: Sending an Interledger payment
+
+You use a payment app to send a payment to a friend. You enter an amount and your friend’s payment pointer into the app. Your friend's payment pointer is `$alice.wallet.example`.
+
+First, the app follows the [syntax and resolution](/syntax) rules to convert the payment pointer to an HTTPS URL. The URL is the endpoint for an SPSP server:
+
+```http
+https://alice.wallet.example/.well-known/pay
+```
+
+The app queries the URL by sending a `GET` request with a MIME type of `application/spsp4+json` included in the header.
+
+```http title="Example request"
+curl --request GET \
+ --url https://alice.wallet.example/.well-known/pay \
+ --header 'accept: application/spsp4+json'
+```
+
+The SPSP server responds with the following connection details.
+
+* `destination_account` - An ILP address, which provides a way to route ILP packets to their intended destination. ILP addresses aren't meant to be user-facing.
+* `shared_secret` - A shared secret between the app and the SPSP server.
+
+```json title="Example response" wrap
+{
+ "destination_account":"example.dev.0.wallet.cloudnine.swx0a0.~ipr.cdfa5e16-e759",
+ "shared_secret":"7h0s7EpQDqcgzqmX-mwrNHFHinPvJq8Jw",
+},
+```
+
+After the app has the destination account and shared secret, it no longer needs the payment pointer. The next step is for the app to use the details to set up a <a href="https://interledger.org/developers/rfcs/stream-protocol/" target="_blank">STREAM</a> connection. STREAM is Interledger's transport layer protocol that creates and transmits the Interledger packets that make up a payment.
+
+## Interledger and Open Payments
+
+<a href="https://openpayments.dev" target="_blank">Open Payments</a> is an open API standard for implementation by banks, mobile money providers, and other account servicing entities (ASEs). It allows developers to build payment capabilities into their clients by calling Open Payments APIs to issue payment instructions to ASEs without needing custom integrations.
+
+Open Payments is an alternative to Interledger’s SPSP. As such, getting the details needed to set up a payment is done through an Open Payments API call.
+
+While Open Payments doesn’t use SPSP, it does use Interledger’s STREAM protocol. The Open Payments standard is designed so that it can relay payment instructions between transacting parties atop any payment method. However, Interledger is the only method that’s currently integrated with Open Payments.
+
+### Payment pointers and wallet addresses
+
+Instead of payment pointers, the Open Payments standard uses wallet addresses to identify Open Payments-enabled accounts. Wallet addresses are expressed as HTTPS URLs which makes them identical to the URL form of payment pointers. However, wallet addresses resolve to Open Payments API endpoints instead of SPSP server endpoints.
+
+```http title="Example wallet address"
+https://wallet.example.com/bob
+```
+
+You can query the URL by sending a `GET` request with `application/json` in the header.
+
+```http title="Example request"
+curl --request GET \
+ --url https://wallet.example.com/bob \
+ --header `accept: application/json`
+```
+
+You can also use `application/spsp4+json` since Open Payments uses Interledger as its payment method, but in either case you'll receive an Open Payments response.
+
+```json title="Example response"
+{
+  "id": "https://wallet.example.com/bob",
+  "publicName": "Bob",
+  "assetCode": "USD",
+  "assetScale": 2,
+  "authServer": "https://auth.wallet.example.com",
+  "resourceServer": "https://wallet.example.com",
+}
+```
diff --git a/src/content/docs/goals.md b/src/content/docs/goals.md
deleted file mode 100644
index 2bc82e4..0000000
--- a/src/content/docs/goals.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: Design Goals
----
-
-Payment Pointers were designed with very specific goals in mind:
-
-## Unique and Easily Recognizable
-
-Various standardized and defacto-standardized identifiers are widely used on the Internet today such as email addresses and social media handles. The Payment Pointer must be obviously unique so that it is not confused with another type of identifier and also so that other identifiers are not assumed to be Payment Pointers.
-
-## Simple Transcription
-
-It should be easy for someone to exchange their payment pointer with a counter-party either by saying it, writing it down or sending it in a digital message.
-
-## Flexible
-
-The payment pointer should not be tightly coupled to a specific payment service. It should be possible for any new payment service to leverage payment pointers by implementing the [Open Payments](https://openpayments.dev) standard.
-
-## Widely Usable
-
-It should be simple for individuals or small companies to host their own payment service endpoints at a URL that can be resolved via a simple and easily recognizable payment pointer. Likewise, it should be possible for a payment services provider to host payment service endpoints for multiple entities without the risk of hosting them at endpoint URLs that conflict with their other services. To that end the provider should have the option of hosting different endpoints under the same domain and a different path or at a different sub-domain for each user.
diff --git a/src/content/docs/how-it-works.md b/src/content/docs/how-it-works.md
new file mode 100644
index 0000000..c85a84d
--- /dev/null
+++ b/src/content/docs/how-it-works.md
@@ -0,0 +1,182 @@
+---
+title: How it works
+---
+
+A payment service endpoint provides the information that's necessary for interacting with a payment pointer's underlying payment account. Payment service endpoints **MUST** accept HTTP GET requests and be identifiable by an HTTPS URI as defined in <a href="https://datatracker.ietf.org/doc/html/rfc7230" target="_blank">RFC7230</a>.
+
+:::note
+In addition to payment service endpoint requirements, you should familiarize yourself with the [syntax and resolution](/syntax) requirements of payment pointers.
+:::
+
+Payment pointers aren't meant to be tightly coupled to any specific payment service. Individuals and small companies can host their own payment service endpoints at URLs that resolve to payment pointers.
+
+Likewise, payment service providers can host payment service endpoints for multiple entities without the risk of hosting them at endpoint URLs that conflict with their other services. To that end, providers have the option of hosting different endpoints under the same domain and a different path, or at a different sub-domain for each of their users.
+
+## Step 1: Resolve server meta-data URL
+
+Let's say you are using a payment app to send a payment to a friend. You enter your friend's payment pointer into the app.
+
+The first step a client (for example, your payment app) must perform is to decode the endpoint URL from the payment pointer using the [rules](/syntax#resolution) defined in this specification.
+
+<div class="pp-converter not-content">
+  <div class="input-wrapper">
+    <label class="payment-pointer">
+      <p>Payment Pointer</p>
+      <input id="pp-input" value="$alice.wallet.example" placeholder="$alice.wallet.example" />
+    </label>
+    <label class="url">
+      <p>URL</p>
+      <input id="url-input" value="https://alice.wallet.example/.well-known/pay" readonly />
+    </label>
+  </div>
+  <p id="error" class="error-msg"></p>
+</div>
+
+## Step 2: Discover endpoints
+
+The client then uses the HTTP protocol to query (`GET`) the resolved endpoint URL. The client uses the `Accept` header to express the media types of the protocol messages it supports.
+
+```http title="Example"
+GET /.well-known/pay HTTP/1.1
+Host: alice.wallet.example
+Accept: application/json
+```
+
+The response contains details the client needs to discover the payment service endpoints for interacting with the underlying account.
+
+The resolved endpoint **MAY** redirect the client to another URL but the client **MUST** ensure it affords the sender an opportunity to verify both the originally resolved and ultimate endpoint hosts.
+
+## Step 3: Initiate payment
+
+Having discovered the available endpoint, the client initiates the payment using the payment setup protocol appropriate to the use case.
+
+<script>
+  function resolveUrl(pointer) {
+    if (typeof pointer !== "string") {
+      throw new Error("Payment pointer must be a string");
+    }
+    if (pointer.charAt(0) !== "$") {
+      throw new Error('Payment pointer must start with "$"');
+    }
+    const url = new URL("https://" + pointer.slice(1));
+    if (url.port) {
+      throw new Error("Payment pointers cannot be defined with a port");
+    }
+    if (url.username || url.password) {
+      throw new Error("Payment pointers cannot be defined with userinfo");
+    }
+    if (url.search) {
+      throw new Error("Payment pointers cannot be defined with query parameters");
+    }
+    if (url.hash) {
+      throw new Error("Payment pointers cannot be defined with a fragment");
+    }
+    if (url.pathname === "" || url.pathname === "/") {
+      url.pathname = "/.well-known/pay";
+    }
+    return url.href;
+  }
+
+  function createPaymentPointer(url) {
+    const u = typeof url === "string" ? new URL(url) : url;
+    if (u instanceof URL) {
+      if (u.protocol !== "https:") {
+        throw new Error(
+          'Payment pointers can only point to URLs with a protocol of "https"'
+        );
+      }
+      if (u.port) {
+        throw new Error(
+          "Payment pointers cannot point to URLs with a custom port"
+        );
+      }
+      if (u.username || u.password) {
+        throw new Error(
+          "Payment pointers cannot point to URLs containing `userinfo`"
+        );
+      }
+      if (u.search) {
+        throw new Error(
+          "Payment pointers cannot point to URLs with query parameters"
+        );
+      }
+      if (u.hash) {
+        throw new Error("Payment pointers cannot point to URLs with a fragment");
+      }
+      const path = u.pathname.endsWith("/")
+        ? u.pathname.slice(0, -1)
+        : u.pathname;
+      if (path === "") {
+        throw new Error(
+          "Payment pointers cannot point to URLs with an empty path"
+        );
+      }
+      return "$" + u.hostname + (path === "/.well-known/pay" ? "" : path);
+    }
+    throw new Error("url must be a valid URL string or URL object");
+  }
+
+  function toggleError(msg) {
+    const error = document.getElementById("error");
+    if (msg) {
+      error.innerHTML = msg;
+    } else {
+      error.innerHTML = "";
+    }
+  }
+
+  document.getElementById("url-input").addEventListener("keyup", (event) => {
+    const url = event.srcElement.value;
+    try {
+      if (url.length > 8) {
+        const pp = createPaymentPointer(url);
+        document.getElementById("pp-input").value = pp;
+      }
+      toggleError();
+    } catch (e) {
+      toggleError(e.message);
+    }
+  });
+
+  document.getElementById("pp-input").addEventListener("keyup", (event) => {
+    const pp = event.srcElement.value;
+    try {
+      if (pp.length > 3) {
+        const url = resolveUrl(pp);
+        document.getElementById("url-input").value = url;
+      }
+      toggleError();
+    } catch (e) {
+      toggleError(e.message);
+    }
+  });
+</script>
+
+<style>
+  .input-wrapper {
+    display: flex;
+    flex-direction: column;
+    gap: 1em;
+  }
+  @media screen and (min-width: 550px) {
+    .input-wrapper {
+      flex-direction: row;
+    }
+  }
+  label p {
+    font-weight: 700;
+  }
+  input { width: 100% }
+  .payment-pointer {
+    flex: 1 1 0;
+  }
+  .url.url {
+    flex: 2 1 0;
+    margin-top: 0;
+  }
+  .pp-converter .error-msg.error-msg {
+    margin-top: var(--space-3xs);
+    color: firebrick;
+    font-size: var(--step--1);
+  }
+</style>
diff --git a/src/content/docs/iana.md b/src/content/docs/iana.md
index 2e2270c..eb3699b 100644
--- a/src/content/docs/iana.md
+++ b/src/content/docs/iana.md
@@ -2,7 +2,7 @@
 title: IANA Considerations
 ---
 
-## Well-Known URI
+## Well-known URI
 
 This specification registers a new well-known URI.
 
diff --git a/src/content/docs/index.md b/src/content/docs/index.md
index 5ca7187..ac6f8e9 100644
--- a/src/content/docs/index.md
+++ b/src/content/docs/index.md
@@ -1,170 +1,15 @@
 ---
 title: Payment Pointers
+template: splash
+hero:
+  tagline: Payment pointers are unique, easily recognizable, and standardized identifers for a payment account. 
+  actions:
+    - text: Read the docs
+      link: /overview
+      icon: open-book
+      variant: primary
+      attrs:
+        data-umami-event: Landing page - Payment Pointer docs
+prev: false
+next: false
 ---
-
-## Explainer
-
-**Payment Pointers** are a standardized identifier for payment accounts. In the same way that an email address provides an identifier for a mailbox in the email ecosystem a payment pointer is used by an account holder to share the details of their account with a counter-party.
-
-A Payment Pointer resolves to a URL (with the https scheme) that can be used to discover the [Open Payments](https://openpayments.dev) endpoints for interacting with the account. Using the [Open Payments](https://openpayments.dev) protocol the counter-party can initiate a payment to or from the owner of the Payment Pointer.
-
-<div class="pp-converter not-content">
-  <div class="input-wrapper">
-    <label class="payment-pointer">
-      <p>Payment Pointer</p>
-      <input id="pp-input" value="$alice.wallet.example" placeholder="$alice.wallet.example" />
-    </label>
-    <label class="url">
-      <p>URL</p>
-      <input id="url-input" value="https://alice.wallet.example/.well-known/pay" readonly />
-    </label>
-  </div>
-  <p id="error" class="error-msg"></p>
-</div>
-
-### Syntax
-
-Payment Pointers start with a `$` character to distinguish them from other identifiers and make it obvious that they are related to payments. To convert a Payment Pointer to a URL the `$` is replaced with the standard prefix of a secure URL, `https://`.
-
-Payment Pointers don't contain query strings or fragments, however [Open Payments](https://openpayments.dev) MAY define standard parameters that can be used by a client when connecting to an [Open Payments](https://openpayments.dev) service endpoint.
-
-[More details...](/syntax)
-
-### Flow
-
-When making or a receiving a payment, a user passes a Payment Pointer to the counter-party who decodes it to the corresponding URL.
-
-That URL represents an account at a wallet and the client begins an interaction with the wallet using the [Open Payments](https://docs.openpayments.dev) protocol.
-
-[More details...](/flow)
-
-<script>
-  function resolveUrl(pointer) {
-    if (typeof pointer !== "string") {
-      throw new Error("Payment Pointer must be a string");
-    }
-    if (pointer.charAt(0) !== "$") {
-      throw new Error('Payment Pointer must start with "$"');
-    }
-    const url = new URL("https://" + pointer.slice(1));
-    if (url.port) {
-      throw new Error("Payment Pointers cannot be defined with a port");
-    }
-    if (url.username || url.password) {
-      throw new Error("Payment Pointers cannot be defined with userinfo");
-    }
-    if (url.search) {
-      throw new Error("Payment Pointers cannot be defined with query parameters");
-    }
-    if (url.hash) {
-      throw new Error("Payment Pointers cannot be defined with a fragment");
-    }
-    if (url.pathname === "" || url.pathname === "/") {
-      url.pathname = "/.well-known/pay";
-    }
-    return url.href;
-  }
-
-  function createPaymentPointer(url) {
-    const u = typeof url === "string" ? new URL(url) : url;
-    if (u instanceof URL) {
-      if (u.protocol !== "https:") {
-        throw new Error(
-          'Payment Pointers can only point to URLs with a protocol of "https"'
-        );
-      }
-      if (u.port) {
-        throw new Error(
-          "Payment Pointers cannot point to URLs with a custom port"
-        );
-      }
-      if (u.username || u.password) {
-        throw new Error(
-          "Payment Pointers cannot point to URLs containing `userinfo`"
-        );
-      }
-      if (u.search) {
-        throw new Error(
-          "Payment Pointers cannot point to URLs with query parameters"
-        );
-      }
-      if (u.hash) {
-        throw new Error("Payment Pointers cannot point to URLs with a fragment");
-      }
-      const path = u.pathname.endsWith("/")
-        ? u.pathname.slice(0, -1)
-        : u.pathname;
-      if (path === "") {
-        throw new Error(
-          "Payment Pointers cannot point to URLs with an empty path"
-        );
-      }
-      return "$" + u.hostname + (path === "/.well-known/pay" ? "" : path);
-    }
-    throw new Error("url must be a valid URL string or URL object");
-  }
-
-  function toggleError(msg) {
-    const error = document.getElementById("error");
-    if (msg) {
-      error.innerHTML = msg;
-    } else {
-      error.innerHTML = "";
-    }
-  }
-
-  document.getElementById("url-input").addEventListener("keyup", (event) => {
-    const url = event.srcElement.value;
-    try {
-      if (url.length > 8) {
-        const pp = createPaymentPointer(url);
-        document.getElementById("pp-input").value = pp;
-      }
-      toggleError();
-    } catch (e) {
-      toggleError(e.message);
-    }
-  });
-
-  document.getElementById("pp-input").addEventListener("keyup", (event) => {
-    const pp = event.srcElement.value;
-    try {
-      if (pp.length > 3) {
-        const url = resolveUrl(pp);
-        document.getElementById("url-input").value = url;
-      }
-      toggleError();
-    } catch (e) {
-      toggleError(e.message);
-    }
-  });
-</script>
-
-<style>
-  .input-wrapper {
-    display: flex;
-    flex-direction: column;
-    gap: 1em;
-  }
-  @media screen and (min-width: 550px) {
-    .input-wrapper {
-      flex-direction: row;
-    }
-  }
-  label p {
-    font-weight: 700;
-  }
-  input { width: 100% }
-  .payment-pointer {
-    flex: 1 1 0;
-  }
-  .url.url {
-    flex: 2 1 0;
-    margin-top: 0;
-  }
-  .pp-converter .error-msg.error-msg {
-    margin-top: var(--space-3xs);
-    color: firebrick;
-    font-size: var(--step--1);
-  }
-</style>
diff --git a/src/content/docs/flow.md b/src/content/docs/overview.md
similarity index 53%
rename from src/content/docs/flow.md
rename to src/content/docs/overview.md
index 23dd267..e3b73a5 100644
--- a/src/content/docs/flow.md
+++ b/src/content/docs/overview.md
@@ -1,16 +1,18 @@
 ---
-title: Flow
+title: Overview
 ---
 
-When a user wishes to make or receive a payment, and is engaging with a counter-party that is able to process Payment Pointers, it provides a Payment Pointer to the counter-party.
+Payment pointers are unique, recognizable, and standardized identifiers for payment accounts.
 
-The counter-party's client then uses this Payment Pointer as described below to discover the services and accounts linked to the Payment Pointer and interact with these to send or request a payment.
+Other standardized identifiers, such as email addresses and social media handles, are widely used across the Internet and provide a simple and straightforward way to exchange information with others. The intent behind payment pointers is no different.
 
-This is analogous to how a user may provide a credit card number to a merchant to make a payment online, or provide their bank account details to a payer to receive a payment. However, in the case of Payment Pointers the pointer and the services are loosely coupled so a variety of service types could be discovered and payments can be both pushed and pulled from the user's account initiated via the same Payment Pointer.
+Payment pointers begin with a `$` to distinguish them from other types of identifiers. For example, `$wallet.example.com/alice`. Every payment pointer also has a corresponding HTTPS URL.
 
-## Step 1: Resolve Open Payments Server Meta-Data URL
+**Although originally developed for Interledger, payment pointers are not tightly coupled with the protocol.** Any payment setup protocol is welcome to leverage payment pointers without integrating with Interledger. Interledger is just one [active implementation](/examples/ilp-implementation) of payment pointers.
 
-The first step the client performs is to decode the **Payment Pointer URL** from the Payment Pointer using the [rules](/syntax#resolution) defined in this specification.
+## Get your payment pointer's URL
+
+If you already have a payment pointer and need to convert it to its corresponding HTTPS URL, enter it in the field below.
 
 <div class="pp-converter not-content">
   <div class="input-wrapper">
@@ -26,44 +28,26 @@ The first step the client performs is to decode the **Payment Pointer URL** from
   <p id="error" class="error-msg"></p>
 </div>
 
-## Step 2: Discover Open Payments Endpoints
-
-The client then uses the HTTP protocol to query the resolved **Open Payments account** URL and [discover](https://docs.openpayments.dev/discovery) the Open Payments services endpoints.
-
-The resolved endpoint MAY redirect the client to another URL but the client MUST ensure it affords the sender an opportunity to verify both the originally resolved and ultimate endpoint hosts.
-
-### Example:
-
-```http
-GET /.well-known/pay HTTP/1.1
-Host: alice.wallet.example
-Accept: application/json
-```
-
-## Step 3: Initiate Payment
-
-Having discovered the available endpoints, the client initiates the payment using one of the supported [Open Payments](https://openpayments.dev) protocols appropriate to the use case.
-
 <script>
   function resolveUrl(pointer) {
     if (typeof pointer !== "string") {
-      throw new Error("Payment Pointer must be a string");
+      throw new Error("Payment pointer must be a string");
     }
     if (pointer.charAt(0) !== "$") {
-      throw new Error('Payment Pointer must start with "$"');
+      throw new Error('Payment pointer must start with "$"');
     }
     const url = new URL("https://" + pointer.slice(1));
     if (url.port) {
-      throw new Error("Payment Pointers cannot be defined with a port");
+      throw new Error("Payment pointers cannot be defined with a port");
     }
     if (url.username || url.password) {
-      throw new Error("Payment Pointers cannot be defined with userinfo");
+      throw new Error("Payment pointers cannot be defined with userinfo");
     }
     if (url.search) {
-      throw new Error("Payment Pointers cannot be defined with query parameters");
+      throw new Error("Payment pointers cannot be defined with query parameters");
     }
     if (url.hash) {
-      throw new Error("Payment Pointers cannot be defined with a fragment");
+      throw new Error("Payment pointers cannot be defined with a fragment");
     }
     if (url.pathname === "" || url.pathname === "/") {
       url.pathname = "/.well-known/pay";
@@ -76,38 +60,38 @@ Having discovered the available endpoints, the client initiates the payment usin
     if (u instanceof URL) {
       if (u.protocol !== "https:") {
         throw new Error(
-          'Payment Pointers can only point to URLs with a protocol of "https"'
+          'Payment pointers can only point to URLs with a protocol of "https"'
         );
       }
       if (u.port) {
         throw new Error(
-          "Payment Pointers cannot point to URLs with a custom port"
+          "Payment pointers cannot point to URLs with a custom port"
         );
       }
       if (u.username || u.password) {
         throw new Error(
-          "Payment Pointers cannot point to URLs containing `userinfo`"
+          "Payment pointers cannot point to URLs containing `userinfo`"
         );
       }
       if (u.search) {
         throw new Error(
-          "Payment Pointers cannot point to URLs with query parameters"
+          "Payment pointers cannot point to URLs with query parameters"
         );
       }
       if (u.hash) {
-        throw new Error("Payment Pointers cannot point to URLs with a fragment");
+        throw new Error("Payment pointers cannot point to URLs with a fragment");
       }
       const path = u.pathname.endsWith("/")
         ? u.pathname.slice(0, -1)
         : u.pathname;
       if (path === "") {
         throw new Error(
-          "Payment Pointers cannot point to URLs with an empty path"
+          "Payment pointers cannot point to URLs with an empty path"
         );
       }
       return "$" + u.hostname + (path === "/.well-known/pay" ? "" : path);
     }
-    throw new Error("url must be a valid URL string or URL object");
+    throw new Error("URL must be a valid URL string or URL object");
   }
 
   function toggleError(msg) {
@@ -146,6 +130,16 @@ Having discovered the available endpoints, the client initiates the payment usin
   });
 </script>
 
+## Brief history
+
+Payment pointers were developed alongside the <a href="https://interledger.org/developers/get-started/" target="_blank">Interledger Protocol</a> stack as a way to express URL endpoints in a user-friendly way. 
+
+Interledger's Simple Payment Setup Protocol (SPSP) exchanges the connection details needed to set up an Interledger payment. An SPSP server exposes an HTTPS endpoint that a client can query to get those details. For example, `https://alice.wallet.example/.well-known/pay`.
+
+Endpoints like that can become unwieldy and hard to remember. Instead of entering the endpoint into a client or sharing the address with a counter-party, the URL can instead be expressed in shorthand form as a payment pointer: `$alice.wallet.example`.
+
+For more information on how Interledger uses payment pointers, see its [implementation example](/examples/ilp-implementation) page.
+
 <style>
   .input-wrapper {
     display: flex;
diff --git a/src/content/docs/security.md b/src/content/docs/security.md
index 61f5c37..7b493f1 100644
--- a/src/content/docs/security.md
+++ b/src/content/docs/security.md
@@ -2,31 +2,26 @@
 title: Security Considerations
 ---
 
-Payment pointers have many of the same security risks as URLs so it follows that the security considerations are the same even though payment pointers do not in and of themselves pose a security threat.
+Payment pointers have many of the same risks as URLs. As such, the security considerations are the same even though payment pointers don't in and of themselves pose a security threat.
 
-However, as payment pointers are used to provide a compact set of instructions for initiation of a payment, care must be taken to properly interpret the data within a payment pointer, to prevent payments being made to the wrong recipient or leaking of sensitive data.
+Payment pointers provide a compact set of instructions for initiation of a payment. As such, take care to properly interpret the data within a payment pointer to prevent leaking sensitive data or making payments to the wrong recipient.
 
-## Reliability and Consistency
+## Reliability and consistency
 
-There is no guarantee that once a Payment Pointer has been used resolve a payment initiation service endpoint, the same service will be hosted at that URI in the future.
+There's no guarantee that once a payment pointer is used to resolve a payment service endpoint that the same endpoint will be posted at that URI in the future.
 
-## Semantic Attacks and Phishing
+The client should always issue a new `GET` request to a payment pointer and not rely on any potentially stored or cached information.
 
-Because Payment Pointers only support a limited profile of the data in a URL, not all of the attacks described in RFC3986 apply to payment pointers.
+## Semantic attacks and phishing
 
-However, it is possible for a malicious actor to construct a payment pointer that appears to point to a trusted receiver but in fact points to a malicious actor. As a result the pointer is constructed that is intended to mislead a human user by appearing to identify one (trusted) naming authority while actually identifying a different authority hidden behind the noise.
+Because payment pointers only support a limited profile of the data in a URL, not all attacks described in the <a href="https://datatracker.ietf.org/doc/html/rfc3986" target="_blank">URI: Generic Syntax</a> specification apply.
 
-As detailed in [RFC7230], the "https" scheme (Section 2.7.2) is intended to prevent (or at least reveal) many of these potential attacks on establishing the authority behind a pointer, provided that the negotiated TLS connection is secured and the client properly verifies that the communicating server's identity matches the target URIs authority component (see [RFC2818]). Correctly implementing such verification can be difficult (see [The Most Dangerous Code in the World](#the-most-dangerous-code-in-the-world-validating-ssl-certificates-in-non-browser-software)).
+It's possible for a malicious actor to construct a payment pointer that appears to point to a trusted recipient but actually points to a malicious actor. As a result, the payment pointer is intended to mislead a human user by appearing to identify one trusted naming authority while identifying a different authority hidden behind the noise.
 
-Payment Initiation Services should take heed of this risk in their design and provide a mechanism for the parties to reliably verify the counter-party's identity.
+As detailed in the _HTTP/1.1: Message Syntax and Routing_ specification, the HTTPS scheme <a href="https://datatracker.ietf.org/doc/html/rfc7230#section-2.7.2" target="_blank">Section 2.7.2</a> is intended to prevent, or at least reveal, many of these potential attacks on establishing the authority behind a payment pointer, provided that the negotiated TLS connection is secured and the client properly verifies that the communicating server’s identity matches the target URIs authority component (see <a href="https://datatracker.ietf.org/doc/html/rfc2818" target="_blank">RFC2818</a>). Correctly implementing such verification can be difficult. See the paper for <a href="https://www.cs.utexas.edu/~shmat/shmat_ccs12.pdf" target="_blank">The Most Dangerous Code In the World</a>.
 
-Agents of a user that is sending to a counter-party using a Payment Pointer MUST provide a way for the party, after processing the Payment Pointer, to verify that the entity they are sending to (or at least the entity hosting the payment initiation service) is who they intended otherwise senders can easily be fooled into sending money to the wrong receiver. An example of such a mechanism is the use of extended validation certificates at the endpoint.
+Payment initiation services should take heed of this risk in their design and provide a mechanism for the parties to reliably verify the counterparty’s identity.
 
-## References
+Agents of a user sending a payment to a counterparty must provide a way for the user, after processing the counterparty's payment pointer, to verify that the counterparty they're sending to (or at least the entity hosting the payment initiation service) is who they intended. Otherwise, users can be fooled into sending money to the wrong recipient. 
 
-### The Most Dangerous Code in the World: Validating SSL Certificates in Non-browser Software
-
-Georgiev, M., Iyengar, S., Jana, S., Anubhai, R., Boneh, D., and V. Shmatikov,
-"The Most Dangerous Code in the World: Validating SSL Certificates in Non-browser Software",
-In Proceedings of the 2012 ACM Conference on Computer and Communications Security (CCS'12), pp. 38-49, October 2012,
-<http://doi.acm.org/10.1145/2382196.2382204>.
+An example of such a mechanism is the use of extended validation certificates at the endpoint.
diff --git a/src/content/docs/syntax.md b/src/content/docs/syntax.md
index d3e9575..f9a5548 100644
--- a/src/content/docs/syntax.md
+++ b/src/content/docs/syntax.md
@@ -2,7 +2,9 @@
 title: Syntax and Resolution
 ---
 
-This specification uses the Augmented Backus-Naur Form (ABNF) notation of [RFC2234](https://tools.ietf.org/html/rfc2234) and imports the following rules from [RFC3986](https://tools.ietf.org/html/rfc3986#section-3.3): `host` and `path-abempty`.
+:::note
+This specification uses the Augmented Backus-Naur Form (ABNF) notation of <a href="https://tools.ietf.org/html/rfc2234" target="_blank">RFC2234</a> and imports the `host` and `path-abempty` rules from <a href="https://tools.ietf.org/html/rfc3986#section-3.3" target="_blank">RFC3986</a>.
+:::
 
 The syntax of a payment pointer is:
 
@@ -10,45 +12,36 @@ The syntax of a payment pointer is:
 "$" host path-abempty
 ```
 
-Example: `$example.com/bob`
+For example: `$example.com/bob`
 
 ## ASCII
 
-Note that the character set of a Payment Pointer, as with a valid URL, is limited to a subset of valid ASCII characters.
-
-Further work may be done to define mappings from other character sets that support international characters (similar to the rules for Internationalized Domain Names) however, such mappings are not defined in this specification. Implementations that attempt to interpret a Payment Pointer that contains non-ASCII characters should be aware of the security risks.
+The character set of a payment pointer is limited to a subset of valid ASCII characters. Payment pointers begin with a dollar sign (`$`) to distinguish them from other types of identifiers and to indicate their association with payments. Implementations that attempt to interpret a payment pointer that contains non-ASCII characters should be aware of the security risks.
 
 ## Resolution
 
-Given a payment pointer of the form `"$" host path-abempty` the endpoint URL that it resolves to is:
-
-```
-"https://" host path-abempty
-```
-
-If _path-abempty_ is empty or equal to `/` then it is assigned the value `/.well-known/pay`.
+Payment pointers **MUST** resolve to an HTTPS URL that conforms to the HTTPS URI scheme as defined in <a href="https://datatracker.ietf.org/doc/html/rfc7230#section-2.7.2" target="_blank">RFC7230</a>.
 
-Note that this is a restricted profile of the data allowed in a full https URL as defined in [RFC3986](https://tools.ietf.org/html/rfc3986#section-3.3).
+Given a payment pointer of the form `"$" host path-abempty`, the endpoint URL that it resolves to is: `"https://" host path-abempty`.
 
-The URL syntax supports an _authority_, however the Payment Pointer syntax only supports a _host_ which excludes the _userinfo_ and _port_. The Payment Pointer syntax also excludes the _query_ and _fragment_ parts that are allowed in the URL syntax.
-
-Payment Pointers that do not meet the limited syntax of this profile MUST be considered invalid and should not be used to resolve a URL.
-
-## Examples:
+```http title="Examples"
+$example.com/bob → https://example.com/bob
+$example.com/invoices/12345 → https://example.com/invoices/12345
+```
 
-The following payment pointers resolve to the specified endpoint URLs:
+If `path-abempty` is empty or equal to `/` (forward slash), then it's assigned a value of `/.well-known/pay`. This is a restricted profile of the data allowed in a full HTTPS URL, as defined in <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.3" target="_blank">RFC3986 Section 3.3</a>.
 
+```http title="Examples"
+$example.com → https://example.com/.well-known/pay
+$bob.example.com  → https://bob.example.com/.well-known/pay
 ```
-$example.com                  ->  https://example.com/.well-known/pay
-$example.com/invoices/12345   ->  https://example.com/invoices/12345
-$bob.example.com              ->  https://bob.example.com/.well-known/pay
-$example.com/bob              ->  https://example.com/bob
-```
 
-## Requirements
+There are a number of components that the <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3" target="_blank">full HTTPS syntax</a> supports, but which the payment pointer syntax does not. The payment pointer syntax only supports the `host` subcomponent.
+
+Payment pointers that don't meet the limited syntax of this profile must be considered invalid and shouldn't be used to resolve URLs.
 
-Payment Pointers MUST resolve to an https URL as defined in [RFC7230](https://tools.ietf.org/html/rfc7230#section-2.7.2).
+## Redirects
 
-Clients MUST support HTTP redirects as a result of `3XX` responses per [RFC 7231](https://tools.ietf.org/html/rfc7231#section-6.4) however these MUST always redirect to a secure (https) URL.
+Clients **MUST** support HTTP redirects as a result of `3XX` responses per <a href="https://tools.ietf.org/html/rfc7231#section-6.4" target="_blank">RFC 7231</a>. The redirects **MUST** always be to a secure (HTTPS) URL.
 
-Servers SHOULD be cautious with the use of permanent (301/308) redirect response codes as clients may stop querying the original Payment Pointer and always query the new URL for future payments.
+Servers **SHOULD** be cautious with the use of permanent (`301`/`308`) redirect response codes as clients may stop querying the original payment pointer and always query the new URL for future payments.
\ No newline at end of file