@recoilpay/intent-core 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -177,6 +177,106 @@ interface OrderResponse {
     fillTransaction?: unknown;
 }
 
+/** The aggregator's fiat API, as it sends it. See design §12.1. */
+type FiatDirection = 'onramp' | 'offramp';
+type FiatTradeState = 'quoted' | 'awaiting_fiat' | 'awaiting_confirmation' | 'disputed' | 'settled_to_fiat_payer' | 'refunded_to_funder' | 'failed';
+/** One fiat trade. Snake case, as `GET /api/v1/fiat/trades/{id}` returns it. */
+interface FiatTrade {
+    id: string;
+    quote_id: string;
+    solver_id: string;
+    direction: FiatDirection;
+    /** CAIP-2, e.g. `eip155:84532`. */
+    chain: string;
+    asset: string;
+    asset_minor_units: string;
+    fiat_currency: string;
+    /** What reaches the payee's account, in minor units (kobo for NGN). */
+    fiat_minor_units: string;
+    rail: string;
+    rate: string;
+    fee_minor_units: string;
+    user_address: string;
+    solver_address: string;
+    state: FiatTradeState;
+    /** When the party the trade is waiting on runs out of time. */
+    deadline_at: string | null;
+    resolution_note: string | null;
+    payee_commitment: string | null;
+    payment_reference: string | null;
+    proof_kind: 'counterparty' | 'provider' | 'zktls' | null;
+    escrow_tx_hash: string | null;
+    release_tx_hash: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** `POST /api/v1/fiat/quotes`. */
+interface RankFiatQuotesRequest {
+    direction: FiatDirection;
+    chain: string;
+    asset: string;
+    fiatCurrency: string;
+    rail: string;
+    /** Minor units of the asset, as a whole-number string. */
+    assetAmount: string;
+}
+/** One priced offer, best first. Amounts are minor-unit strings. */
+interface RankedFiatQuote {
+    quoteId: string;
+    solverId: string;
+    rate: string;
+    assetAmount: string;
+    fiatCurrency: string;
+    rail: string;
+    fiatGross: string;
+    fiatFee: string;
+    /** What reaches the user's account. */
+    fiatNet: string;
+    paymentWindowSecs: number;
+    expiry: number;
+    score: number;
+    /** Seal the bank details to this before opening a trade. */
+    payeeKey: string;
+}
+interface RankFiatQuotesResponse {
+    quotes: RankedFiatQuote[];
+    totalConsidered: number;
+}
+/** What the user signs (Permit2 `PermitWitnessTransferFrom`) and the relay submits. */
+interface FiatLockInstructions {
+    chainId: number;
+    escrow: string;
+    tradeId: string;
+    lockId: string;
+    token: string;
+    amount: string;
+    counterparty: string;
+    nonce: string;
+    deadline: number;
+    typedData: {
+        domain: Record<string, unknown>;
+        types: Record<string, ReadonlyArray<{
+            name: string;
+            type: string;
+        }>>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    };
+}
+interface OpenFiatTradeRequest {
+    quoteId: string;
+    assetAmount: string;
+    userAddress: string;
+    payee: {
+        sealed: unknown;
+        commitment: string;
+    };
+}
+interface OpenFiatTradeResponse {
+    trade: FiatTrade;
+    lock: FiatLockInstructions;
+}
+
 /** Production aggregator. Override with `apiUrl` for staging or a local instance. */
 declare const DEFAULT_API_URL = "https://api.recoilpay.com";
 interface ApiOptions {
@@ -221,10 +321,22 @@ declare function createApiClient(options?: ApiOptions): {
     getQuotes: (req: QuoteRequest) => Promise<QuotesResponse>;
     submitOrder: (req: OrderRequest) => Promise<OrderResponse>;
     getOrder: (id: string) => Promise<OrderResponse>;
+    rankFiatQuotes: (req: RankFiatQuotesRequest) => Promise<RankFiatQuotesResponse>;
+    openFiatTrade: (req: OpenFiatTradeRequest) => Promise<OpenFiatTradeResponse>;
+    getFiatTrade: (id: string) => Promise<FiatTrade>;
+    /** Hand the signed lock to the solver's relay, which submits it and pays the gas. */
+    submitFiatLock: (id: string, signature: string) => Promise<FiatTrade>;
+    /** Report a lock the user submitted themselves; the aggregator reads it from the chain. */
+    reportFiatFunded: (id: string, txHash?: string) => Promise<FiatTrade>;
+    /** `signature` is over `fiatConfirmMessage(id)`. */
+    confirmFiatTrade: (id: string, signature: string) => Promise<FiatTrade>;
+    /** `signature` is over `fiatDisputeMessage(id, reason)`. */
+    disputeFiatTrade: (id: string, reason: string, signature: string) => Promise<FiatTrade>;
 };
 
 /** Intent parser types. See docs/intent-parser-design.md. */
-type IntentAction = 'swap' | 'send';
+/** `offramp` cashes crypto out to a bank account (fiat ramps, design §5.1). */
+type IntentAction = 'swap' | 'send' | 'offramp';
 type AmountKind = 'token' | 'usd';
 /** Output of the grammar parser, before resolution. Raw alias strings as typed. */
 interface RawIntent {
@@ -236,6 +348,10 @@ interface RawIntent {
     tokenOut: string | null;
     chainOut: string | null;
     recipient: string | null;
+    /** offramp only: the currency to receive, as typed ("naira", "NGN"). Bank
+     *  details are never parsed: they are collected in a form, so they never
+     *  leave the browser unsealed. */
+    fiatCurrency?: string | null;
 }
 type ParseResult = {
     ok: true;
@@ -245,7 +361,7 @@ type ParseResult = {
     offTemplate: true;
     message: string;
 };
-type IssueField = 'amount' | 'tokenIn' | 'chainIn' | 'tokenOut' | 'chainOut' | 'recipient';
+type IssueField = 'amount' | 'tokenIn' | 'chainIn' | 'tokenOut' | 'chainOut' | 'recipient' | 'fiatCurrency';
 type IssueKind = 'missing' | 'unknown' | 'unsupported';
 interface ValidationIssue {
     field: IssueField;
@@ -265,7 +381,16 @@ interface ResolvedIntent {
     recipient: string;
 }
 
-declare const 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>";
+declare const 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)";
+/** Shown instead of parsing when the text looks like it holds bank details. */
+declare const 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";
+/**
+ * Parsing sends the text to a third party (Hugging Face), so bank details
+ * must never be in it. An account number is a long run of digits: a NUBAN
+ * is ten, an IBAN's tail more. Hex addresses are skipped, and amounts this
+ * long do not occur in practice.
+ */
+declare function looksLikeBankDetails(text: string): boolean;
 /** Hugging Face's OpenAI-compatible router: the endpoint @huggingface/inference's chatCompletion uses. */
 declare const HF_ROUTER_URL = "https://router.huggingface.co/v1/chat/completions";
 declare const DEFAULT_INTENT_MODEL = "Qwen/Qwen2.5-Coder-32B-Instruct";
@@ -370,6 +495,11 @@ interface IntentWallet {
         to: Address;
         value: bigint;
     }): Promise<Hex>;
+    /**
+     * EIP-191 `personal_sign` of a plain message. Only fiat trades need it (to
+     * confirm or dispute), so a wallet used for swaps alone may omit it.
+     */
+    signMessage?(message: string): Promise<Hex>;
 }
 /** Adapt a viem `WalletClient` (with an account attached) to `IntentWallet`. */
 declare function viemWallet(client: WalletClient): IntentWallet;
@@ -382,6 +512,89 @@ declare function stripDomainType(types: Record<string, ReadonlyArray<{
     type: string;
 }>>;
 
+/**
+ * The registry has two layers (see docs/intent-parser-design.md §2):
+ *  - alias layer (static): maps loose user words → canonical token symbol / chain.
+ *  - support layer (dynamic): what solvers can actually fill, from the live aggregator.
+ *
+ * A word can be a token OR a chain depending on slot (e.g. "eth", "sol"); the grammar
+ * decides which table to consult by position, so the same word appears in both.
+ */
+interface CanonicalChain {
+    id: number;
+    name: string;
+}
+declare const TOKEN_ALIASES: Record<string, string>;
+declare const CHAIN_ALIASES: Record<string, CanonicalChain>;
+declare function normalizeToken(raw: string | null): string | null;
+declare function normalizeChain(raw: string | null): CanonicalChain | null;
+interface SupportedSet {
+    chains: Set<number>;
+    assets: Map<string, SolverAsset>;
+}
+declare const EMPTY_SUPPORTED: SupportedSet;
+declare function buildSupportedSet(assets: SolverAsset[]): SupportedSet;
+declare function findAsset(set: SupportedSet, chainId: number, symbol: string): SolverAsset | undefined;
+
+/**
+ * The fiat corridors this kit knows how to collect payee details for.
+ *
+ * A corridor is a currency, the rail payouts go over, and how its banks are
+ * named. Bank codes matter beyond display: the payee commitment covers the
+ * bank code, and a Tier 1 proof recomputes it from the code the payment
+ * provider reports. So the codes here must be the ones the solvers' provider
+ * uses — Paystack's, for the Phase 1 pilot.
+ */
+interface FiatBank {
+    code: string;
+    name: string;
+}
+interface FiatCorridor {
+    currency: string;
+    rail: string;
+    /** Minor units per major unit, as a power of ten (kobo: 2). */
+    decimals: number;
+    symbol: string;
+    /** What the account number is called, for a form label. */
+    accountLabel: string;
+    /** Checks shape only; the solver checks the account exists. */
+    accountPattern: RegExp;
+    banks: FiatBank[];
+}
+/**
+ * Nigerian banks with Paystack's codes (CBN codes for commercial banks,
+ * Paystack's own for fintechs). Not exhaustive. Checked against Paystack's
+ * `GET /bank?country=nigeria` on 2026-10-05; re-check when adding banks or a
+ * provider: a wrong code here makes a correct payout fail its commitment
+ * check.
+ */
+declare const NG_BANKS: FiatBank[];
+declare const FIAT_CORRIDORS: Record<string, FiatCorridor>;
+declare const FIAT_CURRENCY_ALIASES: Record<string, string>;
+declare function normalizeFiatCurrency(raw: string | null | undefined): string | null;
+/** Minor units → "151,543.85". */
+declare function formatFiat(minor: string | bigint, corridor: Pick<FiatCorridor, 'decimals'>): string;
+
+/** An off-ramp, resolved: everything needed to ask for fiat quotes. */
+interface OfframpRequest {
+    chainId: number;
+    chainName: string;
+    /** Symbol, as fiat quotes name assets (`USDC`). */
+    asset: string;
+    token: string;
+    decimals: number;
+    /** Base units of `asset`. */
+    amount: bigint;
+    corridor: FiatCorridor;
+}
+/**
+ * Validate a parsed `offramp` intent. Like `validateIntent`, it collects
+ * every problem at once.
+ */
+declare function validateOfframp(raw: RawIntent, supported: SupportedSet): ValidationIssue[];
+/** PRECONDITION: `validateOfframp(raw, supported)` returned no issues. */
+declare function resolveOfframp(raw: RawIntent, supported: SupportedSet): OfframpRequest;
+
 /**
  * Where the flow is.
  *
@@ -395,9 +608,12 @@ declare function stripDomainType(types: Record<string, ReadonlyArray<{
  *   switchingChain / approving / signing / submitting   confirm() progress
  *   tracking      order submitted, polling its status
  *   done          every intent reached a terminal status
+ *   offramp       a cash-out to a bank: `offramp` is resolved; hand it to
+ *                 an off-ramp session (`createOfframpSession`), which
+ *                 collects the bank details and runs the trade
  *   error         something threw; see `error`
  */
-type IntentPhase = 'idle' | 'parsing' | 'offTemplate' | 'invalid' | 'needsWallet' | 'quoting' | 'quoted' | 'switchingChain' | 'approving' | 'signing' | 'submitting' | 'tracking' | 'done' | 'error';
+type IntentPhase = 'idle' | 'parsing' | 'offTemplate' | 'invalid' | 'needsWallet' | 'quoting' | 'quoted' | 'switchingChain' | 'approving' | 'signing' | 'submitting' | 'tracking' | 'done' | 'offramp' | 'error';
 /** What a confirm card shows: human amounts and names, no addresses or base units. */
 interface IntentPreview {
     action: 'swap' | 'send';
@@ -442,6 +658,8 @@ interface IntentState {
     /** Multi-intent sentences run one after another. */
     queueIndex: number;
     queueTotal: number;
+    /** Phase `offramp` only. */
+    offramp: OfframpRequest | null;
 }
 interface IntentSession {
     getState(): IntentState;
@@ -484,30 +702,6 @@ declare function isTerminalStatus(status: OrderStatus): boolean;
  */
 declare function createIntentSession(options?: SessionOptions): IntentSession;
 
-/**
- * The registry has two layers (see docs/intent-parser-design.md §2):
- *  - alias layer (static): maps loose user words → canonical token symbol / chain.
- *  - support layer (dynamic): what solvers can actually fill, from the live aggregator.
- *
- * A word can be a token OR a chain depending on slot (e.g. "eth", "sol"); the grammar
- * decides which table to consult by position, so the same word appears in both.
- */
-interface CanonicalChain {
-    id: number;
-    name: string;
-}
-declare const TOKEN_ALIASES: Record<string, string>;
-declare const CHAIN_ALIASES: Record<string, CanonicalChain>;
-declare function normalizeToken(raw: string | null): string | null;
-declare function normalizeChain(raw: string | null): CanonicalChain | null;
-interface SupportedSet {
-    chains: Set<number>;
-    assets: Map<string, SolverAsset>;
-}
-declare const EMPTY_SUPPORTED: SupportedSet;
-declare function buildSupportedSet(assets: SolverAsset[]): SupportedSet;
-declare function findAsset(set: SupportedSet, chainId: number, symbol: string): SolverAsset | undefined;
-
 /**
  * Validate a parsed intent against the live support set. Collects EVERY problem
  * (missing / unknown / unsupported) so the user can fix them in one edit.
@@ -620,4 +814,235 @@ declare function buildPermit2ApproveRequest(token: Address, amount?: bigint): {
     args: readonly [`0x${string}`, bigint];
 };
 
-export { type AggregationMetadata, type AmountKind, type ApiClient, ApiError, type ApiOptions, type AssetAmount, type AssetLockReference, CHAIN_ALIASES, type CanonicalChain, type ChainInfo, type ChainReader, DEFAULT_API_URL, DEFAULT_INTENT_MODEL, EMPTY_SUPPORTED, HF_ROUTER_URL, type Input, type IntentAction, type IntentPhase, type IntentPreview, type IntentRequest, type IntentSession, type IntentState, type IntentWallet, type InteropAddress, type IssueField, type IssueKind, MAX_UINT256, type Order, type OrderPayload, type OrderRequest, type OrderResponse, type OrderStatus, type OriginSubmission, type Output, PERMIT2_ADDRESS, type ParseResult, type ParserOptions, type Quote, type QuotePreview, type QuoteRequest, type QuotesResponse, type RawIntent, type ResolvedIntent, SOLANA_CHAIN_IDS, type SessionOptions, type Settlement, type Solver, type SolverAsset, type SolverOptions, type SolverSupportedAssets, type SolversResponse, type SupportedSet, TEMPLATE_HINT, TOKEN_ALIASES, type TypedDataSigner, type ValidationIssue, buildOrderRequest, buildPermit2ApproveRequest, buildQuoteRequest, buildSupportedSet, chainName, createApiClient, createIntentSession, explorerUrl, extractIntents, findAsset, getPermit2Allowance, hasPermit2Allowance, interopAddress, isTerminalStatus, normalizeChain, normalizeToken, parseIntent, resolveIntent, rpcReaders, signQuote, stripDomainType, validateIntent, viemWallet };
+/**
+ * Payee bank details for a fiat off-ramp: canonical form, commitment, and
+ * sealing to the matched solver.
+ *
+ * Bank details are personal data. They should reach exactly one party — the
+ * solver who pays out — and never a chain, a log, or the aggregator's
+ * database in readable form. So the client:
+ *
+ * 1. normalises the account identity (`rail`, `bank_code`, `account`) into
+ *    one canonical byte string;
+ * 2. commits to it as `keccak256(canonical ‖ salt)` with a fresh 32-byte
+ *    salt — the aggregator stores only this;
+ * 3. seals the identity, the account holder's name and the salt to the
+ *    solver's key, in the same envelope gift cards use.
+ *
+ * # Why the name is not in the commitment
+ *
+ * A Tier 1 proof is a provider's payout event, and the aggregator checks it
+ * by recomputing the commitment from the account the event names. Providers
+ * report account numbers and bank codes reliably but names in their own
+ * format ("OSAHON GINO" for "Gino Osahon"), so a commitment over the name
+ * would reject honest payouts. The name is sealed for the solver's name
+ * check, which is where it is actually used.
+ *
+ * # Why the commitment is salted
+ *
+ * An account number is short: a Nigerian NUBAN is ten digits with a check
+ * digit, about a billion per bank. Unsalted, anyone holding the database
+ * could hash every one in minutes and read every payee's account back out of
+ * its commitment. The salt travels inside the envelope, so the solver can
+ * attach it to a proof and the user can reveal it in a dispute.
+ *
+ * # Canonical form
+ *
+ * Each identity field is normalised and then restricted to a plain character
+ * set, so the canonical JSON needs no escaping and is byte-identical in every
+ * language. The Rust side (`oif_types::fiat_trades::payee`) implements the
+ * same rules, and both are tested against `test-vectors/fiat-payee.json` at
+ * the repository root.
+ */
+
+/** Payee details as a user enters them. */
+interface FiatPayee {
+    /** Stable `country.rail` id, e.g. `ng.nip`, `eu.sepa_instant`, `ke.mpesa`. */
+    rail: string;
+    /** Bank or institution code, e.g. a NIP bank code or a BIC. Empty for rails
+     *  that address an account directly, such as mobile money. */
+    bankCode: string;
+    /** Account number, IBAN, or mobile money number. */
+    account: string;
+    /** The account holder's name, for the solver's name check. */
+    name: string;
+}
+/** The fields that identify where the money goes, normalised. */
+interface PayeeIdentity {
+    rail: string;
+    bank_code: string;
+    account: string;
+}
+/** The sealed envelope. Same shape as the aggregator's `SealedCode`. */
+interface SealedPayee {
+    v: 1;
+    alg: 'ECIES-secp256k1-AES256GCM';
+    epk: Hex;
+    iv: Hex;
+    ct: Hex;
+    tag: Hex;
+}
+/** What the solver recovers on opening an envelope. */
+interface OpenedPayee {
+    identity: PayeeIdentity;
+    name: string;
+    salt: Hex;
+}
+/** Normalise and validate the account identity. Throws on anything that
+ *  would not be safe to commit to.
+ *
+ *  - ASCII whitespace (space, tab, CR, LF) is removed from every field, and
+ *    `-` from the account — so an IBAN written in groups of four and the
+ *    same IBAN written solid are one account.
+ *  - The character set is checked *before* case is changed, and only ASCII
+ *    is accepted. Unicode case mapping would otherwise turn `ß` into `SS`
+ *    or the Kelvin sign into `k`, quietly making a different account; and
+ *    "whitespace" means different characters in different languages, so
+ *    only the ASCII set is stripped and anything else is rejected. */
+declare function payeeIdentity(payee: Pick<FiatPayee, 'rail' | 'bankCode' | 'account'>): PayeeIdentity;
+/** The canonical bytes, as a string: compact JSON with keys in sorted
+ *  order. The character sets enforced by [`payeeIdentity`] mean no value
+ *  ever needs escaping. */
+declare function canonicalPayeeIdentity(identity: PayeeIdentity): string;
+/** `keccak256(canonical ‖ salt)`, `0x`-hex — what the aggregator stores. */
+declare function payeeCommitment(identity: PayeeIdentity, salt: Hex): Hex;
+/** Seal `payee` to the matched solver's encryption key.
+ *
+ *  Returns the envelope and commitment to send to the aggregator, and the
+ *  salt for the user to keep: in a dispute, the details plus the salt are
+ *  what prove which account the solver was told to pay.
+ *
+ *  @param solverPubkey The solver's 65-byte uncompressed secp256k1 key.
+ *  @param salt Only for test vectors. Omit it: a fresh random salt is what
+ *         makes the commitment unguessable. */
+declare function sealPayee(payee: FiatPayee, solverPubkey: Hex, salt?: Hex): {
+    sealed: SealedPayee;
+    commitment: Hex;
+    salt: Hex;
+};
+/** Open an envelope as the solver, and check it against the trade's
+ *  commitment.
+ *
+ *  `expectedCommitment` is required, not optional: a solver must never pay
+ *  out to details that do not match what the aggregator recorded. Otherwise
+ *  a user could seal one account, commit to another, get paid, and then
+ *  dispute the payout as going to "the wrong account".
+ *
+ *  Throws if the envelope was tampered with, was sealed to another key, or
+ *  does not match the commitment. */
+declare function openPayee(sealed: SealedPayee, solverPrivkey: Hex, expectedCommitment: Hex): OpenedPayee;
+
+/**
+ * Where an off-ramp is.
+ *
+ *   idle                   nothing asked yet
+ *   needsWallet            ready to quote once a wallet is set
+ *   quoting / quoted       ranking solvers' offers; `preview` is ready
+ *   switchingChain / approving / opening / signing / locking   confirm() progress
+ *   awaitingFiat           the USDC is locked; the solver is paying out
+ *   awaitingConfirmation   the solver says it paid: the user checks their bank
+ *                          and confirms or disputes. Nothing releases the
+ *                          escrow until they do (design §6.1)
+ *   confirming / disputing signing and sending that answer
+ *   disputed               an admin decides; nobody's clock runs
+ *   settled                the solver was paid out of escrow (the user has the fiat)
+ *   refunded               the USDC went back to the user
+ *   failed                 the lock never landed; nothing moved
+ *   error                  something threw before a trade existed; see `error`
+ */
+type OfframpPhase = 'idle' | 'needsWallet' | 'quoting' | 'quoted' | 'switchingChain' | 'approving' | 'opening' | 'signing' | 'locking' | 'awaitingFiat' | 'awaitingConfirmation' | 'confirming' | 'disputing' | 'disputed' | 'settled' | 'refunded' | 'failed' | 'error';
+/** A confirm card's worth: human amounts, no base units. */
+interface OfframpPreview {
+    payAmount: string;
+    paySymbol: string;
+    chainName: string;
+    /** What reaches the bank account. */
+    receiveAmount: string;
+    currency: string;
+    currencySymbol: string;
+    fee: string;
+    /** Fiat per one unit of the asset. */
+    rate: string;
+    /** How long the solver has to pay once the USDC is locked. */
+    paymentWindowSecs: number;
+    quotesConsidered: number;
+}
+interface OfframpState {
+    phase: OfframpPhase;
+    request: OfframpRequest | null;
+    quote: RankedFiatQuote | null;
+    preview: OfframpPreview | null;
+    /** A Permit2 approval of the asset comes first. */
+    needsApproval: boolean;
+    trade: FiatTrade | null;
+    /**
+     * The salt the bank details were committed with. With the details, it
+     * proves in a dispute which account the solver was told to pay, so offer
+     * it to the user to keep. Only known in the session that opened the trade.
+     */
+    payeeSalt: Hex | null;
+    /** The last failure. During a trade, the phase still follows the trade. */
+    error: string | null;
+}
+interface OfframpSession {
+    getState(): OfframpState;
+    subscribe(listener: (state: OfframpState) => void): () => void;
+    /** Rank solvers' offers for `request`. */
+    quote(request: OfframpRequest): Promise<void>;
+    /** Seal `payee` to the chosen solver, open the trade, and lock the asset. */
+    confirm(payee: FiatPayee): Promise<void>;
+    /** The fiat arrived: release the escrow to the solver. */
+    confirmReceived(): Promise<void>;
+    /** The fiat did not arrive (or not in full): an admin decides. */
+    dispute(reason: string): Promise<void>;
+    /** Pick a trade back up by id, e.g. after a reload, and track it. */
+    resume(tradeId: string): Promise<void>;
+    reset(): void;
+    setWallet(wallet: IntentWallet | null): void;
+    destroy(): void;
+}
+interface OfframpOptions extends ApiOptions {
+    api?: ApiClient;
+    wallet?: IntentWallet | null;
+    /** Trade-status polling interval. Default 3000ms. */
+    pollIntervalMs?: number;
+    /** Chain reads (Permit2 allowance, receipts). Defaults to the aggregator's RPCs. */
+    chainReader?: (chainId: number) => Promise<ChainReader | null>;
+}
+/**
+ * Before the user signs, check that what the aggregator asks them to sign
+ * is the trade they chose: this asset and amount, from this chain, to the
+ * escrow, with the quoted solver as counterparty, for the quoted payout. A
+ * signature is a spend authorisation, so it is never given on trust.
+ */
+declare function checkLock(lock: FiatLockInstructions, trade: FiatTrade, request: OfframpRequest, quote: RankedFiatQuote, user: string): void;
+/**
+ * Cash crypto out to a bank account, as a framework-free store (design §5.1):
+ * quote → (approve) → open → sign the lock → the solver's relay locks it →
+ * the solver pays → the user confirms or disputes.
+ *
+ * The bank details are sealed in the browser to the chosen solver's key;
+ * the aggregator sees only the envelope and a salted commitment.
+ */
+declare function createOfframpSession(options?: OfframpOptions): OfframpSession;
+
+/**
+ * What a user signs (EIP-191 `personal_sign`) to act on a fiat trade.
+ *
+ * One message per action, each naming the trade, so a signature is good for
+ * exactly one action on one trade: a signature given to dispute can never be
+ * replayed to confirm, which would release the escrow. These must match
+ * `oif_types::fiat_trades::actions` byte for byte; both are tested against
+ * `test-vectors/fiat-actions.json` at the repository root.
+ *
+ * The aggregator accepts only printable ASCII for reasons and references,
+ * so trimming here and there cannot disagree.
+ */
+/** The fiat receiver confirms the payment arrived. Releases the escrow to the payer. */
+declare function fiatConfirmMessage(tradeId: string): string;
+/** The fiat receiver contests the payer's claim. The reason is signed too. */
+declare function fiatDisputeMessage(tradeId: string, reason: string): string;
+/** A user who pays fiat (on-ramp) says it is sent, with the transfer's reference. */
+declare function fiatPaymentSentMessage(tradeId: string, reference: string): string;
+
+export { type AggregationMetadata, type AmountKind, type ApiClient, ApiError, type ApiOptions, type AssetAmount, type AssetLockReference, BANK_DETAILS_HINT, CHAIN_ALIASES, type CanonicalChain, type ChainInfo, type ChainReader, DEFAULT_API_URL, DEFAULT_INTENT_MODEL, EMPTY_SUPPORTED, FIAT_CORRIDORS, FIAT_CURRENCY_ALIASES, type FiatBank, type FiatCorridor, type FiatDirection, type FiatLockInstructions, type FiatPayee, type FiatTrade, type FiatTradeState, HF_ROUTER_URL, type Input, type IntentAction, type IntentPhase, type IntentPreview, type IntentRequest, type IntentSession, type IntentState, type IntentWallet, type InteropAddress, type IssueField, type IssueKind, MAX_UINT256, NG_BANKS, type OfframpOptions, type OfframpPhase, type OfframpPreview, type OfframpRequest, type OfframpSession, type OfframpState, type OpenFiatTradeRequest, type OpenFiatTradeResponse, type OpenedPayee, type Order, type OrderPayload, type OrderRequest, type OrderResponse, type OrderStatus, type OriginSubmission, type Output, PERMIT2_ADDRESS, type ParseResult, type ParserOptions, type PayeeIdentity, type Quote, type QuotePreview, type QuoteRequest, type QuotesResponse, type RankFiatQuotesRequest, type RankFiatQuotesResponse, type RankedFiatQuote, type RawIntent, type ResolvedIntent, SOLANA_CHAIN_IDS, type SealedPayee, type SessionOptions, type Settlement, type Solver, type SolverAsset, type SolverOptions, type SolverSupportedAssets, type SolversResponse, type SupportedSet, TEMPLATE_HINT, TOKEN_ALIASES, type TypedDataSigner, type ValidationIssue, buildOrderRequest, buildPermit2ApproveRequest, buildQuoteRequest, buildSupportedSet, canonicalPayeeIdentity, chainName, checkLock, createApiClient, createIntentSession, createOfframpSession, explorerUrl, extractIntents, fiatConfirmMessage, fiatDisputeMessage, fiatPaymentSentMessage, findAsset, formatFiat, getPermit2Allowance, hasPermit2Allowance, interopAddress, isTerminalStatus, looksLikeBankDetails, normalizeChain, normalizeFiatCurrency, normalizeToken, openPayee, parseIntent, payeeCommitment, payeeIdentity, resolveIntent, resolveOfframp, rpcReaders, sealPayee, signQuote, stripDomainType, validateIntent, validateOfframp, viemWallet };