@three-ws/x402-payment-modal 1.1.0

package/docs/architecture.md

@@ -0,0 +1,171 @@
+# Architecture
+
+`@three-ws/x402-payment-modal` is a single zero-dependency vanilla-JS ES module
+that turns any [x402](https://x402.org)-protected HTTP endpoint into a one-click
+checkout. It owns the entire client lifecycle: discovering the payment challenge,
+connecting a wallet, signing the payment, retrying the request with proof, and
+rendering a receipt plus the endpoint's result.
+
+This document explains how the modal works end to end. For the public surface,
+see the [API reference](./api-reference.md). For the Solana checkout backend, see
+[server setup](./server-setup.md).
+
+## The x402 flow in one sentence
+
+> The merchant answers an unpaid request with **HTTP 402** describing what it
+> wants; the modal makes the user **sign** a payment matching that description;
+> the modal **retries** the same request with an `X-PAYMENT` header; the merchant
+> **settles** the payment and returns the real result.
+
+The package never holds funds and never moves money on its own. It only produces
+a signed payment authorization and hands it back to the merchant, who settles it
+through an x402 facilitator.
+
+## Lifecycle
+
+```
+discover  →  connect  →  authorize  →  verify (retry + settle)  →  receipt
+```
+
+These map directly to the four visible modal steps:
+
+| Step        | Modal label          | What happens                                                                 |
+|-------------|----------------------|------------------------------------------------------------------------------|
+| `discover`  | Confirming price     | Probe the endpoint, parse the 402 challenge, render price + network.         |
+| `connect`   | Connect wallet       | Detect Phantom / EVM wallet, let the user pick and connect one.              |
+| `authorize` | Authorize payment    | Produce a signed payment (EVM EIP-3009 typed-data, or Solana signed tx).     |
+| `verify`    | Verify & complete    | Re-send the request with `X-PAYMENT`; merchant settles; show receipt.        |
+
+Each step is rendered as a `.x402-step` element and carries `.x402-active`,
+`.x402-done`, or `.x402-error` modifiers as it progresses. See
+[theming](./theming.md) for styling hooks.
+
+## Challenge discovery
+
+When `pay()` first calls the endpoint (using the configured `method`, `body`, and
+`headers`), it inspects the response for a payment challenge. It accepts any of:
+
+1. **HTTP 402** with a JSON body describing the accepted payment(s).
+2. **HTTP 402** with a `payment-required` response header (the body-less form).
+3. **MCP-style HTTP 401** with a `payment-required` header — used by Model
+   Context Protocol servers that gate tools behind payment.
+
+The parsed challenge contains one or more `accepts` entries. Each entry names a
+`network` (e.g. an EVM chain like Base, or a Solana network), an asset, an
+amount, the pay-to address, and protocol `extra`/`extensions` metadata. If the
+challenge advertises [SIWX](./siwx.md), the modal can offer sign-in re-entry
+instead of a fresh payment.
+
+If the very first response is **not** a payment challenge — e.g. an immediate
+`200` (the endpoint isn't paid) or any other non-`402` status — discovery
+**throws**: the modal renders the error on the `discover` step rather than
+silently succeeding, since pointing the modal at a free or non-x402 endpoint is
+almost always a misconfiguration worth surfacing.
+
+## Two signing paths
+
+x402 supports multiple settlement rails. The modal implements two, and which one
+runs is decided entirely by the `network` in the selected `accepts` entry.
+
+### EVM path — browser-only (EIP-3009)
+
+EVM stablecoin payments (e.g. USDC on Base) use **EIP-3009** "transfer with
+authorization." The browser wallet (MetaMask or any injected EIP-1193 provider)
+signs an EIP-712 typed-data authorization. This is a pure signature — **no funds
+move at signing time and no server call is made.** The signed authorization
+becomes the `X-PAYMENT` header; the merchant's facilitator submits it on-chain
+when it settles.
+
+Because the signature is generated entirely in the browser, **EVM-only sites need
+nothing on the server side** of this package.
+
+### Solana path — server-assisted (prepare / encode + Phantom)
+
+Phantom signs *serialized transactions*, not arbitrary typed data, so the Solana
+path needs a small backend to build the transaction the wallet will sign. The
+flow:
+
+1. Client posts the selected `accepts` entry and the buyer's address to the
+   checkout server: `POST /api/x402-checkout?action=prepare`.
+2. The server builds a partially-signed SPL `transferChecked` v0 transaction.
+   The **fee payer is a facilitator sponsor account** (`accept.extra.feePayer`),
+   so the buyer needs only USDC — no SOL for gas.
+3. The server returns `tx_base64` + `recent_blockhash`.
+4. Phantom signs the transaction (`signTransaction`).
+5. Client posts the signed tx to `?action=encode`; the server wraps it into a
+   base64 x402 v2 payment envelope and returns `x_payment`.
+6. That envelope becomes the `X-PAYMENT` header on the retry.
+
+See [server setup](./server-setup.md) for mounting `prepare`/`encode`.
+
+## Retry, settle, and the 429 auto-retry
+
+Once a signed payment exists, the modal re-issues the original request with the
+`X-PAYMENT` header attached. Outcomes:
+
+- **2xx** — the merchant accepted and settled the payment. The modal parses the
+  body (JSON or text), extracts any `payment`/receipt metadata from the response,
+  renders the receipt + result, and resolves the `pay()` promise.
+- **HTTP 429 (throttled)** — the facilitator was rate-limited. **Payment is not
+  settled until the merchant call actually succeeds**, so it is safe to re-send
+  the *same* signed payment. The modal auto-retries up to **2 additional times**
+  with the identical `X-PAYMENT` payload before surfacing an error.
+- **Other 4xx/5xx** — surfaced as an error in the modal (and via the
+  `x402:error` event), with the reservation rolled back if
+  [spending caps](./spending-caps.md) were in play.
+
+This retry-on-429 is why the modal keeps the signed payment in memory rather than
+re-prompting the wallet: re-signing is unnecessary and would annoy the user.
+
+## Sequence diagram
+
+```
+ User        Modal              Merchant            Checkout server      Wallet
+  |            |                    |                      |                |
+  |  click     |                    |                      |                |
+  |----------->| pay(opts)          |                      |                |
+  |            |  GET/POST endpoint |                      |                |
+  |            |------------------->|                      |                |
+  |            |   402 + accepts    |                      |                |
+  |            |<-------------------|                      |                |
+  |            | [discover] price   |                      |                |
+  |            |                    |                      |                |
+  |            | [connect] pick wallet ------------------------------------>|
+  |            |<----------------------------------------------- address    |
+  |            |                    |                      |                |
+  | == EVM path (browser-only) ==   |                      |                |
+  |            | sign EIP-3009 typed data ----------------------------------->|
+  |            |<-------------------------------------------- signature      |
+  |            |                    |                      |                |
+  | == Solana path (server-assisted) ==                    |                |
+  |            | POST ?action=prepare ------------------->|                |
+  |            |<------------------ tx_base64, blockhash --|                |
+  |            | signTransaction ------------------------------------------>|
+  |            |<-------------------------------- signed tx                  |
+  |            | POST ?action=encode --------------------->|                |
+  |            |<------------------------- x_payment ------|                |
+  |            |                    |                      |                |
+  |            | [verify] retry with X-PAYMENT             |                |
+  |            |------------------->|                      |                |
+  |            |  (429? re-send same payment, up to 2x)    |                |
+  |            |   200 + result + receipt                  |                |
+  |            |<-------------------|                      |                |
+  |  receipt   |                    |                      |                |
+  |<-----------| resolve PayResult  |                      |                |
+```
+
+## Cancellation
+
+If the user closes the modal at any point, `pay()` rejects with an `Error` whose
+`.code === 'cancelled'`. Any spending-cap reservation made for the attempt is
+rolled back. Callers should treat `cancelled` as a no-op, not a failure.
+
+## Distribution shape
+
+- **Client:** one ES module (`src/index.js`), also shipped minified
+  (`dist/x402.min.js`). It self-registers `window.X402` and auto-binds
+  `[data-x402-endpoint]` elements. Crypto helpers (`@solana/web3.js`,
+  noble hashes) are loaded on demand from CDN ESM and can be repointed for
+  strict CSP via [`configure`](./api-reference.md#configure).
+- **Server:** optional, only for the Solana rail. Exposed at
+  `@three-ws/x402-payment-modal/server` with Express and Vercel adapters.

package/docs/server-setup.md

@@ -0,0 +1,239 @@
+# Server setup
+
+The server module exists for **one reason: the Solana payment rail.** It exposes
+`prepare`/`encode` endpoints that build and wrap the SPL transaction Phantom
+signs. If your endpoint only accepts EVM stablecoins (e.g. USDC on Base), you do
+**not** need any of this — see why below.
+
+For the full request lifecycle, see [architecture](./architecture.md). For the
+client side, see the [API reference](./api-reference.md).
+
+```js
+import {
+  prepareSolanaCheckout,
+  encodeX402Payment,
+  handleCheckout,
+  CheckoutError,
+  isSolanaNetwork,
+  X402_VERSION,             // 2
+  NETWORK_SOLANA_MAINNET,
+  NETWORK_SOLANA_DEVNET,
+} from '@three-ws/x402-payment-modal/server';
+```
+
+## Why EVM needs no server, but Solana does
+
+- **EVM (EIP-3009):** the browser wallet signs an EIP-712 typed-data
+  authorization entirely client-side. No funds move at signing time, and no
+  server is contacted. The signature becomes the `X-PAYMENT` header directly.
+- **Solana:** Phantom only signs *serialized transactions*, not arbitrary typed
+  data. Something has to build that transaction. The server builds a partially
+  signed `transferChecked` v0 transaction (`prepare`), the buyer signs it, then
+  the server wraps the signed tx into the x402 v2 envelope (`encode`). The fee
+  payer is a facilitator sponsor account, so the buyer needs only USDC — no SOL
+  for gas.
+
+## Install the peer dependencies
+
+The Solana helpers require these **optional** peer deps. Install them only if you
+mount the Solana checkout:
+
+```bash
+npm install @solana/web3.js@^1.95 @solana/spl-token@^0.4
+```
+
+EVM-only sites can skip this entirely.
+
+## Environment variables
+
+| Variable          | Purpose                                                        |
+|-------------------|---------------------------------------------------------------|
+| `SOLANA_RPC_URL`  | Mainnet RPC endpoint used to build/serialize the transaction. |
+
+You may also pass `rpcUrl` (and `devnetRpcUrl`) explicitly to the adapters or to
+`prepareSolanaCheckout`; explicit options take precedence over the env var.
+
+## Mounting with Express
+
+```js
+import express from 'express';
+import { x402CheckoutRouter } from '@three-ws/x402-payment-modal/server/express';
+
+const app = express();
+app.use(express.json());
+
+app.use(
+  '/api/x402-checkout',
+  x402CheckoutRouter({
+    rpcUrl: process.env.SOLANA_RPC_URL,
+    // devnetRpcUrl: 'https://api.devnet.solana.com',
+    // origin: 'https://yourapp.com',  // CORS allow-origin (default '*')
+  })
+);
+
+app.listen(3000);
+```
+
+`x402CheckoutRouter({ rpcUrl?, devnetRpcUrl?, origin? })` returns an Express
+`RequestHandler`. It sets permissive CORS by default (`origin: '*'`), answers
+`OPTIONS` preflight, and requires `POST` for the actual calls.
+
+## Mounting with Vercel / Next.js (pages API)
+
+Create `api/x402-checkout.js` (or `pages/api/x402-checkout.js`) and re-export the
+handler:
+
+```js
+// api/x402-checkout.js
+import { createVercelCheckoutHandler } from '@three-ws/x402-payment-modal/server/vercel';
+
+export default createVercelCheckoutHandler({
+  rpcUrl: process.env.SOLANA_RPC_URL,
+  // devnetRpcUrl: process.env.SOLANA_DEVNET_RPC_URL,
+  // origin: 'https://yourapp.com',
+});
+```
+
+`createVercelCheckoutHandler()` is also the module's default export, so the
+zero-config form works too:
+
+```js
+// api/x402-checkout.js
+export { default } from '@three-ws/x402-payment-modal/server/vercel';
+```
+
+Like the Express adapter, it applies permissive CORS by default, handles
+`OPTIONS`, and requires `POST`.
+
+> Point the client at this endpoint with `configure({ checkoutOrigin, checkoutPath })`
+> or the `data-x402-checkout-origin` / `data-x402-checkout-path` script
+> attributes. See the [API reference](./api-reference.md#configure).
+
+## From scratch with Node `http` + `handleCheckout`
+
+`handleCheckout` is the framework-agnostic router. Pass it the `action`
+(`'prepare'` or `'encode'`), the parsed JSON `body`, and optional `options`. It
+returns `{ status, body }`, mapping a thrown `CheckoutError` to its `.status` and
+any unexpected error to `502`. It accepts both camelCase and snake_case body
+fields (`signed_tx_base64`/`signedTxBase64`, `resource_url`/`resourceUrl`,
+`builder_code`/`builderCode`).
+
+```js
+import { createServer } from 'node:http';
+import { handleCheckout } from '@three-ws/x402-payment-modal/server';
+
+const server = createServer((req, res) => {
+  const url = new URL(req.url, 'http://localhost');
+  const action = url.searchParams.get('action'); // 'prepare' | 'encode'
+
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, cors).end();
+    return;
+  }
+  if (req.method !== 'POST') {
+    res.writeHead(405, cors).end();
+    return;
+  }
+
+  let raw = '';
+  req.on('data', (c) => (raw += c));
+  req.on('end', async () => {
+    const body = raw ? JSON.parse(raw) : {};
+    const { status, body: out } = await handleCheckout({
+      action,
+      body,
+      options: { rpcUrl: process.env.SOLANA_RPC_URL },
+    });
+    res.writeHead(status, { 'content-type': 'application/json', ...cors });
+    res.end(JSON.stringify(out));
+  });
+});
+
+const cors = {
+  'access-control-allow-origin': '*',
+  'access-control-allow-methods': 'POST, OPTIONS',
+  'access-control-allow-headers': 'content-type',
+};
+
+server.listen(3000);
+```
+
+## CORS notes
+
+Both adapters default to `origin: '*'` so a paywall served from one domain can
+talk to a checkout server on another. For production, pass your site's origin:
+
+```js
+x402CheckoutRouter({ rpcUrl: process.env.SOLANA_RPC_URL, origin: 'https://yourapp.com' });
+```
+
+## Request / response shapes
+
+### `?action=prepare`
+
+`prepareSolanaCheckout({ accept, buyer, rpcUrl?, devnetRpcUrl? })` builds a
+partially signed v0 transaction whose fee payer is `accept.extra.feePayer`.
+
+Request:
+
+```json
+{
+  "accept": {
+    "network": "solana",
+    "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+    "maxAmountRequired": "50000",
+    "payTo": "So111SyntheticMerchantPlaceholder1111111111",
+    "extra": { "feePayer": "So111SyntheticFeePayerPlaceholder11111111" }
+  },
+  "buyer": "So111SyntheticBuyerPlaceholder111111111111"
+}
+```
+
+Response:
+
+```json
+{
+  "network": "solana",
+  "tx_base64": "AQAB...base64-serialized-v0-tx...",
+  "recent_blockhash": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin"
+}
+```
+
+> `asset` above is the real Solana USDC mint (`EPjFW…Dt1v`). All other addresses
+> are synthetic placeholders. Substitute your own facilitator and merchant
+> accounts.
+
+### `?action=encode`
+
+`encodeX402Payment({ accept, signedTxBase64, resourceUrl, builderCode? })` wraps
+the buyer-signed transaction into a base64 x402 v2 envelope (`X402_VERSION === 2`).
+
+Request:
+
+```json
+{
+  "accept": { "network": "solana", "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" },
+  "signed_tx_base64": "AQAB...signed...",
+  "resource_url": "https://api.example.com/premium",
+  "builder_code": { "wallet": "examplewallet", "service": "example_api" }
+}
+```
+
+Response:
+
+```json
+{ "x_payment": "eyJ4NDAyVmVyc2lvbiI6Mn0...base64-envelope..." }
+```
+
+The client puts `x_payment` into the `X-PAYMENT` header and retries the original
+request.
+
+## Helpers
+
+| Export                     | Description                                                            |
+|----------------------------|------------------------------------------------------------------------|
+| `CheckoutError`            | `Error` subclass with `.status` and `.code`; mapped to HTTP by router. |
+| `isSolanaNetwork(network)` | `true` for Solana mainnet/devnet network identifiers.                  |
+| `X402_VERSION`             | `2` — the x402 envelope version produced by `encode`.                  |
+| `NETWORK_SOLANA_MAINNET`   | Canonical Solana mainnet network id.                                   |
+| `NETWORK_SOLANA_DEVNET`    | Canonical Solana devnet network id.                                    |

package/docs/siwx.md

@@ -0,0 +1,116 @@
+# SIWX — Sign-In-With-X re-entry
+
+SIWX ("Sign-In-With-X", standardized as [CAIP-122](https://chainagnostic.org/CAIPs/caip-122))
+lets a wallet that **already paid** for an endpoint get back in by **signing a
+challenge instead of paying again**. It is the difference between a one-time
+purchase and being charged on every page load.
+
+This package implements the **client** side of SIWX. The server endpoint must
+issue the challenge and verify the signed proof — see
+[Server responsibilities](#server-responsibilities).
+
+For the overall flow, see [architecture](./architecture.md).
+
+## Why it matters
+
+x402 charges per call. Without SIWX, a user who paid for `/premium` would pay
+again the next time they hit it. With SIWX, the merchant can recognize a wallet
+that has an active entitlement: the wallet proves ownership with a cheap,
+gasless, off-chain signature, and the merchant grants access without a new
+payment.
+
+## How the server advertises SIWX
+
+When the endpoint returns its **HTTP 402** challenge, it advertises SIWX support
+by including an extension entry in the challenge body:
+
+```json
+{
+  "x402Version": 2,
+  "accepts": [
+    {
+      "network": "base",
+      "asset": "0xUSDC...synthetic",
+      "maxAmountRequired": "50000",
+      "payTo": "0xMerchant...synthetic",
+      "extensions": {
+        "sign-in-with-x": {
+          "domain": "api.example.com",
+          "statement": "Sign in to re-enter your paid session.",
+          "nonce": "synthetic-nonce-abc123"
+        }
+      }
+    }
+  ]
+}
+```
+
+The exact challenge fields are defined by the x402 SIWX spec; the modal only
+needs `extensions['sign-in-with-x']` to be present to offer sign-in.
+
+## How the client submits proof
+
+When the user signs the challenge, the modal sends the signed CAIP-122 proof back
+to the endpoint as a base64-encoded JSON value in the **`SIGN-IN-WITH-X`**
+request header, then retries the original request. If the merchant accepts the
+proof, it returns the result with no payment required.
+
+## Modal behavior
+
+The modal adapts its layout to what the challenge offers:
+
+1. **SIWX advertised + a compatible wallet present** — the modal **leads with
+   "Sign in with wallet"** as the primary (`.x402-pay-btn`) action and **demotes
+   pay to secondary** (`.x402-pay-secondary`). Signing in is cheaper, so it's the
+   default.
+2. **User signs in** — on success the modal resolves [`PayResult`](./api-reference.md#payresult)
+   with the `siwx` field populated (`{ address, network }`) and **no `payment`
+   field**, and fires the [`x402:siwx-signed`](#the-x402siwx-signed-event) event.
+3. **Sign-in rejected (`siwx_not_paid`)** — if the server answers the SIWX
+   attempt with a `401`/`402` carrying a `siwx_not_paid` reason (the wallet has
+   no active entitlement), the modal **falls back to the normal pay flow** and
+   shows a notice explaining that payment is required.
+4. **SIWX not advertised** — the modal behaves as a plain pay modal; nothing
+   changes.
+
+## The `x402:siwx-signed` event
+
+A successful SIWX re-entry dispatches a bubbling `x402:siwx-signed`
+`CustomEvent` on the clicked element:
+
+```js
+const btn = document.querySelector('[data-x402-endpoint]');
+
+btn.addEventListener('x402:siwx-signed', (e) => {
+  const { address, network } = e.detail;
+  console.log(`re-entered as ${address} on ${network}`);
+});
+```
+
+You also get the same data programmatically from the resolved result:
+
+```js
+const res = await pay({ endpoint: 'https://api.example.com/premium' });
+
+if (res.siwx) {
+  console.log('re-entered via SIWX:', res.siwx.address);
+} else if (res.payment) {
+  console.log('paid:', res.payment.transaction);
+}
+```
+
+## Server responsibilities
+
+This package does not store entitlements or verify signatures. Your endpoint
+must:
+
+1. **Advertise** the SIWX extension in the 402 challenge (see above).
+2. **Verify** the CAIP-122 proof from the `SIGN-IN-WITH-X` header — check the
+   nonce, domain, expiry, and signature against the claimed address.
+3. **Authorize** the request if that address has an active paid entitlement;
+   otherwise respond `401`/`402` with `siwx_not_paid` so the client falls back to
+   paying.
+
+Implement these against the x402 SIWX specification. The modal handles
+everything on the browser side: detecting the offer, prompting the signature,
+encoding the header, retrying, and falling back.

package/docs/spending-caps.md

@@ -0,0 +1,92 @@
+# Spending caps
+
+Spending caps are client-side guardrails that stop a wallet from spending more
+than you allow through the modal — per call, per hour, and per day. They make
+unattended or agentic usage safer by bounding the blast radius of a bug or a
+runaway loop.
+
+They are passed to [`pay()`](./api-reference.md#payopts) via the `caps` option.
+
+## Shape
+
+```ts
+interface SpendingCaps {
+  maxPerCall?: string | number;
+  maxPerHour?: string | number;
+  maxPerDay?:  string | number;
+}
+```
+
+All amounts are **atomic micro-USD** — i.e. millionths of a dollar
+(`1_000_000` = 1 USDC). Strings are accepted to avoid floating-point loss on
+large numbers.
+
+| Field        | Meaning                                                |
+|--------------|--------------------------------------------------------|
+| `maxPerCall` | Maximum a single payment may cost.                     |
+| `maxPerHour` | Maximum total across the current UTC hour bucket.      |
+| `maxPerDay`  | Maximum total across the current UTC day bucket.       |
+
+## How enforcement works
+
+- Spend is tracked in **`localStorage`, per wallet address.**
+- Totals are **bucketed by UTC hour and UTC day**, so the windows roll over
+  cleanly and survive a page reload.
+- Before a payment is signed, the modal **reserves** the amount against the
+  relevant buckets. If any cap would be exceeded, the payment is blocked and the
+  user sees an error explaining which limit was hit.
+- If the payment **fails or is cancelled**, the reservation is **rolled back** so
+  a failed attempt never counts against the user's budget. (Cancellation is the
+  `pay()` rejection with `.code === 'cancelled'`.)
+
+## Important caveat: stablecoins only
+
+The drop-in script stays **zero-dependency and does not fetch live prices.** That
+means it can only reason about value when 1 token ≈ 1 USD — i.e. **stablecoins
+(USDC / USDT / DAI).** For those, atomic micro-USD caps are meaningful directly.
+
+For **non-stable assets**, the modal cannot convert an amount to USD without a
+price feed, so browser caps do **not** meaningfully bound spend. **Enforce caps
+for non-stable assets on the server side**, where you can price the asset at
+settlement time.
+
+## Not a security boundary
+
+Client-side caps are **advisory guardrails, not a security control.** They live in
+`localStorage`, which a determined user can clear or edit, and they only cover
+flows that go through this modal. Treat them as a convenience and a safety net for
+honest usage. **Real spending limits belong on the server**, enforced where the
+payment is verified and settled.
+
+## Worked example
+
+```js
+import { pay } from '@three-ws/x402-payment-modal';
+
+// USDC, so atomic micro-USD caps apply directly:
+//   0.10 USDC per call, 2.00 USDC/hour, 10.00 USDC/day
+const res = await pay({
+  endpoint: 'https://api.example.com/premium',
+  method: 'POST',
+  body: { prompt: 'Summarize this article' },
+  merchant: 'Example API',
+  action: 'Generate summary',
+  caps: {
+    maxPerCall: 100_000,      // 0.10 USDC
+    maxPerHour: 2_000_000,    // 2.00 USDC
+    maxPerDay:  10_000_000,   // 10.00 USDC
+  },
+});
+
+console.log(res.result);
+```
+
+If a call would push the current UTC-hour total over `maxPerHour`, the modal
+blocks it before any wallet prompt and surfaces the reason; nothing is reserved.
+
+## See also
+
+- [API reference](./api-reference.md) — where `caps` fits in `PayOptions`.
+- [Architecture](./architecture.md) — where the reservation/rollback sits in the
+  lifecycle.
+- [Server setup](./server-setup.md) — for enforcing real limits server-side.