@x402r/evm 0.0.1 → 0.0.2

package/src/escrow/client/index.ts

@@ -1,88 +1,161 @@
 /**
  * Escrow Scheme - Client
- * Creates payment payloads for escrow payments
+ * Creates payment payloads for escrow payments.
+ *
+ * Implements x402's SchemeNetworkClient interface so it can be registered
+ * on an x402Client via client.register('eip155:84532', new EscrowEvmScheme(signer)).
  */
 
-import type { WalletClient } from "viem";
+import type {
+  Network,
+  PaymentPayload,
+  PaymentRequirements,
+  SchemeNetworkClient,
+} from "@x402/core/types";
+import type { ClientEvmSigner } from "@x402/evm";
+import { x402Client } from "@x402/core/client";
 import {
   computeEscrowNonce,
   signERC3009,
   generateSalt,
 } from "../../shared/nonce.js";
 import { MAX_UINT48 } from "../../shared/constants.js";
-import type { EscrowExtra, EscrowPayload } from "../../shared/types.js";
-
-export interface PaymentRequirements {
-  scheme: string;
-  network: string;
-  amount: string;
-  asset: `0x${string}`;
-  payTo: `0x${string}`;
-  extra: EscrowExtra;
+import type { EscrowExtra } from "../../shared/types.js";
+
+/**
+ * Parse chainId from CAIP-2 network identifier
+ */
+function parseChainId(network: string): number {
+  const parts = network.split(":");
+  if (parts.length !== 2 || parts[0] !== "eip155") {
+    throw new Error(
+      `Invalid network format: ${network}. Expected 'eip155:<chainId>'`,
+    );
+  }
+  const chainId = parseInt(parts[1], 10);
+  if (isNaN(chainId)) {
+    throw new Error(`Invalid chainId in network: ${network}`);
+  }
+  return chainId;
+}
+
+/**
+ * Escrow Client Scheme - implements x402's SchemeNetworkClient
+ */
+export class EscrowEvmScheme implements SchemeNetworkClient {
+  readonly scheme = "escrow";
+
+  constructor(private readonly signer: ClientEvmSigner) {}
+
+  async createPaymentPayload(
+    x402Version: number,
+    requirements: PaymentRequirements,
+  ): Promise<Pick<PaymentPayload, "x402Version" | "payload">> {
+    if (x402Version !== 2) {
+      throw new Error(
+        `Unsupported x402Version: ${x402Version}. Only version 2 is supported.`,
+      );
+    }
+
+    const extra = requirements.extra as unknown as EscrowExtra;
+
+    // Validate required EIP-712 domain parameters (M3, M10)
+    if (!extra.name) {
+      throw new Error(
+        `EIP-712 domain parameter 'name' is required in payment requirements for asset ${requirements.asset}`,
+      );
+    }
+    if (!extra.version) {
+      throw new Error(
+        `EIP-712 domain parameter 'version' is required in payment requirements for asset ${requirements.asset}`,
+      );
+    }
+
+    const {
+      escrowAddress,
+      operatorAddress,
+      tokenCollector,
+      minFeeBps = 0,
+      maxFeeBps = 0,
+      feeReceiver,
+      preApprovalExpirySeconds,
+      refundExpirySeconds,
+      authorizationExpirySeconds,
+    } = extra;
+
+    const chainId = parseChainId(requirements.network);
+    const maxAmount = requirements.amount;
+
+    const paymentInfo = {
+      operator: operatorAddress,
+      receiver: requirements.payTo as `0x${string}`,
+      token: requirements.asset as `0x${string}`,
+      maxAmount,
+      preApprovalExpiry: preApprovalExpirySeconds ?? MAX_UINT48,
+      authorizationExpiry: authorizationExpirySeconds ?? MAX_UINT48,
+      refundExpiry: refundExpirySeconds ?? MAX_UINT48,
+      minFeeBps,
+      maxFeeBps,
+      feeReceiver: feeReceiver ?? operatorAddress,
+      salt: generateSalt(),
+    };
+
+    const nonce = computeEscrowNonce(chainId, escrowAddress, paymentInfo);
+
+    // ERC-3009 authorization - validBefore MUST match what contract passes to receiveWithAuthorization
+    // The contract uses paymentInfo.preApprovalExpiry as validBefore
+    const authorization = {
+      from: this.signer.address,
+      to: tokenCollector,
+      value: maxAmount,
+      validAfter: "0",
+      validBefore: String(paymentInfo.preApprovalExpiry),
+      nonce,
+    };
+
+    const signature = await signERC3009(
+      this.signer,
+      authorization,
+      extra,
+      requirements.asset as `0x${string}`,
+      chainId,
+    );
+
+    return {
+      x402Version,
+      payload: { authorization, signature, paymentInfo },
+    };
+  }
 }
 
 /**
- * Create an escrow payment payload from payment requirements
+ * Register escrow client scheme with x402Client
+ *
+ * @example
+ * ```typescript
+ * const client = new x402Client();
+ * registerEscrowScheme(client, { signer, networks: "eip155:84532" });
+ * ```
  */
-export async function createPaymentPayload(
-  requirements: PaymentRequirements,
-  wallet: WalletClient,
-): Promise<EscrowPayload> {
-  const {
-    escrowAddress,
-    operatorAddress,
-    tokenCollector,
-    minFeeBps = 0,
-    maxFeeBps = 0,
-    feeReceiver,
-    preApprovalExpirySeconds,
-    refundExpirySeconds,
-    authorizationExpirySeconds,
-  } = requirements.extra;
-
-  const chainId = await wallet.getChainId();
-  const maxAmount = requirements.amount;
-
-  const paymentInfo = {
-    operator: operatorAddress,
-    receiver: requirements.payTo,
-    token: requirements.asset,
-    maxAmount,
-    preApprovalExpiry: preApprovalExpirySeconds ?? MAX_UINT48,
-    authorizationExpiry: authorizationExpirySeconds ?? MAX_UINT48,
-    refundExpiry: refundExpirySeconds ?? MAX_UINT48,
-    minFeeBps,
-    maxFeeBps,
-    feeReceiver: feeReceiver ?? operatorAddress,
-    salt: generateSalt(),
-  };
-
-  const nonce = computeEscrowNonce(chainId, escrowAddress, paymentInfo);
-
-  // ERC-3009 authorization - validBefore MUST match what contract passes to receiveWithAuthorization
-  // The contract uses paymentInfo.preApprovalExpiry as validBefore
-  const authorization = {
-    from: wallet.account!.address,
-    to: tokenCollector,
-    value: maxAmount,
-    validAfter: "0",
-    validBefore: String(paymentInfo.preApprovalExpiry),
-    nonce,
-  };
-
-  const signature = await signERC3009(
-    wallet,
-    authorization,
-    requirements.extra,
-    requirements.asset,
-  );
-
-  return { authorization, signature, paymentInfo };
+export function registerEscrowScheme(
+  client: x402Client,
+  config: { signer: ClientEvmSigner; networks: Network | Network[] },
+): x402Client {
+  const scheme = new EscrowEvmScheme(config.signer);
+  const networks = Array.isArray(config.networks)
+    ? config.networks
+    : [config.networks];
+  for (const network of networks) {
+    client.register(network, scheme);
+  }
+  return client;
 }
 
+/**
+ * @deprecated Use `new EscrowEvmScheme(signer)` directly
+ */
 export const EscrowScheme = {
   scheme: "escrow" as const,
-  createPaymentPayload,
 };
 
 export type { EscrowExtra, EscrowPayload } from "../../shared/types.js";

package/src/escrow/facilitator/index.ts

@@ -16,8 +16,16 @@ import type {
 } from "@x402/core/types";
 import type { FacilitatorEvmSigner } from "@x402/evm";
 import { x402Facilitator } from "@x402/core/facilitator";
-import { OPERATOR_ABI } from "../../shared/constants.js";
+import {
+  OPERATOR_ABI,
+  ERC20_BALANCE_OF_ABI,
+  ERC6492_MAGIC_VALUE,
+} from "../../shared/constants.js";
 import { verifyERC3009Signature } from "../../shared/nonce.js";
+import {
+  isEscrowPayload,
+  isEscrowExtra,
+} from "../../shared/types.js";
 import type { EscrowExtra, EscrowPayload } from "../../shared/types.js";
 
 /**
@@ -39,6 +47,46 @@ function parseChainId(network: string): number {
   return chainId;
 }
 
+/**
+ * Extract inner signature from an EIP-6492 wrapped signature.
+ * If the signature is not EIP-6492 wrapped, returns it unchanged.
+ *
+ * EIP-6492 format: abi.encode(address, bytes, bytes) ++ MAGIC_VALUE
+ * The inner signature is the third ABI-encoded bytes field.
+ */
+function unwrapERC6492Signature(signature: `0x${string}`): `0x${string}` {
+  // EIP-6492 magic is 32 bytes (64 hex chars) at the end
+  if (signature.length <= 66) return signature; // Too short to be wrapped
+
+  const magicSuffix = `0x${signature.slice(-64)}`;
+  if (magicSuffix !== ERC6492_MAGIC_VALUE) return signature; // Not wrapped
+
+  // Strip the magic suffix and ABI-decode: (address prepareTarget, bytes prepareData, bytes innerSignature)
+  // The wrapped data (without magic) is: 0x + ABI-encoded (address, bytes, bytes)
+  const wrappedHex = signature.slice(2, -64); // hex without 0x prefix and magic
+
+  // ABI layout for (address, bytes, bytes):
+  // word 0 (0-64): address (padded to 32 bytes)
+  // word 1 (64-128): offset to prepareData bytes
+  // word 2 (128-192): offset to innerSignature bytes
+  // Then the dynamic data follows
+
+  if (wrappedHex.length < 192) return signature; // Malformed
+
+  const innerSigOffset = parseInt(wrappedHex.slice(128, 192), 16) * 2; // byte offset → hex offset
+  if (innerSigOffset + 64 > wrappedHex.length) return signature; // Malformed
+
+  const innerSigLength = parseInt(
+    wrappedHex.slice(innerSigOffset, innerSigOffset + 64),
+    16,
+  ) * 2; // bytes → hex chars
+  const innerSigStart = innerSigOffset + 64;
+
+  if (innerSigStart + innerSigLength > wrappedHex.length) return signature; // Malformed
+
+  return `0x${wrappedHex.slice(innerSigStart, innerSigStart + innerSigLength)}` as `0x${string}`;
+}
+
 /**
  * Escrow Facilitator Scheme - implements x402's SchemeNetworkFacilitator
  *
@@ -56,29 +104,97 @@ export class EscrowFacilitatorScheme implements SchemeNetworkFacilitator {
     return [...this.signer.getAddresses()];
   }
 
-  getExtra(_network: string): Record<string, unknown> {
-    return { name: "USDC", version: "2" };
+  // 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,
   ): Promise<VerifyResponse> {
-    const escrowPayload = payload.payload as unknown as EscrowPayload;
-    const extra = requirements.extra as unknown as EscrowExtra;
+    // 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
+    if (requirements.scheme !== "escrow") {
+      return {
+        isValid: false,
+        invalidReason: "unsupported_scheme",
+        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,
+      };
+    }
+
+    // M4: 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 signatureForVerify = unwrapERC6492Signature(escrowPayload.signature);
+
     // Verify ERC-3009 signature
     const isValidSignature = await verifyERC3009Signature(
       this.signer,
       escrowPayload.authorization,
-      escrowPayload.signature,
+      signatureForVerify,
       { ...extra, chainId },
       requirements.asset as `0x${string}`,
     );
 
     if (!isValidSignature) {
-      return { isValid: false, invalidReason: "Invalid ERC-3009 signature" };
+      return {
+        isValid: false,
+        invalidReason: "invalid_escrow_signature",
+        payer,
+      };
     }
 
     // Verify amount meets requirements
@@ -86,7 +202,11 @@ export class EscrowFacilitatorScheme implements SchemeNetworkFacilitator {
       BigInt(escrowPayload.authorization.value) <
       BigInt(requirements.amount)
     ) {
-      return { isValid: false, invalidReason: "Insufficient payment amount" };
+      return {
+        isValid: false,
+        invalidReason: "insufficient_amount",
+        payer,
+      };
     }
 
     // Verify token matches
@@ -94,7 +214,11 @@ export class EscrowFacilitatorScheme implements SchemeNetworkFacilitator {
       escrowPayload.paymentInfo.token.toLowerCase() !==
       requirements.asset.toLowerCase()
     ) {
-      return { isValid: false, invalidReason: "Token mismatch" };
+      return {
+        isValid: false,
+        invalidReason: "token_mismatch",
+        payer,
+      };
     }
 
     // Verify receiver matches
@@ -102,12 +226,37 @@ export class EscrowFacilitatorScheme implements SchemeNetworkFacilitator {
       escrowPayload.paymentInfo.receiver.toLowerCase() !==
       requirements.payTo.toLowerCase()
     ) {
-      return { isValid: false, invalidReason: "Receiver mismatch" };
+      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: escrowPayload.authorization.from,
+      payer,
     };
   }
 
@@ -115,6 +264,18 @@ export class EscrowFacilitatorScheme implements SchemeNetworkFacilitator {
     payload: PaymentPayload,
     requirements: PaymentRequirements,
   ): 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;
@@ -134,7 +295,8 @@ export class EscrowFacilitatorScheme implements SchemeNetworkFacilitator {
       salt: BigInt(escrowPayload.paymentInfo.salt),
     };
 
-    // Pass raw signature - ERC3009PaymentCollector expects raw bytes, not ABI-encoded
+    // Pass raw signature — ERC3009PaymentCollector/ERC6492SignatureHandler
+    // handles EIP-6492 unwrapping and wallet deployment on-chain
     const collectorData = escrowPayload.signature;
 
     const target = authorizeAddress ?? operatorAddress;
@@ -152,6 +314,28 @@ export class EscrowFacilitatorScheme implements SchemeNetworkFacilitator {
         ],
       });
 
+      // 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,