@x402r/evm 0.0.2 → 0.0.3

package/src/escrow/facilitator/scheme.ts

@@ -0,0 +1,289 @@
+/**
+ * Escrow Scheme - Facilitator
+ * Handles verification and settlement of escrow payments.
+ *
+ * Implements x402's SchemeNetworkFacilitator interface so the escrow scheme
+ * is a drop-in for the x402 facilitator, just like ExactEvmScheme.
+ */
+
+import type {
+  FacilitatorContext,
+  PaymentPayload,
+  PaymentRequirements,
+  SchemeNetworkFacilitator,
+  SettleResponse,
+  VerifyResponse,
+} from '@x402/core/types'
+import type { FacilitatorEvmSigner } from '@x402/evm'
+import { parseErc6492Signature } from 'viem'
+import { OPERATOR_ABI, ERC20_BALANCE_OF_ABI } from '../shared/constants'
+import { verifyERC3009Signature } from '../shared/nonce'
+import { isEscrowPayload, isEscrowExtra } from '../shared/types'
+import type { EscrowExtra, EscrowPayload } from '../shared/types'
+import { parseChainId } from '../shared/utils'
+
+/**
+ * Escrow Facilitator Scheme - implements x402's SchemeNetworkFacilitator
+ *
+ * The facilitator is operator-agnostic: it does not store operator/escrow/tokenCollector
+ * config. Those values are set by the merchant via `refundable()` and arrive in
+ * `requirements.extra` at verify/settle time.
+ */
+export class EscrowFacilitatorScheme implements SchemeNetworkFacilitator {
+  readonly scheme = 'escrow'
+  readonly caipFamily = 'eip155:*'
+
+  constructor(private signer: FacilitatorEvmSigner) {}
+
+  getSigners(_network: string): string[] {
+    return [...this.signer.getAddresses()]
+  }
+
+  // C4: name/version now come from server's parsePrice() via AssetAmount.extra.
+  // The facilitator should not hardcode token-specific metadata.
+  getExtra(_network: string): Record<string, unknown> | undefined {
+    return undefined
+  }
+
+  async verify(
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+    _context?: FacilitatorContext,
+  ): Promise<VerifyResponse> {
+    // M5: Type guard instead of double cast
+    if (!isEscrowPayload(payload.payload)) {
+      return {
+        isValid: false,
+        invalidReason: 'invalid_payload_format',
+      }
+    }
+    const escrowPayload = payload.payload as EscrowPayload
+    const payer = escrowPayload.authorization.from
+
+    // Validate scheme on both payload and requirements
+    if (payload.accepted.scheme !== 'escrow' || requirements.scheme !== 'escrow') {
+      return {
+        isValid: false,
+        invalidReason: 'unsupported_scheme',
+        payer,
+      }
+    }
+
+    // Validate network matches between payload and requirements
+    if (payload.accepted.network !== requirements.network) {
+      return {
+        isValid: false,
+        invalidReason: 'network_mismatch',
+        payer,
+      }
+    }
+
+    // Validate network format
+    const networkParts = requirements.network.split(':')
+    if (networkParts.length !== 2 || networkParts[0] !== 'eip155') {
+      return {
+        isValid: false,
+        invalidReason: 'invalid_network',
+        payer,
+      }
+    }
+
+    // M5: Type guard for extra
+    if (!isEscrowExtra(requirements.extra)) {
+      return {
+        isValid: false,
+        invalidReason: 'invalid_escrow_extra',
+        payer,
+      }
+    }
+    const extra = requirements.extra as EscrowExtra
+    const chainId = parseChainId(requirements.network)
+
+    // Time window validation
+    const now = Math.floor(Date.now() / 1000)
+    const validBefore = Number(escrowPayload.authorization.validBefore)
+    const validAfter = Number(escrowPayload.authorization.validAfter)
+
+    if (validBefore <= now + 6) {
+      return {
+        isValid: false,
+        invalidReason: 'authorization_expired',
+        payer,
+      }
+    }
+
+    if (validAfter > now) {
+      return {
+        isValid: false,
+        invalidReason: 'authorization_not_yet_valid',
+        payer,
+      }
+    }
+
+    // Extract inner signature for verification if EIP-6492 wrapped.
+    // The contract's ERC6492SignatureHandler handles deployment; the facilitator
+    // only needs the inner ECDSA signature for ecrecover verification.
+    const { signature: signatureForVerify } = parseErc6492Signature(escrowPayload.signature)
+
+    // Verify ERC-3009 signature
+    const isValidSignature = await verifyERC3009Signature(
+      this.signer,
+      escrowPayload.authorization,
+      signatureForVerify,
+      { ...extra, chainId },
+      requirements.asset as `0x${string}`,
+    )
+
+    if (!isValidSignature) {
+      return {
+        isValid: false,
+        invalidReason: 'invalid_escrow_signature',
+        payer,
+      }
+    }
+
+    // Verify amount meets requirements
+    if (BigInt(escrowPayload.authorization.value) < BigInt(requirements.amount)) {
+      return {
+        isValid: false,
+        invalidReason: 'insufficient_amount',
+        payer,
+      }
+    }
+
+    // Verify token matches
+    if (escrowPayload.paymentInfo.token.toLowerCase() !== requirements.asset.toLowerCase()) {
+      return {
+        isValid: false,
+        invalidReason: 'token_mismatch',
+        payer,
+      }
+    }
+
+    // Verify receiver matches
+    if (escrowPayload.paymentInfo.receiver.toLowerCase() !== requirements.payTo.toLowerCase()) {
+      return {
+        isValid: false,
+        invalidReason: 'receiver_mismatch',
+        payer,
+      }
+    }
+
+    // H4: Balance check — verify payer has sufficient token balance
+    try {
+      const balance = await this.signer.readContract({
+        address: requirements.asset as `0x${string}`,
+        abi: ERC20_BALANCE_OF_ABI,
+        functionName: 'balanceOf',
+        args: [payer],
+      })
+
+      if (BigInt(balance as string) < BigInt(requirements.amount)) {
+        return {
+          isValid: false,
+          invalidReason: 'insufficient_balance',
+          payer,
+        }
+      }
+    } catch {
+      // If balance check fails (e.g., non-standard token), skip it.
+      // The on-chain transaction will fail anyway if balance is insufficient.
+    }
+
+    return {
+      isValid: true,
+      payer,
+    }
+  }
+
+  async settle(
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+    _context?: FacilitatorContext,
+  ): Promise<SettleResponse> {
+    // H2: Re-verify before settling to catch expired/invalid payloads
+    const verification = await this.verify(payload, requirements)
+    if (!verification.isValid) {
+      return {
+        success: false,
+        errorReason: verification.invalidReason ?? 'verification_failed',
+        transaction: '',
+        network: requirements.network,
+        payer: verification.payer,
+      }
+    }
+
+    const escrowPayload = payload.payload as unknown as EscrowPayload
+    const extra = requirements.extra as unknown as EscrowExtra
+    const { authorizeAddress, operatorAddress, tokenCollector } = extra
+
+    const paymentInfo = {
+      operator: escrowPayload.paymentInfo.operator,
+      payer: escrowPayload.authorization.from,
+      receiver: escrowPayload.paymentInfo.receiver,
+      token: escrowPayload.paymentInfo.token,
+      maxAmount: BigInt(escrowPayload.paymentInfo.maxAmount),
+      preApprovalExpiry: escrowPayload.paymentInfo.preApprovalExpiry,
+      authorizationExpiry: escrowPayload.paymentInfo.authorizationExpiry,
+      refundExpiry: escrowPayload.paymentInfo.refundExpiry,
+      minFeeBps: escrowPayload.paymentInfo.minFeeBps,
+      maxFeeBps: escrowPayload.paymentInfo.maxFeeBps,
+      feeReceiver: escrowPayload.paymentInfo.feeReceiver,
+      salt: BigInt(escrowPayload.paymentInfo.salt),
+    }
+
+    // Pass raw signature — ERC3009PaymentCollector/ERC6492SignatureHandler
+    // handles EIP-6492 unwrapping and wallet deployment on-chain
+    const collectorData = escrowPayload.signature
+
+    const target = authorizeAddress ?? operatorAddress
+
+    try {
+      const txHash = await this.signer.writeContract({
+        address: target,
+        abi: OPERATOR_ABI,
+        functionName: 'authorize',
+        args: [
+          paymentInfo,
+          BigInt(escrowPayload.authorization.value),
+          tokenCollector,
+          collectorData,
+        ],
+      })
+
+      // Wait for transaction confirmation with 60s timeout to avoid hanging on stuck txs
+      const receiptPromise = this.signer.waitForTransactionReceipt({
+        hash: txHash,
+      })
+      const timeoutPromise = new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error('Transaction receipt timeout after 60s')), 60_000),
+      )
+      const receipt = await Promise.race([receiptPromise, timeoutPromise])
+
+      if (receipt.status !== 'success') {
+        return {
+          success: false,
+          errorReason: 'transaction_reverted',
+          transaction: txHash,
+          network: requirements.network,
+          payer: escrowPayload.authorization.from,
+        }
+      }
+
+      return {
+        success: true,
+        transaction: txHash,
+        network: requirements.network,
+        payer: escrowPayload.authorization.from,
+      }
+    } catch (error) {
+      return {
+        success: false,
+        errorReason: error instanceof Error ? error.message : 'Settlement failed',
+        transaction: '',
+        network: requirements.network,
+        payer: escrowPayload.authorization.from,
+      }
+    }
+  }
+}

package/src/escrow/index.ts

@@ -0,0 +1,3 @@
+export { EscrowEvmScheme } from './client/scheme'
+export type { EscrowPayload, EscrowExtra } from './shared/types'
+export { isEscrowPayload, isEscrowExtra } from './shared/types'

package/src/escrow/server/index.ts

@@ -1,261 +1,3 @@
-/**
- * Escrow Scheme - Server
- * Handles price parsing and requirement enhancement for resource servers.
- *
- * Implements x402's SchemeNetworkServer interface so it can be registered
- * on an x402ResourceServer via server.register('eip155:84532', new EscrowServerScheme()).
- */
-
-import type {
-  AssetAmount,
-  MoneyParser,
-  Network,
-  PaymentRequirements,
-  Price,
-  SchemeNetworkServer,
-} from "@x402/core/types";
-import { x402ResourceServer } from "@x402/core/server";
-
-/**
- * Asset info including EIP-712 domain parameters per network
- */
-const ASSET_INFO: Record<
-  string,
-  { address: string; name: string; version: string; decimals: number }
-> = {
-  // Base Sepolia
-  "eip155:84532": {
-    address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
-    name: "USDC",
-    version: "2",
-    decimals: 6,
-  },
-  // Base mainnet
-  "eip155:8453": {
-    address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
-    name: "USD Coin",
-    version: "2",
-    decimals: 6,
-  },
-  // Ethereum Sepolia
-  "eip155:11155111": {
-    address: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
-    name: "USDC",
-    version: "2",
-    decimals: 6,
-  },
-  // Ethereum mainnet
-  "eip155:1": {
-    address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
-    name: "USD Coin",
-    version: "2",
-    decimals: 6,
-  },
-  // Polygon
-  "eip155:137": {
-    address: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
-    name: "USD Coin",
-    version: "2",
-    decimals: 6,
-  },
-  // Arbitrum
-  "eip155:42161": {
-    address: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
-    name: "USD Coin",
-    version: "2",
-    decimals: 6,
-  },
-  // Celo
-  "eip155:42220": {
-    address: "0xcebA9300f2b948710d2653dD7B07f33A8B32118C",
-    name: "USD Coin",
-    version: "2",
-    decimals: 6,
-  },
-  // Monad
-  "eip155:143": {
-    address: "0x754704Bc059F8C67012fEd69BC8A327a5aafb603",
-    name: "USDC",
-    version: "2",
-    decimals: 6,
-  },
-  // Avalanche
-  "eip155:43114": {
-    address: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
-    name: "USD Coin",
-    version: "2",
-    decimals: 6,
-  },
-};
-
-/**
- * Convert decimal amount to token units using string-based conversion
- * (e.g., 0.10 -> 100000 for 6-decimal tokens)
- * Avoids floating-point precision issues from BigInt(Math.round(...))
- */
-function convertToTokenAmount(decimalAmount: string, decimals: number): string {
-  const amount = parseFloat(decimalAmount);
-  if (isNaN(amount)) {
-    throw new Error(`Invalid amount: ${decimalAmount}`);
-  }
-  const [intPart, decPart = ""] = String(amount).split(".");
-  const paddedDec = decPart.padEnd(decimals, "0").slice(0, decimals);
-  const tokenAmount = (intPart + paddedDec).replace(/^0+/, "") || "0";
-  return tokenAmount;
-}
-
-/**
- * Server scheme - handles price parsing and requirement enhancement.
- * Implements x402's SchemeNetworkServer interface.
- */
-export class EscrowServerScheme implements SchemeNetworkServer {
-  readonly scheme = "escrow";
-  private moneyParsers: MoneyParser[] = [];
-
-  /**
-   * Register a custom money parser in the parser chain.
-   * Multiple parsers can be registered — they will be tried in registration order.
-   * Each parser receives a decimal amount (e.g., 1.50 for $1.50).
-   * If a parser returns null, the next parser in the chain will be tried.
-   * The default parser (USDC) is always the final fallback.
-   *
-   * @param parser - Custom function to convert amount to AssetAmount (or null to skip)
-   * @returns The server instance for chaining
-   */
-  registerMoneyParser(parser: MoneyParser): EscrowServerScheme {
-    this.moneyParsers.push(parser);
-    return this;
-  }
-
-  /**
-   * Parse a price into an x402 AssetAmount.
-   *
-   * Accepts x402's Price type:
-   * - string: "$0.01", "0.01", "10000"
-   * - number: 0.01
-   * - AssetAmount: { asset: "0x...", amount: "10000" }
-   */
-  async parsePrice(price: Price, network: Network): Promise<AssetAmount> {
-    // If already an AssetAmount, pass through with validation
-    if (
-      typeof price === "object" &&
-      price !== null &&
-      "amount" in price
-    ) {
-      if (!price.asset) {
-        throw new Error(
-          `Asset address must be specified for AssetAmount on network ${network}`,
-        );
-      }
-      return {
-        amount: price.amount,
-        asset: price.asset,
-        extra: price.extra || {},
-      };
-    }
-
-    // Parse Money to decimal number
-    const numericAmount = this.parseMoneyToDecimal(price);
-
-    // Try each custom money parser in order
-    for (const parser of this.moneyParsers) {
-      const result = await parser(numericAmount, network);
-      if (result !== null) {
-        return result;
-      }
-    }
-
-    // All custom parsers returned null (or none registered), use default conversion
-    return this.defaultMoneyConversion(numericAmount, network);
-  }
-
-  /**
-   * Parse Money (string | number) to a decimal number.
-   */
-  private parseMoneyToDecimal(money: string | number): number {
-    if (typeof money === "number") {
-      return money;
-    }
-    const cleaned = String(money).replace(/[$,]/g, "").trim();
-    const amount = parseFloat(cleaned);
-    if (isNaN(amount)) {
-      throw new Error(`Cannot parse price: ${money}`);
-    }
-    return amount;
-  }
-
-  /**
-   * Default money conversion — converts decimal amount to the default stablecoin on the network.
-   */
-  private defaultMoneyConversion(amount: number, network: Network): AssetAmount {
-    const assetInfo = ASSET_INFO[network];
-    if (!assetInfo) {
-      throw new Error(`No USDC address configured for network: ${network}`);
-    }
-
-    const tokenAmount = convertToTokenAmount(
-      String(amount),
-      assetInfo.decimals,
-    );
-
-    return {
-      asset: assetInfo.address,
-      amount: tokenAmount,
-      extra: {
-        name: assetInfo.name,
-        version: assetInfo.version,
-      },
-    };
-  }
-
-  /**
-   * Enhance payment requirements with facilitator's extra fields.
-   *
-   * Merges supportedKind.extra (from facilitator's /supported endpoint) into
-   * the requirements, so escrow addresses flow from facilitator → merchant
-   * requirements automatically.
-   */
-  async enhancePaymentRequirements(
-    requirements: PaymentRequirements,
-    supportedKind: {
-      x402Version: number;
-      scheme: string;
-      network: Network;
-      extra?: Record<string, unknown>;
-    },
-    _facilitatorExtensions: string[],
-  ): Promise<PaymentRequirements> {
-    return {
-      ...requirements,
-      extra: {
-        ...supportedKind.extra,
-        ...requirements.extra,
-      },
-    };
-  }
-}
-
-/**
- * Register escrow server scheme with x402ResourceServer
- *
- * @example
- * ```typescript
- * const server = new x402ResourceServer(facilitatorConfig);
- * registerEscrowServerScheme(server, { networks: "eip155:84532" });
- * ```
- */
-export function registerEscrowServerScheme(
-  server: x402ResourceServer,
-  config: { networks: Network | Network[] },
-): x402ResourceServer {
-  const scheme = new EscrowServerScheme();
-  const networks = Array.isArray(config.networks)
-    ? config.networks
-    : [config.networks];
-  for (const network of networks) {
-    server.register(network, scheme);
-  }
-  return server;
-}
-
-export type { EscrowExtra, EscrowPayload } from "../../shared/types.js";
+export { EscrowServerScheme } from './scheme'
+export { registerEscrowEvmScheme } from './register'
+export type { EvmResourceServerConfig } from './register'

package/src/escrow/server/register.ts

@@ -0,0 +1,34 @@
+import type { Network } from '@x402/core/types'
+import { x402ResourceServer } from '@x402/core/server'
+import { EscrowServerScheme } from './scheme'
+
+export interface EvmResourceServerConfig {
+  networks?: Network | Network[]
+}
+
+/**
+ * Register escrow server scheme with x402ResourceServer
+ *
+ * @example
+ * ```typescript
+ * const server = new x402ResourceServer(facilitatorConfig);
+ * registerEscrowEvmScheme(server);
+ * // or with specific networks:
+ * registerEscrowEvmScheme(server, { networks: "eip155:84532" });
+ * ```
+ */
+export function registerEscrowEvmScheme(
+  server: x402ResourceServer,
+  config: EvmResourceServerConfig = {},
+): x402ResourceServer {
+  const scheme = new EscrowServerScheme()
+  const networks = config.networks
+    ? Array.isArray(config.networks)
+      ? config.networks
+      : [config.networks]
+    : ['eip155:*' as Network]
+  for (const network of networks) {
+    server.register(network, scheme)
+  }
+  return server
+}