uvd-x402-sdk 2.104.2 → 2.105.0

package/README.md

@@ -23,6 +23,7 @@ Users sign a message or transaction, and the Ultravioleta facilitator handles on
 - **Escrow & Refunds**: Hold payments with dispute resolution
 - **Advanced Escrow**: Full escrow lifecycle (authorize, release, refund, charge) with SigningWalletAdapter support
 - **Escrow Pre-Auth**: Sign-on-assignment `X-Payment-Auth` builder (`buildEscrowPreAuth`) — vector-pinned parity with the Python SDK and Execution Market
+- **Batch Settlement (buyer)**: `uvd-x402-sdk/batch-settlement` — one ERC-3009 deposit opens a channel, each later request pays with a cumulative voucher; capped deposits, vector-pinned parity with the Python SDK
 - **Commerce Scheme**: `'commerce'` scheme alias for marketplace integrations (identical to `'escrow'` on-chain)
 - **`/accepts` Negotiation**: Discover facilitator capabilities before constructing payments
 - **Bazaar Discovery**: Register and discover paid resources across the x402 network
@@ -686,6 +687,26 @@ const paymentAuth = await buildEscrowPreAuth(new EnvKeyAdapter(), {
 
 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.
 
+## Batch Settlement (buyer)
+
+The buyer side of the x402 `batch-settlement` scheme on EVM ([spec](https://github.com/coinbase/x402/tree/main/specs/schemes/batch-settlement)): the first paid request signs an ERC-3009 deposit into a payment channel plus a voucher, and every later request on that channel signs only the next cumulative voucher. Same API and the same golden vectors as the Python SDK's `uvd_x402_sdk.batch_settlement`.
+
+```typescript
+import { EnvKeyAdapter } from 'uvd-x402-sdk';
+import { BatchSettlementClient, FileChannelStorage } from 'uvd-x402-sdk/batch-settlement';
+
+const client = new BatchSettlementClient(new EnvKeyAdapter(), {
+  storage: new FileChannelStorage('./channels.json'), // Node; MemoryChannelStorage by default
+  maxDeposit: 1_000_000n,                             // the default: 1 USDC in atomic units
+});
+
+const prepared = await client.createPayment(accepted, { url }); // accepted = the 402's batch-settlement accept
+const res = await fetch(url, { headers: { 'PAYMENT-SIGNATURE': prepared.header() } });
+if (res.ok) await client.confirm(prepared, settleResponse.extra); // from the PAYMENT-RESPONSE header
+```
+
+A deposit is never above `maxDeposit`: the seller's `extra.minDeposit` is a target, and a deposit the next voucher needs above the cap throws `BatchSettlementError` with nothing signed. Only `eip155:*` networks and the ERC-3009 deposit are signed (`assetTransferMethod: 'permit2'` throws). `confirm` records previous cumulative + `chargedAmount` and never copies the seller's `channelState`; a mismatch leaves the local state untouched and resolves to `false`. If the payer may be an EIP-7702 delegated account (a Paybox wallet), pass `delegationResolver` (e.g. `rpcDelegationResolver(rpcUrl)`): the deposit authorization is then wrapped for ERC-1271 when the delegate needs it, and an unreadable chain refuses instead of signing plain. Not included: Permit2 deposits, the cooperative refund and the corrective-402 resync.
+
 ## Multi-Stablecoin (EVM)
 
 ```typescript

package/dist/adapters/index.d.mts

@@ -1,5 +1,5 @@
 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';
+export { E as EnvKeyAdapter, O as OWSAccountInfo, a as OWSCore, b as OWSSignResult, c as OWSWallet, d as OWSWalletAdapter, e as OWSWalletAdapterOptions } from '../ows-DJu424iz.mjs';
 import '../wallet-T0NFUUkT.mjs';
 import 'ethers';
 

package/dist/adapters/index.d.ts

@@ -1,5 +1,5 @@
 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';
+export { E as EnvKeyAdapter, O as OWSAccountInfo, a as OWSCore, b as OWSSignResult, c as OWSWallet, d as OWSWalletAdapter, e as OWSWalletAdapterOptions } from '../ows-CW-g7qGw.js';
 import '../wallet-T0NFUUkT.js';
 import 'ethers';
 

package/dist/adapters/index.js

@@ -1545,8 +1545,124 @@ function assertTypedDataIntegersExact(doc, where = "typed data", code = "INVALID
   }
   assertNoInexactNumber(message, `${where} message`, code);
 }
+var MIN_EXACT_DIGITS = 22;
+var MAX_EXACT_DIGITS = 78;
+var MAX_DOUBLE_DIGITS = 17;
+function doubleShaped(literal) {
+  const significant = literal.replace(/^-/, "").replace(/0+$/, "");
+  return significant.length <= MAX_DOUBLE_DIGITS || BigInt(literal) === BigInt(Number(literal));
+}
+var JSON_NUMBER = /-?(?:0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?/y;
+var JSON_SPACE = /[ \t\n\r]*/y;
+function dataDescriptor(value) {
+  const descriptor = /* @__PURE__ */ Object.create(null);
+  descriptor.value = value;
+  descriptor.writable = true;
+  descriptor.enumerable = true;
+  descriptor.configurable = true;
+  return descriptor;
+}
+function parseJsonExact(input) {
+  const text = String(input);
+  let pos = 0;
+  let wide = false;
+  const fail = (what) => {
+    throw new SyntaxError(`${what} in JSON at position ${pos}`);
+  };
+  const space = () => {
+    JSON_SPACE.lastIndex = pos;
+    if (JSON_SPACE.exec(text)) pos = JSON_SPACE.lastIndex;
+  };
+  const string = () => {
+    if (text[pos] !== '"') fail("Expected a string");
+    let end = pos + 1;
+    while (end < text.length && text[end] !== '"') end += text[end] === "\\" ? 2 : 1;
+    if (end >= text.length) fail("Unterminated string");
+    const value = JSON.parse(text.slice(pos, end + 1));
+    pos = end + 1;
+    return value;
+  };
+  const key = () => {
+    const name = string();
+    space();
+    if (text[pos] !== ":") fail("Expected ':'");
+    pos += 1;
+    space();
+    return name;
+  };
+  const scalar = () => {
+    if (text[pos] === '"') return string();
+    for (const [word, value] of [["true", true], ["false", false], ["null", null]]) {
+      if (text.startsWith(word, pos)) {
+        pos += word.length;
+        return value;
+      }
+    }
+    JSON_NUMBER.lastIndex = pos;
+    const match = JSON_NUMBER.exec(text);
+    if (!match) return fail("Unexpected token");
+    pos = JSON_NUMBER.lastIndex;
+    const literal = match[0];
+    const digits = literal.length - (literal.startsWith("-") ? 1 : 0);
+    if (match[1] === void 0 && match[2] === void 0 && digits >= MIN_EXACT_DIGITS && digits <= MAX_EXACT_DIGITS && !doubleShaped(literal)) {
+      wide = true;
+      return BigInt(literal);
+    }
+    return Number(literal);
+  };
+  const stack = [];
+  space();
+  for (; ; ) {
+    let value;
+    if (text[pos] === "[") {
+      pos += 1;
+      space();
+      if (text[pos] !== "]") {
+        stack.push({ kind: "array", items: [] });
+        continue;
+      }
+      pos += 1;
+      value = [];
+    } else if (text[pos] === "{") {
+      pos += 1;
+      space();
+      if (text[pos] !== "}") {
+        stack.push({ kind: "object", object: {}, key: key() });
+        continue;
+      }
+      pos += 1;
+      value = {};
+    } else {
+      value = scalar();
+    }
+    for (; ; ) {
+      space();
+      const top = stack[stack.length - 1];
+      if (top === void 0) {
+        if (pos !== text.length) fail("Unexpected non-whitespace character after JSON");
+        return wide ? value : JSON.parse(text);
+      }
+      const close = top.kind === "array" ? "]" : "}";
+      if (top.kind === "array") {
+        top.items.push(value);
+      } else {
+        Object.defineProperty(top.object, top.key, dataDescriptor(value));
+      }
+      if (text[pos] === ",") {
+        pos += 1;
+        space();
+        if (top.kind === "object") top.key = key();
+        break;
+      }
+      if (text[pos] !== close) fail(`Expected ',' or '${close}'`);
+      pos += 1;
+      stack.pop();
+      value = top.kind === "array" ? top.items : top.object;
+    }
+  }
+}
 function parseTypedDataJson(text, where = "typed data", code = "INVALID_CONFIG") {
-  const doc = JSON.parse(text);
+  const doc = parseJsonExact(text);
   assertTypedDataIntegersExact(doc, where, code);
   return doc;
 }
@@ -1589,11 +1705,18 @@ var EnvKeyAdapter = class {
   /**
    * Sign EIP-712 typed structured data.
    *
+   * An integer of 22 to 78 digits written as a JSON number (a 32-byte salt)
+   * is read with every digit, as Python's `json` reads it, not rounded the
+   * way `JSON.parse` rounds it.
+   *
    * @param typedData - JSON string with `domain`, `types`, `primaryType`, and `message` fields
    * @returns Object with signature and v/r/s components
    * @throws {X402Error} `INVALID_CONFIG` when an integer field of `message`
-   *   (or `domain.chainId`) is a JSON number above 2**53 - 1: `JSON.parse`
-   *   rounded it, so it is refused instead of signed. Write uints as strings.
+   *   (or `domain.chainId`) is a JSON number above 2**53 - 1 of up to 21
+   *   digits (a JavaScript hop may have rounded it and written it back in
+   *   digits) or written with an exponent or a fraction (`7.76e+76`): it is
+   *   refused instead of signed. Write uints as strings. An integer out of
+   *   its field's range is refused by ethers (`value out-of-bounds`).
    */
   async signTypedData(typedData) {
     const parsed = parseTypedDataJson(typedData);
@@ -1856,7 +1979,14 @@ function prepareTypedData(input) {
     EIP712Domain: EIP712_DOMAIN_FIELDS.filter(([name]) => domain[name] != null).map(
       ([name, type]) => ({ name, type })
     ),
-    ...structs
+    // Each field as ethers hashes it, name and type: any other key (a wide
+    // number in it is a bigint) never reaches OWS or JSON.stringify.
+    ...Object.fromEntries(
+      Object.entries(structs).map(([struct, fields]) => [
+        struct,
+        fields.map(({ name, type }) => ({ name, type }))
+      ])
+    )
   };
   const owsDomain = owsValue("EIP712Domain", domain, all, "domain");
   const owsMessage = owsValue(root, message, all, "message");
@@ -1988,7 +2118,7 @@ var OWSWalletAdapter = class {
   async signTypedData(typedData) {
     let parsed;
     try {
-      parsed = JSON.parse(typedData);
+      parsed = parseJsonExact(typedData);
     } catch {
       throw refuse("typedData is not a JSON string");
     }