@x402r/refund 0.0.0

package/README.md

@@ -0,0 +1,139 @@
+# @x402r/extensions/refund
+
+Refund Helper Extension for x402 - enables merchants to route payments to DepositRelay contracts via escrow, providing refund and dispute resolution capabilities.
+
+## Installation
+
+```bash
+npm install @x402r/extensions/refund
+```
+
+### Peer Dependencies
+
+This package requires:
+- `@x402/core` (^2.0.0)
+- `@x402/evm` (^2.0.0)
+
+Install them separately:
+```bash
+npm install @x402/core @x402/evm
+```
+
+## 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 routes = {
+  '/api': {
+    accepts: refundable({
+      scheme: 'exact',
+      payTo: '0xmerchant123...',
+      price: '$0.01',
+      network: 'eip155:84532',
+    }),
+  },
+};
+
+// Process routes to route refundable payments to DepositRelay
+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';
+
+facilitator.onBeforeSettle(async (context) => {
+  const result = await settleWithRefundHelper(
+    context.paymentPayload,
+    context.paymentRequirements,
+    signer,
+  );
+
+  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
+
+## API Reference
+
+### `refundable(option: PaymentOption): PaymentOption`
+
+Marks a payment option as refundable. Returns a new PaymentOption with the refund marker set.
+
+### `withRefund(routes: RoutesConfig, factoryAddress: string, createxAddress?: string): RoutesConfig`
+
+Processes route configuration to handle refundable payment options. Computes proxy addresses using CREATE3 and sets `payTo` to proxy for all refundable options.
+
+### `settleWithRefundHelper(paymentPayload, paymentRequirements, signer): Promise<SettleResponse | null>`
+
+Helper for facilitator operators to handle refund settlements via X402DepositRelayProxy. Returns `SettleResponse` on success, `null` if not applicable.
+
+### `extractRefundInfo(paymentPayload, paymentRequirements): { factoryAddress: string; merchantPayouts: Record<string, string> } | null`
+
+Extracts refund extension info from payment payload or requirements.
+
+### `computeRelayAddress(createxAddress: string, factoryAddress: string, merchantPayout: string): string`
+
+Computes the CREATE3 address for a merchant's relay proxy.
+
+## Examples
+
+See the [examples directory](../../examples/) for complete working examples:
+- [Server Example](../../examples/server/) - Express.js server with refund-enabled endpoints
+- [Facilitator Example](../../examples/facilitator/) - Facilitator with refund settlement handling
+
+## License
+
+Apache-2.0

package/dist/cjs/index.d.ts

@@ -0,0 +1,253 @@
+import { PaymentOption, RoutesConfig } from '@x402/core/http';
+import { PaymentPayload, PaymentRequirements, SettleResponse } from '@x402/core/types';
+import { FacilitatorEvmSigner } from '@x402/evm';
+
+/**
+ * Type definitions for the Refund Helper Extension
+ */
+
+/**
+ * Extension identifier constant for the refund extension
+ */
+declare 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
+ */
+declare const REFUND_MARKER_KEY = "_x402_refund";
+/**
+ * Refund extension info structure
+ *
+ * merchantPayouts: Map of proxy address -> merchantPayout
+ * This allows multiple refundable options with different merchantPayouts
+ */
+interface RefundExtensionInfo {
+    factoryAddress: string;
+    merchantPayouts: Record<string, string>;
+}
+/**
+ * Refund extension structure (matches extension pattern with info and schema)
+ */
+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
+ */
+declare function isRefundableOption(option: PaymentOption): boolean;
+
+/**
+ * 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.
+ */
+
+/**
+ * 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...",
+ * });
+ * ```
+ */
+declare function declareRefundExtension(factoryAddress: string, merchantPayouts: Record<string, string>): Record<string, RefundExtension>;
+/**
+ * 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
+ * ```
+ */
+declare function refundable(option: PaymentOption): PaymentOption;
+/**
+ * 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: {...} }
+ * ```
+ */
+declare function withRefund(routes: RoutesConfig, factoryAddress: string, createxAddress?: string): RoutesConfig;
+
+/**
+ * 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.
+ */
+/**
+ * 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
+ * );
+ * ```
+ */
+declare function computeRelayAddress(createxAddress: string, factoryAddress: string, merchantPayout: string): string;
+
+/**
+ * Facilitator-side helpers for the Refund Helper Extension
+ *
+ * These helpers allow facilitator operators to validate refund info
+ * and handle refund settlements via X402DepositRelayProxy contracts.
+ */
+
+/**
+ * Extracts refund extension info from payment payload or requirements
+ *
+ * @param paymentPayload - The payment payload (may contain extensions)
+ * @param _ - The payment requirements (currently unused, kept for API compatibility)
+ * @returns Refund extension info if valid, null otherwise
+ */
+declare function extractRefundInfo(paymentPayload: PaymentPayload, _: PaymentRequirements): {
+    factoryAddress: string;
+    merchantPayouts: Record<string, string>;
+} | null;
+/**
+ * Helper for facilitator operators to handle refund settlements via X402DepositRelayProxy.
+ *
+ * This function:
+ * 1. Extracts refund extension info (factory address)
+ * 2. Validates factory exists
+ * 3. Reads merchantPayout and escrow directly from proxy storage
+ * 4. Checks if merchant is registered
+ * 5. Deploys relay on-demand if needed (via factory)
+ * 6. Calls proxy.executeDeposit() to deposit funds into escrow
+ *
+ * Returns null if refund is not applicable (delegates to normal flow).
+ * Throws error on execution failure or if merchant not registered (facilitator should handle in hook).
+ *
+ * @param paymentPayload - The payment payload containing authorization and signature
+ * @param paymentRequirements - The payment requirements containing refund extension
+ * @param signer - The EVM signer for contract interactions
+ * @returns SettleResponse on success, null if not applicable
+ * @throws Error on execution failure or if merchant not registered
+ *
+ * @example
+ * ```typescript
+ * facilitator.onBeforeSettle(async (context) => {
+ *   try {
+ *     const result = await settleWithRefundHelper(
+ *       context.paymentPayload,
+ *       context.paymentRequirements,
+ *       signer,
+ *     );
+ *
+ *     if (result) {
+ *       return { abort: true, reason: 'handled_by_refund_helper' };
+ *     }
+ *   } catch (error) {
+ *     // Log error but don't abort - let normal settlement proceed
+ *     console.error('Refund helper settlement failed:', error);
+ *   }
+ *
+ *   return null; // Proceed with normal settlement
+ * });
+ * ```
+ */
+declare function settleWithRefundHelper(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements, signer: FacilitatorEvmSigner): Promise<SettleResponse | null>;
+
+export { REFUND_EXTENSION_KEY, REFUND_MARKER_KEY, type RefundExtension, type RefundExtensionInfo, computeRelayAddress, declareRefundExtension, extractRefundInfo, isRefundableOption, refundable, settleWithRefundHelper, withRefund };