@x402r/refund 0.0.0

package/src/index.ts

@@ -0,0 +1,119 @@
+/**
+ * Refund Helper Extension for x402
+ *
+ * Enables merchants to route payments to DepositRelay contracts via escrow,
+ * providing refund and dispute resolution capabilities.
+ *
+ * ## Overview
+ *
+ * The refund helper allows merchants to mark payment options as refundable,
+ * which routes payments through DepositRelay contracts into escrow accounts.
+ * This enables dispute resolution and refunds even if merchants are uncooperative.
+ *
+ * ## For Merchants (Server-Side)
+ *
+ * ### Step 1: Mark Payment Options as Refundable
+ *
+ * Use `refundable()` to mark payment options that should support refunds:
+ *
+ * ```typescript
+ * import { refundable } from '@x402r/extensions/refund';
+ *
+ * const option = refundable({
+ *   scheme: 'exact',
+ *   payTo: '0xmerchant123...', // Your merchant payout address
+ *   price: '$0.01',
+ *   network: 'eip155:84532',
+ * });
+ * ```
+ *
+ * ### Step 2: Process Routes with DepositRelay
+ *
+ * Use `withRefund()` to process route configurations and route refundable
+ * payments to DepositRelay:
+ *
+ * ```typescript
+ * import { refundable, withRefund } from '@x402r/extensions/refund';
+ *
+ * const FACTORY_ADDRESS = '0xFactory123...'; // Any CREATE3-compatible factory
+ * const CREATEX_ADDRESS = '0xCreateX123...'; // CreateX contract address
+ *
+ * const routes = {
+ *   '/api': {
+ *     accepts: refundable({
+ *       scheme: 'exact',
+ *       payTo: '0xmerchant123...',
+ *       price: '$0.01',
+ *       network: 'eip155:84532',
+ *     }),
+ *   },
+ * };
+ *
+ * // Process routes to route refundable payments to DepositRelay
+ * // Uses CREATE3 - no bytecode needed! Works with any CREATE3-compatible factory.
+ * // Version is optional - defaults to config file value
+ * // CreateX address is optional - uses standard address for network if not provided
+ * const processedRoutes = withRefund(routes, FACTORY_ADDRESS);
+ *
+ * // Use processedRoutes with paymentMiddleware
+ * app.use(paymentMiddleware(processedRoutes, server));
+ * ```
+ *
+ * ## For Facilitators
+ *
+ * Facilitators use `settleWithRefundHelper()` in hooks to handle refund settlements:
+ *
+ * ```typescript
+ * import { settleWithRefundHelper } from '@x402r/extensions/refund';
+ * import { x402Facilitator } from '@x402/core/facilitator';
+ *
+ * const ESCROW_FACTORY = '0xEscrowFactory123...';
+ *
+ * facilitator.onBeforeSettle(async (context) => {
+ *   const result = await settleWithRefundHelper(
+ *     context.paymentPayload,
+ *     context.paymentRequirements,
+ *     signer,
+ *     ESCROW_FACTORY,
+ *   );
+ *
+ *   if (result) {
+ *     // Refund was handled via DepositRelay
+ *     return { abort: true, reason: 'handled_by_refund_helper' };
+ *   }
+ *
+ *   return null; // Proceed with normal settlement
+ * });
+ * ```
+ *
+ * ## How It Works
+ *
+ * 1. **Merchant Setup**: Merchant deploys escrow via EscrowFactory and marks options with `refundable()`
+ * 2. **Route Processing**: `withRefund()` sets `payTo` to DepositRelay address, stores original merchantPayout in `extra`
+ * 3. **Client Payment**: Client makes payment to DepositRelay address (transparent to client)
+ * 4. **Facilitator Settlement**: Facilitator detects refund payment, queries EscrowFactory for escrow, calls DepositRelay.executeDeposit()
+ * 5. **Escrow Hold**: Funds are held in escrow, enabling dispute resolution and refunds
+ *
+ * ## Key Features
+ *
+ * - **No Core Changes**: Works entirely through helpers and hooks
+ * - **Client Transparent**: Clients don't need to change anything
+ * - **Flexible**: Mix refundable and non-refundable options in same route
+ * - **Deep Cloning**: All helpers return new objects, don't mutate originals
+ */
+
+// Export types
+export {
+  REFUND_EXTENSION_KEY,
+  REFUND_MARKER_KEY,
+  isRefundableOption,
+  type RefundExtension,
+  type RefundExtensionInfo,
+} from "./types";
+
+// Export server-side helpers
+export { declareRefundExtension, refundable, withRefund } from "./server";
+export { computeRelayAddress } from "./server/computeRelayAddress";
+
+// Export facilitator-side helpers
+export { extractRefundInfo, settleWithRefundHelper } from "./facilitator";

package/src/server/computeRelayAddress.ts

@@ -0,0 +1,73 @@
+/**
+ * Helper to compute CREATE3 address for RelayProxy
+ *
+ * Uses the CREATE3 formula via CreateX (matching Solidity implementation):
+ *
+ * Where:
+ * - salt = keccak256(abi.encodePacked(factoryAddress, merchantPayout))
+ * - guardedSalt = keccak256(abi.encode(salt))  // CreateX guards the salt
+ * - createxDeployer = the CreateX contract address
+ *
+ * CREATE3 is much simpler than CREATE2 - no bytecode needed!
+ * The address depends only on the deployer (CreateX) and salt.
+ *
+ * IMPORTANT: The CreateX address must match the one used by the factory contract.
+ * The factory stores its CreateX address and can be queried via factory.getCreateX().
+ * This function computes addresses locally without any on-chain calls.
+ */
+
+import { keccak256, encodePacked, encodeAbiParameters, getAddress } from "viem";
+import { predictCreate3Address } from "@whoislewys/predict-deterministic-address";
+
+/**
+ * Computes the CREATE3 address for a merchant's relay proxy
+ *
+ * This matches the Solidity implementation in DepositRelayFactory.getRelayAddress():
+ * 1. salt = keccak256(abi.encodePacked(merchantPayout))
+ * 2. guardedSalt = keccak256(abi.encode(salt))  // CreateX guards the salt
+ * 3. return CREATEX.computeCreate3Address(guardedSalt)
+ *
+ * Uses the @whoislewys/predict-deterministic-address library which correctly
+ * implements the CREATE3 formula used by CreateX (based on Solady's CREATE3).
+ * This ensures the computed address matches the factory's on-chain computation
+ * without requiring any on-chain calls.
+ *
+ * @param createxAddress - The CreateX contract address
+ * @param factoryAddress - The DepositRelayFactory contract address
+ * @param merchantPayout - The merchant's payout address
+ * @returns The deterministic proxy address
+ *
+ * @example
+ * ```typescript
+ * // No bytecode needed! Computes locally without on-chain calls.
+ * const relayAddress = computeRelayAddress(
+ *   "0xCreateX123...",
+ *   "0xMerchant123...",
+ *   0n // version
+ * );
+ * ```
+ */
+export function computeRelayAddress(
+  createxAddress: string,
+  factoryAddress: string,
+  merchantPayout: string,
+): string {
+  // Normalize addresses to checksummed format
+  const createx = getAddress(createxAddress);
+  const factory = getAddress(factoryAddress);
+  const merchant = getAddress(merchantPayout);
+
+  // Step 1: salt = keccak256(abi.encodePacked(factoryAddress, merchantPayout))
+  const salt = keccak256(encodePacked(["address", "address"], [factory, merchant]));
+
+  // Step 2: guardedSalt = keccak256(abi.encode(salt))
+  // Note: abi.encode (not encodePacked) - this adds length prefixes
+  const guardedSalt = keccak256(
+    encodeAbiParameters([{ type: "bytes32" }], [salt as `0x${string}`]),
+  );
+
+  // Step 3: Use predictCreate3Address to compute the CREATE3 address
+  // This matches CreateX's computeCreate3Address implementation exactly
+  // No on-chain calls needed - computes locally!
+  return predictCreate3Address(createx, guardedSalt as `0x${string}`);
+}

package/src/server.ts

@@ -0,0 +1,334 @@
+/**
+ * Server-side helpers for the Refund Helper Extension
+ *
+ * These helpers allow merchants to mark payment options as refundable
+ * and process route configurations to route payments to X402DepositRelayProxy contracts.
+ */
+
+import type { PaymentOption, RouteConfig, RoutesConfig } from "@x402/core/http";
+import {
+  REFUND_MARKER_KEY,
+  isRefundableOption,
+  REFUND_EXTENSION_KEY,
+  type RefundExtension,
+} from "./types";
+import { computeRelayAddress } from "./server/computeRelayAddress";
+
+/**
+ * Declares a refund extension with factory address and merchantPayouts map
+ *
+ * @param factoryAddress - The X402DepositRelayFactory contract address
+ * @param merchantPayouts - Map of proxy address to merchant payout address
+ * @returns Refund extension object with info and schema
+ *
+ * @example
+ * ```typescript
+ * const extension = declareRefundExtension("0xFactory123...", {
+ *   "0xProxy1...": "0xMerchant1...",
+ *   "0xProxy2...": "0xMerchant2...",
+ * });
+ * ```
+ */
+export function declareRefundExtension(
+  factoryAddress: string,
+  merchantPayouts: Record<string, string>,
+): Record<string, RefundExtension> {
+  return {
+    [REFUND_EXTENSION_KEY]: {
+      info: {
+        factoryAddress,
+        merchantPayouts,
+      },
+      schema: {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        type: "object",
+        properties: {
+          factoryAddress: {
+            type: "string",
+            pattern: "^0x[a-fA-F0-9]{40}$",
+            description: "The X402DepositRelayFactory contract address",
+          },
+          merchantPayouts: {
+            type: "object",
+            additionalProperties: {
+              type: "string",
+              pattern: "^0x[a-fA-F0-9]{40}$",
+            },
+            description: "Map of proxy address to merchant payout address",
+          },
+        },
+        required: ["factoryAddress", "merchantPayouts"],
+        additionalProperties: false,
+      },
+    },
+  };
+}
+
+/**
+ * Marks a payment option as refundable.
+ *
+ * This function marks the option as refundable so it can be processed by `withRefund()`.
+ * The merchantPayout is read directly from the option's `payTo` field when processing.
+ *
+ * @param option - The payment option to mark as refundable
+ * @returns A new PaymentOption marked as refundable (does not mutate original)
+ *
+ * @example
+ * ```typescript
+ * const refundableOption = refundable({
+ *   scheme: "exact",
+ *   payTo: "0xmerchant123...",
+ *   price: "$0.01",
+ *   network: "eip155:84532",
+ * });
+ * // refundableOption.extra._x402_refund = true
+ * ```
+ */
+export function refundable(option: PaymentOption): PaymentOption {
+  // Deep clone the option to avoid mutation
+  const clonedOption: PaymentOption = {
+    ...option,
+    extra: {
+      ...option.extra,
+    },
+  };
+
+  // Set marker to indicate this option is refundable
+  if (!clonedOption.extra) {
+    clonedOption.extra = {};
+  }
+
+  clonedOption.extra[REFUND_MARKER_KEY] = true;
+
+  return clonedOption;
+}
+
+/**
+ * Standard CreateX contract addresses per network.
+ * These are the official CreateX deployments from https://github.com/pcaversaccio/createx#createx-deployments
+ *
+ * Note: If a network is not listed here, CreateX may need to be deployed separately.
+ * The factory stores the CreateX address and can be queried via factory.getCreateX().
+ */
+const STANDARD_CREATEX_ADDRESSES: Record<string, string> = {
+  // Ethereum Mainnet
+  "eip155:1": "0xba5Ed099633D3B313e4D5F7bdc1305d3c32ba066",
+  // Base Mainnet
+  "eip155:8453": "0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed",
+  // Base Sepolia
+  "eip155:84532": "0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed",
+  // Add more networks as CreateX deployments become available
+};
+
+/**
+ * Processes route configuration to handle refundable payment options.
+ *
+ * This function finds all payment options marked with `refundable()` and:
+ * 1. Computes the proxy address using CREATE3 (no bytecode needed!)
+ * 2. Sets `payTo` to the proxy address
+ * 3. Adds the refund extension with factory address
+ *
+ * @param routes - Route configuration (single RouteConfig or Record<string, RouteConfig>)
+ * @param factoryAddress - The X402DepositRelayFactory contract address (required)
+ * @param createxAddress - The CreateX contract address (optional, will use standard address for network if not provided)
+ * @returns A new RoutesConfig with refundable options routed to proxy (deep cloned, does not mutate original)
+ *
+ * @example
+ * ```typescript
+ * const routes = {
+ *   "/api": {
+ *     accepts: refundable({
+ *       scheme: "exact",
+ *       payTo: "0xmerchant123...",
+ *       price: "$0.01",
+ *       network: "eip155:84532",
+ *     }),
+ *   },
+ * };
+ *
+ * // Version is optional - defaults to config file value
+ * // CreateX address is optional - uses standard address for the network
+ * const processedRoutes = withRefund(routes, "0xFactory123...");
+ * // processedRoutes["/api"].accepts.payTo = computed proxy address
+ * // processedRoutes["/api"].extensions.refund = { info: { factoryAddress: "0xFactory123..." }, schema: {...} }
+ * ```
+ */
+export function withRefund(
+  routes: RoutesConfig,
+  factoryAddress: string,
+  createxAddress?: string,
+): RoutesConfig {
+  // Deep clone to avoid mutation
+  if (typeof routes === "object" && routes !== null && !("accepts" in routes)) {
+    // Nested RoutesConfig: Record<string, RouteConfig>
+    const nestedRoutes = routes as Record<string, RouteConfig>;
+    const processedRoutes: Record<string, RouteConfig> = {};
+
+    for (const [pattern, config] of Object.entries(nestedRoutes)) {
+      processedRoutes[pattern] = processRouteConfig(config, factoryAddress, createxAddress);
+    }
+
+    return processedRoutes;
+  } else {
+    // Single RouteConfig
+    return processRouteConfig(routes as RouteConfig, factoryAddress, createxAddress);
+  }
+}
+
+/**
+ * Gets the CreateX address for a given network.
+ * First checks if provided explicitly, then falls back to standard addresses.
+ *
+ * @param network - The network identifier (e.g., "eip155:84532")
+ * @param providedAddress - Optional CreateX address provided by user
+ * @returns The CreateX address to use
+ * @throws Error if no CreateX address can be determined
+ */
+function getCreateXAddress(network: string, providedAddress?: string): string {
+  if (providedAddress) {
+    return providedAddress;
+  }
+
+  const standardAddress = STANDARD_CREATEX_ADDRESSES[network];
+  if (standardAddress) {
+    return standardAddress;
+  }
+
+  throw new Error(
+    `CreateX address not provided and no standard address found for network ${network}. ` +
+      `Please provide createxAddress parameter or check if CreateX is deployed on this network. ` +
+      `See https://github.com/pcaversaccio/createx#createx-deployments for standard deployments.`,
+  );
+}
+
+/**
+ * Processes a single RouteConfig to transform refundable payment options.
+ *
+ * @param config - The route configuration to process
+ * @param factoryAddress - The X402DepositRelayFactory contract address
+ * @param createxAddress - The CreateX contract address (optional)
+ * @returns A new RouteConfig with refundable options transformed
+ */
+function processRouteConfig(
+  config: RouteConfig,
+  factoryAddress: string,
+  createxAddress?: string,
+): RouteConfig {
+  // Get the network from the first payment option to determine CreateX address
+  const firstOption = Array.isArray(config.accepts) ? config.accepts[0] : config.accepts;
+  const network = firstOption?.network;
+
+  if (!network) {
+    throw new Error("Payment option must have a network field to determine CreateX address");
+  }
+
+  // Get CreateX address (from parameter or standard mapping)
+  const resolvedCreatexAddress = getCreateXAddress(network, createxAddress);
+
+  // Check if any option is refundable
+  const hasRefundable = Array.isArray(config.accepts)
+    ? config.accepts.some(isRefundableOption)
+    : isRefundableOption(config.accepts);
+
+  // Build map of proxyAddress -> merchantPayout BEFORE processing options
+  // This allows us to store all merchantPayouts even if there are multiple refundable options
+  const merchantPayoutsMap: Record<string, string> = {};
+
+  if (hasRefundable) {
+    const refundableOptions = Array.isArray(config.accepts)
+      ? config.accepts.filter(isRefundableOption)
+      : isRefundableOption(config.accepts)
+        ? [config.accepts]
+        : [];
+
+    // Collect merchantPayouts from original options before processing
+    for (const option of refundableOptions) {
+      if (typeof option.payTo === "string") {
+        const merchantPayout = option.payTo; // Original merchantPayout (before we overwrite it)
+        const proxyAddress = computeRelayAddress(
+          resolvedCreatexAddress,
+          factoryAddress,
+          merchantPayout,
+        );
+        merchantPayoutsMap[proxyAddress.toLowerCase()] = merchantPayout;
+      }
+    }
+  }
+
+  // Deep clone the config and process options
+  const processedConfig: RouteConfig = {
+    ...config,
+    accepts: Array.isArray(config.accepts)
+      ? config.accepts.map(option =>
+          processPaymentOption(option, factoryAddress, resolvedCreatexAddress),
+        )
+      : processPaymentOption(config.accepts, factoryAddress, resolvedCreatexAddress),
+    extensions: {
+      ...config.extensions,
+    },
+  };
+
+  // Add refund extension if any option is refundable
+  if (hasRefundable && Object.keys(merchantPayoutsMap).length > 0) {
+    processedConfig.extensions = {
+      ...processedConfig.extensions,
+      ...declareRefundExtension(factoryAddress, merchantPayoutsMap),
+    };
+  } else if (hasRefundable) {
+    throw new Error(
+      "Refundable option must have a string payTo address. DynamicPayTo is not supported for refundable options.",
+    );
+  }
+
+  return processedConfig;
+}
+
+/**
+ * Processes a single PaymentOption to transform it if refundable.
+ *
+ * @param option - The payment option to process
+ * @param factoryAddress - The X402DepositRelayFactory contract address
+ * @param createxAddress - The CreateX contract address (required)
+ * @returns A new PaymentOption (transformed if refundable, unchanged otherwise)
+ */
+function processPaymentOption(
+  option: PaymentOption,
+  factoryAddress: string,
+  createxAddress: string,
+): PaymentOption {
+  // Check if option is refundable
+  if (isRefundableOption(option)) {
+    // Read merchantPayout directly from payTo field (before we overwrite it)
+    const merchantPayout = option.payTo;
+
+    // If it's a function (DynamicPayTo), we can't compute the address (would need to call it)
+    // For now, require it to be a string
+    if (typeof merchantPayout !== "string") {
+      throw new Error(
+        "DynamicPayTo is not supported for refundable options. Use a static address.",
+      );
+    }
+
+    // Compute proxy address using CREATE3 (no bytecode needed!)
+    const proxyAddress = computeRelayAddress(createxAddress, factoryAddress, merchantPayout);
+
+    // Deep clone the option
+    const processedOption: PaymentOption = {
+      ...option,
+      payTo: proxyAddress, // Set payTo to proxy address
+      extra: {
+        ...option.extra,
+      },
+    };
+
+    // Remove the marker since we've processed it
+    if (processedOption.extra) {
+      delete processedOption.extra[REFUND_MARKER_KEY];
+    }
+
+    return processedOption;
+  }
+
+  // Not refundable, return as-is (still clone to avoid mutation)
+  return { ...option, extra: { ...option.extra } };
+}

package/src/types.ts

@@ -0,0 +1,74 @@
+/**
+ * Type definitions for the Refund Helper Extension
+ */
+
+import type { PaymentOption } from "@x402/core/http";
+
+/**
+ * Extension identifier constant for the refund extension
+ */
+export const REFUND_EXTENSION_KEY = "refund";
+
+/**
+ * Constant for the refund marker key (internal marker)
+ * Used to identify refundable payment options
+ * The merchantPayout is read directly from the option's payTo field when processing
+ */
+export const REFUND_MARKER_KEY = "_x402_refund";
+
+/**
+ * Refund extension info structure
+ *
+ * merchantPayouts: Map of proxy address -> merchantPayout
+ * This allows multiple refundable options with different merchantPayouts
+ */
+export interface RefundExtensionInfo {
+  factoryAddress: string;
+  merchantPayouts: Record<string, string>; // proxyAddress -> merchantPayout
+}
+
+/**
+ * Refund extension structure (matches extension pattern with info and schema)
+ */
+export interface RefundExtension {
+  info: RefundExtensionInfo;
+  schema: {
+    $schema: "https://json-schema.org/draft/2020-12/schema";
+    type: "object";
+    properties: {
+      factoryAddress: {
+        type: "string";
+        pattern: "^0x[a-fA-F0-9]{40}$";
+        description: "The X402DepositRelayFactory contract address";
+      };
+      merchantPayouts: {
+        type: "object";
+        additionalProperties: {
+          type: "string";
+          pattern: "^0x[a-fA-F0-9]{40}$";
+        };
+        description: "Map of proxy address to merchant payout address";
+      };
+    };
+    required: ["factoryAddress", "merchantPayouts"];
+    additionalProperties: false;
+  };
+}
+
+/**
+ * Type guard to check if a payment option is refundable
+ * A refundable option has a marker stored in extra
+ *
+ * @param option - The payment option to check
+ * @returns True if the option is refundable
+ */
+export function isRefundableOption(option: PaymentOption): boolean {
+  // Check for marker in extra
+  return (
+    option.extra !== undefined &&
+    typeof option.extra === "object" &&
+    option.extra !== null &&
+    REFUND_MARKER_KEY in option.extra &&
+    option.extra[REFUND_MARKER_KEY] === true
+  );
+}