@x402x/extensions 2.3.0 → 2.3.1

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-import { Network, PaymentRequirements, ResourceServerExtension, SchemeNetworkFacilitator, PaymentPayload, SchemeNetworkClient } from '@x402/core/types';
+import { Network, PaymentRequirements, ResourceServerExtension, SchemeNetworkFacilitator, PaymentPayload } from '@x402/core/types';
 export { Network, PaymentPayload, PaymentRequirements } from '@x402/core/types';
 import { Chain, Address as Address$1 } from 'viem';
 import { x402ResourceServer } from '@x402/core/server';
-import { x402Client } from '@x402/core/client';
+export { ClientEvmSigner, ExactEvmSchemeWithRouterSettlement, injectX402xExtensionHandler, registerX402xScheme } from './client/index.js';
+import '@x402/core/client';
 
 /**
  * Type definitions for @x402x/extensions
@@ -1888,183 +1889,4 @@ declare function getNetworkAliasesV1ToV2(): Record<string, Network>;
  */
 declare function toCanonicalNetworkKey(network: string): Network;
 
-/**
- * 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 Address, AmountError, type ClientEvmSigner, type CommitmentParams, type DemoHooks, ExactEvmSchemeWithRouterSettlement, type FacilitatorConfig, type SettleResponse$1 as FacilitatorSettleResponse, FacilitatorValidationError, type VerifyResponse$1 as FacilitatorVerifyResponse, type FeeCalculationResult, type RouteConfig as LegacyRouteConfig, type MintConfig, type Money, NETWORK_ALIASES, NETWORK_ALIASES_V1_TO_V2, NFTMintHook, type NetworkConfig, ROUTER_SETTLEMENT_KEY, type Resource, type RewardConfig, RewardHook, type RoutePattern, type RouterSettlementExtension, type RouterSettlementExtensionInfo, type RoutesConfig, SETTLEMENT_ROUTER_ABI, type SettleResponse, type SettlementExtra, type SettlementExtraCore, SettlementExtraError, type SettlementHooksConfig, type SettlementOptions, type SettlementPaymentOption, type SettlementRouteConfig, SettlementRouterError, type SettlementRouterParams, type Signer, TransferHook, type ValidationResult, type VerifyResponse, type WithRouterSettlementOptions, addSettlementExtra, assertValidSettlementExtra, calculateCommitment, calculateFacilitatorFee, clearFeeCache, computeRoutePatterns, createExtensionDeclaration, createRouterSettlementExtension, createSettlementRouteConfig, createX402xFacilitator, findMatchingPaymentRequirements, findMatchingRoute, formatDefaultAssetAmount, generateSalt, getChain, getChainById, getCustomChains, getDefaultAsset, getNetworkAlias, getNetworkAliasesV1ToV2, getNetworkConfig, getRouterSettlementExtensionKey, getSupportedNetworkAliases, getSupportedNetworkIds, getSupportedNetworks, injectX402xExtensionHandler, isCustomChain, isNetworkSupported, isRouterSettlement, isSettlementMode, isValid32ByteHex, isValidAddress, isValidHex, isValidNumericString, networks, parseDefaultAssetAmount, parseSettlementExtra, processPriceToAtomicAmount, registerRouterSettlement, registerSettlementHooks, registerX402xScheme, routerSettlementServerExtension, settle, toCanonicalNetworkKey, toJsonSafe, validateCommitmentParams, validateSettlementExtra, verify, withRouterSettlement };
+export { type Address, AmountError, type CommitmentParams, type DemoHooks, type FacilitatorConfig, type SettleResponse$1 as FacilitatorSettleResponse, FacilitatorValidationError, type VerifyResponse$1 as FacilitatorVerifyResponse, type FeeCalculationResult, type RouteConfig as LegacyRouteConfig, type MintConfig, type Money, NETWORK_ALIASES, NETWORK_ALIASES_V1_TO_V2, NFTMintHook, type NetworkConfig, ROUTER_SETTLEMENT_KEY, type Resource, type RewardConfig, RewardHook, type RoutePattern, type RouterSettlementExtension, type RouterSettlementExtensionInfo, type RoutesConfig, SETTLEMENT_ROUTER_ABI, type SettleResponse, type SettlementExtra, type SettlementExtraCore, SettlementExtraError, type SettlementHooksConfig, type SettlementOptions, type SettlementPaymentOption, type SettlementRouteConfig, SettlementRouterError, type SettlementRouterParams, type Signer, TransferHook, type ValidationResult, type VerifyResponse, type WithRouterSettlementOptions, addSettlementExtra, assertValidSettlementExtra, calculateCommitment, calculateFacilitatorFee, clearFeeCache, computeRoutePatterns, createExtensionDeclaration, createRouterSettlementExtension, createSettlementRouteConfig, createX402xFacilitator, findMatchingPaymentRequirements, findMatchingRoute, formatDefaultAssetAmount, generateSalt, getChain, getChainById, getCustomChains, getDefaultAsset, getNetworkAlias, getNetworkAliasesV1ToV2, getNetworkConfig, getRouterSettlementExtensionKey, getSupportedNetworkAliases, getSupportedNetworkIds, getSupportedNetworks, isCustomChain, isNetworkSupported, isRouterSettlement, isSettlementMode, isValid32ByteHex, isValidAddress, isValidHex, isValidNumericString, networks, parseDefaultAssetAmount, parseSettlementExtra, processPriceToAtomicAmount, registerRouterSettlement, registerSettlementHooks, routerSettlementServerExtension, settle, toCanonicalNetworkKey, toJsonSafe, validateCommitmentParams, validateSettlementExtra, verify, withRouterSettlement };

package/dist/index.js

@@ -771,6 +771,28 @@ exports.RewardHook = void 0;
 })(exports.RewardHook || (exports.RewardHook = {}));
 
 // src/validation.ts
+function validateX402Version(version) {
+  if (typeof version === "number" && version === 2) {
+    return;
+  }
+  const baseMessage = "x402Version is required and must be 2. v1 is deprecated - please use x402Version=2. See https://github.com/nuwa-protocol/x402-exec for migration guide.";
+  if (version === void 0 || version === null) {
+    throw new Error(baseMessage);
+  }
+  if (typeof version !== "number") {
+    throw new Error(
+      `Invalid x402Version: expected number, got ${typeof version}. ${baseMessage}`
+    );
+  }
+  if (version === 1) {
+    throw new Error(
+      "x402Version 1 is deprecated. Please use x402Version=2. See https://github.com/nuwa-protocol/x402-exec for migration guide."
+    );
+  }
+  throw new Error(
+    `Version not supported: x402Version ${version} is not supported. Please use x402Version=2. See https://github.com/nuwa-protocol/x402-exec for migration guide.`
+  );
+}
 function isValidAddress2(address) {
   return /^0x[a-fA-F0-9]{40}$/.test(address);
 }
@@ -1076,7 +1098,9 @@ async function verify(facilitatorUrl, paymentPayload, paymentRequirements) {
       },
       body: JSON.stringify({
         paymentPayload,
-        paymentRequirements
+        paymentRequirements,
+        x402Version: paymentPayload.x402Version
+        // Include x402Version at top level
       }),
       // Add timeout
       signal: AbortSignal.timeout(1e4)
@@ -1115,7 +1139,9 @@ async function settle(facilitatorUrl, paymentPayload, paymentRequirements, timeo
       },
       body: JSON.stringify({
         paymentPayload,
-        paymentRequirements
+        paymentRequirements,
+        x402Version: paymentPayload.x402Version
+        // Include x402Version at top level
       }),
       signal: controller.signal
     });
@@ -1290,6 +1316,7 @@ function registerSettlementHooks(server, config = {}) {
   if (enableSaltExtraction) {
     server.onBeforeVerify(async (context) => {
       const { paymentPayload, requirements } = context;
+      validateX402Version(paymentPayload.x402Version);
       if (paymentPayload.extensions && "x402x-router-settlement" in paymentPayload.extensions) {
         const extension = paymentPayload.extensions["x402x-router-settlement"];
         if (extension?.info) {
@@ -1313,6 +1340,7 @@ function registerSettlementHooks(server, config = {}) {
   if (validateSettlementParams) {
     server.onBeforeSettle(async (context) => {
       const { paymentPayload, requirements } = context;
+      validateX402Version(paymentPayload.x402Version);
       let settlementParams = {};
       if (paymentPayload.extensions && "x402x-router-settlement" in paymentPayload.extensions) {
         const extension = paymentPayload.extensions["x402x-router-settlement"];