@x402x/extensions 2.3.0 → 2.4.0

package/dist/client/index.d.mts

@@ -0,0 +1,183 @@
+import { SchemeNetworkClient, PaymentRequirements, PaymentPayload, Network } from '@x402/core/types';
+import { x402Client } from '@x402/core/client';
+
+/**
+ * x402x EVM Client Scheme with Router Settlement
+ *
+ * This scheme extends the standard EVM exact scheme to support x402x router settlement.
+ * The key difference is using a commitment hash (binding all settlement parameters)
+ * as the EIP-3009 nonce instead of a random value.
+ */
+
+/**
+ * Client EVM signer interface
+ * Compatible with viem WalletClient and LocalAccount
+ */
+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}`>;
+};
+/**
+ * EVM client implementation for the Exact payment scheme with x402x router settlement.
+ *
+ * This scheme uses a commitment hash as the EIP-3009 nonce to cryptographically bind
+ * all settlement parameters (salt, hook, hookData, etc.) to the user's signature,
+ * preventing parameter tampering attacks.
+ *
+ * @example
+ * ```typescript
+ * import { ExactEvmSchemeWithRouterSettlement } from '@x402x/extensions/client';
+ * import { x402Client } from '@x402/core/client';
+ *
+ * const signer = { address, signTypedData }; // viem WalletClient or LocalAccount
+ * const scheme = new ExactEvmSchemeWithRouterSettlement(signer);
+ *
+ * const client = new x402Client()
+ *   .register('eip155:84532', scheme);
+ * ```
+ */
+declare class ExactEvmSchemeWithRouterSettlement implements SchemeNetworkClient {
+    private readonly signer;
+    readonly scheme = "exact";
+    /**
+     * Per-request router settlement extension (typically sourced from PaymentRequired.extensions).
+     *
+     * IMPORTANT: We do NOT put this on `paymentRequirements.extra`, because for x402 v2 the
+     * server matches paid requests by deep-equality between `paymentPayload.accepted` and the
+     * server-side `accepts[]`. Mutating `accepted` will cause "No matching payment requirements".
+     */
+    private routerSettlementFromPaymentRequired?;
+    /**
+     * Creates a new ExactEvmSchemeWithRouterSettlement instance.
+     *
+     * @param signer - The EVM signer for client operations (viem WalletClient or LocalAccount)
+     */
+    constructor(signer: ClientEvmSigner);
+    /**
+     * Set router-settlement extension data for the next payment payload creation.
+     *
+     * Intended to be called from an `x402Client.onBeforePaymentCreation` hook, which has access
+     * to `paymentRequired.extensions`.
+     */
+    setRouterSettlementExtensionFromPaymentRequired(ext: unknown | undefined): void;
+    /**
+     * Creates a payment payload for the Exact scheme with router settlement.
+     *
+     * This method:
+     * 1. Extracts settlement parameters from PaymentRequired.extensions
+     * 2. Calculates a commitment hash binding all parameters
+     * 3. Uses the commitment as the EIP-3009 nonce
+     * 4. Signs with settlementRouter as the 'to' address
+     *
+     * @param x402Version - The x402 protocol version (must be 2)
+     * @param paymentRequirements - The payment requirements from the server
+     * @returns Promise resolving to a payment payload
+     *
+     * @throws Error if x402Version is not 2
+     * @throws Error if x402x-router-settlement extension is missing
+     * @throws Error if required settlement parameters are missing
+     */
+    createPaymentPayload(x402Version: number, paymentRequirements: PaymentRequirements): Promise<Pick<PaymentPayload, "x402Version" | "payload">>;
+    /**
+     * Sign the EIP-3009 authorization using EIP-712
+     *
+     * @param authorization - The authorization to sign
+     * @param requirements - The payment requirements
+     * @param chainId - The chain ID
+     * @returns Promise resolving to the signature
+     */
+    private signAuthorization;
+}
+
+/**
+ * x402x Extension Handler
+ *
+ * Provides utilities to integrate x402x router settlement with official x402 SDK.
+ *
+ * The challenge: x402 v2 spec places extensions at root level in PaymentRequired,
+ * but x402x scheme needs settlement parameters from PaymentRequirements.extra.
+ *
+ * Solution: Provide two-layer API:
+ * 1. High-level: registerX402xScheme() - one line setup (recommended)
+ * 2. Low-level: injectX402xExtensionHandler() - flexible configuration
+ */
+
+/**
+ * Injects x402x extension handler into x402Client (Low-level API).
+ *
+ * IMPORTANT (x402 v2 + x402x multi-network):
+ * - Server returns per-option x402x info in `accepts[i].extra["x402x-router-settlement"]`
+ * - x402Client only passes `PaymentRequirements` to scheme (no root extensions)
+ * - Facilitator v2 reads from `paymentPayload.extensions["x402x-router-settlement"]`
+ *
+ * Solution: Copy the selected option's x402x info from `selectedRequirements.extra`
+ * into `paymentRequired.extensions` so it gets included in `paymentPayload.extensions`.
+ *
+ * This does NOT mutate `selectedRequirements` (which becomes `paymentPayload.accepted`),
+ * so v2 deepEqual matching still works.
+ *
+ * @param client - x402Client instance to inject handler into
+ * @param onRouterSettlementExtension - Callback to receive the per-request extension object
+ * @returns The same client instance for chaining
+ *
+ * @example Low-level API (for advanced users)
+ * ```typescript
+ * import { x402Client } from '@x402/core/client';
+ * import {
+ *   injectX402xExtensionHandler,
+ *   ExactEvmSchemeWithRouterSettlement
+ * } from '@x402x/extensions';
+ *
+ * const client = new x402Client();
+ * const scheme = new ExactEvmSchemeWithRouterSettlement(signer);
+ * injectX402xExtensionHandler(client, (ext) => scheme.setRouterSettlementExtensionFromPaymentRequired(ext))
+ *   .register('eip155:84532', scheme);
+ * ```
+ */
+declare function injectX402xExtensionHandler(client: x402Client, onRouterSettlementExtension?: (extension: unknown | undefined) => void): x402Client;
+/**
+ * Register x402x router settlement scheme with automatic extension handling (High-level API).
+ *
+ * This is the recommended way to set up x402x payments. It combines:
+ * 1. Extension handler injection (injectX402xExtensionHandler)
+ * 2. Scheme registration (ExactEvmSchemeWithRouterSettlement)
+ *
+ * Use this for the simplest integration - just provide your signer and network.
+ *
+ * @param client - x402Client instance
+ * @param network - Network identifier in CAIP-2 format (e.g., "eip155:84532")
+ * @param signer - EVM signer with address and signTypedData method
+ * @returns The client instance for chaining
+ *
+ * @example High-level API (recommended)
+ * ```typescript
+ * import { x402Client } from '@x402/core/client';
+ * import { registerX402xScheme } from '@x402x/extensions';
+ * import { useWalletClient } from 'wagmi';
+ *
+ * const { data: walletClient } = useWalletClient();
+ *
+ * const client = new x402Client();
+ * registerX402xScheme(client, 'eip155:84532', {
+ *   address: walletClient.account.address,
+ *   signTypedData: walletClient.signTypedData,
+ * });
+ *
+ * // That's it! Client is ready for x402x payments
+ * ```
+ *
+ * @example Multiple networks
+ * ```typescript
+ * const client = new x402Client();
+ * registerX402xScheme(client, 'eip155:84532', signer); // Base Sepolia
+ * registerX402xScheme(client, 'eip155:8453', signer);  // Base Mainnet
+ * ```
+ */
+declare function registerX402xScheme(client: x402Client, network: Network, signer: ClientEvmSigner): x402Client;
+
+export { type ClientEvmSigner, ExactEvmSchemeWithRouterSettlement, injectX402xExtensionHandler, registerX402xScheme };

package/dist/client/index.d.ts

@@ -0,0 +1,183 @@
+import { SchemeNetworkClient, PaymentRequirements, PaymentPayload, Network } from '@x402/core/types';
+import { x402Client } from '@x402/core/client';
+
+/**
+ * x402x EVM Client Scheme with Router Settlement
+ *
+ * This scheme extends the standard EVM exact scheme to support x402x router settlement.
+ * The key difference is using a commitment hash (binding all settlement parameters)
+ * as the EIP-3009 nonce instead of a random value.
+ */
+
+/**
+ * Client EVM signer interface
+ * Compatible with viem WalletClient and LocalAccount
+ */
+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}`>;
+};
+/**
+ * EVM client implementation for the Exact payment scheme with x402x router settlement.
+ *
+ * This scheme uses a commitment hash as the EIP-3009 nonce to cryptographically bind
+ * all settlement parameters (salt, hook, hookData, etc.) to the user's signature,
+ * preventing parameter tampering attacks.
+ *
+ * @example
+ * ```typescript
+ * import { ExactEvmSchemeWithRouterSettlement } from '@x402x/extensions/client';
+ * import { x402Client } from '@x402/core/client';
+ *
+ * const signer = { address, signTypedData }; // viem WalletClient or LocalAccount
+ * const scheme = new ExactEvmSchemeWithRouterSettlement(signer);
+ *
+ * const client = new x402Client()
+ *   .register('eip155:84532', scheme);
+ * ```
+ */
+declare class ExactEvmSchemeWithRouterSettlement implements SchemeNetworkClient {
+    private readonly signer;
+    readonly scheme = "exact";
+    /**
+     * Per-request router settlement extension (typically sourced from PaymentRequired.extensions).
+     *
+     * IMPORTANT: We do NOT put this on `paymentRequirements.extra`, because for x402 v2 the
+     * server matches paid requests by deep-equality between `paymentPayload.accepted` and the
+     * server-side `accepts[]`. Mutating `accepted` will cause "No matching payment requirements".
+     */
+    private routerSettlementFromPaymentRequired?;
+    /**
+     * Creates a new ExactEvmSchemeWithRouterSettlement instance.
+     *
+     * @param signer - The EVM signer for client operations (viem WalletClient or LocalAccount)
+     */
+    constructor(signer: ClientEvmSigner);
+    /**
+     * Set router-settlement extension data for the next payment payload creation.
+     *
+     * Intended to be called from an `x402Client.onBeforePaymentCreation` hook, which has access
+     * to `paymentRequired.extensions`.
+     */
+    setRouterSettlementExtensionFromPaymentRequired(ext: unknown | undefined): void;
+    /**
+     * Creates a payment payload for the Exact scheme with router settlement.
+     *
+     * This method:
+     * 1. Extracts settlement parameters from PaymentRequired.extensions
+     * 2. Calculates a commitment hash binding all parameters
+     * 3. Uses the commitment as the EIP-3009 nonce
+     * 4. Signs with settlementRouter as the 'to' address
+     *
+     * @param x402Version - The x402 protocol version (must be 2)
+     * @param paymentRequirements - The payment requirements from the server
+     * @returns Promise resolving to a payment payload
+     *
+     * @throws Error if x402Version is not 2
+     * @throws Error if x402x-router-settlement extension is missing
+     * @throws Error if required settlement parameters are missing
+     */
+    createPaymentPayload(x402Version: number, paymentRequirements: PaymentRequirements): Promise<Pick<PaymentPayload, "x402Version" | "payload">>;
+    /**
+     * Sign the EIP-3009 authorization using EIP-712
+     *
+     * @param authorization - The authorization to sign
+     * @param requirements - The payment requirements
+     * @param chainId - The chain ID
+     * @returns Promise resolving to the signature
+     */
+    private signAuthorization;
+}
+
+/**
+ * x402x Extension Handler
+ *
+ * Provides utilities to integrate x402x router settlement with official x402 SDK.
+ *
+ * The challenge: x402 v2 spec places extensions at root level in PaymentRequired,
+ * but x402x scheme needs settlement parameters from PaymentRequirements.extra.
+ *
+ * Solution: Provide two-layer API:
+ * 1. High-level: registerX402xScheme() - one line setup (recommended)
+ * 2. Low-level: injectX402xExtensionHandler() - flexible configuration
+ */
+
+/**
+ * Injects x402x extension handler into x402Client (Low-level API).
+ *
+ * IMPORTANT (x402 v2 + x402x multi-network):
+ * - Server returns per-option x402x info in `accepts[i].extra["x402x-router-settlement"]`
+ * - x402Client only passes `PaymentRequirements` to scheme (no root extensions)
+ * - Facilitator v2 reads from `paymentPayload.extensions["x402x-router-settlement"]`
+ *
+ * Solution: Copy the selected option's x402x info from `selectedRequirements.extra`
+ * into `paymentRequired.extensions` so it gets included in `paymentPayload.extensions`.
+ *
+ * This does NOT mutate `selectedRequirements` (which becomes `paymentPayload.accepted`),
+ * so v2 deepEqual matching still works.
+ *
+ * @param client - x402Client instance to inject handler into
+ * @param onRouterSettlementExtension - Callback to receive the per-request extension object
+ * @returns The same client instance for chaining
+ *
+ * @example Low-level API (for advanced users)
+ * ```typescript
+ * import { x402Client } from '@x402/core/client';
+ * import {
+ *   injectX402xExtensionHandler,
+ *   ExactEvmSchemeWithRouterSettlement
+ * } from '@x402x/extensions';
+ *
+ * const client = new x402Client();
+ * const scheme = new ExactEvmSchemeWithRouterSettlement(signer);
+ * injectX402xExtensionHandler(client, (ext) => scheme.setRouterSettlementExtensionFromPaymentRequired(ext))
+ *   .register('eip155:84532', scheme);
+ * ```
+ */
+declare function injectX402xExtensionHandler(client: x402Client, onRouterSettlementExtension?: (extension: unknown | undefined) => void): x402Client;
+/**
+ * Register x402x router settlement scheme with automatic extension handling (High-level API).
+ *
+ * This is the recommended way to set up x402x payments. It combines:
+ * 1. Extension handler injection (injectX402xExtensionHandler)
+ * 2. Scheme registration (ExactEvmSchemeWithRouterSettlement)
+ *
+ * Use this for the simplest integration - just provide your signer and network.
+ *
+ * @param client - x402Client instance
+ * @param network - Network identifier in CAIP-2 format (e.g., "eip155:84532")
+ * @param signer - EVM signer with address and signTypedData method
+ * @returns The client instance for chaining
+ *
+ * @example High-level API (recommended)
+ * ```typescript
+ * import { x402Client } from '@x402/core/client';
+ * import { registerX402xScheme } from '@x402x/extensions';
+ * import { useWalletClient } from 'wagmi';
+ *
+ * const { data: walletClient } = useWalletClient();
+ *
+ * const client = new x402Client();
+ * registerX402xScheme(client, 'eip155:84532', {
+ *   address: walletClient.account.address,
+ *   signTypedData: walletClient.signTypedData,
+ * });
+ *
+ * // That's it! Client is ready for x402x payments
+ * ```
+ *
+ * @example Multiple networks
+ * ```typescript
+ * const client = new x402Client();
+ * registerX402xScheme(client, 'eip155:84532', signer); // Base Sepolia
+ * registerX402xScheme(client, 'eip155:8453', signer);  // Base Mainnet
+ * ```
+ */
+declare function registerX402xScheme(client: x402Client, network: Network, signer: ClientEvmSigner): x402Client;
+
+export { type ClientEvmSigner, ExactEvmSchemeWithRouterSettlement, injectX402xExtensionHandler, registerX402xScheme };

package/dist/client/index.js

@@ -0,0 +1,255 @@
+'use strict';
+
+var viem = require('viem');
+
+// src/client/exact-evm-scheme.ts
+function calculateCommitment(params) {
+  return viem.keccak256(
+    viem.encodePacked(
+      [
+        "string",
+        // Protocol identifier
+        "uint256",
+        // Chain ID
+        "address",
+        // Hub address
+        "address",
+        // Token address
+        "address",
+        // From (payer)
+        "uint256",
+        // Value
+        "uint256",
+        // Valid after
+        "uint256",
+        // Valid before
+        "bytes32",
+        // Salt
+        "address",
+        // Pay to
+        "uint256",
+        // Facilitator fee
+        "address",
+        // Hook
+        "bytes32"
+        // keccak256(hookData)
+      ],
+      [
+        "X402/settle/v1",
+        BigInt(params.chainId),
+        params.hub,
+        params.asset,
+        params.from,
+        BigInt(params.value),
+        BigInt(params.validAfter),
+        BigInt(params.validBefore),
+        params.salt,
+        params.payTo,
+        BigInt(params.facilitatorFee),
+        params.hook,
+        viem.keccak256(params.hookData)
+      ]
+    )
+  );
+}
+
+// src/server-extension.ts
+var ROUTER_SETTLEMENT_KEY = "x402x-router-settlement";
+
+// src/client/exact-evm-scheme.ts
+var authorizationTypes = {
+  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" }
+  ]
+};
+var ExactEvmSchemeWithRouterSettlement = class {
+  /**
+   * Creates a new ExactEvmSchemeWithRouterSettlement instance.
+   *
+   * @param signer - The EVM signer for client operations (viem WalletClient or LocalAccount)
+   */
+  constructor(signer) {
+    this.signer = signer;
+    this.scheme = "exact";
+  }
+  /**
+   * Set router-settlement extension data for the next payment payload creation.
+   *
+   * Intended to be called from an `x402Client.onBeforePaymentCreation` hook, which has access
+   * to `paymentRequired.extensions`.
+   */
+  setRouterSettlementExtensionFromPaymentRequired(ext) {
+    if (!ext) {
+      this.routerSettlementFromPaymentRequired = void 0;
+      return;
+    }
+    this.routerSettlementFromPaymentRequired = ext;
+  }
+  /**
+   * Creates a payment payload for the Exact scheme with router settlement.
+   *
+   * This method:
+   * 1. Extracts settlement parameters from PaymentRequired.extensions
+   * 2. Calculates a commitment hash binding all parameters
+   * 3. Uses the commitment as the EIP-3009 nonce
+   * 4. Signs with settlementRouter as the 'to' address
+   *
+   * @param x402Version - The x402 protocol version (must be 2)
+   * @param paymentRequirements - The payment requirements from the server
+   * @returns Promise resolving to a payment payload
+   *
+   * @throws Error if x402Version is not 2
+   * @throws Error if x402x-router-settlement extension is missing
+   * @throws Error if required settlement parameters are missing
+   */
+  async createPaymentPayload(x402Version, paymentRequirements) {
+    if (x402Version !== 2) {
+      throw new Error(
+        `ExactEvmSchemeWithRouterSettlement only supports x402 version 2, got: ${x402Version}`
+      );
+    }
+    const routerSettlement = paymentRequirements.extra?.[ROUTER_SETTLEMENT_KEY] ?? this.routerSettlementFromPaymentRequired;
+    if (!routerSettlement?.info) {
+      throw new Error(
+        "x402x-router-settlement extension not available for scheme signing. Ensure the resource server includes the extension in PaymentRequired.extensions and the client registered x402x via registerX402xScheme() (or injected the handler)."
+      );
+    }
+    const { salt, settlementRouter, hook, hookData, finalPayTo, facilitatorFee } = routerSettlement.info;
+    this.routerSettlementFromPaymentRequired = void 0;
+    if (!salt) throw new Error("Missing required parameter: salt");
+    if (!settlementRouter) throw new Error("Missing required parameter: settlementRouter");
+    if (!hook) throw new Error("Missing required parameter: hook");
+    if (hookData === void 0) throw new Error("Missing required parameter: hookData");
+    if (!finalPayTo) throw new Error("Missing required parameter: finalPayTo");
+    const resolvedFacilitatorFee = facilitatorFee ?? "0";
+    const chainId = parseInt(paymentRequirements.network.split(":")[1]);
+    if (isNaN(chainId)) {
+      throw new Error(`Invalid network format: ${paymentRequirements.network}`);
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    const validAfter = (now - 600).toString();
+    const validBefore = (now + paymentRequirements.maxTimeoutSeconds).toString();
+    const commitmentParams = {
+      chainId,
+      hub: settlementRouter,
+      asset: paymentRequirements.asset,
+      from: this.signer.address,
+      value: paymentRequirements.amount,
+      validAfter,
+      validBefore,
+      salt,
+      payTo: finalPayTo,
+      facilitatorFee: resolvedFacilitatorFee,
+      hook,
+      hookData
+    };
+    const nonce = calculateCommitment(commitmentParams);
+    const authorization = {
+      from: this.signer.address,
+      to: viem.getAddress(settlementRouter),
+      value: paymentRequirements.amount,
+      validAfter,
+      validBefore,
+      nonce
+    };
+    const signature = await this.signAuthorization(authorization, paymentRequirements, chainId);
+    const payload = {
+      authorization,
+      signature
+    };
+    return {
+      x402Version,
+      payload
+    };
+  }
+  /**
+   * Sign the EIP-3009 authorization using EIP-712
+   *
+   * @param authorization - The authorization to sign
+   * @param requirements - The payment requirements
+   * @param chainId - The chain ID
+   * @returns Promise resolving to the signature
+   */
+  async signAuthorization(authorization, requirements, chainId) {
+    if (!requirements.extra?.name || !requirements.extra?.version) {
+      throw new Error(
+        `EIP-712 domain parameters (name, version) are required in payment requirements for asset ${requirements.asset}`
+      );
+    }
+    const { name, version } = requirements.extra;
+    const domain = {
+      name,
+      version,
+      chainId,
+      verifyingContract: viem.getAddress(requirements.asset)
+    };
+    const message = {
+      from: viem.getAddress(authorization.from),
+      to: viem.getAddress(authorization.to),
+      value: BigInt(authorization.value),
+      validAfter: BigInt(authorization.validAfter),
+      validBefore: BigInt(authorization.validBefore),
+      nonce: authorization.nonce
+    };
+    return await this.signer.signTypedData({
+      domain,
+      types: authorizationTypes,
+      primaryType: "TransferWithAuthorization",
+      message
+    });
+  }
+};
+
+// src/client/extension-handler.ts
+function injectX402xExtensionHandler(client, onRouterSettlementExtension) {
+  return client.onBeforePaymentCreation(async (context) => {
+    const { paymentRequired, selectedRequirements } = context;
+    console.log("[x402x-handler] onBeforePaymentCreation called");
+    console.log("[x402x-handler] selectedRequirements.network:", selectedRequirements.network);
+    console.log(
+      "[x402x-handler] selectedRequirements.extra keys:",
+      Object.keys(selectedRequirements.extra || {})
+    );
+    const perOptionExtension = selectedRequirements.extra?.[ROUTER_SETTLEMENT_KEY];
+    if (perOptionExtension) {
+      if (!paymentRequired.extensions) {
+        paymentRequired.extensions = {};
+      }
+      paymentRequired.extensions[ROUTER_SETTLEMENT_KEY] = perOptionExtension;
+      console.log(
+        "[x402x-handler] \u2705 Copied per-option x402x info into PaymentRequired.extensions"
+      );
+      console.log("[x402x-handler] Extension info:", JSON.stringify(perOptionExtension, null, 2));
+    } else {
+      console.warn(
+        "[x402x-handler] \u26A0\uFE0F No per-option x402x info found in selectedRequirements.extra"
+      );
+      console.warn(
+        "[x402x-handler] This may cause facilitator errors. Check server-side createSettlementRouteConfig."
+      );
+    }
+    if (onRouterSettlementExtension) {
+      const extensionToUse = perOptionExtension || paymentRequired.extensions?.[ROUTER_SETTLEMENT_KEY];
+      onRouterSettlementExtension(extensionToUse);
+    }
+  });
+}
+function registerX402xScheme(client, network, signer) {
+  const scheme = new ExactEvmSchemeWithRouterSettlement(signer);
+  injectX402xExtensionHandler(client, (ext) => {
+    scheme.setRouterSettlementExtensionFromPaymentRequired(ext);
+  });
+  client.register(network, scheme);
+  return client;
+}
+
+exports.ExactEvmSchemeWithRouterSettlement = ExactEvmSchemeWithRouterSettlement;
+exports.injectX402xExtensionHandler = injectX402xExtensionHandler;
+exports.registerX402xScheme = registerX402xScheme;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map