uvd-x402-sdk 2.104.3 → 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/batch-settlement/index.d.mts

@@ -0,0 +1,322 @@
+import { D as DelegationResolver } from '../erc7702-CC-UIL7E.mjs';
+
+/**
+ * uvd-x402-sdk/batch-settlement - x402 `batch-settlement` on EVM, BUYER side.
+ *
+ * The scheme (coinbase/x402, `specs/schemes/batch-settlement/scheme_batch_settlement_evm.md`)
+ * lets a buyer open a payment channel once and pay each later request with an
+ * off-chain voucher. This module is the part a buyer needs, and nothing of the
+ * seller or the facilitator:
+ *
+ * - {@link computeChannelId} - the chain-bound EIP-712 hash of the channel config.
+ * - {@link signVoucher} - the cumulative `Voucher` typed data.
+ * - {@link buildDepositPayload} - ERC-3009 `ReceiveWithAuthorization` to the
+ *   deposit collector + a voucher.
+ * - {@link BatchSettlementClient} - decides deposit vs voucher, keeps the channel
+ *   state, and updates it from the seller's response the way the spec says (from
+ *   its own previous state plus `chargedAmount`, never by copying the seller's
+ *   `channelState`).
+ *
+ * It signs through anything with `signTypedData(typedDataJson)` - the SDK's
+ * `SigningWalletAdapter` (`EnvKeyAdapter`, `OWSWalletAdapter`) or a wrapper over
+ * a remote wallet - so the key never has to be loaded here.
+ *
+ * WHAT IS NOT HERE, on purpose: the Permit2 deposit path
+ * (`assetTransferMethod: "permit2"` throws {@link BatchSettlementError}, it is
+ * never guessed), the cooperative refund, and the corrective-402 resync. USDC
+ * settles through ERC-3009, which is the default the spec names.
+ *
+ * MONEY RULES this module enforces, because a 402 is somebody else's input:
+ *
+ * - A deposit is capped by `maxDeposit` (default 1 USDC in atomic units of the
+ *   asset, i.e. `1_000_000` for a 6-decimals token). A seller whose `minDeposit`
+ *   is above the cap is capped, not obeyed; a deposit the next voucher NEEDS above
+ *   the cap is refused.
+ * - The seller's `extra.minDeposit` is only a target; the amount is never below
+ *   what the next voucher needs.
+ * - Only `eip155:*` networks and only `scheme === "batch-settlement"` are signed.
+ *
+ * Port of `uvd_x402_sdk.batch_settlement` (Python). Keep the two in step: the
+ * golden vectors of `src/batch-settlement.test.ts` are the Python suite's, and a
+ * divergence here is a channel the seller cannot open or a voucher it rejects.
+ *
+ * @example
+ * ```ts
+ * 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'),
+ * });
+ * const prepared = await client.createPayment(accepted, { url });
+ * const res = await fetch(url, { headers: { 'PAYMENT-SIGNATURE': prepared.header() } });
+ * if (res.ok) await client.confirm(prepared, settleResponse.extra);
+ * ```
+ */
+
+declare const SCHEME = "batch-settlement";
+/** Deterministic CREATE2 addresses, the same on every supported EVM chain (spec, "Contract addresses"). */
+declare const BATCH_SETTLEMENT_ADDRESS = "0x4020074e9dF2ce1deE5A9C1b5c3f541D02a10003";
+declare const ERC3009_DEPOSIT_COLLECTOR_ADDRESS = "0x4020806089470a89826cB9fB1f4059150b550004";
+declare const PERMIT2_DEPOSIT_COLLECTOR_ADDRESS = "0x4020425FAf3B746C082C2f942b4E5159887B0005";
+declare const BATCH_SETTLEMENT_DOMAIN_NAME = "x402 Batch Settlement";
+declare const BATCH_SETTLEMENT_DOMAIN_VERSION = "1";
+declare const MIN_WITHDRAW_DELAY = 900;
+declare const MAX_WITHDRAW_DELAY = 2592000;
+declare const ZERO_ADDRESS: string;
+declare const ZERO_BYTES32: string;
+/** Default ceiling for ONE deposit, in atomic units. A 402 must not be able to lock unbounded escrow (spec). */
+declare const DEFAULT_MAX_DEPOSIT = 1000000n;
+/** Used when the seller announces no `minDeposit`: the deposit target is this many requests. */
+declare const DEFAULT_DEPOSIT_MULTIPLIER = 5n;
+type TypedFields = Record<string, Array<{
+    name: string;
+    type: string;
+}>>;
+declare const CHANNEL_CONFIG_TYPES: TypedFields;
+declare const VOUCHER_TYPES: TypedFields;
+declare const RECEIVE_AUTHORIZATION_TYPES: TypedFields;
+/** The 402 or the channel state cannot be signed as asked. Never retried blindly. */
+declare class BatchSettlementError extends Error {
+    constructor(message: string);
+}
+/**
+ * What this module signs with: EIP-712 over the full typed-data JSON string
+ * (`domain`, `types`, `primaryType`, `message`), the contract of
+ * `SigningWalletAdapter.signTypedData`, so `EnvKeyAdapter` and
+ * `OWSWalletAdapter` satisfy it structurally. The address comes from
+ * `getAddress()` or, failing that, `address`.
+ */
+interface BatchSettlementSigner {
+    signTypedData(typedData: string): Promise<{
+        signature: string;
+    } | string>;
+    getAddress?: () => string;
+    address?: string;
+}
+/** The fields of a `batch-settlement` accept this module reads. Other fields travel untouched in `accepted`. */
+interface BatchSettlementRequirements {
+    scheme: string;
+    network: string;
+    amount: string | number | bigint;
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds?: number | string;
+    extra?: unknown;
+}
+interface ChannelConfigFields {
+    payer: string;
+    payerAuthorizer: string;
+    receiver: string;
+    receiverAuthorizer: string;
+    token: string;
+    withdrawDelay: number;
+    salt?: string;
+}
+/** `channelConfig` as it travels in the payload: checksummed addresses, lowercase salt. */
+interface ChannelConfigJSON {
+    payer: string;
+    payerAuthorizer: string;
+    receiver: string;
+    receiverAuthorizer: string;
+    token: string;
+    withdrawDelay: number;
+    salt: string;
+}
+interface SignedVoucher {
+    channelId: string;
+    maxClaimableAmount: string;
+    signature: string;
+}
+interface DepositPayload {
+    type: 'deposit';
+    channelConfig: ChannelConfigJSON;
+    voucher: SignedVoucher;
+    deposit: {
+        amount: string;
+        authorization: {
+            erc3009Authorization: {
+                validAfter: string;
+                validBefore: string;
+                salt: string;
+                signature: string;
+            };
+        };
+    };
+}
+interface VoucherPayload {
+    type: 'voucher';
+    channelConfig: ChannelConfigJSON;
+    voucher: SignedVoucher;
+}
+type BatchSettlementInnerPayload = DepositPayload | VoucherPayload;
+/** The x402 v2 `PaymentPayload` envelope. */
+interface BatchSettlementPaymentPayload {
+    x402Version: 2;
+    resource?: Record<string, unknown>;
+    accepted: BatchSettlementRequirements;
+    payload: BatchSettlementInnerPayload;
+}
+/**
+ * The immutable channel identity. `channelId = EIP712Hash(ChannelConfig)`.
+ *
+ * Addresses are kept as given and checksummed when the config is hashed or
+ * serialized, as the Python SDK's frozen dataclass does.
+ */
+declare class ChannelConfig {
+    readonly payer: string;
+    readonly payerAuthorizer: string;
+    readonly receiver: string;
+    readonly receiverAuthorizer: string;
+    readonly token: string;
+    readonly withdrawDelay: number;
+    readonly salt: string;
+    constructor(fields: ChannelConfigFields);
+    /** The EIP-712 message and the payload's `channelConfig`: one shape for both. */
+    toDict(): ChannelConfigJSON;
+    toJSON(): ChannelConfigJSON;
+}
+declare function batchSettlementDomain(chainId: number): {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: string;
+};
+/** The chain-bound channel id (`0x` + 32 bytes, lowercase): keccak(0x1901 || domainSeparator || structHash). */
+declare function computeChannelId(config: ChannelConfig | ChannelConfigFields, network: string): string;
+/** The ERC-3009 nonce the deposit collector expects: `keccak256(abi.encode(bytes32 channelId, uint256 salt))`. */
+declare function erc3009DepositNonce(channelId: string, salt: string | bigint): string;
+/** Sign a cumulative `Voucher`: the seller may claim up to `maxClaimableAmount` from the channel. */
+declare function signVoucher(wallet: BatchSettlementSigner, channelId: string, maxClaimableAmount: bigint | number | string, network: string): Promise<SignedVoucher>;
+interface BuildDepositOptions {
+    /** Signs the voucher instead of `wallet`; its address must be the config's `payerAuthorizer`. */
+    voucherWallet?: BatchSettlementSigner;
+    /** The deposit's ERC-3009 salt (32-byte hex). Random when omitted. */
+    depositSalt?: string;
+    /** Unix seconds; `validBefore = now + maxTimeoutSeconds`. The clock when omitted. */
+    now?: number;
+    /**
+     * `(address, network) -> target | true | false | null`: pass it when the payer
+     * may be an EIP-7702 delegated account (a Paybox wallet), so the deposit
+     * authorization is wrapped for ERC-1271 when needed. See
+     * {@link signDepositAuthorization}.
+     */
+    delegationResolver?: DelegationResolver;
+}
+/** The inner `payload` of a `deposit`: an ERC-3009 authorization to the collector plus the first voucher. */
+declare function buildDepositPayload(wallet: BatchSettlementSigner, requirements: BatchSettlementRequirements, config: ChannelConfig | ChannelConfigFields, depositAmount: bigint | number | string, maxClaimableAmount: bigint | number | string, options?: BuildDepositOptions): Promise<DepositPayload>;
+/** The inner `payload` of a `voucher`: the next cumulative voucher on an open channel. */
+declare function buildVoucherPayload(wallet: BatchSettlementSigner, config: ChannelConfig | ChannelConfigFields, network: string, maxClaimableAmount: bigint | number | string): Promise<VoucherPayload>;
+/** The x402 v2 `PaymentPayload` envelope around an inner deposit/voucher payload. */
+declare function paymentPayload(requirements: BatchSettlementRequirements, inner: BatchSettlementInnerPayload, resource?: Record<string, unknown>): BatchSettlementPaymentPayload;
+/**
+ * The base64 value for the `PAYMENT-SIGNATURE` request header.
+ *
+ * Byte for byte the Python SDK's `payment_header`: compact JSON with every
+ * character above `~` written as a JSON escape (Python's `json.dumps` with
+ * `ensure_ascii`), so a token named `USD₮0` gives the same header in both SDKs.
+ * The decoded JSON is the same value either way.
+ */
+declare function paymentHeader(payload: BatchSettlementPaymentPayload): string;
+/** What the buyer keeps per channel: decimal strings, `balance` and `chargedCumulativeAmount`. */
+type ChannelState = Record<string, string>;
+/**
+ * Where the buyer keeps its channels. A Fargate task dies between beats: persist
+ * somewhere that lives on. Both methods may return a promise (an S3 or database
+ * store); the client awaits them.
+ */
+interface ChannelStorage {
+    get(channelId: string): ChannelState | null | undefined | Promise<ChannelState | null | undefined>;
+    set(channelId: string, state: ChannelState): void | Promise<void>;
+}
+declare class MemoryChannelStorage implements ChannelStorage {
+    private readonly data;
+    get(channelId: string): ChannelState | undefined;
+    set(channelId: string, state: ChannelState): void;
+}
+/**
+ * One JSON file for all channels, replaced atomically: written to a temporary
+ * file beside it and renamed over it (a half-written file would lose the
+ * cumulative). Node only; `node:fs` is loaded on its first use, not when this
+ * module is imported, so {@link MemoryChannelStorage} works without it.
+ */
+declare class FileChannelStorage implements ChannelStorage {
+    readonly path: string;
+    constructor(path: string);
+    private read;
+    get(channelId: string): Promise<ChannelState | undefined>;
+    set(channelId: string, state: ChannelState): Promise<void>;
+}
+/** What {@link BatchSettlementClient.createPayment} returns: the payload, and what to confirm afterwards. */
+declare class PreparedPayment {
+    readonly payload: BatchSettlementPaymentPayload;
+    readonly channelId: string;
+    readonly requestAmount: bigint;
+    readonly depositAmount: bigint | undefined;
+    constructor(fields: {
+        payload: BatchSettlementPaymentPayload;
+        channelId: string;
+        requestAmount: bigint;
+        depositAmount?: bigint;
+    });
+    header(): string;
+}
+interface BatchSettlementClientOptions {
+    /** Default: a {@link MemoryChannelStorage}, which dies with the process. */
+    storage?: ChannelStorage;
+    /** The channel config's `salt`. Default {@link ZERO_BYTES32}. */
+    salt?: string;
+    /** A second key that signs vouchers; its address becomes the channel's `payerAuthorizer`. */
+    voucherWallet?: BatchSettlementSigner;
+    /** Ceiling for one deposit, in atomic units. Default {@link DEFAULT_MAX_DEPOSIT}. */
+    maxDeposit?: bigint | number | string;
+    /** Deposit target in requests when the seller announces no `minDeposit`. Default {@link DEFAULT_DEPOSIT_MULTIPLIER}. */
+    depositMultiplier?: bigint | number | string;
+    /**
+     * `(address, network) -> target | true | false | null`: pass it when the payer
+     * may be an EIP-7702 delegated account (a Paybox wallet), so the deposit
+     * authorization is wrapped for ERC-1271 when needed. Vouchers are never wrapped.
+     */
+    delegationResolver?: DelegationResolver;
+}
+/** The response fields {@link BatchSettlementClient.confirm} reads: the settle response's `extra`. */
+interface BatchSettlementResponseExtra {
+    chargedAmount?: unknown;
+    channelState?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Signs `batch-settlement` payments for one wallet and keeps its channels' state.
+ *
+ * `wallet` is anything with `getAddress()` (or `address`) and
+ * `signTypedData(typedDataJson)`. `voucherWallet` is an optional second key that
+ * signs vouchers; its address becomes the channel's `payerAuthorizer` so the
+ * seller can verify vouchers without an RPC call.
+ */
+declare class BatchSettlementClient {
+    readonly wallet: BatchSettlementSigner;
+    readonly storage: ChannelStorage;
+    readonly salt: string;
+    readonly voucherWallet: BatchSettlementSigner | undefined;
+    readonly maxDeposit: bigint;
+    readonly depositMultiplier: bigint;
+    readonly delegationResolver: DelegationResolver | undefined;
+    constructor(wallet: BatchSettlementSigner, options?: BatchSettlementClientOptions);
+    channelConfig(requirements: BatchSettlementRequirements): ChannelConfig;
+    private depositAmountFor;
+    /** Sign a deposit (first request or top-up) or a voucher for one paid request. */
+    createPayment(requirements: BatchSettlementRequirements, resource?: Record<string, unknown>, options?: {
+        now?: number;
+    }): Promise<PreparedPayment>;
+    /**
+     * Record a SUCCESSFUL paid response. The new cumulative is the previous one plus `chargedAmount`.
+     *
+     * The seller's `extra.channelState` is untrusted and never copied: it is only
+     * compared with the number the buyer computed itself, and a mismatch leaves the
+     * local state untouched (the next request would then get a corrective 402).
+     * Resolves to whether the state was written.
+     */
+    confirm(prepared: PreparedPayment, responseExtra?: BatchSettlementResponseExtra | null): Promise<boolean>;
+}
+
+export { BATCH_SETTLEMENT_ADDRESS, BATCH_SETTLEMENT_DOMAIN_NAME, BATCH_SETTLEMENT_DOMAIN_VERSION, BatchSettlementClient, type BatchSettlementClientOptions, BatchSettlementError, type BatchSettlementInnerPayload, type BatchSettlementPaymentPayload, type BatchSettlementRequirements, type BatchSettlementResponseExtra, type BatchSettlementSigner, type BuildDepositOptions, CHANNEL_CONFIG_TYPES, ChannelConfig, type ChannelConfigFields, type ChannelConfigJSON, type ChannelState, type ChannelStorage, DEFAULT_DEPOSIT_MULTIPLIER, DEFAULT_MAX_DEPOSIT, type DepositPayload, ERC3009_DEPOSIT_COLLECTOR_ADDRESS, FileChannelStorage, MAX_WITHDRAW_DELAY, MIN_WITHDRAW_DELAY, MemoryChannelStorage, PERMIT2_DEPOSIT_COLLECTOR_ADDRESS, PreparedPayment, RECEIVE_AUTHORIZATION_TYPES, SCHEME, type SignedVoucher, VOUCHER_TYPES, type VoucherPayload, ZERO_ADDRESS, ZERO_BYTES32, batchSettlementDomain, buildDepositPayload, buildVoucherPayload, computeChannelId, erc3009DepositNonce, paymentHeader, paymentPayload, signVoucher };