@x402r/evm 0.0.1

package/src/escrow/server/index.ts

@@ -0,0 +1,133 @@
+/**
+ * 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 { EscrowExtra } from "../../shared/types.js";
+
+/**
+ * x402 PaymentRequirements (matches @x402/core/types PaymentRequirements)
+ */
+export interface PaymentRequirements {
+  scheme: string;
+  network: string;
+  amount: string;
+  asset: string;
+  payTo: string;
+  maxTimeoutSeconds: number;
+  extra: Record<string, unknown>;
+}
+
+export interface SupportedKind {
+  x402Version: number;
+  scheme: string;
+  network: string;
+  extra?: Record<string, unknown>;
+}
+
+/**
+ * x402 AssetAmount (matches @x402/core/types AssetAmount)
+ */
+export interface AssetAmount {
+  asset: string;
+  amount: string;
+  extra?: Record<string, unknown>;
+}
+
+/**
+ * x402 Price type (matches @x402/core/types Price)
+ */
+export type Price = string | number | AssetAmount;
+
+export type Network = `${string}:${string}`;
+
+/**
+ * Known USDC addresses per network
+ */
+const USDC_ADDRESSES: Record<string, string> = {
+  "eip155:84532": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+  "eip155:8453": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+};
+
+/**
+ * Server scheme - handles price parsing and requirement enhancement.
+ * Implements x402's SchemeNetworkServer interface.
+ */
+export class EscrowServerScheme {
+  readonly scheme = "escrow";
+  private readonly decimals: number;
+
+  constructor(config?: { decimals?: number }) {
+    this.decimals = config?.decimals ?? 6; // USDC default
+  }
+
+  /**
+   * 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
+    if (
+      typeof price === "object" &&
+      price !== null &&
+      "amount" in price &&
+      "asset" in price
+    ) {
+      return price as AssetAmount;
+    }
+
+    // Convert to number for calculation
+    let numericAmount: number;
+    if (typeof price === "number") {
+      numericAmount = price;
+    } else {
+      const cleaned = String(price).replace(/[$,]/g, "").trim();
+      numericAmount = parseFloat(cleaned);
+    }
+
+    if (isNaN(numericAmount)) {
+      throw new Error(`Cannot parse price: ${price}`);
+    }
+
+    const rawAmount = BigInt(Math.round(numericAmount * 10 ** this.decimals));
+    const asset = USDC_ADDRESSES[network];
+    if (!asset) {
+      throw new Error(`No USDC address configured for network: ${network}`);
+    }
+
+    return {
+      asset,
+      amount: rawAmount.toString(),
+    };
+  }
+
+  /**
+   * 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: SupportedKind,
+    _facilitatorExtensions: string[],
+  ): Promise<PaymentRequirements> {
+    return {
+      ...requirements,
+      extra: {
+        ...supportedKind.extra,
+        ...requirements.extra,
+      },
+    };
+  }
+}
+
+export type { EscrowExtra, EscrowPayload } from "../../shared/types.js";

package/src/shared/constants.ts

@@ -0,0 +1,43 @@
+export const ZERO_ADDRESS =
+  "0x0000000000000000000000000000000000000000" as const;
+export const MAX_UINT48 = 281474976710655;
+export const MAX_UINT32 = 4294967295;
+
+// PaymentInfo struct for AuthCaptureEscrow (matches commerce-payments contract)
+export const PAYMENT_INFO_COMPONENTS = [
+  { name: "operator", type: "address" },
+  { name: "payer", type: "address" },
+  { name: "receiver", type: "address" },
+  { name: "token", type: "address" },
+  { name: "maxAmount", type: "uint120" },
+  { name: "preApprovalExpiry", type: "uint48" },
+  { name: "authorizationExpiry", type: "uint48" },
+  { name: "refundExpiry", type: "uint48" },
+  { name: "minFeeBps", type: "uint16" },
+  { name: "maxFeeBps", type: "uint16" },
+  { name: "feeReceiver", type: "address" },
+  { name: "salt", type: "uint256" },
+] as const;
+
+export const OPERATOR_ABI = [
+  {
+    name: "authorize",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      {
+        name: "paymentInfo",
+        type: "tuple",
+        components: PAYMENT_INFO_COMPONENTS,
+      },
+      { name: "amount", type: "uint256" },
+      { name: "tokenCollector", type: "address" },
+      { name: "collectorData", type: "bytes" },
+    ],
+    outputs: [],
+  },
+] as const;
+
+// ERC-3009 TransferWithAuthorization type hash
+export const TRANSFER_WITH_AUTHORIZATION_TYPEHASH =
+  "0x7c7c6cdb67a18743f49ec6fa9b35f50d52ed05cbed4cc592e13b44501c1a2267" as const;

package/src/shared/nonce.ts

@@ -0,0 +1,202 @@
+/**
+ * Nonce computation and ERC-3009 signing utilities
+ * Adapted from @agentokratia/x402-escrow (MIT)
+ */
+
+import { encodeAbiParameters, keccak256, type WalletClient } from "viem";
+import { ZERO_ADDRESS, PAYMENT_INFO_COMPONENTS } from "./constants.js";
+import type { EscrowExtra, EscrowPayload } from "./types.js";
+
+/**
+ * PaymentInfo typehash - must match AuthCaptureEscrow.PAYMENT_INFO_TYPEHASH
+ */
+const PAYMENT_INFO_TYPEHASH = keccak256(
+  new TextEncoder().encode(
+    "PaymentInfo(address operator,address payer,address receiver,address token,uint120 maxAmount,uint48 preApprovalExpiry,uint48 authorizationExpiry,uint48 refundExpiry,uint16 minFeeBps,uint16 maxFeeBps,address feeReceiver,uint256 salt)",
+  ),
+);
+
+/**
+ * Compute escrow nonce for ERC-3009 authorization
+ * Must match AuthCaptureEscrow.getHash() with payer=address(0)
+ */
+export function computeEscrowNonce(
+  chainId: number,
+  escrowAddress: `0x${string}`,
+  paymentInfo: EscrowPayload["paymentInfo"],
+): `0x${string}` {
+  // Step 1: Encode paymentInfo with payer=0 (payer-agnostic)
+  const paymentInfoEncoded = encodeAbiParameters(
+    [
+      { name: "typehash", type: "bytes32" },
+      { name: "operator", type: "address" },
+      { name: "payer", type: "address" },
+      { name: "receiver", type: "address" },
+      { name: "token", type: "address" },
+      { name: "maxAmount", type: "uint120" },
+      { name: "preApprovalExpiry", type: "uint48" },
+      { name: "authorizationExpiry", type: "uint48" },
+      { name: "refundExpiry", type: "uint48" },
+      { name: "minFeeBps", type: "uint16" },
+      { name: "maxFeeBps", type: "uint16" },
+      { name: "feeReceiver", type: "address" },
+      { name: "salt", type: "uint256" },
+    ],
+    [
+      PAYMENT_INFO_TYPEHASH,
+      paymentInfo.operator,
+      ZERO_ADDRESS, // payer-agnostic
+      paymentInfo.receiver,
+      paymentInfo.token,
+      BigInt(paymentInfo.maxAmount),
+      paymentInfo.preApprovalExpiry,
+      paymentInfo.authorizationExpiry,
+      paymentInfo.refundExpiry,
+      paymentInfo.minFeeBps,
+      paymentInfo.maxFeeBps,
+      paymentInfo.feeReceiver,
+      BigInt(paymentInfo.salt),
+    ],
+  );
+  const paymentInfoHash = keccak256(paymentInfoEncoded);
+
+  // Step 2: Encode (chainId, escrow, paymentInfoHash) and hash
+  const outerEncoded = encodeAbiParameters(
+    [
+      { name: "chainId", type: "uint256" },
+      { name: "escrow", type: "address" },
+      { name: "paymentInfoHash", type: "bytes32" },
+    ],
+    [BigInt(chainId), escrowAddress, paymentInfoHash],
+  );
+
+  return keccak256(outerEncoded);
+}
+
+/**
+ * Sign ERC-3009 ReceiveWithAuthorization
+ * Note: receiveWithAuthorization uses a different primary type than transferWithAuthorization
+ */
+export async function signERC3009(
+  wallet: WalletClient,
+  authorization: EscrowPayload["authorization"],
+  extra: EscrowExtra,
+  tokenAddress: `0x${string}`,
+): Promise<`0x${string}`> {
+  // EIP-712 domain - name must match the token's EIP-712 domain
+  // (e.g., "USDC" for Base USDC, not "USD Coin")
+  const domain = {
+    name: extra.name,
+    version: extra.version ?? "2",
+    chainId: await wallet.getChainId(),
+    verifyingContract: tokenAddress,
+  };
+
+  // ERC-3009 uses ReceiveWithAuthorization for receiveWithAuthorization()
+  const types = {
+    ReceiveWithAuthorization: [
+      { name: "from", type: "address" },
+      { name: "to", type: "address" },
+      { name: "value", type: "uint256" },
+      { name: "validAfter", type: "uint256" },
+      { name: "validBefore", type: "uint256" },
+      { name: "nonce", type: "bytes32" },
+    ],
+  };
+
+  const message = {
+    from: authorization.from,
+    to: authorization.to,
+    value: BigInt(authorization.value),
+    validAfter: BigInt(authorization.validAfter),
+    validBefore: BigInt(authorization.validBefore),
+    nonce: authorization.nonce,
+  };
+
+  return wallet.signTypedData({
+    account: wallet.account!,
+    domain,
+    types,
+    primaryType: "ReceiveWithAuthorization",
+    message,
+  });
+}
+
+/**
+ * Verify ERC-3009 signature (facilitator-side)
+ * @param signer - The signer with verifyTypedData method
+ * @param authorization - ERC-3009 authorization data
+ * @param signature - The signature to verify
+ * @param extra - Extra configuration including chainId
+ * @param tokenAddress - The token contract address (verifyingContract for EIP-712)
+ */
+export async function verifyERC3009Signature(
+  signer: {
+    verifyTypedData: (args: {
+      address: `0x${string}`;
+      domain: Record<string, unknown>;
+      types: Record<string, unknown>;
+      primaryType: string;
+      message: Record<string, unknown>;
+      signature: `0x${string}`;
+    }) => Promise<boolean>;
+  },
+  authorization: EscrowPayload["authorization"],
+  signature: `0x${string}`,
+  extra: EscrowExtra & { chainId: number },
+  tokenAddress: `0x${string}`,
+): Promise<boolean> {
+  // EIP-712 domain - name must match the token's EIP-712 domain
+  // (e.g., "USDC" for Base USDC, not "USD Coin")
+  const domain = {
+    name: extra.name,
+    version: extra.version ?? "2",
+    chainId: extra.chainId,
+    verifyingContract: tokenAddress,
+  };
+
+  // Must use ReceiveWithAuthorization to match what was signed
+  const types = {
+    ReceiveWithAuthorization: [
+      { name: "from", type: "address" },
+      { name: "to", type: "address" },
+      { name: "value", type: "uint256" },
+      { name: "validAfter", type: "uint256" },
+      { name: "validBefore", type: "uint256" },
+      { name: "nonce", type: "bytes32" },
+    ],
+  };
+
+  const message = {
+    from: authorization.from,
+    to: authorization.to,
+    value: BigInt(authorization.value),
+    validAfter: BigInt(authorization.validAfter),
+    validBefore: BigInt(authorization.validBefore),
+    nonce: authorization.nonce,
+  };
+
+  try {
+    return await signer.verifyTypedData({
+      address: authorization.from,
+      domain,
+      types,
+      primaryType: "ReceiveWithAuthorization",
+      message,
+      signature,
+    });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Generate random salt for paymentInfo
+ */
+export function generateSalt(): `0x${string}` {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return `0x${Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("")}` as `0x${string}`;
+}

package/src/shared/types.ts

@@ -0,0 +1,43 @@
+// EscrowExtra - fields in PaymentRequirements.extra
+export interface EscrowExtra {
+  escrowAddress: `0x${string}`;
+  operatorAddress: `0x${string}`;
+  tokenCollector: `0x${string}`;
+  authorizeAddress?: `0x${string}`;
+  minDeposit?: string;
+  maxDeposit?: string;
+  preApprovalExpirySeconds?: number;
+  authorizationExpirySeconds?: number;
+  refundExpirySeconds?: number;
+  minFeeBps?: number;
+  maxFeeBps?: number;
+  feeReceiver?: `0x${string}`;
+  name: string; // EIP-712 domain name (e.g., "USDC" for Base USDC)
+  version?: string;
+}
+
+// EscrowPayload - the payload field in PaymentPayload
+export interface EscrowPayload {
+  authorization: {
+    from: `0x${string}`;
+    to: `0x${string}`;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: `0x${string}`;
+  };
+  signature: `0x${string}`;
+  paymentInfo: {
+    operator: `0x${string}`;
+    receiver: `0x${string}`;
+    token: `0x${string}`;
+    maxAmount: string;
+    preApprovalExpiry: number;
+    authorizationExpiry: number;
+    refundExpiry: number;
+    minFeeBps: number;
+    maxFeeBps: number;
+    feeReceiver: `0x${string}`;
+    salt: `0x${string}`;
+  };
+}