uvd-x402-sdk 2.104.0 → 2.104.2

package/README.md

@@ -684,7 +684,7 @@ const paymentAuth = await buildEscrowPreAuth(new EnvKeyAdapter(), {
 // Send as the X-Payment-Auth header (raw JSON, NOT base64).
 ```
 
-Any `SigningWalletAdapter` works as the signer (only `signTypedData` is used); browser wallets can pass a minimal `{ signTypedData }` wrapper. Validation fails loud instead of falling back: incomplete network config, unknown tier, bounty outside the on-chain deposit limit ($100), or a `maxFeeBps` below the operator's 1300 bps all throw before anything is signed. What the config asserts is also checked against the SDK's own tables before signing, as in the Python SDK: the `chain_id` against the `network` you name (a registry name or `eip155:<id>`), the escrow, token collector and USDC against `ESCROW_CONTRACTS`, the operator against `ESCROW_OPERATORS`, and `maxFeeBps` against the chain's ceiling in `ESCROW_MAX_FEE_BPS`. A contradiction throws `INVALID_CONFIG`, and so do a `network` the SDK does not register and a chain without a row in each of the three tables, with or without `network`; name the network you expect to pay on, from your own code, never one read from the config. A server-published tier window must be an integer from 0 to its `ESCROW_TIER_WINDOW_MAX`, and `authorizationExpiry` at most `ESCROW_MAX_AUTHORIZATION_SEC` after now: past either, the SDK refuses, it never clamps. `computeEscrowNonce` is exported to reproduce `AuthCaptureEscrow.getHash` externally.
+Any `SigningWalletAdapter` works as the signer (only `signTypedData` is used); browser wallets can pass a minimal `{ signTypedData }` wrapper. Validation fails loud instead of falling back: incomplete network config, unknown tier, bounty outside the on-chain deposit limit ($100), or a `maxFeeBps` below the operator's 1300 bps all throw before anything is signed. What the config asserts is also checked against the SDK's own tables before signing, as in the Python SDK: the `chain_id` against the `network` you name (a registry name or `eip155:<id>`), the escrow, token collector and USDC against `ESCROW_CONTRACTS`, the operator against `ESCROW_OPERATORS`, `maxFeeBps` against the chain's ceiling in `ESCROW_MAX_FEE_BPS`, and the USDC EIP-712 domain (`usdc_domain_name` / `usdc_domain_version`) against the token's on-chain domain in `VERIFIED_USDC_DOMAINS`. A contradiction throws `INVALID_CONFIG`, and so do a `network` the SDK does not register and a chain without a row in each of the four tables, with or without `network`; name the network you expect to pay on, from your own code, never one read from the config. A server-published tier window must be an integer from 0 to its `ESCROW_TIER_WINDOW_MAX`, and `authorizationExpiry` at most `ESCROW_MAX_AUTHORIZATION_SEC` after now: past either, the SDK refuses, it never clamps. `computeEscrowNonce` is exported to reproduce `AuthCaptureEscrow.getHash` externally.
 
 ## Multi-Stablecoin (EVM)
 
@@ -889,6 +889,8 @@ app.post('/api/premium', async (req, res) => {
 });
 ```
 
+To be listed in the facilitator's Bazaar after a paid call, flag the accepts as discoverable: `discoverable: true` in the options of `createHonoMiddleware()` or `createFetchPaywall()` writes `extra.discoverable: true` on every accept, in the 402 and in the requirements sent to `/verify` and `/settle`; the other `extra` fields (`name`, `version`) stay. `false` writes `discoverable: false`, overriding a hand-written `true`, as the Python SDK's `False` does (for the facilitator, `false` and no flag both mean "not listed"); without the option the accepts go out as given. Native Hedera accepts go out as given with either value: the facilitator allows only `feePayer` in their `extra`, so a Hedera settle is never listed. For one accept, or for `create402Response`, use `withDiscoverable(accept)` (`withDiscoverable(accept, false)` to opt out); it throws for a native Hedera accept. Neither modifies the object it is given. A `discoverable` that is not a boolean and an `extra` that is not a plain object throw when the paywall is built, before any request.
+
 `createPaymentMiddleware()`, `createHonoMiddleware()` and `createFetchPaywall()` verify and settle automatically by default (`before-handler`). Use `settlementStrategy: 'manual'` if you need to control when settlement happens (e.g., settle only after confirming you can fulfill the request).
 
 A buyer in a browser on another origin reads the terms of a v2 402, in the `PAYMENT-REQUIRED` header, only if the app's CORS exposes that header: list it in `Access-Control-Expose-Headers` (with `hono/cors`, `exposeHeaders: ['PAYMENT-REQUIRED']`) and send `Access-Control-Allow-Origin`. The 402 of `createHonoMiddleware` and `createFetchPaywall` sets no CORS header of its own; `create402Response` lists the header in its `headers` but sets no `Access-Control-Allow-Origin` (spread `getCorsHeaders(origin)` too).
@@ -2050,6 +2052,91 @@ const result = await anchorEvidence(body, {
 res.setHeader('X-Durable-Evidence', evidenceHeader(result));
 ```
 
+### Seller: from the paywall itself (`durable`)
+
+`createFetchPaywall`, `createHonoMiddleware` and `createPaymentMiddleware`
+(Express) take an opt-in `durable`. With it, a paid `2xx` answer that the
+handler did not anchor itself is captured once, sealed and anchored through
+`anchorEvidence`, and goes out with `X-Durable-Evidence`:
+
+```ts
+import { TypedDataEncoder, getBytes } from 'ethers';
+import { createFetchPaywall, type DurableEvidenceContext } from 'uvd-x402-sdk/backend';
+import { caip2ToChain, getChainByName, payerKeyFromEvmSignature } from 'uvd-x402-sdk';
+
+const TRANSFER_WITH_AUTHORIZATION = {
+  TransferWithAuthorization: [
+    { name: 'from', type: 'address' }, { name: 'to', type: 'address' },
+    { name: 'value', type: 'uint256' }, { name: 'validAfter', type: 'uint256' },
+    { name: 'validBefore', type: 'uint256' }, { name: 'nonce', type: 'bytes32' },
+  ],
+};
+
+// The key behind an EIP-3009 USDC payment: recovered from the signature over the
+// digest the buyer signed, with the token domain of the chain registry.
+const evmPayerKey = ({ payment }: DurableEvidenceContext) => {
+  const payload = payment.payment.payload;
+  if (!('authorization' in payload)) return undefined; // not an EVM payment: skipped
+  const network = payment.requirements.network;
+  const chain = getChainByName(caip2ToChain(network) ?? network);
+  if (!chain) return undefined;
+  const digest = TypedDataEncoder.hash(
+    { name: chain.usdc.name, version: chain.usdc.version, chainId: chain.chainId, verifyingContract: payment.requirements.asset },
+    TRANSFER_WITH_AUTHORIZATION,
+    payload.authorization,
+  );
+  return payerKeyFromEvmSignature(payload.signature, getBytes(digest));
+};
+
+const paywall = createFetchPaywall({
+  accepts,
+  durable: {
+    payerKey: evmPayerKey,   // Solana: ({ payment }) => payerKeyFromSolanaAddress(payment.verifyResult.payer!)
+    maxBodyBytes: 64 * 1024, // default ANCHOR_MAX_REQUEST_BYTES
+    timeoutMs: 5000,         // default DURABLE_DEFAULT_TIMEOUT_MS
+  },
+});
+```
+
+A wrong digest does not throw: it recovers another valid key, and the evidence
+would be sealed to it. `src/backend/durable-evidence.test.ts` checks this
+derivation against a signature made with a synthetic key.
+
+Without `durable` nothing changes and nothing is anchored. It anchors only a
+payment this request settled with a transaction hash (`'manual'`: once
+`x402.settle()` resolved successfully before the answer); a replayed settle, or
+one whose receipt is `pending`, `unknown` or `rejected`, is not anchored. The body is read once
+and held at most `maxBodyBytes`; past that, past `timeoutMs`, for an event
+stream, for a body already locked or read, or when the handler's own stream
+fails, the response goes out whole and unchanged except for a skip notice in
+the header, and nothing is anchored. A failed anchor is a skip notice too: the
+response and the payment stand. A `HEAD`, a non-`2xx` answer and a response that
+already has `X-Durable-Evidence` are left alone. Every field of `durable` but
+`payerKey`, `maxBodyBytes` and `timeoutMs` is the `anchorEvidence` option of the
+same name; `facilitator` defaults to the paywall's facilitator.
+
+The skip notices the paywall adds, besides those of `anchorEvidence`:
+
+| `skipped` | When |
+|---|---|
+| `no_payer_key` | `payerKey` returned `undefined` or an empty key, or threw |
+| `too_large` | the body is over `maxBodyBytes` (declared or read) |
+| `not_capturable` | an event stream, a body already sent, a chunk that is not bytes, or a handler stream that failed |
+| `timeout` | capture, `payerKey`, upload or anchor did not finish within `timeoutMs` |
+| `anchor_failed` | the anchor failed |
+
+In Express, the answer is held from the handler's `end()` until the anchor
+returns (at most `timeoutMs`). In that window `res.headersSent` and
+`res.writableEnded` are `true`, a further `write()` is refused as a write after
+end, a further `end()` only queues its callback, and headers can no longer be
+set: the paid answer goes out as the handler ended it. A close the server asks
+for in that window without an error (`res.destroy()` or `req.socket.destroy()`,
+which is what Express's final handler does on an error once headers are sent)
+waits until the body is written and then closes the connection. A close with an
+error, or one once the connection can no longer write, is not held. A client
+that hangs up its side during the window does not get the body: the window
+lengthens (up to `timeoutMs`) the time in which that happens.
+
 **It never throws.** Every failure resolves to `result.skipped`, because
 evidence is an addition to the payment path and must never be a gate in front of
 it. An unreachable facilitator costs the receipt, never the sale.

package/dist/adapters/index.d.mts

@@ -1,4 +1,4 @@
-import { X as X402Version, a as PaymentResult } from '../index-DagQ74ZQ.mjs';
+import { X as X402Version, a as PaymentResult } from '../index-DARXHuQl.mjs';
 export { E as EnvKeyAdapter, O as OWSAccountInfo, a as OWSCore, b as OWSSignResult, c as OWSWallet, d as OWSWalletAdapter, e as OWSWalletAdapterOptions } from '../ows-DazT4KQH.mjs';
 import '../wallet-T0NFUUkT.mjs';
 import 'ethers';

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-import { X as X402Version, a as PaymentResult } from '../index-DagQ74ZQ.js';
+import { X as X402Version, a as PaymentResult } from '../index-DARXHuQl.js';
 export { E as EnvKeyAdapter, O as OWSAccountInfo, a as OWSCore, b as OWSSignResult, c as OWSWallet, d as OWSWalletAdapter, e as OWSWalletAdapterOptions } from '../ows-BB6Sgj0W.js';
 import '../wallet-T0NFUUkT.js';
 import 'ethers';

package/dist/adapters/index.js

@@ -1126,6 +1126,9 @@ var SUPPORTED_CHAINS = {
 var CHAIN_ALIASES = {
   hedera: "hedera:mainnet",
   "hedera-testnet": "hedera:testnet",
+  // Execution Market's and Karmakadabra's keys for SKALE Base.
+  skale: "skale-base",
+  "skale-testnet": "skale-base-sepolia",
   // Renamed in 2.85.0: the facilitator advertises the mainnet as `xrpl`.
   "xrpl-mainnet": "xrpl"
 };