@payai/x402-evm 2.4.0 → 2.4.2

package/dist/esm/batch-settlement/client/index.d.mts

@@ -0,0 +1,111 @@
+import { a as BatchSettlementClientDeps } from '../../scheme-DtbSS4Fk.mjs';
+export { b as BatchSettlementDepositPolicy, c as BatchSettlementDepositStrategy, d as BatchSettlementDepositStrategyContext, e as BatchSettlementDepositStrategyResult, B as BatchSettlementEvmScheme, f as BatchSettlementEvmSchemeOptions, R as RefundOptions, j as ResolvedClientOptions, k as buildChannelConfig, g as depositAmountForRequest, l as getChannel, m as hasChannel, i as isBatchSettlementEvmSchemeOptions, p as processPaymentResponse, n as processSettleResponse, o as readChannelBalanceAndTotalClaimed, q as recoverChannel, r as refundChannel, h as resolveClientOptions, u as updateChannelAfterRefund, v as validateDepositPolicy } from '../../scheme-DtbSS4Fk.mjs';
+export { B as BatchSettlementClientContext, C as ClientChannelStorage, I as InMemoryClientChannelStorage } from '../../storage-6W5MO46W.mjs';
+import { PaymentRequirements, PaymentPayloadResult, SchemeClientHooks, PaymentRequired } from '@payai/x402/types';
+import { C as ClientEvmSigner } from '../../signer-tYS6Y46X.mjs';
+import { C as ChannelConfig, d as BatchSettlementVoucherFields, t as BatchSettlementChannelStateExtra, u as BatchSettlementVoucherStateExtra } from '../../types-CF8P2-NM.mjs';
+import { PaymentResponseContext } from '@payai/x402/client';
+import '../../rpc-DULZzRne.mjs';
+import 'viem';
+
+/**
+ * Computes the chain-bound channel id from a {@link ChannelConfig} struct.
+ *
+ * @param config - The immutable channel configuration.
+ * @param networkOrChainId - CAIP-2 network identifier or numeric EVM chain id.
+ * @returns The `bytes32` channel id as a hex string.
+ */
+declare function computeChannelId(config: ChannelConfig, networkOrChainId: string | number): `0x${string}`;
+
+/**
+ * Creates a deposit payload that bundles an ERC-3009 `receiveWithAuthorization` approval
+ * together with a cumulative voucher signature.
+ *
+ * When the facilitator submits this payload onchain, the contract atomically transfers
+ * tokens from the payer into the channel and records the initial voucher.
+ *
+ * @param signer - Client wallet used to sign the ERC-3009 authorization (`from` = payer).
+ * @param x402Version - Protocol version to embed in the payload envelope.
+ * @param paymentRequirements - Server-provided payment requirements (asset, network, amount, etc.).
+ * @param channelConfig - Immutable channel configuration (payer, receiver, token, …).
+ * @param depositAmount - Number of tokens (decimal string) to deposit into the channel.
+ * @param maxClaimableAmount - Cumulative ceiling for the accompanying voucher.
+ * @param voucherSigner - Optional key that signs the voucher; defaults to `signer` (same as payer).
+ * @returns A {@link PaymentPayloadResult} containing the signed deposit + voucher payload.
+ */
+declare function createBatchSettlementEIP3009DepositPayload(signer: ClientEvmSigner, x402Version: number, paymentRequirements: PaymentRequirements, channelConfig: ChannelConfig, depositAmount: string, maxClaimableAmount: string, voucherSigner?: ClientEvmSigner): Promise<PaymentPayloadResult>;
+
+/**
+ * Signs a cumulative voucher using the client's wallet.
+ *
+ * The voucher authorises the receiver to claim up to `maxClaimableAmount` from the
+ * channel identified by `channelId`.  The signature covers the EIP-712 `Voucher` struct
+ * under the batched domain.
+ *
+ * @param signer - Client wallet used to produce the EIP-712 signature.
+ * @param channelId - Identifier of the payment channel. This is the EIP-712
+ * hash of the `ChannelConfig` typed data for the batch settlement domain; see
+ * `computeChannelId`.
+ * @param maxClaimableAmount - Cumulative ceiling the receiver may claim (decimal string in token units).
+ * @param network - CAIP-2 network identifier (e.g. `eip155:84532`).
+ * @returns Signed voucher fields ready to be included in a payment payload.
+ */
+declare function signVoucher(signer: ClientEvmSigner, channelId: `0x${string}`, maxClaimableAmount: string, network: string): Promise<BatchSettlementVoucherFields>;
+
+/**
+ * Creates storage-aware client hooks for batch-settlement payment responses.
+ *
+ * @param deps - Client identity and storage inputs.
+ * @returns Scheme hooks for response reconciliation and corrective recovery.
+ */
+declare function createBatchSettlementClientHooks(deps: BatchSettlementClientDeps): SchemeClientHooks;
+/**
+ * Reconciles batch-settlement client state after a paid request or refund attempt.
+ *
+ * @param deps - Client identity and storage inputs.
+ * @param ctx - Core payment response context.
+ * @returns A recovery signal when corrective recovery succeeds.
+ */
+declare function handleBatchSettlementPaymentResponse(deps: BatchSettlementClientDeps, ctx: PaymentResponseContext): Promise<void | {
+    recovered: true;
+}>;
+
+/**
+ * Handles a corrective 402 response from the server when the client's
+ * cumulative base is out of sync.
+ *
+ * Validates the server-provided state (chargedCumulativeAmount,
+ * signedMaxClaimable, signature) against onchain data and the client's own
+ * signing key, then updates the local channel state if everything checks out.
+ *
+ * @param deps - Signer + storage + identity inputs.
+ * @param paymentRequired - The decoded 402 response body.
+ * @returns `true` if the channel state was successfully resynced and the request can be retried.
+ */
+declare function processCorrectivePaymentRequired(deps: BatchSettlementClientDeps, paymentRequired: PaymentRequired): Promise<boolean>;
+/**
+ * Recovers channel state from a corrective 402 that includes a server-provided
+ * voucher signature. Verifies the signature matches the client's own signing
+ * key before accepting.
+ *
+ * @param deps - Signer + storage + identity inputs.
+ * @param accept - Batch settlement payment requirements from the corrective 402.
+ * @param channelState - Server channel snapshot from `accept.extra.channelState`.
+ * @param voucherState - Latest signed voucher proof from `accept.extra.voucherState`.
+ * @returns `true` when local channel state was updated successfully.
+ */
+declare function recoverFromSignature(deps: BatchSettlementClientDeps, accept: PaymentRequirements, channelState: BatchSettlementChannelStateExtra, voucherState: BatchSettlementVoucherStateExtra): Promise<boolean>;
+/**
+ * Recovers channel state purely from onchain state when the server has no stored
+ * voucher (e.g. after a cooperative refund deleted the channel record). The onchain
+ * `totalClaimed` becomes the new baseline — no signature verification is
+ * needed because the contract is the source of truth when no outstanding
+ * voucher exists.
+ *
+ * @param deps - Signer + storage + identity inputs.
+ * @param accept - Batch settlement payment requirements from the corrective 402.
+ * @returns `true` when local channel state was updated from onchain data.
+ */
+declare function recoverFromOnChainState(deps: BatchSettlementClientDeps, accept: PaymentRequirements): Promise<boolean>;
+
+export { BatchSettlementClientDeps, computeChannelId, createBatchSettlementClientHooks, createBatchSettlementEIP3009DepositPayload, handleBatchSettlementPaymentResponse, processCorrectivePaymentRequired, recoverFromOnChainState, recoverFromSignature, signVoucher };

package/dist/esm/batch-settlement/client/index.mjs

@@ -0,0 +1,59 @@
+import {
+  BatchSettlementEvmScheme,
+  InMemoryClientChannelStorage,
+  buildChannelConfig,
+  createBatchSettlementClientHooks,
+  createBatchSettlementEIP3009DepositPayload,
+  depositAmountForRequest,
+  getChannel,
+  handleBatchSettlementPaymentResponse,
+  hasChannel,
+  isBatchSettlementEvmSchemeOptions,
+  processCorrectivePaymentRequired,
+  processPaymentResponse,
+  processSettleResponse,
+  readChannelBalanceAndTotalClaimed,
+  recoverChannel,
+  recoverFromOnChainState,
+  recoverFromSignature,
+  refundChannel,
+  resolveClientOptions,
+  signVoucher,
+  updateChannelAfterRefund,
+  validateDepositPolicy
+} from "../../chunk-NKYVYGRA.mjs";
+import "../../chunk-W6ON4LG2.mjs";
+import {
+  computeChannelId
+} from "../../chunk-HYABYUBD.mjs";
+import "../../chunk-U4HCGTLU.mjs";
+import "../../chunk-YMQCTKDU.mjs";
+import "../../chunk-GD4MKCN7.mjs";
+import "../../chunk-MACPBXCT.mjs";
+import "../../chunk-TW7Z65AO.mjs";
+export {
+  BatchSettlementEvmScheme,
+  InMemoryClientChannelStorage,
+  buildChannelConfig,
+  computeChannelId,
+  createBatchSettlementClientHooks,
+  createBatchSettlementEIP3009DepositPayload,
+  depositAmountForRequest,
+  getChannel,
+  handleBatchSettlementPaymentResponse,
+  hasChannel,
+  isBatchSettlementEvmSchemeOptions,
+  processCorrectivePaymentRequired,
+  processPaymentResponse,
+  processSettleResponse,
+  readChannelBalanceAndTotalClaimed,
+  recoverChannel,
+  recoverFromOnChainState,
+  recoverFromSignature,
+  refundChannel,
+  resolveClientOptions,
+  signVoucher,
+  updateChannelAfterRefund,
+  validateDepositPolicy
+};
+//# sourceMappingURL=index.mjs.map

package/dist/esm/batch-settlement/client/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/esm/batch-settlement/facilitator/index.d.mts

@@ -0,0 +1,71 @@
+import { SchemeNetworkFacilitator, PaymentPayload, PaymentRequirements, FacilitatorContext, VerifyResponse, SettleResponse } from '@payai/x402/types';
+import { F as FacilitatorEvmSigner } from '../../signer-tYS6Y46X.mjs';
+import { A as AuthorizerSigner } from '../../types-CF8P2-NM.mjs';
+import 'viem';
+
+/**
+ * Facilitator-side implementation of the `batch-settlement` scheme for EVM networks.
+ *
+ * Routes incoming verify/settle requests to the appropriate handler based on payload
+ * type (deposit, voucher, claim, settle, refund).
+ */
+declare class BatchSettlementEvmScheme implements SchemeNetworkFacilitator {
+    private readonly signer;
+    private readonly authorizerSigner;
+    readonly scheme: "batch-settlement";
+    readonly caipFamily = "eip155:*";
+    /**
+     * Creates a facilitator scheme for verifying and settling batch-settlement payments.
+     *
+     * @param signer - Facilitator EVM signer(s) used for tx submission and onchain reads.
+     * @param authorizerSigner - Dedicated key that provides EIP-712 signatures for
+     *   `claimWithSignature` / `refundWithSignature`.  The facilitator will sign missing
+     *   authorizer signatures using this key when the server omits them.
+     */
+    constructor(signer: FacilitatorEvmSigner, authorizerSigner: AuthorizerSigner);
+    /**
+     * Returns facilitator-specific extra fields to be merged into payment requirements.
+     *
+     * Exposes the configured `receiverAuthorizer` address so the server and client can
+     * embed it in `ChannelConfig`.
+     *
+     * @param _ - Network identifier (unused).
+     * @returns Extra fields containing `receiverAuthorizer`.
+     */
+    getExtra(_: string): {
+        receiverAuthorizer: `0x${string}`;
+    } | undefined;
+    /**
+     * Returns all facilitator signer addresses available for the given network.
+     *
+     * @param _ - Network identifier (unused).
+     * @returns Array of hex addresses.
+     */
+    getSigners(_: string): `0x${string}`[];
+    /**
+     * Verifies a payment payload (deposit or voucher) without executing settlement.
+     *
+     * @param payload - The x402 payment payload envelope.
+     * @param requirements - Server payment requirements (scheme, network, asset, amount).
+     * @param context - Optional facilitator extension context.
+     * @returns A {@link VerifyResponse} indicating validity with payer and channel state in `extra`.
+     */
+    verify(payload: PaymentPayload, requirements: PaymentRequirements, context?: FacilitatorContext): Promise<VerifyResponse>;
+    /**
+     * Executes settlement for a payment payload.
+     *
+     * Dispatches to the correct handler based on payload settle action:
+     * - `deposit` → onchain `deposit(config, amount, collector, collectorData)`
+     * - `claim` → onchain `claimWithSignature(VoucherClaim[], bytes)`
+     * - `settle` → onchain `settle(receiver, token)`
+     * - `refund` → optional claim + onchain `refundWithSignature(config, amount, nonce, sig)`
+     *
+     * @param payload - The x402 payment payload envelope.
+     * @param requirements - Server payment requirements.
+     * @param context - Optional facilitator extension context.
+     * @returns A {@link SettleResponse} with the transaction hash on success.
+     */
+    settle(payload: PaymentPayload, requirements: PaymentRequirements, context?: FacilitatorContext): Promise<SettleResponse>;
+}
+
+export { BatchSettlementEvmScheme };