@recoilpay/intent-core 0.2.0 → 0.4.0

package/dist/index.cjs

@@ -21,12 +21,16 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ApiError: () => ApiError,
+  BANK_DETAILS_HINT: () => BANK_DETAILS_HINT,
   CHAIN_ALIASES: () => CHAIN_ALIASES,
   DEFAULT_API_URL: () => DEFAULT_API_URL,
   DEFAULT_INTENT_MODEL: () => DEFAULT_INTENT_MODEL,
   EMPTY_SUPPORTED: () => EMPTY_SUPPORTED,
+  FIAT_CORRIDORS: () => FIAT_CORRIDORS,
+  FIAT_CURRENCY_ALIASES: () => FIAT_CURRENCY_ALIASES,
   HF_ROUTER_URL: () => HF_ROUTER_URL,
   MAX_UINT256: () => MAX_UINT256,
+  NG_BANKS: () => NG_BANKS,
   PERMIT2_ADDRESS: () => PERMIT2_ADDRESS,
   SOLANA_CHAIN_IDS: () => SOLANA_CHAIN_IDS,
   TEMPLATE_HINT: () => TEMPLATE_HINT,
@@ -35,30 +39,48 @@ __export(index_exports, {
   buildPermit2ApproveRequest: () => buildPermit2ApproveRequest,
   buildQuoteRequest: () => buildQuoteRequest,
   buildSupportedSet: () => buildSupportedSet,
+  canonicalPayeeIdentity: () => canonicalPayeeIdentity,
   chainName: () => chainName,
+  checkLock: () => checkLock,
   createApiClient: () => createApiClient,
   createIntentSession: () => createIntentSession,
+  createOfframpSession: () => createOfframpSession,
   explorerUrl: () => explorerUrl,
   extractIntents: () => extractIntents,
+  fiatClaimMessage: () => fiatClaimMessage,
+  fiatConfirmMessage: () => fiatConfirmMessage,
+  fiatDisputeMessage: () => fiatDisputeMessage,
+  fiatPaymentSentMessage: () => fiatPaymentSentMessage,
+  fiatRevealMessage: () => fiatRevealMessage,
+  fiatStatementMessage: () => fiatStatementMessage,
   findAsset: () => findAsset,
+  formatFiat: () => formatFiat,
   getPermit2Allowance: () => getPermit2Allowance,
   hasPermit2Allowance: () => hasPermit2Allowance,
   interopAddress: () => interopAddress,
   isTerminalStatus: () => isTerminalStatus,
+  looksLikeBankDetails: () => looksLikeBankDetails,
   normalizeChain: () => normalizeChain,
+  normalizeFiatCurrency: () => normalizeFiatCurrency,
   normalizeToken: () => normalizeToken,
+  openPayee: () => openPayee,
   parseIntent: () => parseIntent,
+  payeeCommitment: () => payeeCommitment,
+  payeeIdentity: () => payeeIdentity,
   resolveIntent: () => resolveIntent,
+  resolveOfframp: () => resolveOfframp,
   rpcReaders: () => rpcReaders,
+  sealPayee: () => sealPayee,
   signQuote: () => signQuote,
   stripDomainType: () => stripDomainType,
   validateIntent: () => validateIntent,
+  validateOfframp: () => validateOfframp,
   viemWallet: () => viemWallet
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/session.ts
-var import_viem4 = require("viem");
+var import_viem5 = require("viem");
 
 // src/api.ts
 var DEFAULT_API_URL = "https://api.recoilpay.com";
@@ -117,12 +139,29 @@ function createApiClient(options = {}) {
     },
     getQuotes: (req) => post("/quotes", req),
     submitOrder: (req) => post("/orders", req),
-    getOrder: (id) => request(`/orders/${encodeURIComponent(id)}`)
+    getOrder: (id) => request(`/orders/${encodeURIComponent(id)}`),
+    // ── Fiat ramps (design §12.1) ──
+    rankFiatQuotes: (req) => post("/fiat/quotes", req),
+    openFiatTrade: (req) => post("/fiat/trades", req),
+    getFiatTrade: (id) => request(`/fiat/trades/${encodeURIComponent(id)}`),
+    /** Hand the signed lock to the solver's relay, which submits it and pays the gas. */
+    submitFiatLock: (id, signature) => post(`/fiat/trades/${encodeURIComponent(id)}/lock`, { signature }),
+    /** Report a lock the user submitted themselves; the aggregator reads it from the chain. */
+    reportFiatFunded: (id, txHash) => post(`/fiat/trades/${encodeURIComponent(id)}/funded`, txHash ? { txHash } : {}),
+    /** `signature` is over `fiatConfirmMessage(id)`. */
+    confirmFiatTrade: (id, signature) => post(`/fiat/trades/${encodeURIComponent(id)}/confirm`, { signature }),
+    /** `signature` is over `fiatDisputeMessage(id, reason)`. */
+    disputeFiatTrade: (id, reason, signature) => post(`/fiat/trades/${encodeURIComponent(id)}/dispute`, { reason, signature })
   };
 }
 
 // src/parse.ts
-var TEMPLATE_HINT = "Try: swap <amount> <token> on <chain> for <token> on <chain> [to <address>] (e.g. swap 10 USDC on Base for ETH on Arbitrum) OR send <amount> <token> on <chain> to <address>";
+var TEMPLATE_HINT = "Try: swap <amount> <token> on <chain> for <token> on <chain> [to <address>] (e.g. swap 10 USDC on Base for ETH on Arbitrum) OR send <amount> <token> on <chain> to <address> OR cash out <amount> <token> on <chain> to <currency> (e.g. cash out 50 USDC on Base to NGN)";
+var BANK_DETAILS_HINT = "Leave bank details out of the sentence \u2014 you'll enter them privately on the next step. Try: cash out 50 USDC on Base to NGN";
+function looksLikeBankDetails(text) {
+  const rest = text.replace(/0x[0-9a-fA-F]+/g, " ").replace(/[.,]\d+/g, "");
+  return /(\d[\s-]?){10,}/.test(rest);
+}
 var HF_ROUTER_URL = "https://router.huggingface.co/v1/chat/completions";
 var DEFAULT_INTENT_MODEL = "Qwen/Qwen2.5-Coder-32B-Instruct";
 var SYSTEM_PROMPT = `You are an intent extraction engine for a cross-chain swap protocol.
@@ -131,7 +170,7 @@ If the user specifies multiple intents (e.g. "swap X and then send Y"), return m
 The JSON objects must perfectly match the following TypeScript interface:
 
 type AmountKind = "token" | "usd";
-type IntentAction = "swap" | "send";
+type IntentAction = "swap" | "send" | "offramp";
 
 interface RawIntent {
   action: IntentAction;
@@ -142,14 +181,19 @@ interface RawIntent {
   tokenOut: string | null;        // target token (optional for send)
   chainOut: string | null;        // target chain (optional for send)
   recipient: string | null;       // address/ens (required for 'send', optional for 'swap')
+  fiatCurrency?: string | null;   // 'offramp' only: the local currency to receive, e.g. "NGN" or "naira"
 }
 
+Use "offramp" when the user wants to cash out, sell, or withdraw crypto to a bank account or local currency.
+For "offramp", tokenIn/chainIn/amount describe the crypto they give; tokenOut, chainOut and recipient are null.
+Never put bank names, account numbers or personal names in any field.
+
 Return ONLY the JSON array, nothing else. If you absolutely cannot determine any intents, return {"error": "unrecognized"}. Do not make up information that is missing; use null.`;
 var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 var readString = (v) => typeof v === "string" && v.trim().length > 0 ? v : null;
 var readAmount = (v) => v === null || v === void 0 ? null : String(v);
 var readAmountKind = (v) => v === "usd" ? "usd" : "token";
-var readAction = (v) => v === "swap" || v === "send" ? v : null;
+var readAction = (v) => v === "swap" || v === "send" || v === "offramp" ? v : null;
 var offTemplate = (message = TEMPLATE_HINT) => ({ ok: false, offTemplate: true, message });
 function extractIntents(content) {
   let json = content.trim();
@@ -174,7 +218,7 @@ function extractIntents(content) {
   for (const item of items) {
     const action = readAction(item.action);
     if (!action) return offTemplate();
-    intents.push({
+    const intent = {
       action,
       amount: readAmount(item.amount),
       amountKind: readAmountKind(item.amountKind),
@@ -183,13 +227,16 @@ function extractIntents(content) {
       tokenOut: readString(item.tokenOut),
       chainOut: readString(item.chainOut),
       recipient: readString(item.recipient)
-    });
+    };
+    if (action === "offramp") intent.fiatCurrency = readString(item.fiatCurrency);
+    intents.push(intent);
   }
   return { ok: true, intents };
 }
 async function parseIntent(text, options = {}) {
   const norm = text.trim();
   if (!norm) return offTemplate();
+  if (looksLikeBankDetails(norm)) return offTemplate(BANK_DETAILS_HINT);
   const token = options.hfAccessToken?.trim();
   if (!token) return offTemplate(`Natural-language parsing isn't set up here. ${TEMPLATE_HINT}`);
   const doFetch = options.fetch ?? ((...args) => fetch(...args));
@@ -437,7 +484,8 @@ var LABEL = {
   chainIn: "Source chain",
   tokenOut: "Destination token",
   chainOut: "Destination chain",
-  recipient: "Recipient"
+  recipient: "Recipient",
+  fiatCurrency: "Currency"
 };
 var EVM_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
 var SOLANA_ADDRESS_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
@@ -706,6 +754,23 @@ var PERMIT2_TYPES = {
     { name: "amount", type: "uint256" }
   ]
 };
+var PERMIT2_ESCROW_LOCK_TYPES = {
+  PermitWitnessTransferFrom: [
+    { name: "permitted", type: "TokenPermissions" },
+    { name: "spender", type: "address" },
+    { name: "nonce", type: "uint256" },
+    { name: "deadline", type: "uint256" },
+    { name: "witness", type: "EscrowLock" }
+  ],
+  EscrowLock: [
+    { name: "tradeId", type: "bytes32" },
+    { name: "counterparty", type: "address" }
+  ],
+  TokenPermissions: [
+    { name: "token", type: "address" },
+    { name: "amount", type: "uint256" }
+  ]
+};
 var EIP3009_TYPES = {
   TransferWithAuthorization: [
     { name: "from", type: "address" },
@@ -742,8 +807,11 @@ function extractDomain(payload) {
 function getTypesForPayload(payload) {
   switch (payload.primaryType) {
     case "PermitBatchWitnessTransferFrom":
-    case "PermitWitnessTransferFrom":
       return PERMIT2_TYPES;
+    // The batch types do not define this primary type at all, so mapping it
+    // to them made every single-token signature fail.
+    case "PermitWitnessTransferFrom":
+      return PERMIT2_ESCROW_LOCK_TYPES;
     case "TransferWithAuthorization":
     case "ReceiveWithAuthorization":
     case "CancelAuthorization":
@@ -811,6 +879,105 @@ async function signQuote(quote, signTypedDataAsync) {
   }
 }
 
+// src/fiat/intent.ts
+var import_viem4 = require("viem");
+
+// src/fiat/corridors.ts
+var NG_BANKS = [
+  { code: "044", name: "Access Bank" },
+  { code: "023", name: "Citibank Nigeria" },
+  { code: "050", name: "Ecobank Nigeria" },
+  { code: "070", name: "Fidelity Bank" },
+  { code: "011", name: "First Bank of Nigeria" },
+  { code: "214", name: "First City Monument Bank" },
+  { code: "058", name: "Guaranty Trust Bank" },
+  { code: "082", name: "Keystone Bank" },
+  { code: "50211", name: "Kuda Bank" },
+  { code: "50515", name: "Moniepoint MFB" },
+  { code: "999992", name: "OPay" },
+  { code: "999991", name: "PalmPay" },
+  { code: "076", name: "Polaris Bank" },
+  { code: "101", name: "Providus Bank" },
+  { code: "221", name: "Stanbic IBTC Bank" },
+  { code: "068", name: "Standard Chartered Bank" },
+  { code: "232", name: "Sterling Bank" },
+  { code: "032", name: "Union Bank of Nigeria" },
+  { code: "033", name: "United Bank For Africa" },
+  { code: "215", name: "Unity Bank" },
+  { code: "035", name: "Wema Bank" },
+  { code: "057", name: "Zenith Bank" }
+];
+var FIAT_CORRIDORS = {
+  NGN: {
+    currency: "NGN",
+    rail: "ng.nip",
+    decimals: 2,
+    symbol: "\u20A6",
+    accountLabel: "Account number (NUBAN)",
+    accountPattern: /^\d{10}$/,
+    banks: NG_BANKS
+  }
+};
+var FIAT_CURRENCY_ALIASES = {
+  ngn: "NGN",
+  naira: "NGN",
+  "\u20A6": "NGN",
+  nigeria: "NGN",
+  nigerian: "NGN"
+};
+function normalizeFiatCurrency(raw) {
+  if (!raw) return null;
+  const k = raw.trim().toLowerCase();
+  return FIAT_CURRENCY_ALIASES[k] ?? (FIAT_CORRIDORS[k.toUpperCase()] ? k.toUpperCase() : null);
+}
+function formatFiat(minor, corridor) {
+  const n = typeof minor === "bigint" ? minor : BigInt(minor);
+  const scale = 10n ** BigInt(corridor.decimals);
+  const whole = (n / scale).toLocaleString("en-US");
+  if (corridor.decimals === 0) return whole;
+  return `${whole}.${(n % scale).toString().padStart(corridor.decimals, "0")}`;
+}
+
+// src/fiat/intent.ts
+function validateOfframp(raw, supported) {
+  const issues = [];
+  if (!raw.amount) issues.push({ field: "amount", kind: "missing", message: "Amount is not stated." });
+  else if (!(Number(raw.amount) > 0)) issues.push({ field: "amount", kind: "unknown", message: "Amount must be a positive number." });
+  const chain = normalizeChain(raw.chainIn);
+  if (!raw.chainIn) issues.push({ field: "chainIn", kind: "missing", message: "Source chain is not stated." });
+  else if (!chain) issues.push({ field: "chainIn", kind: "unknown", message: `Chain '${raw.chainIn}' isn't recognized.` });
+  const sym = normalizeToken(raw.tokenIn);
+  if (!raw.tokenIn) issues.push({ field: "tokenIn", kind: "missing", message: "Source token is not stated." });
+  else if (!sym) issues.push({ field: "tokenIn", kind: "unknown", message: `Token '${raw.tokenIn}' isn't recognized.` });
+  else if (chain && !findAsset(supported, chain.id, sym)) {
+    issues.push({ field: "tokenIn", kind: "unsupported", message: `${sym} isn't supported on ${chain.name} yet.` });
+  }
+  const currency = normalizeFiatCurrency(raw.fiatCurrency);
+  if (!raw.fiatCurrency) {
+    issues.push({ field: "fiatCurrency", kind: "missing", message: "Say which currency to receive, e.g. NGN." });
+  } else if (!currency) {
+    const known = Object.keys(FIAT_CORRIDORS).join(", ");
+    issues.push({ field: "fiatCurrency", kind: "unsupported", message: `Cash out to ${raw.fiatCurrency} isn't available yet (only ${known}).` });
+  }
+  return issues;
+}
+function resolveOfframp(raw, supported) {
+  const chain = normalizeChain(raw.chainIn);
+  const sym = normalizeToken(raw.tokenIn);
+  const currency = normalizeFiatCurrency(raw.fiatCurrency);
+  const asset = chain && sym ? findAsset(supported, chain.id, sym) : void 0;
+  if (!chain || !asset || !currency || !raw.amount) throw new Error("resolveOfframp called on an invalid intent");
+  return {
+    chainId: chain.id,
+    chainName: chain.name,
+    asset: asset.symbol.toUpperCase(),
+    token: (0, import_viem4.getAddress)(asset.address),
+    decimals: asset.decimals,
+    amount: (0, import_viem4.parseUnits)(raw.amount, asset.decimals),
+    corridor: FIAT_CORRIDORS[currency]
+  };
+}
+
 // src/session.ts
 var ERC20_TRANSFER_ABI = [
   {
@@ -827,7 +994,7 @@ var ERC20_TRANSFER_ABI = [
 var errMessage = (e) => e instanceof Error ? e.message : typeof e === "string" ? e : "Something went wrong.";
 function fmtUnits(amount, decimals) {
   if (amount === void 0) return "";
-  const human = (0, import_viem4.formatUnits)(typeof amount === "bigint" ? amount : BigInt(amount), decimals);
+  const human = (0, import_viem5.formatUnits)(typeof amount === "bigint" ? amount : BigInt(amount), decimals);
   const n = Number(human);
   return Number.isFinite(n) ? n.toLocaleString("en-US", { maximumFractionDigits: 6 }) : human;
 }
@@ -862,7 +1029,8 @@ var INITIAL = {
   error: null,
   isConnected: false,
   queueIndex: 0,
-  queueTotal: 0
+  queueTotal: 0,
+  offramp: null
 };
 function createIntentSession(options = {}) {
   const api = options.api ?? createApiClient(options);
@@ -907,6 +1075,7 @@ function createIntentSession(options = {}) {
     }
   }
   async function quoteFor(raw, gen) {
+    if (raw.action === "offramp") return;
     if (!wallet) return set({ phase: "needsWallet" });
     try {
       set({ phase: "quoting", error: null });
@@ -1057,6 +1226,12 @@ function createIntentSession(options = {}) {
     const parsed = await parseIntent(text, { hfAccessToken, model: options.hfModel, fetch: api.fetch });
     if (gen !== generation) return;
     if (!parsed.ok) return set({ phase: "offTemplate", hint: parsed.message });
+    const offramp = parsed.intents.find((i) => i.action === "offramp");
+    if (offramp) {
+      const issues = parsed.intents.length > 1 ? [{ field: "fiatCurrency", kind: "unsupported", message: "Cash out on its own, not in the same sentence as other actions." }] : validateOfframp(offramp, supported);
+      if (issues.length) return set({ phase: "invalid", issues });
+      return set({ phase: "offramp", offramp: resolveOfframp(offramp, supported) });
+    }
     for (const intent of parsed.intents) {
       const issues = validateIntent(intent, supported);
       if (issues.length) return set({ phase: "invalid", issues });
@@ -1126,7 +1301,8 @@ function viemWallet(client) {
       functionName: req.functionName,
       args: req.args
     }),
-    sendTransaction: (req) => client.sendTransaction({ account, chain: null, to: req.to, value: req.value })
+    sendTransaction: (req) => client.sendTransaction({ account, chain: null, to: req.to, value: req.value }),
+    signMessage: (message) => client.signMessage({ account, message })
   };
 }
 function stripDomainType(types) {
@@ -1134,15 +1310,409 @@ function stripDomainType(types) {
   for (const [name, fields] of Object.entries(types)) if (name !== "EIP712Domain") out[name] = fields;
   return out;
 }
+
+// src/fiat/payee.ts
+var import_aes = require("@noble/ciphers/aes");
+var import_secp256k1 = require("@noble/curves/secp256k1");
+var import_hkdf = require("@noble/hashes/hkdf");
+var import_sha256 = require("@noble/hashes/sha256");
+var import_viem6 = require("viem");
+var ALG = "ECIES-secp256k1-AES256GCM";
+var ENVELOPE_VERSION = 1;
+var PAYLOAD_VERSION = 1;
+var GCM_TAG_BYTES = 16;
+var SALT_BYTES = 32;
+var MAX_NAME_LENGTH = 140;
+var HKDF_INFO = (0, import_viem6.stringToBytes)("recoilpay/fiat-payee/v1");
+var RAIL = /^[A-Za-z]{2}\.[A-Za-z0-9_]{1,30}$/;
+var BANK_CODE = /^[A-Za-z0-9]{0,16}$/;
+var ACCOUNT = /^\+?[A-Za-z0-9]{1,34}$/;
+var ASCII_SPACE = /[ \t\r\n]/g;
+function payeeIdentity(payee) {
+  const rail = payee.rail.replace(ASCII_SPACE, "");
+  const bankCode = payee.bankCode.replace(ASCII_SPACE, "");
+  const account = payee.account.replace(ASCII_SPACE, "").replace(/-/g, "");
+  if (!RAIL.test(rail)) throw new Error(`invalid rail: ${JSON.stringify(payee.rail)}`);
+  if (!BANK_CODE.test(bankCode)) throw new Error("invalid bank code");
+  if (!ACCOUNT.test(account)) throw new Error("invalid account number");
+  return {
+    rail: rail.toLowerCase(),
+    bank_code: bankCode.toUpperCase(),
+    account: account.toUpperCase()
+  };
+}
+function canonicalPayeeIdentity(identity) {
+  const { account, bank_code, rail } = payeeIdentity({
+    rail: identity.rail,
+    bankCode: identity.bank_code,
+    account: identity.account
+  });
+  return JSON.stringify({ account, bank_code, rail });
+}
+function payeeCommitment(identity, salt) {
+  const saltBytes = (0, import_viem6.hexToBytes)(salt);
+  if (saltBytes.length !== SALT_BYTES) throw new Error(`salt must be ${SALT_BYTES} bytes`);
+  return (0, import_viem6.keccak256)((0, import_viem6.concat)([(0, import_viem6.stringToBytes)(canonicalPayeeIdentity(identity)), saltBytes]));
+}
+function normaliseName(name) {
+  const n = name.normalize("NFC").trim().replace(/\s+/g, " ");
+  if (n.length === 0) throw new Error("the account holder name is required");
+  if (n.length > MAX_NAME_LENGTH) throw new Error("the account holder name is too long");
+  return n;
+}
+function deriveKey(sharedX, ephemeralPub) {
+  return (0, import_hkdf.hkdf)(import_sha256.sha256, sharedX, ephemeralPub, HKDF_INFO, 32);
+}
+function sealPayee(payee, solverPubkey, salt) {
+  const identity = payeeIdentity(payee);
+  const name = normaliseName(payee.name);
+  const saltHex = salt ?? (0, import_viem6.bytesToHex)(crypto.getRandomValues(new Uint8Array(SALT_BYTES)));
+  const commitment = payeeCommitment(identity, saltHex);
+  const recipient = (0, import_viem6.hexToBytes)(solverPubkey);
+  if (recipient.length !== 65 || recipient[0] !== 4) {
+    throw new Error("solver public key must be 65 bytes uncompressed (0x04\u2026)");
+  }
+  const plaintext = (0, import_viem6.stringToBytes)(
+    JSON.stringify({ v: PAYLOAD_VERSION, ...identity, name, salt: saltHex })
+  );
+  const ephemeralPriv = import_secp256k1.secp256k1.utils.randomPrivateKey();
+  const ephemeralPub = import_secp256k1.secp256k1.getPublicKey(ephemeralPriv, false);
+  const shared = import_secp256k1.secp256k1.getSharedSecret(ephemeralPriv, recipient, true).slice(1);
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const out = (0, import_aes.gcm)(deriveKey(shared, ephemeralPub), iv).encrypt(plaintext);
+  return {
+    sealed: {
+      v: ENVELOPE_VERSION,
+      alg: ALG,
+      epk: (0, import_viem6.bytesToHex)(ephemeralPub),
+      iv: (0, import_viem6.bytesToHex)(iv),
+      // @noble appends the tag; split so any standard GCM can read it.
+      ct: (0, import_viem6.bytesToHex)(out.slice(0, out.length - GCM_TAG_BYTES)),
+      tag: (0, import_viem6.bytesToHex)(out.slice(out.length - GCM_TAG_BYTES))
+    },
+    commitment,
+    salt: saltHex
+  };
+}
+function openPayee(sealed, solverPrivkey, expectedCommitment) {
+  if (sealed.alg !== ALG) throw new Error(`unsupported envelope algorithm: ${sealed.alg}`);
+  if (sealed.v !== ENVELOPE_VERSION) throw new Error(`unsupported envelope version: ${sealed.v}`);
+  const epk = (0, import_viem6.hexToBytes)(sealed.epk);
+  const shared = import_secp256k1.secp256k1.getSharedSecret((0, import_viem6.hexToBytes)(solverPrivkey), epk, true).slice(1);
+  const plaintext = (0, import_aes.gcm)(deriveKey(shared, epk), (0, import_viem6.hexToBytes)(sealed.iv)).decrypt(
+    (0, import_viem6.concat)([(0, import_viem6.hexToBytes)(sealed.ct), (0, import_viem6.hexToBytes)(sealed.tag)])
+  );
+  const body = JSON.parse(new TextDecoder().decode(plaintext));
+  if (body.v !== PAYLOAD_VERSION) throw new Error(`unsupported payee payload version: ${String(body.v)}`);
+  const identity = payeeIdentity({
+    rail: String(body.rail ?? ""),
+    bankCode: String(body.bank_code ?? ""),
+    account: String(body.account ?? "")
+  });
+  const salt = String(body.salt ?? "");
+  if (payeeCommitment(identity, salt).toLowerCase() !== expectedCommitment.toLowerCase()) {
+    throw new Error("sealed payee details do not match the trade commitment");
+  }
+  return { identity, name: normaliseName(String(body.name ?? "")), salt };
+}
+
+// src/fiat/offramp.ts
+var import_viem7 = require("viem");
+
+// src/fiat/actions.ts
+function fiatConfirmMessage(tradeId) {
+  return `RecoilPay: I confirm I received the fiat payment for trade ${tradeId}.`;
+}
+function fiatDisputeMessage(tradeId, reason) {
+  return `RecoilPay: I dispute trade ${tradeId}. Reason: ${reason.trim()}`;
+}
+function fiatPaymentSentMessage(tradeId, reference) {
+  return `RecoilPay: I have sent the fiat payment for trade ${tradeId}. Reference: ${reference.trim()}`;
+}
+function fiatClaimMessage(tradeId, reason) {
+  return `RecoilPay: I claim the fiat payment for trade ${tradeId} never arrived. Reason: ${reason.trim()}`;
+}
+function fiatRevealMessage(tradeId) {
+  return `RecoilPay: I reveal the bank details I gave for trade ${tradeId}.`;
+}
+function fiatStatementMessage(tradeId, text) {
+  return `RecoilPay: My statement on trade ${tradeId}: ${text.trim()}`;
+}
+
+// src/fiat/offramp.ts
+var TERMINAL = ["settled_to_fiat_payer", "refunded_to_funder", "failed"];
+var PHASE_OF = {
+  quoted: "locking",
+  awaiting_fiat: "awaitingFiat",
+  awaiting_confirmation: "awaitingConfirmation",
+  disputed: "disputed",
+  settled_to_fiat_payer: "settled",
+  refunded_to_funder: "refunded",
+  failed: "failed"
+};
+var PLAIN_TEXT = /^[\x20-\x7e]+$/;
+var MAX_REASON = 500;
+var errMessage2 = (e) => e instanceof Error ? e.message : typeof e === "string" ? e : "Something went wrong.";
+var same = (a, b) => typeof a === "string" && typeof b === "string" && a.toLowerCase() === b.toLowerCase();
+function fmtAsset(amount, decimals) {
+  const n = Number((0, import_viem7.formatUnits)(amount, decimals));
+  return n.toLocaleString("en-US", { maximumFractionDigits: 6 });
+}
+function checkLock(lock, trade, request, quote, user) {
+  const m = lock.typedData.message;
+  const d = lock.typedData.domain;
+  const problems = [
+    lock.typedData.primaryType !== "PermitWitnessTransferFrom" && "not a Permit2 witness transfer",
+    !same(d.verifyingContract, PERMIT2_ADDRESS) && "not signed for Permit2",
+    Number(d.chainId) !== request.chainId && "the wrong chain",
+    !same(m.permitted?.token, request.token) && "the wrong token",
+    m.permitted?.amount !== request.amount.toString() && "the wrong amount",
+    !same(m.spender, lock.escrow) && "a spender other than the escrow",
+    !same(m.witness?.tradeId, lock.tradeId) && "another trade",
+    !same(m.witness?.counterparty, trade.solver_address) && "a counterparty other than the solver",
+    trade.quote_id !== quote.quoteId && "another quote",
+    trade.fiat_minor_units !== quote.fiatNet && "a payout other than the one quoted",
+    !same(trade.user_address, user) && "another wallet"
+  ].filter(Boolean);
+  if (problems.length) throw new Error(`Refusing to sign: the lock names ${problems.join(", ")}.`);
+}
+function fmtRate(rate) {
+  const n = Number(rate);
+  return Number.isFinite(n) ? n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 6 }) : rate;
+}
+var INITIAL2 = {
+  phase: "idle",
+  request: null,
+  quote: null,
+  preview: null,
+  needsApproval: false,
+  trade: null,
+  payeeSalt: null,
+  error: null
+};
+function createOfframpSession(options = {}) {
+  const api = options.api ?? createApiClient(options);
+  const pollMs = options.pollIntervalMs ?? 3e3;
+  let chainsPromise = null;
+  const chains = () => chainsPromise ??= api.getChains().catch((e) => (chainsPromise = null, Promise.reject(e)));
+  const reader = options.chainReader ?? rpcReaders(chains);
+  let wallet = options.wallet ?? null;
+  let pollTimer;
+  let destroyed = false;
+  let generation = 0;
+  let state = { ...INITIAL2 };
+  const listeners = /* @__PURE__ */ new Set();
+  function set(patch) {
+    if (destroyed) return;
+    state = { ...state, ...patch };
+    for (const l of listeners) l(state);
+  }
+  const stopPolling = () => {
+    if (pollTimer) clearTimeout(pollTimer);
+    pollTimer = void 0;
+  };
+  function showTrade(trade, patch = {}) {
+    set({ trade, phase: PHASE_OF[trade.state], ...patch });
+  }
+  function track(tradeId, gen) {
+    stopPolling();
+    const poll = async () => {
+      try {
+        const trade = await api.getFiatTrade(tradeId);
+        if (gen !== generation) return;
+        if (state.phase === "confirming" || state.phase === "disputing") set({ trade });
+        else showTrade(trade);
+        if (TERMINAL.includes(trade.state)) return;
+      } catch {
+      }
+      if (gen !== generation || destroyed) return;
+      const wait = state.trade?.state === "disputed" ? pollMs * 10 : pollMs;
+      pollTimer = setTimeout(poll, wait);
+    };
+    void poll();
+  }
+  async function quote(request) {
+    const gen = ++generation;
+    stopPolling();
+    set({ ...INITIAL2, request, phase: wallet ? "quoting" : "needsWallet" });
+    if (!wallet) return;
+    try {
+      const res = await api.rankFiatQuotes({
+        direction: "offramp",
+        chain: `eip155:${request.chainId}`,
+        asset: request.asset,
+        fiatCurrency: request.corridor.currency,
+        rail: request.corridor.rail,
+        assetAmount: request.amount.toString()
+      });
+      const best = res.quotes?.[0];
+      if (!best) throw new Error(`No solver is cashing out ${request.asset} on ${request.chainName} to ${request.corridor.currency} for this amount right now.`);
+      const pc = await reader(request.chainId).catch(() => null);
+      const needsApproval = pc ? !await hasPermit2Allowance(pc, request.token, wallet.address, request.amount).catch(() => false) : true;
+      if (gen !== generation) return;
+      const c = request.corridor;
+      set({
+        phase: "quoted",
+        quote: best,
+        needsApproval,
+        preview: {
+          payAmount: fmtAsset(request.amount, request.decimals),
+          paySymbol: request.asset,
+          chainName: request.chainName,
+          receiveAmount: formatFiat(best.fiatNet, c),
+          currency: c.currency,
+          currencySymbol: c.symbol,
+          fee: formatFiat(best.fiatFee, c),
+          rate: fmtRate(best.rate),
+          paymentWindowSecs: best.paymentWindowSecs,
+          quotesConsidered: res.totalConsidered
+        }
+      });
+    } catch (e) {
+      if (gen === generation) set({ phase: "error", error: errMessage2(e) });
+    }
+  }
+  async function confirm(payee) {
+    const { request, quote: chosen } = state;
+    const w = wallet;
+    if (!request || !chosen || !w || state.phase !== "quoted") return;
+    const gen = generation;
+    try {
+      set({ error: null });
+      const details = { ...payee, rail: request.corridor.rail };
+      payeeIdentity(details);
+      if (!request.corridor.accountPattern.test(details.account.replace(/[\s-]/g, ""))) {
+        throw new Error(`That doesn't look like a valid ${request.corridor.accountLabel.toLowerCase()}.`);
+      }
+      if (!details.name.trim()) throw new Error("Enter the account holder's name.");
+      if (await w.getChainId() !== request.chainId) {
+        set({ phase: "switchingChain" });
+        await w.switchChain(request.chainId);
+      }
+      const pc = await reader(request.chainId).catch(() => null);
+      const needsApproval = pc ? !await hasPermit2Allowance(pc, request.token, w.address, request.amount) : state.needsApproval;
+      if (needsApproval) {
+        set({ phase: "approving" });
+        const approve = buildPermit2ApproveRequest(request.token);
+        const hash = await w.writeContract({ chainId: request.chainId, ...approve, abi: approve.abi });
+        if (pc) await pc.waitForTransactionReceipt({ hash });
+        set({ needsApproval: false });
+      }
+      set({ phase: "opening" });
+      const { sealed, commitment, salt } = sealPayee(details, chosen.payeeKey);
+      const opened = await api.openFiatTrade({
+        quoteId: chosen.quoteId,
+        assetAmount: request.amount.toString(),
+        userAddress: (0, import_viem7.getAddress)(w.address),
+        payee: { sealed, commitment }
+      });
+      if (gen !== generation) return;
+      set({ trade: opened.trade, payeeSalt: salt });
+      checkLock(opened.lock, opened.trade, request, chosen, w.address);
+      if (!same(opened.trade.payee_commitment, commitment)) throw new Error("Refusing to sign: the trade is not for the bank details you entered.");
+      set({ phase: "signing" });
+      const { domain, types, primaryType, message } = opened.lock.typedData;
+      const signature = await w.signTypedData({ domain, types, primaryType, message });
+      set({ phase: "locking" });
+      const trade = await api.submitFiatLock(opened.trade.id, signature);
+      if (gen !== generation) return;
+      showTrade(trade);
+      track(trade.id, gen);
+    } catch (e) {
+      if (gen !== generation) return;
+      if (state.trade) {
+        set({ error: errMessage2(e) });
+        track(state.trade.id, gen);
+      } else set({ phase: "error", error: errMessage2(e) });
+    }
+  }
+  async function act(phase, message, send) {
+    const trade = state.trade;
+    const w = wallet;
+    if (!trade || trade.state !== "awaiting_confirmation") return;
+    const gen = generation;
+    const before = state.phase;
+    try {
+      if (!w) throw new Error("Connect the wallet that opened this trade.");
+      if (!same(w.address, trade.user_address)) throw new Error("Switch to the wallet that opened this trade.");
+      if (!w.signMessage) throw new Error("This wallet can't sign messages, so it can't confirm or dispute.");
+      set({ phase, error: null });
+      const signature = await w.signMessage(message(trade.id));
+      const next = await send(trade.id, signature);
+      if (gen !== generation) return;
+      showTrade(next);
+      track(next.id, gen);
+    } catch (e) {
+      if (gen === generation) set({ phase: before, error: errMessage2(e) });
+    }
+  }
+  async function dispute(reason) {
+    const r = reason.trim();
+    if (!r || r.length > MAX_REASON || !PLAIN_TEXT.test(r)) {
+      set({ error: `Describe the problem in 1 to ${MAX_REASON} plain characters (letters, digits, punctuation).` });
+      return;
+    }
+    await act("disputing", (id) => fiatDisputeMessage(id, r), (id, sig) => api.disputeFiatTrade(id, r, sig));
+  }
+  async function resume(tradeId) {
+    const gen = ++generation;
+    stopPolling();
+    set({ ...INITIAL2, phase: "quoting" });
+    try {
+      const trade = await api.getFiatTrade(tradeId);
+      if (gen !== generation) return;
+      showTrade(trade);
+      track(trade.id, gen);
+    } catch (e) {
+      if (gen === generation) set({ phase: "error", error: errMessage2(e) });
+    }
+  }
+  function reset() {
+    generation++;
+    stopPolling();
+    set({ ...INITIAL2 });
+  }
+  function setWallet(next) {
+    const changed = wallet?.address !== next?.address;
+    wallet = next;
+    if (next && state.request && !state.trade && (state.phase === "needsWallet" || changed && state.phase === "quoted")) {
+      void quote(state.request);
+    }
+  }
+  return {
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    quote,
+    confirm,
+    confirmReceived: () => act("confirming", fiatConfirmMessage, (id, sig) => api.confirmFiatTrade(id, sig)),
+    dispute,
+    resume,
+    reset,
+    setWallet,
+    destroy() {
+      generation++;
+      stopPolling();
+      destroyed = true;
+      listeners.clear();
+    }
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ApiError,
+  BANK_DETAILS_HINT,
   CHAIN_ALIASES,
   DEFAULT_API_URL,
   DEFAULT_INTENT_MODEL,
   EMPTY_SUPPORTED,
+  FIAT_CORRIDORS,
+  FIAT_CURRENCY_ALIASES,
   HF_ROUTER_URL,
   MAX_UINT256,
+  NG_BANKS,
   PERMIT2_ADDRESS,
   SOLANA_CHAIN_IDS,
   TEMPLATE_HINT,
@@ -1151,23 +1721,41 @@ function stripDomainType(types) {
   buildPermit2ApproveRequest,
   buildQuoteRequest,
   buildSupportedSet,
+  canonicalPayeeIdentity,
   chainName,
+  checkLock,
   createApiClient,
   createIntentSession,
+  createOfframpSession,
   explorerUrl,
   extractIntents,
+  fiatClaimMessage,
+  fiatConfirmMessage,
+  fiatDisputeMessage,
+  fiatPaymentSentMessage,
+  fiatRevealMessage,
+  fiatStatementMessage,
   findAsset,
+  formatFiat,
   getPermit2Allowance,
   hasPermit2Allowance,
   interopAddress,
   isTerminalStatus,
+  looksLikeBankDetails,
   normalizeChain,
+  normalizeFiatCurrency,
   normalizeToken,
+  openPayee,
   parseIntent,
+  payeeCommitment,
+  payeeIdentity,
   resolveIntent,
+  resolveOfframp,
   rpcReaders,
+  sealPayee,
   signQuote,
   stripDomainType,
   validateIntent,
+  validateOfframp,
   viemWallet
 });