@agentcash/router 1.5.1 → 1.6.0

package/.claude/CLAUDE.md

@@ -24,7 +24,8 @@ Protocol-agnostic route framework for Next.js App Router APIs with x402 payment,
 - `src/pricing.ts` — Price resolution (static, tiered, dynamic)
 - `src/plugin.ts` — Plugin hook system
 - `src/server.ts` — x402 server initialization
-- `src/auth/` — Auth modules (siwx.ts, api-key.ts, nonce.ts)
+- `src/auth/` — Auth modules (siwx.ts, api-key.ts)
+- `src/kv-store/` — Single KV cache layer (`client.ts` is the only file that talks to Redis; `nonce.ts`/`entitlement.ts`/`mpp.ts` are namespaced adapters on top)
 - `src/protocols/` — Protocol handlers (x402.ts, detect.ts). MPP is handled via `mppx` high-level API (`Mppx.create` in index.ts)
 - `src/discovery/` — Auto-generated endpoints (well-known.ts, openapi.ts)
 
@@ -35,10 +36,91 @@ Four auth modes, mutually exclusive (except `.apiKey()` composes with `.paid()`)
 ### `.paid(pricing)` — Payment required
 ```typescript
 .paid('0.01')                    // Static price
-.paid((body) => calcPrice(body)) // Dynamic pricing
+.paid((body) => calcPrice(body)) // Dynamic pricing (body-driven, pre-handler)
 .paid({ field: 'tier', tiers: { basic: { price: '0.01' } } }) // Tiered
+
+// Handler-driven dynamic pricing — `.handler()` request-mode bills exactly
+// tickCost per request; `.stream()` streaming bills per `charge()` call.
+.paid({ dynamic: true, tickCost: '0.0005', unitType: 'token', maxPrice: '0.10' })
+```
+
+#### Handler-driven dynamic (`.paid({ dynamic: true })`)
+
+The handler shape determines the billing model and wire transport:
+
+**Request-mode** — `async (ctx) => value`. Bills exactly `tickCost` per
+request. No `charge()` on the context — the wire commitment is fixed at
+credential verification (mppx's non-SSE auto-charge for MPP, or x402 `upto`
+settled for `tickCost`). This is the spec-aligned "discrete paid unit" mode
+per `paymentauth.org/draft-tempo-session-00`.
+
+```typescript
+router
+  .route('llm/summarize')
+  .paid({ dynamic: true, tickCost: '0.01', unitType: 'request', maxPrice: '0.01' })
+  .body(z.object({ prompt: z.string() }))
+  .handler(async ({ body }) => {
+    const summary = await callLLM(body.prompt);
+    return { summary }; // always bills $0.01
+  });
+```
+
+For variable-cost-per-request billing, use the streaming shape below —
+splitting work into yields lets `charge()` meter per unit.
+
+**Streaming mode** — `.stream(async function* (ctx) { ... })`. Receives a
+`charge()` callback on `ctx`; one call adds one tick. The invariant:
+
+> **one `charge()` call === one tick === `tickCost` USDC === one route-defined unit**
+
+The route picks `tickCost` to match its billing unit (one token at $0.0005,
+one byte at $0.0000001, one frame at $0.001) and labels it via `unitType`.
+Total billed is `tickCost × call_count`, capped at `maxPrice`. (Internally:
+mppx auto-charges one prepaid tick at credential verify and marks it; the
+first `charge()` consumes the prepaid without an extra debit, then subsequent
+calls bill fresh ticks live.)
+
+```typescript
+router
+  .route('llm/stream')
+  .paid({ dynamic: true, tickCost: '0.0001', unitType: 'token', maxPrice: '0.05', protocols: ['mpp'] })
+  .body(z.object({ prompt: z.string() }))
+  .stream(async function* ({ body, charge }) {
+    for await (const token of streamLLM(body.prompt)) {
+      await charge();        // one tick = one token; blocks on need-voucher
+      yield token;
+    }
+    yield '[DONE]';            // free trailing event — no charge before it
+  });
 ```
 
+**Type safety**: TypeScript discriminates by which terminal method you call.
+`.handler()` receives a `HandlerContext` with no `charge` — calling it is a
+compile-time error. `.stream()` receives a `StreamingHandlerContext` with
+`charge` and is only callable after `.paid({ dynamic: true, ... })`.
+
+`tickCost` is required per-route on `.paid({ dynamic: true })` — the builder
+throws at registration if it's missing. `unitType` is optional (cosmetic
+label, defaults to undefined which mppx surfaces as plain ticks).
+
+**Transport selection**: the router picks the wire format from the terminal
+method. `.handler()` request-mode goes through plain HTTP with a
+`Payment-Receipt` header (mppx's `tempo.session({ sse: false })`). `.stream()`
+goes through SSE with inline per-tick voucher events
+(`tempo.session({ sse: true })`). Two mppx instances run side-by-side
+sharing the same store, secretKey, and realm so channel state and challenge
+HMACs are interchangeable.
+
+Both terminal methods work on x402 `upto` (settles cumulative atomic amount;
+Permit2Proxy enforces ≤ maxPrice) and MPP. `.stream()` requires MPP — x402
+has no streaming primitive.
+
+**`suggestedDeposit` on MPP session 402 challenges**: defaults to
+`tickCost × RouterConfig.mpp.session.depositMultiplier` (default `10`), or
+the route's `maxPrice` when set. Raise the multiplier at deployment level to
+cover more requests per channel, or set `maxPrice` per-route when a single
+request can exceed the default budget.
+
 ### `.siwx()` — Wallet identity required (no payment)
 ```typescript
 .siwx().handler(async ({ wallet }) => { /* wallet is verified */ })
@@ -161,6 +243,38 @@ MPP payment verification requires an **authenticated** Tempo RPC endpoint. The p
 
 Alternatively, pass `rpcUrl` in the `mpp` config object to `createRouter()`. Without either, MPP on-chain verification fails with "unauthorized: authentication required".
 
+### MPP Server Wallets: `operatorKey` and `feePayerKey`
+
+Two distinct roles, two distinct wallets:
+
+- **`mpp.operatorKey`** — signs server-side on-chain ops (channel close/settle). Required for sessions. Its derived address **must equal `recipient`/payee** because mppx's close handler asserts `sender === payee` on settle.
+- **`mpp.feePayerKey`** *(optional)* — sponsors gas for client-signed open/topUp txs. Omit to disable sponsorship; clients then pay their own gas.
+
+**The two MUST resolve to different addresses when both are set.** Tempo rejects fee-delegated txs where `sender === feePayer` with `-32000 "fee payer cannot resolve to sender"`. This bites the server-signed close/settle path. The router validates the addresses at `createRouter()` time and throws `mpp_operator_equals_fee_payer` if they collide — production `next build` fails fast; dev surfaces a logged error.
+
+### KV Store
+
+One KV cache backs all three persistent stores (SIWX nonce, SIWX entitlement, MPP tx-hash replay). Each consumer gets its own key prefix (`siwx:nonce:`, `siwx:ent:`, `mpp:`).
+
+Resolution order in `createRouter`:
+
+1. `kvStore: { url, token }` — build the REST client from those credentials.
+2. `kvStore: <KvStore>` — bring-your-own implementation (escape hatch for Cloudflare KV, ioredis, etc.).
+3. Omitted — auto-read `KV_REST_API_URL` + `KV_REST_API_TOKEN` from `process.env`.
+4. Env missing — fall back to in-memory stores (fine for local dev, unsafe in serverless production).
+
+```typescript
+createRouter({
+  kvStore: {
+    url: process.env.UPSTASH_REDIS_REST_URL!,
+    token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+  },
+  // ...
+});
+```
+
+The only file that talks to Redis is `src/kv-store/client.ts`. It speaks the Upstash REST protocol with plain `fetch` (also what Vercel KV exposes). If you need a different backend, implement the `KvStore` interface and pass it as `kvStore`.
+
 ### CDP Environment Variables
 
 Without these keys, the default facilitator cannot authenticate with CDP:

package/README.md

@@ -75,7 +75,6 @@ const config = {
   x402: { accepts },
   mpp: mppFromEnv(process.env, {
     recipient: payeeAddress,
-    useDefaultStore: true,
   }),
   discovery: {
     title: 'My API',
@@ -99,8 +98,38 @@ and `TEMPO_RPC_URL`. `MPP_CURRENCY` must be the Tempo currency address; for
 Tempo USDC use `TEMPO_USDC_CURRENCY`. Optional `MPP_FEE_PAYER_KEY` is included
 when present and validated as a 32-byte EVM private key. `mppFromEnv()` only
 builds config; call `validateRouterConfig(config)` before `createRouter(config)`
-to fail fast on `mpp.useDefaultStore` store env (`KV_REST_API_URL` and
-`KV_REST_API_TOKEN`) when you use the default store.
+to fail fast on misconfiguration.
+
+### Persistent KV store
+
+The router uses a single KV cache for three things: SIWX nonce replay
+protection, SIWX entitlement records, and MPP tx-hash replay protection. Each
+consumer gets its own key prefix (`siwx:nonce:`, `siwx:ent:`, `mpp:`) so one
+Redis/Upstash instance serves all three.
+
+`createRouter` reads `KV_REST_API_URL` + `KV_REST_API_TOKEN` from `process.env`
+automatically (Vercel KV and Upstash both set these). If both are present, it
+builds an Upstash-compatible REST client and wires it into every store. If
+either is missing, all three stores fall back to in-memory — fine for local
+dev, unsafe in serverless production.
+
+To use REST credentials under a different env name, pass them as
+`{ url, token }`:
+
+```typescript
+import { createRouter } from '@agentcash/router';
+
+createRouter({
+  kvStore: {
+    url: process.env.UPSTASH_REDIS_REST_URL!,
+    token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+  },
+  // ...
+});
+```
+
+For a different backend entirely (Cloudflare KV, ioredis, etc.), implement the
+`KvStore` interface and pass your instance as `kvStore`.
 
 ## Quick Start
 
@@ -196,8 +225,8 @@ Creates a `ServiceRouter` instance.
 | `network` | `string` | `'eip155:8453'` | Blockchain network |
 | `plugin` | `RouterPlugin` | `undefined` | Observability plugin |
 | `prices` | `Record<string, string>` | `undefined` | Central pricing map (auto-applied) |
-| `siwx.nonceStore` | `NonceStore` | `MemoryNonceStore` | Custom nonce store |
-| `mpp` | `{ secretKey, currency, recipient?, rpcUrl?, feePayerKey?, useDefaultStore? }` | `undefined` | MPP config |
+| `kvStore` | `KvStore \| { url, token }` | auto from `KV_REST_API_URL` + `KV_REST_API_TOKEN`, else memory | Single KV cache for SIWX nonce, SIWX entitlement, and MPP tx-hash replay |
+| `mpp` | `{ secretKey, currency, recipient?, rpcUrl?, feePayerKey?, session? }` | `undefined` | MPP config |
 | `protocols` | `('x402' \| 'mpp')[]` | `['x402']` | Default protocols for paid routes |
 | `strictRoutes` | `boolean` | `false` | Enforce `route({ path })` and prevent key/path divergence |