@gibs/bridge-sdk 1.12.0 → 1.13.0

package/dist/origin-deposit.d.ts

@@ -0,0 +1,326 @@
+import type { Hex } from 'viem';
+/**
+ * An Ethereum-Virtual-Machine origin deposit: the transaction the user signs on
+ * the source chain.
+ *
+ * Every variant in {@link OriginDeposit} is produced by the Relay parser, but
+ * being produced is not the same as being signable: a variant can only be
+ * executed where the interface has a wallet adapter for its ecosystem. This
+ * repository's interface now has one for every variant below, including Tron and
+ * The Open Network. An interface that does not must reject the variant
+ * explicitly rather than let it reach a signer meant for another ecosystem.
+ */
+export type EvmDeposit = {
+    ecosystem: 'evm';
+    to: Hex;
+    data: Hex;
+    value: bigint;
+    chainId: number;
+    gasLimit: bigint | null;
+};
+/** One Solana instruction: the account metas, the program, and hex-encoded instruction data. */
+export type SolanaInstruction = {
+    keys: Array<{
+        pubkey: string;
+        isSigner: boolean;
+        isWritable: boolean;
+    }>;
+    programId: string;
+    data: string;
+};
+/**
+ * A Solana origin deposit expressed as the raw instruction set plus the
+ * address-lookup-table addresses, which the execution layer compiles into a
+ * versioned transaction with the Solana web3 library. There is no separate
+ * fee-payer field — the fee payer is the signer account inside an
+ * instruction's keys. This is the shape Relay returns.
+ *
+ * Because the transaction is compiled at signing time, its recent blockhash is
+ * stamped then too, so this form does not go stale while the user deliberates.
+ */
+export type SolanaInstructionsDeposit = {
+    ecosystem: 'svm';
+    form: 'instructions';
+    instructions: SolanaInstruction[];
+    addressLookupTableAddresses: string[];
+    chainId: number;
+};
+/**
+ * A Solana origin deposit that arrives ALREADY COMPILED: a base64 versioned
+ * (v0) transaction the wallet deserializes, signs and sends unchanged. This is
+ * the shape LI.FI's plain `/v1/quote` returns for a Solana origin, where the
+ * whole payload is a single `transactionRequest.data` string with no `to`,
+ * `value` or `chainId` beside it.
+ *
+ * The two forms are kept as separate members of a discriminated union rather
+ * than one type with optional fields, because they are not interchangeable at
+ * the signer: this one must NOT be recompiled or re-stamped, and the
+ * instruction form cannot be signed without being compiled first.
+ *
+ * GOTCHA: the quote bakes a recent blockhash into the serialized bytes, so this
+ * form EXPIRES (Solana retains roughly 150 blocks, on the order of a minute).
+ * A quote the user sits on will be rejected as an expired blockhash rather than
+ * silently re-priced, so treat a stale-transaction failure as "re-quote", not
+ * as a wallet fault.
+ */
+export type SolanaSerializedDeposit = {
+    ecosystem: 'svm';
+    form: 'serialized';
+    /** The compiled v0 transaction, base64, exactly as the provider returned it. */
+    transaction: string;
+    chainId: number;
+};
+/** A Solana origin deposit in either of the two forms providers return. */
+export type SolanaDeposit = SolanaInstructionsDeposit | SolanaSerializedDeposit;
+/** A Bitcoin origin deposit: either a partially-signed transaction, or a deposit address plus an amount in satoshis. */
+export type BitcoinDeposit = {
+    ecosystem: 'bvm';
+    psbt: string | null;
+    depositAddress: string;
+    amountSats: bigint;
+    chainId: number;
+};
+/**
+ * A Tron origin deposit: one contract call for the user's wallet to sign and
+ * broadcast. Relay returns Tron's own wire shape, whose field names are
+ * snake_case and whose addresses are hex with Tron's `41` prefix byte rather
+ * than `0x`; the fields are renamed here to the codebase's conventions and the
+ * wire name of each is recorded so a signer can map back without guessing.
+ */
+export type TronDeposit = {
+    ecosystem: 'tvm';
+    /** Tron contract type; `TriggerSmartContract` is the only shape Relay returns. Wire name `type`. */
+    contractType: string;
+    /** The signer's account, hex with Tron's `41` prefix. Wire name `parameter.owner_address`. */
+    ownerAddress: string;
+    /** The contract being called, hex with Tron's `41` prefix. Wire name `parameter.contract_address`. */
+    contractAddress: string;
+    /** Native TRX sent with the call, in sun. Wire name `parameter.call_value`. */
+    callValue: bigint;
+    /** Call data as bare hex with NO `0x` prefix, unlike every Ethereum payload. Wire name `parameter.data`. */
+    data: string;
+    chainId: number;
+};
+/**
+ * One message in a TON deposit. TON wallets send a list of messages rather than
+ * a single transaction, and the payload (`body`) is a base64 bag-of-cells, not
+ * hex.
+ */
+export type TonMessage = {
+    /** Destination account. */
+    to: string;
+    /** Amount attached to the message, in nanotons. */
+    value: bigint;
+    /** Base64 bag-of-cells payload. */
+    body: string;
+    /** TON send mode flags. */
+    mode: number;
+    /** Whether the message bounces back if the destination cannot accept it. */
+    bounce: boolean;
+    /** Sending account; absent when the wallet is left to fill it in. */
+    from: string | null;
+};
+/**
+ * A TON origin deposit: the message list the user's wallet signs and sends.
+ */
+export type TonDeposit = {
+    ecosystem: 'tonvm';
+    messages: TonMessage[];
+    chainId: number;
+};
+/** One field of an typed-data structure: its name and its solidity-style type. */
+export type TypedDataField = {
+    name: string;
+    type: string;
+};
+/**
+ * The authorization a Hyperliquid deposit must complete BEFORE its action is
+ * submitted: the user signs `sign` as typed data, then the signature and `post`
+ * are sent to Relay. Skipping it makes the action unusable, which is why it
+ * travels with the deposit rather than being dropped as a separate step.
+ */
+export type HyperliquidAuthorization = {
+    /** The typed-data structure the user signs. */
+    sign: {
+        /** Signing scheme; `eip712` is the only value observed. */
+        signatureKind: string;
+        domain: Record<string, unknown>;
+        types: Record<string, TypedDataField[]>;
+        value: Record<string, unknown>;
+        primaryType: string;
+    };
+    /** Where the resulting signature is submitted. */
+    post: {
+        endpoint: string;
+        method: string;
+        body: Record<string, unknown>;
+    };
+};
+/**
+ * A Hyperliquid origin deposit. Unlike every other ecosystem, nothing here is
+ * broadcast to a chain: the user signs a typed-data ACTION and it is posted to
+ * Hyperliquid's API. There is therefore no transaction, no gas, and no calldata
+ * — and two signatures are required, the {@link HyperliquidAuthorization} first
+ * and this action second.
+ */
+export type HyperliquidDeposit = {
+    ecosystem: 'hypevm';
+    /** The action to sign, e.g. `sendAsset`, with its parameters. */
+    action: {
+        type: string;
+        parameters: Record<string, unknown>;
+    };
+    /** Typed-data structures for the action. */
+    eip712Types: Record<string, TypedDataField[]>;
+    /** Which structure in `eip712Types` the action signs. */
+    eip712PrimaryType: string;
+    /** Replay-protection nonce, shared with the authorization. */
+    nonce: bigint;
+    /** The authorization to complete first; null when Relay omits that step. */
+    authorization: HyperliquidAuthorization | null;
+    chainId: number;
+};
+/**
+ * An origin deposit that is an ADDRESS AND AN AMOUNT, with no transaction of
+ * any kind — not a signed one, not an unsigned one, not a partially-signed one.
+ * The reader pays it by hand, from any wallet or any exchange, on a chain this
+ * interface has no wallet connector for.
+ *
+ * DISCRIMINATED BY `kind`, NOT BY `ecosystem`, AND THAT IS DELIBERATE. Every
+ * other variant here is tagged with the ecosystem whose signer it needs. This
+ * one needs no signer, and the SAME shape serves Zcash, Dogecoin, Litecoin and the
+ * XRP Ledger alike — the chain is `chainId`, not the type. Tagging it with an
+ * ecosystem would force one variant per chain for no difference in handling,
+ * and would let an ecosystem guard such as {@link isBitcoinDeposit} claim a
+ * deposit that has nothing to sign.
+ *
+ * NOT A VARIANT OF {@link BitcoinDeposit}, AND THE DIFFERENCE IS THE POINT.
+ * `BitcoinDeposit.psbt` is nullable, so it can already carry an address and no
+ * partially-signed transaction. But a name is a claim: `psbt` says a
+ * partially-signed Bitcoin transaction is the thing that might be missing, and
+ * here there is no such thing even in principle. A reader who found
+ * `psbt: null` on a Zcash deposit would reach for the signer that fills it in.
+ * There is no signer.
+ *
+ * WHERE EVERY FIELD COMES FROM, because this is the whole safety argument: the
+ * address is read off the provider's LIVE answer and nowhere else. It is never
+ * typed, never seeded from a link, never derived on this side. A provider
+ * answer with no address produces no deposit, and therefore no screen.
+ *
+ * HOW IT MOVES FORWARD. Nothing here is signed or broadcast. The reader sends
+ * an ordinary transfer, the provider's own watcher sees it arrive at the
+ * address it issued, and the existing status poll — keyed by this same
+ * address — reports the fill.
+ */
+export type DepositAddressDeposit = {
+    kind: 'deposit-address';
+    /** The origin chain. */
+    chainId: number;
+    /**
+     * The address the provider reserved for this one quote, exactly as it
+     * answered. Single-use: a second quote for the same route gets a different
+     * address.
+     */
+    depositAddress: string;
+    /**
+     * What the reader is asked to send, in base units of the origin asset. The
+     * amount the quote was priced at.
+     */
+    amount: bigint;
+    /**
+     * The smallest payment the provider will still fill, in the same base units.
+     *
+     * NOT A RESTATEMENT OF `amount`. The request asks for a flexible input, so
+     * the provider names a floor about one percent under the quote and fills
+     * anything at or above it. A reader typing a figure into an exchange
+     * withdrawal form misses the exact amount routinely, and this tolerance is
+     * what turns those payments into fills rather than refunds.
+     */
+    minimumAmount: bigint;
+    /** Decimal places of the origin asset, so a screen can print the amounts without a second lookup. */
+    decimals: number;
+    /**
+     * When the address goes cold, in milliseconds since the epoch.
+     *
+     * READ OFF THE ANSWER, NEVER OFF THE ECHOED REQUEST. The provider discards
+     * the deadline a caller asks for and substitutes one three days out. A screen
+     * built on the echoed request would run a thirty-minute countdown against an
+     * address that is live for three days.
+     */
+    expiresAtMs: number;
+};
+/**
+ * A route that has been PRICED BUT NOT RESERVED: there is nothing to pay yet.
+ *
+ * WHY IT EXISTS. NEAR Intents reserves a real deposit address, with a
+ * three-day clock, for every live quote it answers. Asking live merely to draw
+ * a route on screen reserved one per keystroke, per route, for readers who
+ * mostly never paid, and registered their recipient and refund accounts with
+ * the provider on every glance. So a route on display is priced with a dry
+ * quote, which carries figures and no address, and its deposit says so here.
+ *
+ * WHAT A SURFACE MUST DO WITH ONE. Nothing that pays: it has no address, no
+ * calldata and no amount to send. The moment the reader commits — the press
+ * before a signature, or "Show payment address" on a route paid by hand — the
+ * surface asks for a live quote and pays that one instead, having checked its
+ * terms against what the reader was shown.
+ */
+export type UnreservedDeposit = {
+    kind: 'unreserved';
+    /** The origin chain the route was priced from. */
+    chainId: number;
+};
+/** The origin deposit for any supported source ecosystem. */
+export type OriginDeposit = EvmDeposit | SolanaDeposit | BitcoinDeposit | TronDeposit | TonDeposit | HyperliquidDeposit | DepositAddressDeposit | UnreservedDeposit;
+export declare const isEvmDeposit: (deposit: OriginDeposit) => deposit is EvmDeposit;
+export declare const isSolanaDeposit: (deposit: OriginDeposit) => deposit is SolanaDeposit;
+/**
+ * Narrows a Solana deposit to the instruction form, which must be compiled
+ * before it can be signed.
+ */
+export declare const isSolanaInstructionsDeposit: (deposit: SolanaDeposit) => deposit is SolanaInstructionsDeposit;
+/**
+ * Narrows a Solana deposit to the pre-compiled form, which must be signed
+ * as-is.
+ */
+export declare const isSolanaSerializedDeposit: (deposit: SolanaDeposit) => deposit is SolanaSerializedDeposit;
+export declare const isBitcoinDeposit: (deposit: OriginDeposit) => deposit is BitcoinDeposit;
+export declare const isTronDeposit: (deposit: OriginDeposit) => deposit is TronDeposit;
+export declare const isTonDeposit: (deposit: OriginDeposit) => deposit is TonDeposit;
+export declare const isHyperliquidDeposit: (deposit: OriginDeposit) => deposit is HyperliquidDeposit;
+/**
+ * Narrows a deposit to the pay-by-hand shape: an address, an amount, and
+ * nothing to sign.
+ *
+ * THE GUARD EVERY EXECUTION PATH MUST ASK FIRST. A surface that falls through
+ * to a signer with one of these has no transaction to give it, and a surface
+ * that asks the reader to connect a wallet is asking for one that does not
+ * exist for this chain.
+ *
+ * @param deposit - any origin deposit
+ * @returns whether the reader pays this one by hand
+ */
+export declare const isDepositAddressDeposit: (deposit: OriginDeposit) => deposit is DepositAddressDeposit;
+/**
+ * Narrows a deposit to the priced-but-not-reserved shape: a route on display,
+ * with nothing to pay until a live quote replaces it.
+ *
+ * @param deposit - any origin deposit
+ * @returns whether the route must be quoted live before anything is paid
+ */
+export declare const isUnreservedDeposit: (deposit: OriginDeposit) => deposit is UnreservedDeposit;
+/**
+ * Names a deposit's family for a message shown to someone: its ecosystem, or
+ * its `kind` for a deposit that has none — a {@link DepositAddressDeposit}
+ * reads as `"deposit-address"`, an {@link UnreservedDeposit} as `"unreserved"`.
+ *
+ * THE ONE COPY. The same `'ecosystem' in deposit ? deposit.ecosystem :
+ * deposit.kind` expression used to be written out separately in
+ * `consolidated-quote.ts` and in the interface's `consolidated-execute.ts`;
+ * each copy was a chance for the two to describe the same deposit
+ * differently. Import this instead of restating the expression.
+ *
+ * @param deposit - any origin deposit
+ * @returns the ecosystem name, or the deposit's `kind` when it has none
+ */
+export declare const depositFamilyOf: (deposit: OriginDeposit) => string;

package/dist/origin-deposit.js

@@ -0,0 +1,68 @@
+/**
+ * The ecosystem whose signer a deposit needs, or null for a deposit that needs
+ * no signer at all.
+ *
+ * THE ONE PLACE THE ECOSYSTEM TAG IS READ. A {@link DepositAddressDeposit} has
+ * no `ecosystem`, so every guard below asks through this instead of reading the
+ * field directly — which also means no ecosystem guard can ever answer true for
+ * a deposit the reader pays by hand.
+ *
+ * TYPED `Ecosystem | null`, NOT `string | null`. A `string` return let a typo
+ * such as `signerEcosystemOf(deposit) === 'hypvm'` compile silently — the
+ * comparison is just false forever, so `isHyperliquidDeposit` would always
+ * answer false and every Hyperliquid deposit would fall through to the
+ * Ethereum branch. Typed on the union, the same typo fails to compile instead.
+ */
+const signerEcosystemOf = (deposit) => 'ecosystem' in deposit ? deposit.ecosystem : null;
+export const isEvmDeposit = (deposit) => signerEcosystemOf(deposit) === 'evm';
+export const isSolanaDeposit = (deposit) => signerEcosystemOf(deposit) === 'svm';
+/**
+ * Narrows a Solana deposit to the instruction form, which must be compiled
+ * before it can be signed.
+ */
+export const isSolanaInstructionsDeposit = (deposit) => deposit.form === 'instructions';
+/**
+ * Narrows a Solana deposit to the pre-compiled form, which must be signed
+ * as-is.
+ */
+export const isSolanaSerializedDeposit = (deposit) => deposit.form === 'serialized';
+export const isBitcoinDeposit = (deposit) => signerEcosystemOf(deposit) === 'bvm';
+export const isTronDeposit = (deposit) => signerEcosystemOf(deposit) === 'tvm';
+export const isTonDeposit = (deposit) => signerEcosystemOf(deposit) === 'tonvm';
+export const isHyperliquidDeposit = (deposit) => signerEcosystemOf(deposit) === 'hypevm';
+/**
+ * Narrows a deposit to the pay-by-hand shape: an address, an amount, and
+ * nothing to sign.
+ *
+ * THE GUARD EVERY EXECUTION PATH MUST ASK FIRST. A surface that falls through
+ * to a signer with one of these has no transaction to give it, and a surface
+ * that asks the reader to connect a wallet is asking for one that does not
+ * exist for this chain.
+ *
+ * @param deposit - any origin deposit
+ * @returns whether the reader pays this one by hand
+ */
+export const isDepositAddressDeposit = (deposit) => 'kind' in deposit && deposit.kind === 'deposit-address';
+/**
+ * Narrows a deposit to the priced-but-not-reserved shape: a route on display,
+ * with nothing to pay until a live quote replaces it.
+ *
+ * @param deposit - any origin deposit
+ * @returns whether the route must be quoted live before anything is paid
+ */
+export const isUnreservedDeposit = (deposit) => 'kind' in deposit && deposit.kind === 'unreserved';
+/**
+ * Names a deposit's family for a message shown to someone: its ecosystem, or
+ * its `kind` for a deposit that has none — a {@link DepositAddressDeposit}
+ * reads as `"deposit-address"`, an {@link UnreservedDeposit} as `"unreserved"`.
+ *
+ * THE ONE COPY. The same `'ecosystem' in deposit ? deposit.ecosystem :
+ * deposit.kind` expression used to be written out separately in
+ * `consolidated-quote.ts` and in the interface's `consolidated-execute.ts`;
+ * each copy was a chance for the two to describe the same deposit
+ * differently. Import this instead of restating the expression.
+ *
+ * @param deposit - any origin deposit
+ * @returns the ecosystem name, or the deposit's `kind` when it has none
+ */
+export const depositFamilyOf = (deposit) => 'ecosystem' in deposit ? deposit.ecosystem : deposit.kind;

package/dist/pre-quote.d.ts

@@ -0,0 +1,198 @@
+import type { Hex } from 'viem';
+import { type OriginVmType } from './consolidated-quote.js';
+import { type RelayTradeType } from './relay-quote.js';
+/**
+ * Phase one of the two-phase consolidated-route quoting model ("option 2").
+ *
+ * The consolidated route swaps the user's origin token into an ANCHOR token on
+ * an omnibridge entry chain (Ethereum or Binance Smart Chain), then the
+ * omnibridge crosses that anchor onto PulseChain. The execution quote
+ * (consolidated-quote / relay-quote) is EXACT_OUTPUT: it solves BACKWARD to a
+ * FIXED anchor amount, because the omnibridge entry call encodes that exact
+ * amount and it must arrive exactly.
+ *
+ * The problem the EXACT_OUTPUT path cannot answer on its own is "for the user's
+ * fixed input, how much anchor does this entry actually deliver?". Previously
+ * that target was estimated from PRICES, which is fragile (garbage when a price
+ * is missing) and makes every entry target the same value-equivalent amount, so
+ * the routes deliver alike and cannot be ranked by who delivers most.
+ *
+ * The PRE-QUOTE solves that: a plain EXACT_INPUT swap of origin token -> anchor
+ * for the FIXED input, with NO destination transactions. Its delivered amount
+ * is provider-accurate and decimals-correct, with no price dependency. The
+ * caller feeds that delivered amount as the EXACT_OUTPUT `toAmount`, so each
+ * entry now targets its OWN real delivered amount and ranking-by-delivered
+ * becomes meaningful.
+ *
+ * These builders/parsers are deliberately SEPARATE from the EXACT_OUTPUT
+ * consolidated builders so the execution path is never disturbed.
+ */
+/**
+ * Provider-agnostic input for an EXACT_INPUT origin -> anchor pre-quote. A plain
+ * swap: no destination calls, no recipient on PulseChain, no omnibridge entry
+ * call. Carries only what a forward-solving swap needs.
+ */
+export type PreQuoteRequest = {
+    /** Chain the user's funds start on. */
+    fromChainId: number;
+    /**
+     * Origin token address. Typed `string` (not `Hex`) so a non-Ethereum native
+     * currency address (Solana base58 mint, Bitcoin native string) flows through
+     * unchanged; an Ethereum Virtual Machine address is a subset of `string`.
+     */
+    fromTokenAddress: string;
+    /**
+     * The user's origin-chain address. Typed `string` for the same reason as
+     * `fromTokenAddress`: a non-Ethereum origin carries a base58/bech32 address.
+     */
+    fromAddress: string;
+    /** The omnibridge entry chain whose anchor token is the swap target. */
+    toChainId: number;
+    /** The anchor token on the entry chain; always an Ethereum Virtual Machine address. */
+    toTokenAddress: Hex;
+    /** The user's FIXED input amount, in origin-token base units. */
+    amount: bigint;
+    /** Maximum slippage as a fraction (e.g. 0.005); provider default when omitted. */
+    slippage?: number;
+    /**
+     * Virtual-machine family of the ORIGIN chain. Defaults to Ethereum Virtual
+     * Machine when absent. A non-Ethereum origin (`svm`/`bvm`) excludes LI.FI (it
+     * cannot cross ecosystems) and routes the Relay refund to the user's own
+     * origin address.
+     */
+    originVmType?: OriginVmType;
+    /**
+     * Where the swapped anchor conceptually lands on the entry chain (an
+     * Ethereum Virtual Machine address). REQUIRED for a non-Ethereum origin:
+     * Relay validates this address's FORMAT against `toChainId` even though the
+     * pre-quote never executes (no `txs` are attached), so a non-Ethereum
+     * origin's own base58/bech32 `fromAddress` is rejected outright — it is not
+     * an Ethereum-format address. Omitted (and defaulted to `fromAddress`) for
+     * an Ethereum origin, preserving the pre-quote's original behavior there.
+     */
+    recipient?: Hex;
+    /**
+     * The `referrer` sent to Relay. Left out or `null`, the field is OMITTED —
+     * never sent as `''`. Relay's live behavior (verified 2026-09-23) answers a
+     * keyless request with NO `referrer` field 200, but treats ANY `referrer` —
+     * including `''` — as "a referrer was supplied", which requires an API key
+     * and gets 401 without one. A package default would therefore break every
+     * caller without a key, so there is none. A string is sent as-is; Gibs
+     * Finance's own value is `relayReferrer` from `relay-quote.ts`.
+     */
+    relayReferrer?: string | null;
+    /**
+     * Overrides the `integrator` sent to LI.FI: `undefined` defaults to
+     * {@link lifiIntegrator} (a free attribution label, `gibs.finance`),
+     * `null` OMITS the `integrator` query parameter entirely (it is optional
+     * per LI.FI's own `/v1/quote` schema — verified 2026-09-23 — an empty
+     * string is not "absent", it is a literal empty integrator), and a string
+     * is sent as-is.
+     */
+    lifiIntegrator?: string | null;
+};
+/**
+ * The two delivered anchor amounts a pre-quote yields.
+ *
+ * Both come from the provider's own forward solve for the fixed input, so they
+ * are decimals-correct and free of any price dependency.
+ */
+export type PreQuoteResult = {
+    /** The EXPECTED delivered anchor amount, for display and ranking. */
+    expectedAmount: bigint;
+    /**
+     * The GUARANTEED delivered anchor amount after slippage. This is the
+     * conservative figure the caller uses as the EXACT_OUTPUT `toAmount`, so the
+     * fixed input can actually achieve the execution target.
+     */
+    minimumAmount: bigint;
+};
+/**
+ * Plain LI.FI swap quote endpoint (forward-solving), re-exported from
+ * `consolidated-quote.js` rather than redeclared here — both modules must
+ * agree on the same address, and a second literal would be free to drift from
+ * it.
+ */
+export { lifiQuoteUrl, lifiRequestHeaders } from './consolidated-quote.js';
+/**
+ * The JSON body for a Relay EXACT_INPUT swap pre-quote. Mirrors
+ * `RelayQuoteRequestBody` but carries NO `txs` (it is a plain swap) and adds a
+ * `recipient` because, without destination calls, Relay needs an explicit
+ * delivery address on the entry chain.
+ */
+export type RelayPreQuoteRequestBody = {
+    user: string;
+    originChainId: number;
+    originCurrency: string;
+    destinationChainId: number;
+    destinationCurrency: Hex;
+    amount: string;
+    tradeType: RelayTradeType;
+    /** Where the swapped anchor lands on the entry chain (the user, for a pre-quote). */
+    recipient: string;
+    /** Origin-chain refund target; required for Relay to enable automatic refunds. */
+    refundTo: string;
+    /**
+     * OPTIONAL — omitted entirely (not `''`) for an unconfigured host. See
+     * {@link PreQuoteRequest.relayReferrer}'s doc for why `null` and `''` are
+     * two different requests to Relay.
+     */
+    referrer?: string;
+    /** Maximum slippage in basis points; omitted when the caller defers to Relay. */
+    slippageTolerance?: string;
+};
+/**
+ * Builds the Relay EXACT_INPUT swap pre-quote body for a fixed input. NO `txs`
+ * are attached: Relay solves FORWARD and reports the delivered anchor amount.
+ *
+ * `recipient` and `refundTo` name TWO DIFFERENT chains and must never be
+ * conflated. `refundTo` is always the user's OWN origin-chain address — Relay
+ * refunds a failed (or, here, never-run) swap on the origin chain, and an
+ * Ethereum fallback address could not receive one there. `recipient` names
+ * where the swap lands on the ENTRY chain (`toChainId`), which is always
+ * Ethereum Virtual Machine — for an Ethereum origin the user's own address
+ * already satisfies that and is the default; for a non-Ethereum origin
+ * (Solana base58, Bitcoin bech32, ...) it does NOT, and Relay's `/quote/v2`
+ * validates the recipient's FORMAT against `toChainId` even though this
+ * pre-quote never executes. Sending the origin account there — as an earlier
+ * version of this builder did, reasoning that an unexecuted quote's recipient
+ * is "informational" — gets Relay's `400 INVALID_ADDRESS` on every
+ * non-Ethereum-origin pre-quote, which starves `fetchBestEntryAnchorPreQuote`
+ * of its only capable provider and surfaces as "No route available" for the
+ * whole non-Ethereum-origin flow. `request.recipient` (an explicit
+ * Ethereum-format address the caller supplies) is therefore REQUIRED for a
+ * non-Ethereum origin; without it this returns null.
+ *
+ * @param request - the provider-agnostic pre-quote request
+ * @returns the request body, or null when the input amount is non-positive or
+ *   a non-Ethereum origin has no explicit Ethereum-format `recipient`
+ */
+export declare const buildRelayPreQuoteRequest: (request: PreQuoteRequest) => RelayPreQuoteRequestBody | null;
+/**
+ * Builds the plain LI.FI swap pre-quote as a query string for `GET /v1/quote`.
+ * LI.FI's plain `/quote` is forward-solving by construction (`fromAmount` in,
+ * `estimate.toAmount` out), so no trade-type flag is needed.
+ *
+ * Returns null for a non-Ethereum origin (LI.FI cannot bridge across
+ * virtual-machine ecosystems) and for a non-positive input amount.
+ *
+ * @param request - the provider-agnostic pre-quote request
+ * @returns the URL query string (without a leading `?`), or null
+ */
+export declare const buildLifiPreQuoteRequest: (request: PreQuoteRequest) => string | null;
+/**
+ * Parses a Relay EXACT_INPUT pre-quote response. The delivered anchor figures
+ * live under `details.currencyOut`: `amount` (expected) and `minimumAmount`
+ * (guaranteed slippage floor). Verified live against `api.relay.link/quote/v2`.
+ *
+ * @returns the delivered amounts, or null when the payload shape is unexpected
+ */
+export declare const parseRelayPreQuote: (payload: unknown) => PreQuoteResult | null;
+/**
+ * Parses a plain LI.FI `/quote` response. The delivered anchor figures live
+ * under `estimate`: `toAmount` (expected) and `toAmountMin` (guaranteed minimum
+ * after slippage) — the same estimate shape the route-step normalizer reads.
+ *
+ * @returns the delivered amounts, or null when the payload shape is unexpected
+ */
+export declare const parseLifiPreQuote: (payload: unknown) => PreQuoteResult | null;