@gibs/bridge-sdk 1.13.1 → 1.17.0

package/dist/cjs/consolidated-quote.d.ts

@@ -0,0 +1,648 @@
+import { type Hex } from 'viem';
+import type { DestinationCall } from './destination-calldata.js';
+import type { Ecosystem } from './ecosystems.js';
+import { type EvmDeposit, type OriginDeposit } from './origin-deposit.js';
+import type { ProviderId, ProviderQuoteContext } from './providers.js';
+import { type QuoteFee } from './quote-fees.js';
+import type { ApprovalRequirement } from './settings.js';
+import type { RouteStep, Token } from './types.js';
+/**
+ * Gibs Finance's own LI.FI `integrator` label.
+ *
+ * NOT A DEFAULT. A request that leaves
+ * {@link ConsolidatedQuoteRequest.lifiIntegrator} out sends no `integrator`
+ * at all. An integrator label is attribution: LI.FI records the traffic under
+ * it, and pays any `fee` to the account behind it. A wallet that builds on this
+ * package must not attribute its users' routes to Gibs Finance without
+ * choosing to. The Gibs interface passes this value explicitly.
+ */
+export declare const lifiIntegrator = "gibs.finance";
+/**
+ * The referral fee Gibs Finance charges on its own LI.FI routes (0.001 = 0.1%).
+ * No builder applies it. A request carries a fee only when it sets `lifiFee`.
+ */
+export declare const lifiReferralFeePercent = 0.001;
+/**
+ * LI.FI's HTTP origin when the interface's `PUBLIC_LIFI_API_URL` build flag is
+ * unset. Points straight at LI.FI rather than through the server-side proxy,
+ * so local development and the anonymous IPFS build still get real quotes —
+ * at LI.FI's shared, unauthenticated tier — with no configuration at all.
+ */
+export declare const lifiDefaultApiOrigin = "https://li.quest";
+/**
+ * Every LI.FI endpoint address this codebase calls, built from one origin.
+ *
+ * @see {@link lifiEndpoints}
+ */
+export type LifiEndpoints = {
+    /** The plain quote endpoint: carry funds and stop. A GET; parameters ride in the query string. */
+    readonly quote: string;
+    /** Quote endpoint that accepts destination contract calls. A POST. */
+    readonly contractCallsQuote: string;
+    /** Chain listing endpoint. */
+    readonly chains: string;
+    /** Builds the per-chain token listing address. */
+    readonly tokens: (chainId: number) => string;
+    /** Builds the status-poll address for an origin transaction. */
+    readonly status: (params: {
+        txHash: string;
+        fromChainId?: number;
+        toChainId?: number;
+    }) => string;
+};
+/**
+ * Builds every LI.FI endpoint address from one origin — THE ONE PLACE the
+ * `/v1/...` paths are spelled, so a caller pointed at a different origin (the
+ * server-side proxy at `https://lifi.gibs.finance`, or LI.FI itself) never
+ * duplicates them by hand.
+ *
+ * `apiOrigin` is the scheme-plus-host ONLY (e.g. `https://lifi.gibs.finance`),
+ * never a path — a trailing slash is trimmed, but this throws for anything
+ * that is not an absolute `http:`/`https:` URL, so a malformed configuration
+ * fails at startup rather than silently building a broken address.
+ *
+ * @param apiOrigin - the scheme-plus-host to reach LI.FI's `/v1` interface through
+ * @returns a frozen object of every endpoint this codebase calls
+ */
+export declare const lifiEndpoints: (apiOrigin: string) => LifiEndpoints;
+/** Quote endpoint that accepts destination contract calls, at {@link lifiDefaultApiOrigin}. */
+export declare const lifiContractCallsQuoteUrl: string;
+/**
+ * The plain quote endpoint, at {@link lifiDefaultApiOrigin}: carry funds and stop.
+ *
+ * WHICH ENDPOINT A ROUTE USES IS DECIDED BY WHETHER ANYTHING RUNS ON ARRIVAL,
+ * not by which chains the provider covers. A crossing into the omnibridge needs
+ * a call made on the entry chain, so it goes to
+ * {@link lifiContractCallsQuoteUrl} and arrives as one signature. A route the
+ * omnibridge does not touch has nothing to run on arrival, so it asks here.
+ *
+ * A GET, unlike its sibling — the parameters are a query string.
+ */
+export declare const lifiQuoteUrl: string;
+/**
+ * Builds the headers for a LI.FI request.
+ *
+ * CARRIES NO API KEY. LI.FI's own documentation forbids setting
+ * `x-lifi-api-key` in a browser — "Never expose your x-lifi-api-key in
+ * client-side environments such as browser-based JavaScript" — so this
+ * codebase never attaches one here. The key lives on the server-side proxy
+ * (`https://lifi.gibs.finance`) that fronts `lifiApiOrigin`, added to the
+ * outbound request there, never in this bundle. LI.FI answers every endpoint
+ * with no key at a lower, shared rate limit, so a request built from this is a
+ * normal operating state, not a degraded one.
+ *
+ * ONE HELPER FOR EVERY LI.FI ENDPOINT — the plain quote, the contract-calls
+ * quote, `/v1/chains`, `/v1/tokens`, and `/v1/status` all build their headers
+ * through this, rather than each call site duplicating the content-type.
+ */
+export declare const lifiRequestHeaders: () => Record<string, string>;
+/**
+ * Provider-agnostic input for a consolidated quote: bridge `toAmount` of the
+ * Ethereum-side token onto Ethereum and have the aggregator's executor perform
+ * `destinationCall` to relay it onward through the omnibridge.
+ */
+/**
+ * The virtual-machine family of a NON-ETHEREUM origin chain. The destination
+ * half of a consolidated route is always an Ethereum Virtual Machine entry
+ * chain (Ethereum or Binance Smart Chain), so only the origin can differ, and
+ * "Ethereum origin" is spelled by leaving this field UNSET, never by setting
+ * it to `'evm'`.
+ *
+ * - `svm` — Solana Virtual Machine (base58 addresses, native lamports)
+ * - `bvm` — Bitcoin Virtual Machine (bech32/base58 addresses, native satoshis)
+ * - `tvm` — Tron Virtual Machine (base58check addresses, native sun)
+ * - `tonvm` — The Open Network (base64url or raw addresses, native nanotons)
+ * - `hypevm` — Hyperliquid (Ethereum-style accounts, HyperCore token identifiers)
+ * - `zcash` — a pay-by-hand origin (no wallet, no signer; see `chain-names.ts`)
+ *
+ * EXCLUDES `'evm'` ON PURPOSE. `Ecosystem` (this type's source union) includes
+ * `'evm'`, and until this exclusion the field's own type allowed a request to
+ * set `originVmType: 'evm'` explicitly — a request that CONTRADICTS "absent
+ * means Ethereum" without being rejected by anything. `isNonEthereumVirtualMachineOrigin`
+ * and every other reader here treat "absent" and "'evm'" as the same state,
+ * but a caller that built the request the other way used `recipient` as the
+ * Ethereum identity instead of the connected account, silently. Excluding
+ * `'evm'` from the type makes that request impossible to construct, rather
+ * than merely unlikely — the same shape of fix `near-intents.ts` applies to
+ * its own request-building for exactly this reason.
+ */
+export type OriginVmType = Exclude<Ecosystem, 'evm'>;
+export type ConsolidatedQuoteRequest = {
+    /** Chain the user's funds start on (any aggregator-supported chain) */
+    fromChainId: number;
+    /**
+     * Token the user pays with on the origin chain (zero address for an Ethereum
+     * Virtual Machine native asset). Typed as `string` rather than `Hex` so a
+     * non-Ethereum native currency address can flow through unchanged — a Solana
+     * base58 mint or the Bitcoin native-currency string Relay expects. Existing
+     * Ethereum Virtual Machine callers are unaffected: `Hex` is a subset of
+     * `string`, so this is a safe widening.
+     */
+    fromTokenAddress: string;
+    /**
+     * The user's address on the origin chain. Typed as `string` rather than `Hex`
+     * for the same reason as `fromTokenAddress`: a non-Ethereum origin carries a
+     * base58 (Solana) or bech32 (Bitcoin) address here. Ethereum Virtual Machine
+     * callers pass the same `0x` address they always have.
+     *
+     * A CHAIN THE READER PAYS BY HAND HAS NO ORIGIN ADDRESS, because no wallet
+     * connects to it (see `isDepositAddressChain`). Nothing reads this field for
+     * such a route; the refund account travels in
+     * {@link ConsolidatedQuoteRequest.connectedEthereumAccount} instead, under a
+     * name that says what it is.
+     */
+    fromAddress: string;
+    /**
+     * The reader's CONNECTED Ethereum account, exactly as the wallet connection
+     * reports it — never a value from any field the reader can type or a link
+     * can seed.
+     *
+     * Read only for an origin the reader pays by hand. There the NEAR Intents
+     * builder names it, lower-cased, as the refund account inside NEAR Intents:
+     * the reader holds no origin-chain address to refund to, and an Ethereum key
+     * controls the implicit NEAR account of the same name. The service accepts
+     * any string shaped like a NEAR account name, so its acceptance proves
+     * nothing — this field's source is the only proof the refund reaches the
+     * reader. Absent, a pay-by-hand route builds no request at all. See
+     * `docs/near-implicit-account-refunds.md`.
+     */
+    connectedEthereumAccount?: Hex;
+    /** Ethereum-side token the omnibridge mapping accepts */
+    toTokenAddress: Hex;
+    /** Guaranteed minimum amount of the Ethereum-side token arriving, in base units */
+    toAmount: bigint;
+    /**
+     * The omnibridge entry call the executor performs with exactly `toAmount`.
+     *
+     * ABSENT ON A ROUTE THAT DOES NOT TOUCH THE OMNIBRIDGE. Every route this type
+     * described used to end on PulseChain, so an entry call was always part of
+     * the answer: the aggregator carried funds to Ethereum or Binance Smart
+     * Chain, and this call handed them to the bridge. A route between two chains
+     * the bridge's own contracts do not run on has no such leg — the provider
+     * delivers to the recipient and the journey is over — so this is optional and
+     * its absence is what distinguishes the two kinds.
+     */
+    destinationCall?: DestinationCall;
+    /**
+     * What the reader is spending, in the origin token's base units.
+     *
+     * Carried only for a route with no {@link destinationCall}, and it is what
+     * makes that route a different QUESTION rather than the same one with a
+     * missing field. A route into the omnibridge is solved BACKWARDS: the entry
+     * call must receive an exact amount, so the provider is asked for an exact
+     * OUTPUT and works out the input. A direct route has no such constraint — the
+     * reader says what they are sending — so the provider is asked for an exact
+     * INPUT and the delivered amount is whatever the market gives.
+     */
+    fromAmount?: bigint;
+    /**
+     * Where the bridged tokens are delivered on PulseChain. Already encoded inside
+     * `destinationCall`; carried here as well so the resume record and the
+     * confirmation surface can show the destination without decoding calldata.
+     */
+    recipient: Hex;
+    /** Where tokens land on Ethereum if the destination call reverts */
+    fallbackAddress: Hex;
+    /** Maximum slippage as a fraction (e.g. 0.005); provider default when omitted */
+    slippage?: number;
+    /**
+     * The omnibridge entry chain the aggregator bridges to (Ethereum or Binance
+     * Smart Chain). Defaults to Ethereum when omitted, preserving the original
+     * single-entry behavior.
+     */
+    toChainId?: number;
+    /**
+     * Virtual-machine family of the ORIGIN chain. Defaults to Ethereum Virtual
+     * Machine semantics when absent, so every existing caller behaves exactly as
+     * before. Set to `svm` or `bvm` for a non-Ethereum origin: this is what gates
+     * the provider that may quote the route (only Relay can cross ecosystems) and
+     * what selects the origin-side refund address inside the Relay request
+     * builder.
+     */
+    originVmType?: OriginVmType;
+    /**
+     * Bitcoin pay-to-script-hash public key. Relay requires it via the request's
+     * `additionalData.userPublicKey` to construct a Bitcoin deposit. Only consulted
+     * for a Bitcoin origin (`originVmType` of `bvm`); ignored otherwise.
+     */
+    bitcoinPublicKey?: string;
+    /**
+     * Solana fee-payer address. Relay accepts it as `depositFeePayer` to sponsor
+     * the deposit transaction's fee on Solana. Only consulted for a Solana origin
+     * (`originVmType` of `svm`); ignored otherwise.
+     */
+    solanaFeePayer?: string;
+    /**
+     * LI.FI referral fee as a decimal fraction (e.g. 0.001 = 0.1%). When set and
+     * positive, forwarded as the `fee` parameter in LI.FI quote requests. Omitted
+     * when zero or absent so no fee is charged on unannotated requests.
+     */
+    lifiFee?: number;
+    /**
+     * The LI.FI `integrator` label. Left out or `null`, the field is not sent; a
+     * string is sent as-is. REQUIRED (as a string)
+     * whenever {@link lifiFee} is positive: LI.FI pays a fee to the account behind
+     * the integrator label, so a fee needs a label that is yours.
+     */
+    lifiIntegrator?: string | null;
+    /**
+     * The Relay `referrer`. Left out or `null`, the field is not sent: Relay
+     * reads any `referrer` as "a referrer was supplied" and then requires an API
+     * key, so a default would break a caller who has none. A string is sent as-is.
+     */
+    relayReferrer?: string | null;
+    /**
+     * Relay app-fee configuration. When set, the Relay quote builder attaches the
+     * fee recipient and basis-point amount to the request. Wired in Task 5.
+     */
+    relayAppFee?: {
+        recipient: Hex;
+        basisPoints: bigint;
+    };
+};
+/**
+ * Whether a consolidated quote request originates on a non-Ethereum-Virtual-
+ * Machine chain. A missing `originVmType` is treated as Ethereum Virtual
+ * Machine, so existing callers are never classified non-Ethereum.
+ *
+ * Deliberately expressed as "anything that is not Ethereum" rather than as a
+ * list of the non-Ethereum families. The two behaviors this gates — excluding a
+ * route from LI.FI, and refunding on the ORIGIN chain instead of to an Ethereum
+ * fallback address — are both wrong by default for an unlisted ecosystem, and a
+ * positive list fails open: a newly registered family would be handed to LI.FI
+ * with a non-Ethereum address cast to `Hex`, and would name an Ethereum address
+ * as its origin-chain refund target. Inverting the test makes every future
+ * ecosystem safe on arrival.
+ *
+ * Hyperliquid counts as non-Ethereum here despite using Ethereum-style account
+ * addresses: Relay's origin for it is HyperCore, whose deposit is a signed
+ * typed-data action posted to an API rather than a broadcast transaction, and
+ * which LI.FI does not carry.
+ *
+ * @param request - the consolidated quote request to classify
+ * @returns true when the origin is any ecosystem other than Ethereum
+ */
+export declare const isNonEthereumVirtualMachineOrigin: (request: Pick<ConsolidatedQuoteRequest, "originVmType">) => boolean;
+/** One destination contract call in the LI.FI request body. */
+export type LifiContractCall = {
+    fromAmount: string;
+    fromTokenAddress: Hex;
+    toContractAddress: Hex;
+    toContractCallData: Hex;
+    toContractGasLimit: string;
+    toApprovalAddress?: Hex;
+};
+/** The JSON body for `POST /v1/quote/contractCalls`. */
+export type LifiContractCallsRequestBody = {
+    fromChain: number;
+    fromToken: Hex;
+    fromAddress: Hex;
+    toChain: number;
+    toToken: Hex;
+    toAmount: string;
+    toFallbackAddress: Hex;
+    /** Present only when the request names a `lifiIntegrator`. */
+    integrator?: string;
+    /** Referral fee as a decimal fraction (e.g. 0.001 = 0.1%). Omitted when not charging a fee. */
+    fee?: number;
+    slippage?: number;
+    contractCalls: LifiContractCall[];
+};
+/**
+ * The attribution fields of a LI.FI request: the `integrator` label and, when
+ * one is charged, the referral `fee`. Shared by both LI.FI builders so the two
+ * endpoints can never attribute or charge differently.
+ *
+ * @param request - the consolidated request's attribution fields
+ * @returns the fields to merge into the request; empty when none apply
+ * @throws when a positive `lifiFee` arrives without an explicit `lifiIntegrator`
+ *   string — LI.FI would have nobody of yours to pay it to
+ */
+export declare const lifiAttribution: (request: Pick<ConsolidatedQuoteRequest, "lifiFee" | "lifiIntegrator">) => {
+    integrator?: string;
+    fee?: number;
+};
+/**
+ * Builds the LI.FI contract-calls quote request from a provider-agnostic
+ * consolidated request. LI.FI quotes backwards from `toAmount` (the guaranteed
+ * minimum arriving on Ethereum), which is what makes the fixed amount inside
+ * the destination calldata safe.
+ *
+ * @returns the request body, or null when the inputs cannot form a valid call
+ */
+/**
+ * Builds the query string for LI.FI's plain `GET /v1/quote`.
+ *
+ * THE ROUTE THIS EXISTS FOR. A crossing with no omnibridge leg had exactly one
+ * bidder — Relay — because our only LI.FI endpoint was the contract-calls one,
+ * which cannot express a route that calls nothing. Every any-to-any quote was
+ * therefore a price with nothing to rank it against.
+ *
+ * SOLVED FORWARDS, WHICH IS THE OPPOSITE OF ITS SIBLING. An omnibridge route is
+ * asked for an exact OUTPUT, because the entry call must receive an exact
+ * amount. Here the reader names what they spend and the delivered amount is
+ * whatever the market gives, so `fromAmount` is the input and the answer's
+ * `toAmount` is the thing that differs between providers. Ranking two forward
+ * quotes on what they cost compares two identical numbers — see
+ * `orderQuotesByCost` in the interface, which ranks these on what ARRIVES.
+ *
+ * Returns null for a request carrying a `destinationCall`: that route belongs
+ * to the other endpoint, and sending it here would quote a crossing that stops
+ * on the entry chain and never enters the bridge.
+ *
+ * @param request - the consolidated request to express
+ * @returns the query string, or null when this endpoint cannot express it
+ * @throws when `lifiFee` is positive and `lifiIntegrator` is not a string — see {@link lifiAttribution}
+ */
+export declare const buildLifiQuoteRequest: (request: ConsolidatedQuoteRequest) => string | null;
+export declare const buildLifiContractCallsRequest: (request: ConsolidatedQuoteRequest) => LifiContractCallsRequestBody | null;
+/** Aggregators that can quote the consolidated route. Alias of the registry's id. */
+export type ConsolidatedProvider = ProviderId;
+/**
+ * A provider-agnostic, normalized consolidated quote. The guaranteed minimum
+ * arriving on Ethereum is NOT in here — the response echoes it as zero because
+ * the destination contract call consumes it; callers already hold it on the
+ * request they quoted with.
+ */
+export type ConsolidatedQuote = {
+    provider: ConsolidatedProvider;
+    /** The provider's quote identifier, kept for support and resume records */
+    quoteId: string;
+    /** Bridging tool the provider selected (e.g. stargateV2) */
+    tool: string;
+    /** Human-readable tool name for display */
+    toolName: string;
+    /** Amount of the origin token the user pays, in base units */
+    fromAmount: bigint;
+    /**
+     * What the route delivers, in the destination token's base units, when the
+     * provider is the only one who knows.
+     *
+     * Absent on an omnibridge route and deliberately so: that route asks for an
+     * exact OUTPUT, so the caller already named the delivered amount and reading
+     * it back off the answer would be asking the provider to confirm arithmetic
+     * the caller did. A DIRECT route asks for an exact INPUT, so the delivered
+     * amount exists nowhere until the provider says it.
+     */
+    toAmount?: bigint;
+    /** United States dollar value of `fromAmount`, as reported by the provider */
+    fromAmountUsd: string | null;
+    /**
+     * United States dollar value of {@link toAmount}, as reported by the SAME
+     * provider that valued `fromAmount`.
+     *
+     * WHY THE PROVIDER'S OWN NUMBER AND NOT A PRICE FEED. A route's cost is the
+     * gap between what was paid and what arrived, and that gap is only a cost if
+     * both figures come from one feed — two feeds disagree by more than a small
+     * route's whole fee, which is how a zero-fee crossing once reported a loss.
+     * The provider prices both sides in one answer, so the difference is the
+     * route and nothing else.
+     *
+     * Absent on an omnibridge route for the same reason as {@link toAmount}: the
+     * provider's delivered side there is the ENTRY chain's tokens, not what
+     * finally lands on PulseChain, so its valuation answers a different question.
+     */
+    toAmountUsd?: string;
+    /** Contract the user must approve for token spends on the origin chain, null for native */
+    approvalAddress: Hex | null;
+    /** Provider's estimate of seconds until the route completes */
+    executionDurationSeconds: number;
+    /**
+     * Ordered list of normalized route legs the UI can display as a "steps" view.
+     * Empty when the provider response carries no per-leg breakdown — never undefined.
+     */
+    steps: RouteStep[];
+    /** The signable origin deposit for the user to submit on the source chain */
+    originDeposit: OriginDeposit;
+    /**
+     * What the route charges, normalized across providers.
+     *
+     * Read `includedInFromAmount` before totalling: a charge marked false is paid
+     * ON TOP of `fromAmount`, so `fromAmount` alone is not what the route costs.
+     * See `totalQuoteCostUsd`. Empty when the provider reported no breakdown -
+     * never undefined.
+     */
+    fees: QuoteFee[];
+};
+/**
+ * Narrows a quote's origin deposit to the Ethereum-Virtual-Machine variant.
+ * Throws when the deposit is not Ethereum, because the Ethereum-only execute
+ * path must never silently proceed on a Solana or Bitcoin payload.
+ */
+export declare const evmDepositOf: (quote: ConsolidatedQuote) => EvmDeposit;
+/** Why an aggregator's origin deposit is refused before anything is approved or sent. */
+export type AggregatorOriginRefusal = {
+    reason: 'not-evm-deposit';
+    depositFamily: string;
+} | {
+    reason: 'chain-mismatch';
+    depositChainId: number;
+    requestChainId: number;
+} | {
+    reason: 'unverified-provider';
+    provider: string;
+} | {
+    reason: 'unverified-chain';
+    provider: string;
+    chainId: number;
+} | {
+    reason: 'spender-not-allowed';
+    provider: string;
+    spender: Hex;
+} | {
+    reason: 'deposit-target-not-allowed';
+    provider: string;
+    target: Hex;
+} | {
+    reason: 'deposit-shape';
+    provider: string;
+    detail: string;
+} | {
+    reason: 'amount-mismatch';
+    provider: string;
+    /** Which figure disagreed: the quote's own, the native value, or the amount inside the calldata. */
+    field: 'quote-from-amount' | 'deposit-value' | 'calldata-amount';
+    expected: bigint;
+    actual: bigint;
+} | {
+    reason: 'recipient-mismatch';
+    provider: string;
+    /** Which address disagreed: the native payee, the transfer payee, or the token a deposit names. */
+    field: 'deposit-to' | 'transfer-to' | 'calldata-token';
+    expected: string;
+    actual: string;
+} | {
+    reason: 'lifi-guard';
+    detail: string;
+};
+/**
+ * What an aggregator's Ethereum origin deposit asks the wallet to send: the
+ * approval it needs first, if any, and the deposit itself. Both are checked
+ * before they are returned.
+ */
+export type AggregatorOriginCalls = {
+    kind: 'calls';
+    approval: ApprovalRequirement | null;
+    deposit: EvmDeposit;
+} | {
+    kind: 'refused';
+    refusal: AggregatorOriginRefusal;
+};
+/**
+ * Reads the approval and the deposit off an aggregator quote with an Ethereum
+ * origin, after checking both against what this code knows about the
+ * provider. The interface's aggregator press (`stores/consolidated-execute.ts`)
+ * and the SDK's execution planner both read them here, so neither can sign a
+ * call the other would refuse.
+ *
+ * WHAT IS CHECKED, BEFORE ANYTHING IS APPROVED OR SENT:
+ * - Every provider: when the request names the amount to send
+ *   (`request.fromAmount`), the quote's own `fromAmount` must equal it.
+ * - LI.FI: `verifyLifiEvmExecution`: the Diamond for the chain, a known
+ *   facet call, calldata that matches the request, and the decoded amount
+ *   pulled from the reader equal to the amount to send.
+ * - Relay: the deposit target and the spender are Relay's depository for the
+ *   chain (`relayDepositoryByChainId`). A native deposit carries the amount
+ *   as `value` through `depositNative`; a token deposit carries no value and
+ *   is `depositErc20` for the request's token and the amount.
+ * - NEAR Intents: no spender, and a plain payment of the amount to send to the
+ *   quote's own deposit address (`quote.quoteId`), native or `transfer`.
+ * - Any other provider is refused. Its spender is unknown.
+ *
+ * The approval is for exactly the amount to send (the request's, else the
+ * quote's when the route is solved backwards and the request names none), on
+ * the request's origin chain. The native coin needs none.
+ *
+ * @param options.quote - the live quote to sign
+ * @param options.request - the request it answered
+ * @returns the checked approval and deposit, or why they are refused
+ */
+export declare const aggregatorOriginCalls: ({ quote, request, }: {
+    quote: ConsolidatedQuote;
+    request: ConsolidatedQuoteRequest;
+}) => AggregatorOriginCalls;
+/**
+ * Normalizes a quote response from the contract-calls endpoint.
+ *
+ * A present but malformed `transactionRequest.value` fails the parse — silently
+ * sending zero native value would produce a transaction that under-pays the
+ * provider's bridging fee.
+ *
+ * REQUIRES `context.request` — see {@link lifiEvmDeposit}. Every live caller
+ * (`providers.ts`'s registry entry, the interface's `consolidated-quote.ts`
+ * store) supplies it; a caller that omits it gets a thrown
+ * {@link LifiExecutionRefusedError} rather than a silently unchecked
+ * execution transaction.
+ *
+ * @returns the normalized quote, or null when the payload shape is unexpected
+ * @throws {LifiExecutionRefusedError} when the response's execution
+ *   transaction disagrees with `context.request` — see `lifi-execution-guard.ts`
+ */
+export declare const parseLifiContractCallsQuote: (payload: unknown, context?: ProviderQuoteContext) => ConsolidatedQuote | null;
+/**
+ * Normalizes a quote response from LI.FI's plain `GET /v1/quote`.
+ *
+ * `request` IS REQUIRED FOR AN ETHEREUM ORIGIN, though its type stays
+ * optional — omitting it there throws {@link LifiExecutionRefusedError}
+ * rather than returning an unverified deposit; see `lifiEvmDeposit`'s doc
+ * comment for why the type cannot say so directly. It is genuinely optional
+ * for a Solana or Bitcoin origin, which never reach the execution guard.
+ *
+ * @param payload - the raw JSON body from `GET /v1/quote`
+ * @param options.originEcosystem - the virtual-machine family the route starts from
+ * @param options.request - the consolidated request this response answers
+ * @returns the normalized quote, or null when the payload does not match that ecosystem
+ * @throws {LifiExecutionRefusedError} for an Ethereum origin, when `request`
+ *   is absent or the execution transaction disagrees with it
+ */
+export declare const parseLifiQuote: (payload: unknown, { originEcosystem, request }: {
+    originEcosystem: Ecosystem;
+    request?: ConsolidatedQuoteRequest;
+}) => ConsolidatedQuote | null;
+declare const consolidatedStatusValues: readonly ["NOT_FOUND", "INVALID", "PENDING", "DONE", "FAILED"];
+/** Transfer status values reported by the provider's status endpoint. */
+export type ConsolidatedStatusValue = (typeof consolidatedStatusValues)[number];
+/** Normalized status of an in-flight consolidated bridge. */
+export type ConsolidatedStatus = {
+    status: ConsolidatedStatusValue;
+    /** Provider-specific refinement (e.g. WAIT_DESTINATION_TRANSACTION, REFUNDED) */
+    substatus: string | null;
+    /** The Ethereum-side transaction hash, once the provider has executed it */
+    receivingTxHash: Hex | null;
+    /**
+     * Where a refund was credited, when the provider says it refunded into an
+     * account of its own that the reader must withdraw from. Absent or null for
+     * every other answer, including a refund sent straight back to the origin
+     * chain, which leaves the reader nothing to do.
+     */
+    refund?: ConsolidatedAccountRefund | null;
+};
+/**
+ * A refund the provider credited to an account inside its own settlement
+ * contract rather than sending back on chain. NEAR Intents does this for a
+ * pay-by-hand origin with no wallet here: the refund lands in the ledger entry
+ * named for the reader's lower-cased Ethereum address, and the reader has to
+ * withdraw it from there.
+ */
+export type ConsolidatedAccountRefund = {
+    /** The ledger account the refund was credited to, lower case. */
+    account: string;
+    /** The provider's own identifier for the refunded asset, e.g. `nep141:zec.omft.near`. */
+    assetId: string;
+    /** How much was refunded, in that asset's base units, as a decimal string. */
+    baseUnits: string;
+};
+/**
+ * Builds the status-poll address for an origin transaction, at
+ * {@link lifiDefaultApiOrigin}. Chain hints narrow the provider's lookup and
+ * are recommended when known. `txHash` is typed as `string` rather than `Hex`
+ * because a non-Ethereum origin (Solana base58 signature, Bitcoin transaction
+ * id) is not `0x`-prefixed.
+ */
+export declare const lifiStatusUrl: ({ txHash, fromChainId, toChainId, }: {
+    txHash: string;
+    fromChainId?: number;
+    toChainId?: number;
+}) => string;
+/**
+ * Normalizes a status response for an in-flight consolidated bridge.
+ *
+ * The receiving hash gates the handover from provider polling to the
+ * omnibridge indexer, so it must be a full 32-byte transaction hash — an
+ * empty or malformed value collapses to null rather than masquerading as a
+ * real transaction.
+ *
+ * @returns the normalized status, or null when the payload shape is unexpected
+ */
+export declare const parseLifiStatus: (payload: unknown) => ConsolidatedStatus | null;
+/**
+ * Chain listing endpoint, at {@link lifiDefaultApiOrigin}. Deliberately
+ * carries no query parameters: the `chainTypes` filter requires an API key on
+ * the anonymous tier (verified live 2026-06-12, error code 1010), and the
+ * default response is EVM-only.
+ */
+export declare const lifiChainsUrl: string;
+/** A chain the aggregator can originate a consolidated route from. */
+export type ConsolidatedOriginChain = {
+    id: number;
+    name: string;
+    logoURI: string | null;
+};
+/**
+ * Normalizes a `GET /v1/chains` response body to mainnet EVM chains.
+ *
+ * @returns the chain list, or null when the payload shape is unexpected
+ */
+export declare const parseLifiChains: (payload: unknown) => ConsolidatedOriginChain[] | null;
+/** Builds the per-chain token listing URL, at {@link lifiDefaultApiOrigin}. */
+export declare const lifiTokensUrl: (chainId: number) => string;
+/**
+ * Normalizes a `GET /v1/tokens?chains=<id>` response body into the shared
+ * token shape used across the bridge frontend. Malformed entries are skipped
+ * rather than failing the whole list; `logoURI` is optional on the live
+ * interface.
+ *
+ * @returns the token list, or null when the payload shape is unexpected
+ */
+export declare const parseLifiTokens: (payload: unknown, chainId: number) => Token[] | null;
+export {};