@relai-fi/x402 0.6.5 → 0.6.7

package/README.md

@@ -1483,6 +1483,257 @@ Both interfaces are exported from `@relai-fi/x402`.
 
 ---
 
+## Cross-Chain Bridge Flows
+
+The SDK supports transparent cross-chain payments via the RelAI bridge. There are two approaches depending on who manages the bridge logic — the **client** or the **server**.
+
+### x402 Auto-Bridge (client-side)
+
+The server is a standard x402 server. The client has a wallet on a different chain and uses `bridge: { enabled: true }` to auto-bridge.
+
+```mermaid
+sequenceDiagram
+    participant Client as Client (Solana)
+    participant Server as Server (Base)
+    participant Bridge as RelAI Bridge API
+    participant Facilitator as Facilitator
+
+    Client->>Server: GET /api/data
+    Server-->>Client: 402 (accepts: Base USDC)
+
+    Note over Client: No Base wallet → auto-bridge
+
+    Client->>Bridge: GET /bridge/info
+    Bridge-->>Client: source chains, payTo, fees
+
+    Client->>Client: Build Solana SPL transfer to bridge payTo
+    Client->>Bridge: POST /bridge/settle (sourcePayment, targetAccept)
+    Bridge->>Bridge: Co-sign & broadcast Solana tx
+    Bridge->>Bridge: Sign EIP-3009 authorization (Base)
+    Bridge-->>Client: xPayment (base64)
+
+    Client->>Server: GET /api/data + X-PAYMENT header
+    Server->>Facilitator: POST /settle (paymentPayload)
+    Facilitator->>Facilitator: Execute transferWithAuthorization on Base
+    Facilitator-->>Server: tx hash
+    Server-->>Client: 200 OK + data
+```
+
+### MPP Client-Side Bridge (evmChargeWithBridge)
+
+The server exposes a standard `evm/charge` MPP method. The client detects it's on a different chain and bridges transparently — the server never knows.
+
+```mermaid
+sequenceDiagram
+    participant Client as Client (Tempo)
+    participant Server as Server (SKALE)
+    participant Bridge as RelAI Bridge API
+    participant Facilitator as Facilitator
+
+    Client->>Server: GET /api/data
+    Server-->>Client: 402 + WWW-Authenticate: Payment (evm/charge, chainId=SKALE)
+
+    Note over Client: Source chain ≠ target chain → bridge
+
+    Client->>Bridge: GET /bridge/info
+    Bridge-->>Client: source chains, payTo, fees
+
+    Client->>Client: ERC-20 transfer on Tempo → bridge payTo
+    Client->>Client: Sign settle message (ECDSA)
+    Client->>Bridge: POST /bridge/settle (sourceTxHash, signature, targetAccept)
+    Bridge->>Bridge: Verify source tx on-chain + signature
+    Bridge->>Bridge: Sign EIP-3009 authorization (SKALE)
+    Bridge-->>Client: xPayment + targetTxId=pending
+
+    Client->>Facilitator: POST /settle (paymentPayload, paymentRequirements)
+    Facilitator->>Facilitator: Execute transferWithAuthorization on SKALE
+    Facilitator-->>Client: tx hash (SKALE)
+
+    Client->>Server: GET /api/data + Authorization: Payment (hash=SKALE tx)
+    Server->>Server: Verify ERC-20 Transfer on SKALE (standard evm/charge verify)
+    Server-->>Client: 200 OK + data
+```
+
+### MPP Server-Side Bridge (bridge/charge method)
+
+The server explicitly exposes a `bridge/charge` method alongside its direct method. The client picks bridge/charge when it can't pay directly. Use this when the target chain is not EVM (e.g. Solana).
+
+```mermaid
+sequenceDiagram
+    participant Client as Client (Tempo)
+    participant Server as Server (SKALE)
+    participant Bridge as RelAI Bridge API
+    participant Facilitator as Facilitator
+
+    Client->>Server: GET /api/data
+    Server->>Bridge: GET /bridge/info (auto-discover)
+    Server-->>Client: 402 + WWW-Authenticate: Payment<br/>(evm/charge + bridge/charge)
+
+    Note over Client: Can't match evm/charge → picks bridge/charge
+
+    Client->>Client: ERC-20 transfer on Tempo → bridge payTo
+    Client->>Client: Sign settle message (ECDSA)
+    Client->>Bridge: POST /bridge/settle (sourceTxHash, signature, targetAccept)
+    Bridge->>Bridge: Verify source tx on-chain + signature
+    Bridge->>Bridge: Sign EIP-3009 authorization (SKALE)
+    Bridge-->>Client: xPayment + targetTxId=pending
+
+    Client->>Facilitator: POST /settle (paymentPayload, paymentRequirements)
+    Facilitator->>Facilitator: Execute transferWithAuthorization on SKALE
+    Facilitator-->>Client: tx hash (SKALE)
+
+    Client->>Server: Authorization: Payment (targetTxHash=SKALE tx)
+    Server->>Server: bridge/charge verify() — check ERC-20 Transfer on SKALE
+    Server-->>Client: 200 OK + data
+```
+
+### When to use which approach
+
+| Approach | Server config | Client config | Best for |
+|----------|--------------|---------------|----------|
+| **x402 auto-bridge** | Standard x402 (no change) | `bridge: { enabled: true }` | Solana client → EVM server |
+| **MPP client-side** | Standard `evm/charge` (no change) | `evmChargeWithBridge()` | EVM client → different EVM server |
+| **MPP server-side** | `evm/charge` + `bridge/charge` | `bridgeCharge()` client | Any client → Solana server, or when server wants to control bridge options |
+
+See [`examples/bridge/`](./examples/bridge/) for runnable examples of each approach.
+
+---
+
+## Payment Codes
+
+BLIK-style one-time payment codes — pre-signed EIP-3009 tokens that can be generated in advance and redeemed later, without a wallet at redemption time. Ideal for AI agents and walletless buyers.
+
+```typescript
+import {
+  createPrivateKeySigner,
+  generatePaymentCode,
+  generatePaymentCodesBatch,
+  redeemPaymentCode,
+  getPaymentCode,
+  cancelPaymentCode,
+} from '@relai-fi/x402';
+import { ethers } from 'ethers';
+
+const config = { facilitatorUrl: 'https://relai.fi/facilitator' };
+
+// ── Create a signer from a private key (agent / server-side) ──────────────
+const signer = createPrivateKeySigner(process.env.AGENT_PRIVATE_KEY!);
+
+// ── Generate a single payment code ($10 USDC, expires in 24 h) ───────────
+const code = await generatePaymentCode(config, signer, {
+  amount:  10_000_000,       // $10.00 in µUSDC
+  network: 'base-sepolia',
+});
+console.log('Code:', code.code);  // "ABCD1234"
+
+// ── Batch generate 5 codes (requires API key) ─────────────────────────────
+const batch = await generatePaymentCodesBatch(config, signer, {
+  amount:   5_000_000,
+  network:  'base-sepolia',
+  count:    5,
+  apiKey:   process.env.RELAI_API_KEY!,
+});
+
+// ── Check status ──────────────────────────────────────────────────────────
+const status = await getPaymentCode(config, 'ABCD1234');
+console.log(status.redeemed, status.expired, status.value);
+
+// ── Redeem (settle USDC to a payee) ──────────────────────────────────────
+const result = await redeemPaymentCode(config, 'ABCD1234', {
+  payee: '0xMerchantWallet',
+});
+console.log('Explorer:', result.explorerUrl);
+
+// ── Cancel before use ─────────────────────────────────────────────────────
+await cancelPaymentCode(config, 'ABCD1234');
+```
+
+### `generatePaymentCode` options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `amount` | `number` | — | Amount in µUSDC (1 USDC = 1 000 000) |
+| `network` | `string` | `'base-sepolia'` | Settlement network |
+| `description` | `string` | — | Optional note stored with the code |
+| `payee` | `string` | — | Lock the code to a specific payee address |
+| `ttl` | `number` | `86400` | Expiry in seconds (default: 24 h) |
+
+### `RedeemResult` fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | `boolean` | Settlement succeeded |
+| `code` | `string` | The redeemed code |
+| `l2TxHash` | `string` | On-chain tx hash |
+| `explorerUrl` | `string` | Block explorer link |
+| `amount` | `string` | Amount settled (µUSDC) |
+| `change` | `string?` | Remainder returned to buyer (µUSDC), if partial |
+| `changeMode` | `'code' \| 'wallet'?` | How change was returned |
+| `changeCode` | `string?` | New payment code for change (when `changeMode === 'code'`) |
+
+---
+
+## Payment Requests
+
+Merchant-initiated invoices — the merchant creates a payment request, shares the code or link, and any buyer (or agent) can pay it.
+
+```typescript
+import {
+  createPayRequest,
+  getPayRequest,
+  payPayRequest,
+  payPayRequestWithCode,
+} from '@relai-fi/x402';
+
+const config = { facilitatorUrl: 'https://relai.fi/facilitator' };
+
+// ── Merchant: create an invoice ───────────────────────────────────────────
+const req = await createPayRequest(config, {
+  to:          '0xMerchantWallet',
+  amount:      5_000_000,       // $5.00 USDC
+  network:     'base-sepolia',
+  description: 'Order #42',
+  ttl:         3600,            // expires in 1 h
+});
+console.log('Invoice code:', req.code);    // "MW78SGTW"
+console.log('Pay URL:', req.payUrl);       // "https://relai.fi/pay#MW78SGTW"
+
+// ── Buyer: read the request ────────────────────────────────────────────────
+const info = await getPayRequest(config, 'MW78SGTW');
+console.log(`$${Number(info.amount) / 1e6} USDC → ${info.to}`);
+
+// ── Buyer: pay with EIP-3009 signer (has wallet) ─────────────────────────
+const signer = createPrivateKeySigner(process.env.BUYER_PRIVATE_KEY!);
+const paid = await payPayRequest(config, 'MW78SGTW', signer);
+console.log('Explorer:', paid.explorerUrl);
+
+// ── Buyer: pay using a pre-generated payment code (no wallet at payment time)
+const result = await payPayRequestWithCode(config, 'MW78SGTW', 'MYBLIK78');
+console.log('Success:', result.success);
+console.log('Explorer:', result.explorerUrl);
+
+// If the code covers more than the invoice → change is returned as a new code
+if (result.changeCode) {
+  console.log(`Change $${Number(result.change) / 1e6} USDC → code: ${result.changeCode}`);
+}
+```
+
+### `payPayRequestWithCode` options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `returnChange` | `'code' \| 'wallet'` | `'code'` | How to return surplus when code value > invoice |
+| `allowOverpayment` | `boolean` | `true` | If `false`, throws when code value ≠ invoice amount |
+
+**`returnChange` behaviour:**
+
+| Value | Mechanism | Requires buyer wallet? |
+|-------|-----------|----------------------|
+| `'code'` (default) | Relayer pays merchant, generates a new code for the remainder | No |
+| `'wallet'` | `PaymentSettler.settleExact()` — merchant + change in one atomic tx | Yes (`from` address) |
+
+---
+
 ## Development
 
 ```bash

package/dist/bridge.cjs

@@ -0,0 +1,109 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/bridge.ts
+var bridge_exports = {};
+__export(bridge_exports, {
+  DEFAULT_EVM_RPC: () => DEFAULT_EVM_RPC,
+  computeSourceAmount: () => computeSourceAmount,
+  getBridgeInfo: () => getBridgeInfo,
+  selectSourceChain: () => selectSourceChain,
+  settleBridge: () => settleBridge
+});
+module.exports = __toCommonJS(bridge_exports);
+var RELAI_API_BASE = "https://api.relai.fi";
+var _cacheMap = /* @__PURE__ */ new Map();
+var CACHE_TTL = 5 * 60 * 1e3;
+async function getBridgeInfo(baseUrl = RELAI_API_BASE) {
+  const key = baseUrl.replace(/\/$/, "");
+  const now = Date.now();
+  const cached = _cacheMap.get(key);
+  if (cached && now - cached.time < CACHE_TTL) return cached.info;
+  const url = `${key}/bridge/info`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    if (cached) return cached.info;
+    throw new Error(`[relai:bridge] Failed to fetch ${url}: ${res.status}`);
+  }
+  const data = await res.json();
+  const info = {
+    settleEndpoint: data.settleEndpoint,
+    supportedSourceChains: data.supportedSourceChains || [],
+    supportedSourceAssets: data.supportedSourceAssets || [],
+    payTo: data.payTo || {},
+    feePayerSvm: data.feePayerSvm ?? null,
+    feeBps: data.feeBps ?? 100,
+    paymentFacilitator: data.paymentFacilitator || "https://facilitator.x402.fi"
+  };
+  _cacheMap.set(key, { info, time: now });
+  return info;
+}
+async function settleBridge(settleEndpoint, body) {
+  const res = await fetch(settleEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(`[relai:bridge] settle failed: ${err.error || res.status}${err.details ? " \u2014 " + err.details : ""}`);
+  }
+  return res.json();
+}
+function selectSourceChain(supportedChains, hasEvmWallet, hasSolanaWallet, preferredSourceChainId) {
+  if (preferredSourceChainId && hasEvmWallet) {
+    const preferred = `eip155:${preferredSourceChainId}`;
+    if (supportedChains.includes(preferred)) {
+      return { type: "evm", chain: preferred };
+    }
+  }
+  if (hasSolanaWallet) {
+    const sol = supportedChains.find((c) => c.startsWith("solana:"));
+    if (sol) return { type: "solana", chain: sol };
+  }
+  if (hasEvmWallet) {
+    for (const chain of supportedChains) {
+      if (chain.startsWith("eip155:")) {
+        return { type: "evm", chain };
+      }
+    }
+  }
+  return null;
+}
+function computeSourceAmount(targetAmount, feeBps) {
+  const fee = targetAmount * BigInt(feeBps) / 10000n;
+  return targetAmount + fee;
+}
+var DEFAULT_EVM_RPC = {
+  "eip155:8453": "https://mainnet.base.org",
+  "eip155:137": "https://polygon-rpc.com",
+  "eip155:1": "https://eth.llamarpc.com",
+  "eip155:42161": "https://arb1.arbitrum.io/rpc",
+  "eip155:43114": "https://api.avax.network/ext/bc/C/rpc",
+  "eip155:1187947933": "https://skale-base.skalenodes.com/v1/base"
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_EVM_RPC,
+  computeSourceAmount,
+  getBridgeInfo,
+  selectSourceChain,
+  settleBridge
+});
+//# sourceMappingURL=bridge.cjs.map

package/dist/bridge.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bridge.ts"],"sourcesContent":["/**\n * Core bridge utilities — shared between x402 and MPP clients.\n *\n * Auto-discovers bridge info from the RelAI API and provides helpers\n * for executing cross-chain payments transparently.\n *\n * Usage (MPP):\n * ```ts\n * import { evmChargeWithBridge } from '@relai-fi/x402/mpp/with-bridge'\n * ```\n *\n * Usage (x402):\n * ```ts\n * import { createX402Client } from '@relai-fi/x402'\n * const client = createX402Client({ ..., bridge: { enabled: true } })\n * ```\n */\n\nconst RELAI_API_BASE = 'https://api.relai.fi'\n\nexport interface BridgeInfo {\n  settleEndpoint: string\n  supportedSourceChains: string[]\n  supportedSourceAssets: string[]\n  payTo: Record<string, string>\n  feePayerSvm: string | null\n  feeBps: number\n  paymentFacilitator: string\n}\n\nexport interface BridgeSettleRequest {\n  /** x402 mode: base64-encoded payment header */\n  sourcePayment?: string\n  /** MPP mode: source tx hash */\n  sourceTxHash?: string\n  /** MPP mode: wallet address that sent the source tx */\n  senderAddress?: string\n  /** MPP mode: signature of (sourceTxHash + JSON(targetAccept)) */\n  senderSignature?: string\n  /** CAIP-2 source chain identifier */\n  sourceChain: string\n  targetAccept: {\n    scheme: 'exact'\n    network: string\n    asset: string\n    payTo: string\n    amount: string\n  }\n  /** x402 payment requirements (full 402 body) — needed by settle for x402 flow */\n  requirements?: any\n  resource?: string\n  paymentFacilitator?: string | null\n}\n\nexport interface BridgeSettleResponse {\n  success?: boolean\n  targetTxId?: string\n  sourceTxId?: string\n  /** x402 payment header (returned by x402-flavored settle) */\n  xPayment?: string\n}\n\n// ── Cache (keyed by base URL) ──────────────────────────────────────────\n\nconst _cacheMap = new Map<string, { info: BridgeInfo; time: number }>()\nconst CACHE_TTL = 5 * 60 * 1000 // 5 minutes\n\n/**\n * Fetch bridge info from the RelAI API (cached per base URL for 5 minutes).\n */\nexport async function getBridgeInfo(baseUrl = RELAI_API_BASE): Promise<BridgeInfo> {\n  const key = baseUrl.replace(/\\/$/, '')\n  const now = Date.now()\n  const cached = _cacheMap.get(key)\n  if (cached && now - cached.time < CACHE_TTL) return cached.info\n\n  const url = `${key}/bridge/info`\n  const res = await fetch(url)\n  if (!res.ok) {\n    if (cached) return cached.info // stale cache better than failure\n    throw new Error(`[relai:bridge] Failed to fetch ${url}: ${res.status}`)\n  }\n\n  const data = (await res.json()) as any\n  const info: BridgeInfo = {\n    settleEndpoint: data.settleEndpoint,\n    supportedSourceChains: data.supportedSourceChains || [],\n    supportedSourceAssets: data.supportedSourceAssets || [],\n    payTo: data.payTo || {},\n    feePayerSvm: data.feePayerSvm ?? null,\n    feeBps: data.feeBps ?? 100,\n    paymentFacilitator: data.paymentFacilitator || 'https://facilitator.x402.fi',\n  }\n  _cacheMap.set(key, { info, time: now })\n  return info\n}\n\n/**\n * Call the bridge settle endpoint.\n */\nexport async function settleBridge(\n  settleEndpoint: string,\n  body: BridgeSettleRequest,\n): Promise<BridgeSettleResponse> {\n  const res = await fetch(settleEndpoint, {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/json' },\n    body: JSON.stringify(body),\n  })\n\n  if (!res.ok) {\n    const err = (await res.json().catch(() => ({}))) as any\n    throw new Error(`[relai:bridge] settle failed: ${err.error || res.status}${err.details ? ' — ' + err.details : ''}`)\n  }\n\n  return res.json() as Promise<BridgeSettleResponse>\n}\n\n/**\n * Select a source chain from supported chains that matches the available wallet.\n */\nexport function selectSourceChain(\n  supportedChains: string[],\n  hasEvmWallet: boolean,\n  hasSolanaWallet: boolean,\n  preferredSourceChainId?: number,\n): { type: 'evm' | 'solana'; chain: string } | null {\n  // If a specific source chain is preferred, try it first\n  if (preferredSourceChainId && hasEvmWallet) {\n    const preferred = `eip155:${preferredSourceChainId}`\n    if (supportedChains.includes(preferred)) {\n      return { type: 'evm', chain: preferred }\n    }\n  }\n\n  // Solana first (lower fees)\n  if (hasSolanaWallet) {\n    const sol = supportedChains.find((c) => c.startsWith('solana:'))\n    if (sol) return { type: 'solana', chain: sol }\n  }\n\n  // Then any EVM chain\n  if (hasEvmWallet) {\n    for (const chain of supportedChains) {\n      if (chain.startsWith('eip155:')) {\n        return { type: 'evm', chain }\n      }\n    }\n  }\n\n  return null\n}\n\n/**\n * Compute source amount including bridge fee.\n */\nexport function computeSourceAmount(targetAmount: bigint, feeBps: number): bigint {\n  const fee = (targetAmount * BigInt(feeBps)) / 10000n\n  return targetAmount + fee\n}\n\n// Known EVM RPC URLs (fallback)\nexport const DEFAULT_EVM_RPC: Record<string, string> = {\n  'eip155:8453': 'https://mainnet.base.org',\n  'eip155:137': 'https://polygon-rpc.com',\n  'eip155:1': 'https://eth.llamarpc.com',\n  'eip155:42161': 'https://arb1.arbitrum.io/rpc',\n  'eip155:43114': 'https://api.avax.network/ext/bc/C/rpc',\n  'eip155:1187947933': 'https://skale-base.skalenodes.com/v1/base',\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAkBA,IAAM,iBAAiB;AA8CvB,IAAM,YAAY,oBAAI,IAAgD;AACtE,IAAM,YAAY,IAAI,KAAK;AAK3B,eAAsB,cAAc,UAAU,gBAAqC;AACjF,QAAM,MAAM,QAAQ,QAAQ,OAAO,EAAE;AACrC,QAAM,MAAM,KAAK,IAAI;AACrB,QAAM,SAAS,UAAU,IAAI,GAAG;AAChC,MAAI,UAAU,MAAM,OAAO,OAAO,UAAW,QAAO,OAAO;AAE3D,QAAM,MAAM,GAAG,GAAG;AAClB,QAAM,MAAM,MAAM,MAAM,GAAG;AAC3B,MAAI,CAAC,IAAI,IAAI;AACX,QAAI,OAAQ,QAAO,OAAO;AAC1B,UAAM,IAAI,MAAM,kCAAkC,GAAG,KAAK,IAAI,MAAM,EAAE;AAAA,EACxE;AAEA,QAAM,OAAQ,MAAM,IAAI,KAAK;AAC7B,QAAM,OAAmB;AAAA,IACvB,gBAAgB,KAAK;AAAA,IACrB,uBAAuB,KAAK,yBAAyB,CAAC;AAAA,IACtD,uBAAuB,KAAK,yBAAyB,CAAC;AAAA,IACtD,OAAO,KAAK,SAAS,CAAC;AAAA,IACtB,aAAa,KAAK,eAAe;AAAA,IACjC,QAAQ,KAAK,UAAU;AAAA,IACvB,oBAAoB,KAAK,sBAAsB;AAAA,EACjD;AACA,YAAU,IAAI,KAAK,EAAE,MAAM,MAAM,IAAI,CAAC;AACtC,SAAO;AACT;AAKA,eAAsB,aACpB,gBACA,MAC+B;AAC/B,QAAM,MAAM,MAAM,MAAM,gBAAgB;AAAA,IACtC,QAAQ;AAAA,IACR,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,IAC9C,MAAM,KAAK,UAAU,IAAI;AAAA,EAC3B,CAAC;AAED,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,MAAO,MAAM,IAAI,KAAK,EAAE,MAAM,OAAO,CAAC,EAAE;AAC9C,UAAM,IAAI,MAAM,iCAAiC,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,UAAU,aAAQ,IAAI,UAAU,EAAE,EAAE;AAAA,EACrH;AAEA,SAAO,IAAI,KAAK;AAClB;AAKO,SAAS,kBACd,iBACA,cACA,iBACA,wBACkD;AAElD,MAAI,0BAA0B,cAAc;AAC1C,UAAM,YAAY,UAAU,sBAAsB;AAClD,QAAI,gBAAgB,SAAS,SAAS,GAAG;AACvC,aAAO,EAAE,MAAM,OAAO,OAAO,UAAU;AAAA,IACzC;AAAA,EACF;AAGA,MAAI,iBAAiB;AACnB,UAAM,MAAM,gBAAgB,KAAK,CAAC,MAAM,EAAE,WAAW,SAAS,CAAC;AAC/D,QAAI,IAAK,QAAO,EAAE,MAAM,UAAU,OAAO,IAAI;AAAA,EAC/C;AAGA,MAAI,cAAc;AAChB,eAAW,SAAS,iBAAiB;AACnC,UAAI,MAAM,WAAW,SAAS,GAAG;AAC/B,eAAO,EAAE,MAAM,OAAO,MAAM;AAAA,MAC9B;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AAKO,SAAS,oBAAoB,cAAsB,QAAwB;AAChF,QAAM,MAAO,eAAe,OAAO,MAAM,IAAK;AAC9C,SAAO,eAAe;AACxB;AAGO,IAAM,kBAA0C;AAAA,EACrD,eAAe;AAAA,EACf,cAAc;AAAA,EACd,YAAY;AAAA,EACZ,gBAAgB;AAAA,EAChB,gBAAgB;AAAA,EAChB,qBAAqB;AACvB;","names":[]}

package/dist/bridge.d.cts

@@ -0,0 +1,78 @@
+/**
+ * Core bridge utilities — shared between x402 and MPP clients.
+ *
+ * Auto-discovers bridge info from the RelAI API and provides helpers
+ * for executing cross-chain payments transparently.
+ *
+ * Usage (MPP):
+ * ```ts
+ * import { evmChargeWithBridge } from '@relai-fi/x402/mpp/with-bridge'
+ * ```
+ *
+ * Usage (x402):
+ * ```ts
+ * import { createX402Client } from '@relai-fi/x402'
+ * const client = createX402Client({ ..., bridge: { enabled: true } })
+ * ```
+ */
+interface BridgeInfo {
+    settleEndpoint: string;
+    supportedSourceChains: string[];
+    supportedSourceAssets: string[];
+    payTo: Record<string, string>;
+    feePayerSvm: string | null;
+    feeBps: number;
+    paymentFacilitator: string;
+}
+interface BridgeSettleRequest {
+    /** x402 mode: base64-encoded payment header */
+    sourcePayment?: string;
+    /** MPP mode: source tx hash */
+    sourceTxHash?: string;
+    /** MPP mode: wallet address that sent the source tx */
+    senderAddress?: string;
+    /** MPP mode: signature of (sourceTxHash + JSON(targetAccept)) */
+    senderSignature?: string;
+    /** CAIP-2 source chain identifier */
+    sourceChain: string;
+    targetAccept: {
+        scheme: 'exact';
+        network: string;
+        asset: string;
+        payTo: string;
+        amount: string;
+    };
+    /** x402 payment requirements (full 402 body) — needed by settle for x402 flow */
+    requirements?: any;
+    resource?: string;
+    paymentFacilitator?: string | null;
+}
+interface BridgeSettleResponse {
+    success?: boolean;
+    targetTxId?: string;
+    sourceTxId?: string;
+    /** x402 payment header (returned by x402-flavored settle) */
+    xPayment?: string;
+}
+/**
+ * Fetch bridge info from the RelAI API (cached per base URL for 5 minutes).
+ */
+declare function getBridgeInfo(baseUrl?: string): Promise<BridgeInfo>;
+/**
+ * Call the bridge settle endpoint.
+ */
+declare function settleBridge(settleEndpoint: string, body: BridgeSettleRequest): Promise<BridgeSettleResponse>;
+/**
+ * Select a source chain from supported chains that matches the available wallet.
+ */
+declare function selectSourceChain(supportedChains: string[], hasEvmWallet: boolean, hasSolanaWallet: boolean, preferredSourceChainId?: number): {
+    type: 'evm' | 'solana';
+    chain: string;
+} | null;
+/**
+ * Compute source amount including bridge fee.
+ */
+declare function computeSourceAmount(targetAmount: bigint, feeBps: number): bigint;
+declare const DEFAULT_EVM_RPC: Record<string, string>;
+
+export { type BridgeInfo, type BridgeSettleRequest, type BridgeSettleResponse, DEFAULT_EVM_RPC, computeSourceAmount, getBridgeInfo, selectSourceChain, settleBridge };

package/dist/bridge.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Core bridge utilities — shared between x402 and MPP clients.
+ *
+ * Auto-discovers bridge info from the RelAI API and provides helpers
+ * for executing cross-chain payments transparently.
+ *
+ * Usage (MPP):
+ * ```ts
+ * import { evmChargeWithBridge } from '@relai-fi/x402/mpp/with-bridge'
+ * ```
+ *
+ * Usage (x402):
+ * ```ts
+ * import { createX402Client } from '@relai-fi/x402'
+ * const client = createX402Client({ ..., bridge: { enabled: true } })
+ * ```
+ */
+interface BridgeInfo {
+    settleEndpoint: string;
+    supportedSourceChains: string[];
+    supportedSourceAssets: string[];
+    payTo: Record<string, string>;
+    feePayerSvm: string | null;
+    feeBps: number;
+    paymentFacilitator: string;
+}
+interface BridgeSettleRequest {
+    /** x402 mode: base64-encoded payment header */
+    sourcePayment?: string;
+    /** MPP mode: source tx hash */
+    sourceTxHash?: string;
+    /** MPP mode: wallet address that sent the source tx */
+    senderAddress?: string;
+    /** MPP mode: signature of (sourceTxHash + JSON(targetAccept)) */
+    senderSignature?: string;
+    /** CAIP-2 source chain identifier */
+    sourceChain: string;
+    targetAccept: {
+        scheme: 'exact';
+        network: string;
+        asset: string;
+        payTo: string;
+        amount: string;
+    };
+    /** x402 payment requirements (full 402 body) — needed by settle for x402 flow */
+    requirements?: any;
+    resource?: string;
+    paymentFacilitator?: string | null;
+}
+interface BridgeSettleResponse {
+    success?: boolean;
+    targetTxId?: string;
+    sourceTxId?: string;
+    /** x402 payment header (returned by x402-flavored settle) */
+    xPayment?: string;
+}
+/**
+ * Fetch bridge info from the RelAI API (cached per base URL for 5 minutes).
+ */
+declare function getBridgeInfo(baseUrl?: string): Promise<BridgeInfo>;
+/**
+ * Call the bridge settle endpoint.
+ */
+declare function settleBridge(settleEndpoint: string, body: BridgeSettleRequest): Promise<BridgeSettleResponse>;
+/**
+ * Select a source chain from supported chains that matches the available wallet.
+ */
+declare function selectSourceChain(supportedChains: string[], hasEvmWallet: boolean, hasSolanaWallet: boolean, preferredSourceChainId?: number): {
+    type: 'evm' | 'solana';
+    chain: string;
+} | null;
+/**
+ * Compute source amount including bridge fee.
+ */
+declare function computeSourceAmount(targetAmount: bigint, feeBps: number): bigint;
+declare const DEFAULT_EVM_RPC: Record<string, string>;
+
+export { type BridgeInfo, type BridgeSettleRequest, type BridgeSettleResponse, DEFAULT_EVM_RPC, computeSourceAmount, getBridgeInfo, selectSourceChain, settleBridge };

package/dist/bridge.js

@@ -0,0 +1,80 @@
+// src/bridge.ts
+var RELAI_API_BASE = "https://api.relai.fi";
+var _cacheMap = /* @__PURE__ */ new Map();
+var CACHE_TTL = 5 * 60 * 1e3;
+async function getBridgeInfo(baseUrl = RELAI_API_BASE) {
+  const key = baseUrl.replace(/\/$/, "");
+  const now = Date.now();
+  const cached = _cacheMap.get(key);
+  if (cached && now - cached.time < CACHE_TTL) return cached.info;
+  const url = `${key}/bridge/info`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    if (cached) return cached.info;
+    throw new Error(`[relai:bridge] Failed to fetch ${url}: ${res.status}`);
+  }
+  const data = await res.json();
+  const info = {
+    settleEndpoint: data.settleEndpoint,
+    supportedSourceChains: data.supportedSourceChains || [],
+    supportedSourceAssets: data.supportedSourceAssets || [],
+    payTo: data.payTo || {},
+    feePayerSvm: data.feePayerSvm ?? null,
+    feeBps: data.feeBps ?? 100,
+    paymentFacilitator: data.paymentFacilitator || "https://facilitator.x402.fi"
+  };
+  _cacheMap.set(key, { info, time: now });
+  return info;
+}
+async function settleBridge(settleEndpoint, body) {
+  const res = await fetch(settleEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(`[relai:bridge] settle failed: ${err.error || res.status}${err.details ? " \u2014 " + err.details : ""}`);
+  }
+  return res.json();
+}
+function selectSourceChain(supportedChains, hasEvmWallet, hasSolanaWallet, preferredSourceChainId) {
+  if (preferredSourceChainId && hasEvmWallet) {
+    const preferred = `eip155:${preferredSourceChainId}`;
+    if (supportedChains.includes(preferred)) {
+      return { type: "evm", chain: preferred };
+    }
+  }
+  if (hasSolanaWallet) {
+    const sol = supportedChains.find((c) => c.startsWith("solana:"));
+    if (sol) return { type: "solana", chain: sol };
+  }
+  if (hasEvmWallet) {
+    for (const chain of supportedChains) {
+      if (chain.startsWith("eip155:")) {
+        return { type: "evm", chain };
+      }
+    }
+  }
+  return null;
+}
+function computeSourceAmount(targetAmount, feeBps) {
+  const fee = targetAmount * BigInt(feeBps) / 10000n;
+  return targetAmount + fee;
+}
+var DEFAULT_EVM_RPC = {
+  "eip155:8453": "https://mainnet.base.org",
+  "eip155:137": "https://polygon-rpc.com",
+  "eip155:1": "https://eth.llamarpc.com",
+  "eip155:42161": "https://arb1.arbitrum.io/rpc",
+  "eip155:43114": "https://api.avax.network/ext/bc/C/rpc",
+  "eip155:1187947933": "https://skale-base.skalenodes.com/v1/base"
+};
+export {
+  DEFAULT_EVM_RPC,
+  computeSourceAmount,
+  getBridgeInfo,
+  selectSourceChain,
+  settleBridge
+};
+//# sourceMappingURL=bridge.js.map

package/dist/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bridge.ts"],"sourcesContent":["/**\n * Core bridge utilities — shared between x402 and MPP clients.\n *\n * Auto-discovers bridge info from the RelAI API and provides helpers\n * for executing cross-chain payments transparently.\n *\n * Usage (MPP):\n * ```ts\n * import { evmChargeWithBridge } from '@relai-fi/x402/mpp/with-bridge'\n * ```\n *\n * Usage (x402):\n * ```ts\n * import { createX402Client } from '@relai-fi/x402'\n * const client = createX402Client({ ..., bridge: { enabled: true } })\n * ```\n */\n\nconst RELAI_API_BASE = 'https://api.relai.fi'\n\nexport interface BridgeInfo {\n  settleEndpoint: string\n  supportedSourceChains: string[]\n  supportedSourceAssets: string[]\n  payTo: Record<string, string>\n  feePayerSvm: string | null\n  feeBps: number\n  paymentFacilitator: string\n}\n\nexport interface BridgeSettleRequest {\n  /** x402 mode: base64-encoded payment header */\n  sourcePayment?: string\n  /** MPP mode: source tx hash */\n  sourceTxHash?: string\n  /** MPP mode: wallet address that sent the source tx */\n  senderAddress?: string\n  /** MPP mode: signature of (sourceTxHash + JSON(targetAccept)) */\n  senderSignature?: string\n  /** CAIP-2 source chain identifier */\n  sourceChain: string\n  targetAccept: {\n    scheme: 'exact'\n    network: string\n    asset: string\n    payTo: string\n    amount: string\n  }\n  /** x402 payment requirements (full 402 body) — needed by settle for x402 flow */\n  requirements?: any\n  resource?: string\n  paymentFacilitator?: string | null\n}\n\nexport interface BridgeSettleResponse {\n  success?: boolean\n  targetTxId?: string\n  sourceTxId?: string\n  /** x402 payment header (returned by x402-flavored settle) */\n  xPayment?: string\n}\n\n// ── Cache (keyed by base URL) ──────────────────────────────────────────\n\nconst _cacheMap = new Map<string, { info: BridgeInfo; time: number }>()\nconst CACHE_TTL = 5 * 60 * 1000 // 5 minutes\n\n/**\n * Fetch bridge info from the RelAI API (cached per base URL for 5 minutes).\n */\nexport async function getBridgeInfo(baseUrl = RELAI_API_BASE): Promise<BridgeInfo> {\n  const key = baseUrl.replace(/\\/$/, '')\n  const now = Date.now()\n  const cached = _cacheMap.get(key)\n  if (cached && now - cached.time < CACHE_TTL) return cached.info\n\n  const url = `${key}/bridge/info`\n  const res = await fetch(url)\n  if (!res.ok) {\n    if (cached) return cached.info // stale cache better than failure\n    throw new Error(`[relai:bridge] Failed to fetch ${url}: ${res.status}`)\n  }\n\n  const data = (await res.json()) as any\n  const info: BridgeInfo = {\n    settleEndpoint: data.settleEndpoint,\n    supportedSourceChains: data.supportedSourceChains || [],\n    supportedSourceAssets: data.supportedSourceAssets || [],\n    payTo: data.payTo || {},\n    feePayerSvm: data.feePayerSvm ?? null,\n    feeBps: data.feeBps ?? 100,\n    paymentFacilitator: data.paymentFacilitator || 'https://facilitator.x402.fi',\n  }\n  _cacheMap.set(key, { info, time: now })\n  return info\n}\n\n/**\n * Call the bridge settle endpoint.\n */\nexport async function settleBridge(\n  settleEndpoint: string,\n  body: BridgeSettleRequest,\n): Promise<BridgeSettleResponse> {\n  const res = await fetch(settleEndpoint, {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/json' },\n    body: JSON.stringify(body),\n  })\n\n  if (!res.ok) {\n    const err = (await res.json().catch(() => ({}))) as any\n    throw new Error(`[relai:bridge] settle failed: ${err.error || res.status}${err.details ? ' — ' + err.details : ''}`)\n  }\n\n  return res.json() as Promise<BridgeSettleResponse>\n}\n\n/**\n * Select a source chain from supported chains that matches the available wallet.\n */\nexport function selectSourceChain(\n  supportedChains: string[],\n  hasEvmWallet: boolean,\n  hasSolanaWallet: boolean,\n  preferredSourceChainId?: number,\n): { type: 'evm' | 'solana'; chain: string } | null {\n  // If a specific source chain is preferred, try it first\n  if (preferredSourceChainId && hasEvmWallet) {\n    const preferred = `eip155:${preferredSourceChainId}`\n    if (supportedChains.includes(preferred)) {\n      return { type: 'evm', chain: preferred }\n    }\n  }\n\n  // Solana first (lower fees)\n  if (hasSolanaWallet) {\n    const sol = supportedChains.find((c) => c.startsWith('solana:'))\n    if (sol) return { type: 'solana', chain: sol }\n  }\n\n  // Then any EVM chain\n  if (hasEvmWallet) {\n    for (const chain of supportedChains) {\n      if (chain.startsWith('eip155:')) {\n        return { type: 'evm', chain }\n      }\n    }\n  }\n\n  return null\n}\n\n/**\n * Compute source amount including bridge fee.\n */\nexport function computeSourceAmount(targetAmount: bigint, feeBps: number): bigint {\n  const fee = (targetAmount * BigInt(feeBps)) / 10000n\n  return targetAmount + fee\n}\n\n// Known EVM RPC URLs (fallback)\nexport const DEFAULT_EVM_RPC: Record<string, string> = {\n  'eip155:8453': 'https://mainnet.base.org',\n  'eip155:137': 'https://polygon-rpc.com',\n  'eip155:1': 'https://eth.llamarpc.com',\n  'eip155:42161': 'https://arb1.arbitrum.io/rpc',\n  'eip155:43114': 'https://api.avax.network/ext/bc/C/rpc',\n  'eip155:1187947933': 'https://skale-base.skalenodes.com/v1/base',\n}\n"],"mappings":";AAkBA,IAAM,iBAAiB;AA8CvB,IAAM,YAAY,oBAAI,IAAgD;AACtE,IAAM,YAAY,IAAI,KAAK;AAK3B,eAAsB,cAAc,UAAU,gBAAqC;AACjF,QAAM,MAAM,QAAQ,QAAQ,OAAO,EAAE;AACrC,QAAM,MAAM,KAAK,IAAI;AACrB,QAAM,SAAS,UAAU,IAAI,GAAG;AAChC,MAAI,UAAU,MAAM,OAAO,OAAO,UAAW,QAAO,OAAO;AAE3D,QAAM,MAAM,GAAG,GAAG;AAClB,QAAM,MAAM,MAAM,MAAM,GAAG;AAC3B,MAAI,CAAC,IAAI,IAAI;AACX,QAAI,OAAQ,QAAO,OAAO;AAC1B,UAAM,IAAI,MAAM,kCAAkC,GAAG,KAAK,IAAI,MAAM,EAAE;AAAA,EACxE;AAEA,QAAM,OAAQ,MAAM,IAAI,KAAK;AAC7B,QAAM,OAAmB;AAAA,IACvB,gBAAgB,KAAK;AAAA,IACrB,uBAAuB,KAAK,yBAAyB,CAAC;AAAA,IACtD,uBAAuB,KAAK,yBAAyB,CAAC;AAAA,IACtD,OAAO,KAAK,SAAS,CAAC;AAAA,IACtB,aAAa,KAAK,eAAe;AAAA,IACjC,QAAQ,KAAK,UAAU;AAAA,IACvB,oBAAoB,KAAK,sBAAsB;AAAA,EACjD;AACA,YAAU,IAAI,KAAK,EAAE,MAAM,MAAM,IAAI,CAAC;AACtC,SAAO;AACT;AAKA,eAAsB,aACpB,gBACA,MAC+B;AAC/B,QAAM,MAAM,MAAM,MAAM,gBAAgB;AAAA,IACtC,QAAQ;AAAA,IACR,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,IAC9C,MAAM,KAAK,UAAU,IAAI;AAAA,EAC3B,CAAC;AAED,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,MAAO,MAAM,IAAI,KAAK,EAAE,MAAM,OAAO,CAAC,EAAE;AAC9C,UAAM,IAAI,MAAM,iCAAiC,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,UAAU,aAAQ,IAAI,UAAU,EAAE,EAAE;AAAA,EACrH;AAEA,SAAO,IAAI,KAAK;AAClB;AAKO,SAAS,kBACd,iBACA,cACA,iBACA,wBACkD;AAElD,MAAI,0BAA0B,cAAc;AAC1C,UAAM,YAAY,UAAU,sBAAsB;AAClD,QAAI,gBAAgB,SAAS,SAAS,GAAG;AACvC,aAAO,EAAE,MAAM,OAAO,OAAO,UAAU;AAAA,IACzC;AAAA,EACF;AAGA,MAAI,iBAAiB;AACnB,UAAM,MAAM,gBAAgB,KAAK,CAAC,MAAM,EAAE,WAAW,SAAS,CAAC;AAC/D,QAAI,IAAK,QAAO,EAAE,MAAM,UAAU,OAAO,IAAI;AAAA,EAC/C;AAGA,MAAI,cAAc;AAChB,eAAW,SAAS,iBAAiB;AACnC,UAAI,MAAM,WAAW,SAAS,GAAG;AAC/B,eAAO,EAAE,MAAM,OAAO,MAAM;AAAA,MAC9B;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AAKO,SAAS,oBAAoB,cAAsB,QAAwB;AAChF,QAAM,MAAO,eAAe,OAAO,MAAM,IAAK;AAC9C,SAAO,eAAe;AACxB;AAGO,IAAM,kBAA0C;AAAA,EACrD,eAAe;AAAA,EACf,cAAc;AAAA,EACd,YAAY;AAAA,EACZ,gBAAgB;AAAA,EAChB,gBAAgB;AAAA,EAChB,qBAAqB;AACvB;","names":[]}