@bankofai/x402-evm 1.0.0-beta.0

package/dist/cjs/signer-BFelv8DL.d.ts

@@ -0,0 +1,170 @@
+import { Log } from 'viem';
+
+/**
+ * ClientEvmSigner - Used by x402 clients to sign payment authorizations.
+ *
+ * Typically a viem WalletClient extended with publicActions:
+ * ```typescript
+ * const client = createWalletClient({
+ *   account: privateKeyToAccount('0x...'),
+ *   chain: baseSepolia,
+ *   transport: http(),
+ * }).extend(publicActions);
+ * ```
+ *
+ * Or composed via `toClientEvmSigner(account, publicClient)`.
+ */
+type ClientEvmSigner = {
+    readonly address: `0x${string}`;
+    signTypedData(message: {
+        domain: Record<string, unknown>;
+        types: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }): Promise<`0x${string}`>;
+    /**
+     * Optional on-chain reads.
+     * Required only for extension enrichment (EIP-2612 / ERC-20 approval).
+     */
+    readContract?(args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args?: readonly unknown[];
+    }): Promise<unknown>;
+    /**
+     * Optional: Signs a raw EIP-1559 transaction without broadcasting.
+     * Required for ERC-20 approval gas sponsoring when the token lacks EIP-2612.
+     */
+    signTransaction?(args: {
+        to: `0x${string}`;
+        data: `0x${string}`;
+        nonce: number;
+        gas: bigint;
+        maxFeePerGas: bigint;
+        maxPriorityFeePerGas: bigint;
+        chainId: number;
+    }): Promise<`0x${string}`>;
+    /**
+     * Optional: Gets the current transaction count (nonce) for an address.
+     * Required for ERC-20 approval gas sponsoring.
+     */
+    getTransactionCount?(args: {
+        address: `0x${string}`;
+    }): Promise<number>;
+    /**
+     * Optional: Estimates current gas fees per gas.
+     * Required for ERC-20 approval gas sponsoring.
+     */
+    estimateFeesPerGas?(): Promise<{
+        maxFeePerGas: bigint;
+        maxPriorityFeePerGas: bigint;
+    }>;
+};
+/**
+ * FacilitatorEvmSigner - Used by x402 facilitators to verify and settle payments
+ * This is typically a viem PublicClient + WalletClient combination that can
+ * read contract state, verify signatures, write transactions, and wait for receipts
+ *
+ * Supports multiple addresses for load balancing, key rotation, and high availability
+ */
+type FacilitatorEvmSigner = {
+    /**
+     * Get all addresses this facilitator can use for signing
+     * Enables dynamic address selection for load balancing and key rotation
+     */
+    getAddresses(): readonly `0x${string}`[];
+    readContract(args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args?: readonly unknown[];
+    }): Promise<unknown>;
+    verifyTypedData(args: {
+        address: `0x${string}`;
+        domain: Record<string, unknown>;
+        types: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+        signature: `0x${string}`;
+    }): Promise<boolean>;
+    writeContract(args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args: readonly unknown[];
+        gas?: bigint;
+        dataSuffix?: `0x${string}`;
+    }): Promise<`0x${string}`>;
+    sendTransaction(args: {
+        to: `0x${string}`;
+        data: `0x${string}`;
+    }): Promise<`0x${string}`>;
+    waitForTransactionReceipt(args: {
+        hash: `0x${string}`;
+    }): Promise<{
+        status: string;
+        logs?: readonly Log[];
+    }>;
+    getCode(args: {
+        address: `0x${string}`;
+    }): Promise<`0x${string}` | undefined>;
+};
+/**
+ * Composes a ClientEvmSigner from a local account and a public client.
+ *
+ * Use this when your signer (e.g., `privateKeyToAccount`) doesn't have
+ * `readContract`. The `publicClient` provides the on-chain read capability.
+ *
+ * Alternatively, use a WalletClient extended with publicActions directly:
+ * ```typescript
+ * const signer = createWalletClient({
+ *   account: privateKeyToAccount('0x...'),
+ *   chain: baseSepolia,
+ *   transport: http(),
+ * }).extend(publicActions);
+ * ```
+ *
+ * @param signer - A signer with `address` and `signTypedData` (and optionally `readContract`)
+ * @param publicClient - A client with optional read/nonce/fee helpers
+ * @param publicClient.readContract - The readContract method from the public client
+ * @param publicClient.getTransactionCount - Optional getTransactionCount for ERC-20 approval
+ * @param publicClient.estimateFeesPerGas - Optional estimateFeesPerGas for ERC-20 approval
+ * @returns A ClientEvmSigner with any available optional capabilities
+ *
+ * @example
+ * ```typescript
+ * const account = privateKeyToAccount("0x...");
+ * const publicClient = createPublicClient({ chain: baseSepolia, transport: http() });
+ * const signer = toClientEvmSigner(account, publicClient);
+ * ```
+ */
+declare function toClientEvmSigner(signer: Omit<ClientEvmSigner, "readContract"> & {
+    readContract?: ClientEvmSigner["readContract"];
+}, publicClient?: {
+    readContract(args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args?: readonly unknown[];
+    }): Promise<unknown>;
+    getTransactionCount?(args: {
+        address: `0x${string}`;
+    }): Promise<number>;
+    estimateFeesPerGas?(): Promise<{
+        maxFeePerGas: bigint;
+        maxPriorityFeePerGas: bigint;
+    }>;
+}): ClientEvmSigner;
+/**
+ * Converts a viem client with single address to a FacilitatorEvmSigner
+ * Wraps the single address in a getAddresses() function for compatibility
+ *
+ * @param client - The client to convert (must have 'address' property)
+ * @returns FacilitatorEvmSigner with getAddresses() support
+ */
+declare function toFacilitatorEvmSigner(client: Omit<FacilitatorEvmSigner, "getAddresses"> & {
+    address: `0x${string}`;
+}): FacilitatorEvmSigner;
+
+export { type ClientEvmSigner as C, type FacilitatorEvmSigner as F, toFacilitatorEvmSigner as a, toClientEvmSigner as t };

package/dist/cjs/storage-6W5MO46W.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Client-side channel fields mirrored from PAYMENT-RESPONSE / recovery flows.
+ */
+interface BatchSettlementClientContext {
+    /** Current cumulative amount charged by the server for this channel */
+    chargedCumulativeAmount?: string;
+    /** Current onchain channel balance */
+    balance?: string;
+    /** Total claimed onchain */
+    totalClaimed?: string;
+    /** Latest client-signed maxClaimableAmount cap (after corrective recovery, optional) */
+    signedMaxClaimable?: string;
+    /** Client voucher signature for {@link signedMaxClaimable} (optional) */
+    signature?: `0x${string}`;
+}
+interface ClientChannelStorage {
+    get(key: string): Promise<BatchSettlementClientContext | undefined>;
+    set(key: string, context: BatchSettlementClientContext): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * Default in-memory {@link ClientChannelStorage} (channel records do not survive process restart).
+ */
+declare class InMemoryClientChannelStorage implements ClientChannelStorage {
+    private readonly channels;
+    /**
+     * Returns the channel record for `key` if present.
+     *
+     * @param key - Channel storage key (channelId).
+     * @returns Persisted context or undefined.
+     */
+    get(key: string): Promise<BatchSettlementClientContext | undefined>;
+    /**
+     * Stores or replaces the channel record for `key`.
+     *
+     * @param key - Channel storage key.
+     * @param context - Channel fields to persist.
+     * @returns Resolves when stored.
+     */
+    set(key: string, context: BatchSettlementClientContext): Promise<void>;
+    /**
+     * Removes the channel record for `key` if it exists.
+     *
+     * @param key - Channel storage key.
+     * @returns Resolves when removed.
+     */
+    delete(key: string): Promise<void>;
+}
+
+export { type BatchSettlementClientContext as B, type ClientChannelStorage as C, InMemoryClientChannelStorage as I };

package/dist/cjs/storage-CHNote8s.d.ts

@@ -0,0 +1,81 @@
+import { C as ChannelConfig } from './types-CKd3Xoi1.js';
+
+interface Channel {
+    channelId: string;
+    channelConfig: ChannelConfig;
+    chargedCumulativeAmount: string;
+    signedMaxClaimable: string;
+    signature: string;
+    balance: string;
+    totalClaimed: string;
+    withdrawRequestedAt: number;
+    refundNonce: number;
+    onchainSyncedAt?: number;
+    lastRequestTimestamp: number;
+    pendingRequest?: PendingRequest;
+}
+interface PendingRequest {
+    pendingId: string;
+    signedMaxClaimable: string;
+    expiresAt: number;
+}
+interface ChannelUpdateResult {
+    channel: Channel | undefined;
+    status: "updated" | "unchanged" | "deleted";
+}
+interface ChannelStorage {
+    get(channelId: string): Promise<Channel | undefined>;
+    list(): Promise<Channel[]>;
+    /**
+     * Atomically inspects and mutates a channel record.
+     *
+     * Implementations must guarantee that no concurrent mutation can interleave between
+     * reading `current` and writing the callback result for all application instances that
+     * share the backend. The in-memory backend only provides this guarantee inside one JS
+     * runtime; production multi-instance deployments need storage with backend-level atomic
+     * conditional mutation, such as Redis/Valkey Lua scripts, SQL transactions, or Durable Objects.
+     *
+     * @param channelId - The channel identifier.
+     * @param update - Mutation callback. Return `undefined` to delete, or `current` to leave unchanged.
+     * @returns The final stored channel and whether storage updated, stayed unchanged, or deleted.
+     */
+    updateChannel(channelId: string, update: (current: Channel | undefined) => Channel | undefined): Promise<ChannelUpdateResult>;
+}
+/**
+ * In-memory {@link ChannelStorage} backed by a Map keyed by `channelId`.
+ */
+declare class InMemoryChannelStorage implements ChannelStorage {
+    private readonly channels;
+    private readonly channelLocks;
+    /**
+     * Returns the channel record for a channel, if present.
+     *
+     * @param channelId - The channel identifier.
+     * @returns The channel record or undefined when not found.
+     */
+    get(channelId: string): Promise<Channel | undefined>;
+    /**
+     * Lists all stored channel records.
+     *
+     * @returns All channel records in storage.
+     */
+    list(): Promise<Channel[]>;
+    /**
+     * Atomically inspects and mutates a channel record while holding a per-channel lock.
+     *
+     * @param channelId - The channel identifier.
+     * @param update - Mutation callback. Return `undefined` to delete, or `current` to leave unchanged.
+     * @returns The final stored channel and whether storage updated, stayed unchanged, or deleted.
+     */
+    updateChannel(channelId: string, update: (current: Channel | undefined) => Channel | undefined): Promise<ChannelUpdateResult>;
+    /**
+     * Runs `fn` after any prior locked work for the same channel key has finished.
+     *
+     * @param key - Lowercased channel id used as the lock key.
+     * @param fn - Async work to run while holding the logical per-channel lock.
+     * @returns The resolved result of `fn`.
+     */
+    private withChannelLock;
+}
+
+export { type ChannelStorage as C, InMemoryChannelStorage as I, type PendingRequest as P, type Channel as a, type ChannelUpdateResult as b };

package/dist/cjs/storage-DjCv5IPh.d.ts

@@ -0,0 +1,81 @@
+import { C as ChannelConfig } from './types-DIt9uAUy.js';
+
+interface Channel {
+    channelId: string;
+    channelConfig: ChannelConfig;
+    chargedCumulativeAmount: string;
+    signedMaxClaimable: string;
+    signature: string;
+    balance: string;
+    totalClaimed: string;
+    withdrawRequestedAt: number;
+    refundNonce: number;
+    onchainSyncedAt?: number;
+    lastRequestTimestamp: number;
+    pendingRequest?: PendingRequest;
+}
+interface PendingRequest {
+    pendingId: string;
+    signedMaxClaimable: string;
+    expiresAt: number;
+}
+interface ChannelUpdateResult {
+    channel: Channel | undefined;
+    status: "updated" | "unchanged" | "deleted";
+}
+interface ChannelStorage {
+    get(channelId: string): Promise<Channel | undefined>;
+    list(): Promise<Channel[]>;
+    /**
+     * Atomically inspects and mutates a channel record.
+     *
+     * Implementations must guarantee that no concurrent mutation can interleave between
+     * reading `current` and writing the callback result for all application instances that
+     * share the backend. The in-memory backend only provides this guarantee inside one JS
+     * runtime; production multi-instance deployments need storage with backend-level atomic
+     * conditional mutation, such as Redis/Valkey Lua scripts, SQL transactions, or Durable Objects.
+     *
+     * @param channelId - The channel identifier.
+     * @param update - Mutation callback. Return `undefined` to delete, or `current` to leave unchanged.
+     * @returns The final stored channel and whether storage updated, stayed unchanged, or deleted.
+     */
+    updateChannel(channelId: string, update: (current: Channel | undefined) => Channel | undefined): Promise<ChannelUpdateResult>;
+}
+/**
+ * In-memory {@link ChannelStorage} backed by a Map keyed by `channelId`.
+ */
+declare class InMemoryChannelStorage implements ChannelStorage {
+    private readonly channels;
+    private readonly channelLocks;
+    /**
+     * Returns the channel record for a channel, if present.
+     *
+     * @param channelId - The channel identifier.
+     * @returns The channel record or undefined when not found.
+     */
+    get(channelId: string): Promise<Channel | undefined>;
+    /**
+     * Lists all stored channel records.
+     *
+     * @returns All channel records in storage.
+     */
+    list(): Promise<Channel[]>;
+    /**
+     * Atomically inspects and mutates a channel record while holding a per-channel lock.
+     *
+     * @param channelId - The channel identifier.
+     * @param update - Mutation callback. Return `undefined` to delete, or `current` to leave unchanged.
+     * @returns The final stored channel and whether storage updated, stayed unchanged, or deleted.
+     */
+    updateChannel(channelId: string, update: (current: Channel | undefined) => Channel | undefined): Promise<ChannelUpdateResult>;
+    /**
+     * Runs `fn` after any prior locked work for the same channel key has finished.
+     *
+     * @param key - Lowercased channel id used as the lock key.
+     * @param fn - Async work to run while holding the logical per-channel lock.
+     * @returns The resolved result of `fn`.
+     */
+    private withChannelLock;
+}
+
+export { type ChannelStorage as C, InMemoryChannelStorage as I, type PendingRequest as P, type Channel as a, type ChannelUpdateResult as b };

package/dist/cjs/types-CKd3Xoi1.d.ts

@@ -0,0 +1,180 @@
+import { TypedData } from 'viem';
+
+interface AuthorizerSigner {
+    address: `0x${string}`;
+    signTypedData(params: {
+        domain: Record<string, unknown>;
+        types: TypedData;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }): Promise<`0x${string}`>;
+}
+type ChannelState = {
+    balance: bigint;
+    totalClaimed: bigint;
+    withdrawRequestedAt: number;
+    refundNonce: bigint;
+};
+type ChannelConfig = {
+    payer: `0x${string}`;
+    payerAuthorizer: `0x${string}`;
+    receiver: `0x${string}`;
+    receiverAuthorizer: `0x${string}`;
+    token: `0x${string}`;
+    withdrawDelay: number;
+    salt: `0x${string}`;
+};
+type BatchSettlementErc3009Authorization = {
+    validAfter: string;
+    validBefore: string;
+    salt: `0x${string}`;
+    signature: `0x${string}`;
+};
+type BatchSettlementPermit2Authorization = {
+    from: `0x${string}`;
+    permitted: {
+        token: `0x${string}`;
+        amount: string;
+    };
+    spender: `0x${string}`;
+    nonce: string;
+    deadline: string;
+    witness: {
+        channelId: `0x${string}`;
+    };
+    signature: `0x${string}`;
+};
+type BatchSettlementAssetTransferMethod = "eip3009" | "permit2";
+type BatchSettlementDepositAuthorization = {
+    erc3009Authorization: BatchSettlementErc3009Authorization;
+    permit2Authorization?: never;
+} | {
+    erc3009Authorization?: never;
+    permit2Authorization: BatchSettlementPermit2Authorization;
+};
+type BatchSettlementDepositPayload = {
+    type: "deposit";
+    channelConfig: ChannelConfig;
+    voucher: BatchSettlementVoucherFields;
+    deposit: {
+        amount: string;
+        authorization: BatchSettlementDepositAuthorization;
+    };
+};
+type BatchSettlementVoucherPayload = {
+    type: "voucher";
+    channelConfig: ChannelConfig;
+    voucher: BatchSettlementVoucherFields;
+};
+type BatchSettlementRefundPayload = {
+    type: "refund";
+    channelConfig: ChannelConfig;
+    voucher: BatchSettlementVoucherFields;
+    amount?: string;
+};
+type BatchSettlementVoucherFields = {
+    channelId: `0x${string}`;
+    maxClaimableAmount: string;
+    signature: `0x${string}`;
+};
+type BatchSettlementVoucherClaim = {
+    voucher: {
+        channel: ChannelConfig;
+        maxClaimableAmount: string;
+    };
+    signature: `0x${string}`;
+    totalClaimed: string;
+};
+type BatchSettlementChannelStateExtra = {
+    channelId: `0x${string}`;
+    balance: string;
+    totalClaimed: string;
+    withdrawRequestedAt: number;
+    refundNonce: string;
+    chargedCumulativeAmount?: string;
+};
+type BatchSettlementVoucherStateExtra = {
+    signedMaxClaimable?: string;
+    signature?: `0x${string}`;
+};
+type BatchSettlementPaymentRequirementsExtra = {
+    receiverAuthorizer: `0x${string}`;
+    withdrawDelay: number;
+    name: string;
+    version: string;
+    assetTransferMethod?: BatchSettlementAssetTransferMethod;
+    channelState?: BatchSettlementChannelStateExtra;
+    voucherState?: BatchSettlementVoucherStateExtra;
+};
+type FileChannelStorageOptions = {
+    /** Root directory; channels are stored under `{directory}/{client|server}/{channelId}.json`. */
+    directory: string;
+};
+type BatchSettlementPaymentResponseExtra = {
+    chargedAmount?: string;
+    channelState?: BatchSettlementChannelStateExtra;
+    voucherState?: BatchSettlementVoucherStateExtra;
+};
+type BatchSettlementClaimPayload = {
+    type: "claim";
+    claims: BatchSettlementVoucherClaim[];
+    claimAuthorizerSignature?: `0x${string}`;
+};
+type BatchSettlementSettlePayload = {
+    type: "settle";
+    receiver: `0x${string}`;
+    token: `0x${string}`;
+};
+type BatchSettlementEnrichedRefundPayload = BatchSettlementRefundPayload & {
+    amount: string;
+    refundNonce: string;
+    claims: BatchSettlementVoucherClaim[];
+    refundAuthorizerSignature?: `0x${string}`;
+    claimAuthorizerSignature?: `0x${string}`;
+};
+type BatchSettlementPayload = BatchSettlementDepositPayload | BatchSettlementVoucherPayload | BatchSettlementRefundPayload;
+type BatchSettlementFacilitatorSettlePayload = BatchSettlementDepositPayload | BatchSettlementClaimPayload | BatchSettlementSettlePayload | BatchSettlementEnrichedRefundPayload;
+/**
+ * Type guard for {@link BatchSettlementDepositPayload}.
+ *
+ * @param payload - Unknown payload to check.
+ * @returns True if `payload` is a deposit payload (carries `deposit` and `voucher`).
+ */
+declare function isBatchSettlementDepositPayload(payload: unknown): payload is BatchSettlementDepositPayload;
+/**
+ * Type guard for {@link BatchSettlementVoucherPayload}.
+ *
+ * @param payload - Unknown payload to check.
+ * @returns True if `payload` is a voucher payload with channel and signature fields.
+ */
+declare function isBatchSettlementVoucherPayload(payload: unknown): payload is BatchSettlementVoucherPayload;
+/**
+ * Type guard for {@link BatchSettlementRefundPayload}.
+ *
+ * @param payload - Unknown payload to check.
+ * @returns True if `payload` is a refund payload with channel config and voucher fields.
+ */
+declare function isBatchSettlementRefundPayload(payload: unknown): payload is BatchSettlementRefundPayload;
+/**
+ * Type guard for {@link BatchSettlementClaimPayload}.
+ *
+ * @param payload - Unknown payload to check.
+ * @returns True if `payload` is a settle-action `claimWithSignature` payload.
+ */
+declare function isBatchSettlementClaimPayload(payload: unknown): payload is BatchSettlementClaimPayload;
+/**
+ * Type guard for {@link BatchSettlementSettlePayload}.
+ *
+ * @param payload - Unknown payload to check.
+ * @returns True if `payload` is a settle-action `settle` payload.
+ */
+declare function isBatchSettlementSettlePayload(payload: unknown): payload is BatchSettlementSettlePayload;
+/**
+ * Type guard for {@link BatchSettlementEnrichedRefundPayload}.
+ *
+ * @param payload - Unknown payload to check.
+ * @returns True if `payload` is a settle-action `refundWithSignature` payload.
+ */
+declare function isBatchSettlementEnrichedRefundPayload(payload: unknown): payload is BatchSettlementEnrichedRefundPayload;
+
+export { type AuthorizerSigner as A, type BatchSettlementVoucherClaim as B, type ChannelConfig as C, type FileChannelStorageOptions as F, type BatchSettlementVoucherFields as a, type BatchSettlementChannelStateExtra as b, type BatchSettlementVoucherStateExtra as c, type BatchSettlementClaimPayload as d, type BatchSettlementDepositPayload as e, type BatchSettlementEnrichedRefundPayload as f, type BatchSettlementErc3009Authorization as g, type BatchSettlementFacilitatorSettlePayload as h, type BatchSettlementPayload as i, type BatchSettlementPaymentRequirementsExtra as j, type BatchSettlementPaymentResponseExtra as k, type BatchSettlementRefundPayload as l, type BatchSettlementSettlePayload as m, type BatchSettlementVoucherPayload as n, type ChannelState as o, isBatchSettlementClaimPayload as p, isBatchSettlementDepositPayload as q, isBatchSettlementEnrichedRefundPayload as r, isBatchSettlementRefundPayload as s, isBatchSettlementSettlePayload as t, isBatchSettlementVoucherPayload as u };