@gibs/bridge-sdk 1.12.0 → 1.13.0

package/dist/consolidated-quote.js

@@ -0,0 +1,773 @@
+import { Chains } from './config.js';
+import { LifiExecutionRefusedError, verifyLifiEvmExecution, } from './lifi-execution-guard.js';
+import { depositFamilyOf, isEvmDeposit, } from './origin-deposit.js';
+import { lifiQuoteFees } from './quote-fees.js';
+import { referralIntegrator, resolveAttribution } from './referral.js';
+import { normalizeLifiSteps } from './route-steps.js';
+/**
+ * The LI.FI `integrator` sent when a request leaves
+ * {@link ConsolidatedQuoteRequest.lifiIntegrator} out.
+ *
+ * KEPT AS A DEFAULT BECAUSE IT COSTS THE CALLER NOTHING. LI.FI's `integrator`
+ * is an optional label: it changes neither the quote nor the rate limit, and it
+ * moves no money unless a `fee` rides with it. A fee is the one case where the
+ * label decides who gets paid, so a request that charges a fee must name its
+ * own integrator — see {@link lifiAttribution}.
+ */
+export const lifiIntegrator = referralIntegrator;
+/** Referral fee charged by this integrator on LI.FI routes (0.001 = 0.1%). */
+export 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 const lifiDefaultApiOrigin = 'https://li.quest';
+const isAbsoluteHttpUrl = (value) => {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'http:' || url.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * 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 const lifiEndpoints = (apiOrigin) => {
+    if (!isAbsoluteHttpUrl(apiOrigin)) {
+        throw new Error(`lifiEndpoints: "${apiOrigin}" is not an absolute http(s) origin`);
+    }
+    const base = `${apiOrigin.replace(/\/+$/, '')}/v1`;
+    return Object.freeze({
+        quote: `${base}/quote`,
+        contractCallsQuote: `${base}/quote/contractCalls`,
+        chains: `${base}/chains`,
+        tokens: (chainId) => {
+            const url = new URL(`${base}/tokens`);
+            url.searchParams.set('chains', chainId.toString());
+            return url.toString();
+        },
+        status: ({ txHash, fromChainId, toChainId }) => {
+            const url = new URL(`${base}/status`);
+            url.searchParams.set('txHash', txHash);
+            if (fromChainId !== undefined) {
+                url.searchParams.set('fromChain', fromChainId.toString());
+            }
+            if (toChainId !== undefined) {
+                url.searchParams.set('toChain', toChainId.toString());
+            }
+            return url.toString();
+        },
+    });
+};
+const defaultLifiEndpoints = lifiEndpoints(lifiDefaultApiOrigin);
+/** Quote endpoint that accepts destination contract calls, at {@link lifiDefaultApiOrigin}. */
+export const lifiContractCallsQuoteUrl = defaultLifiEndpoints.contractCallsQuote;
+/**
+ * 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 const lifiQuoteUrl = defaultLifiEndpoints.quote;
+/**
+ * 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 const lifiRequestHeaders = () => ({
+    'Content-Type': 'application/json',
+});
+/**
+ * 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 const isNonEthereumVirtualMachineOrigin = (request) => (request.originVmType ?? 'evm') !== 'evm';
+/**
+ * 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 — that fee would otherwise be paid to the default integrator
+ */
+export const lifiAttribution = (request) => {
+    const integrator = resolveAttribution(request.lifiIntegrator, lifiIntegrator);
+    const chargesFee = request.lifiFee !== undefined && request.lifiFee > 0;
+    if (!chargesFee) {
+        return integrator === undefined ? {} : { integrator };
+    }
+    if (typeof request.lifiIntegrator !== 'string') {
+        throw new Error('lifiFee needs an explicit lifiIntegrator: LI.FI pays the fee to the integrator label, and the default label is not yours');
+    }
+    return { integrator: request.lifiIntegrator, fee: request.lifiFee };
+};
+/**
+ * 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 const buildLifiQuoteRequest = (request) => {
+    const { destinationCall, fromAmount, toChainId } = request;
+    if (destinationCall !== undefined) {
+        return null;
+    }
+    if (fromAmount === undefined || fromAmount <= 0n) {
+        return null;
+    }
+    if (toChainId === undefined) {
+        return null;
+    }
+    // LI.FI quotes Ethereum-Virtual-Machine origins only, and a non-Ethereum
+    // origin address would be rejected as malformed rather than declined.
+    if ((request.originVmType ?? 'evm') !== 'evm') {
+        return null;
+    }
+    const params = new URLSearchParams({
+        fromChain: request.fromChainId.toString(),
+        toChain: toChainId.toString(),
+        fromToken: request.fromTokenAddress,
+        toToken: request.toTokenAddress,
+        fromAmount: fromAmount.toString(),
+        fromAddress: request.fromAddress,
+        // WHERE THE FUNDS LAND, stated separately from who is paying. They are the
+        // same account for an ordinary transfer and are NOT when a reader has named
+        // a delivery address, which is exactly the case a bridge has to get right.
+        toAddress: request.recipient,
+    });
+    // Same attribution as the contract-calls builder, so a fee the reader agreed
+    // to is charged on both endpoints, not only on one.
+    const { integrator, fee } = lifiAttribution(request);
+    if (integrator !== undefined) {
+        params.set('integrator', integrator);
+    }
+    if (fee !== undefined) {
+        params.set('fee', fee.toString());
+    }
+    if (request.slippage !== undefined) {
+        params.set('slippage', request.slippage.toString());
+    }
+    return params.toString();
+};
+export const buildLifiContractCallsRequest = (request) => {
+    const { destinationCall, toAmount } = request;
+    // THIS ENDPOINT EXISTS TO DELIVER AND THEN CALL SOMETHING. A route with no
+    // omnibridge leg has nothing to call, so it is not a request this builder can
+    // express — LI.FI's plain quote is the right endpoint for that shape, and
+    // wiring it is separate work. Refusing here leaves the route to Relay rather
+    // than sending LI.FI a contract-call request with no contract call in it.
+    if (destinationCall === undefined) {
+        return null;
+    }
+    if (toAmount <= 0n) {
+        return null;
+    }
+    // contract-call entries carry no native value; native-entry calls
+    // (wrapAndRelayTokens) stay out of scope until value support is verified
+    if (destinationCall.value > 0n) {
+        return null;
+    }
+    // LI.FI cannot bridge across virtual-machine ecosystems. The provider gate
+    // (`providerSupportsOrigin`) already keeps non-Ethereum origins away from
+    // LI.FI; this guard makes the boundary explicit so the origin fields below are
+    // genuinely Ethereum `Hex` addresses, not merely the widened `string` shape.
+    if (isNonEthereumVirtualMachineOrigin(request)) {
+        return null;
+    }
+    return {
+        fromChain: request.fromChainId,
+        fromToken: request.fromTokenAddress,
+        fromAddress: request.fromAddress,
+        toChain: request.toChainId ?? Number(Chains.ETH),
+        toToken: request.toTokenAddress,
+        toAmount: toAmount.toString(),
+        toFallbackAddress: request.fallbackAddress,
+        ...lifiAttribution(request),
+        ...(request.slippage === undefined ? {} : { slippage: request.slippage }),
+        contractCalls: [
+            {
+                fromAmount: toAmount.toString(),
+                fromTokenAddress: request.toTokenAddress,
+                toContractAddress: destinationCall.to,
+                toContractCallData: destinationCall.data,
+                toContractGasLimit: destinationCall.gasLimit.toString(),
+                ...(destinationCall.approvalTarget === null
+                    ? {}
+                    : { toApprovalAddress: destinationCall.approvalTarget }),
+            },
+        ],
+    };
+};
+/**
+ * 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 const evmDepositOf = (quote) => {
+    if (!isEvmDeposit(quote.originDeposit)) {
+        throw new Error(`expected an Ethereum-Virtual-Machine origin deposit, received "${depositFamilyOf(quote.originDeposit)}"`);
+    }
+    return quote.originDeposit;
+};
+const isHexString = (value) => typeof value === 'string' && value.startsWith('0x');
+/**
+ * Parses the ecosystem-independent part of a LI.FI quote.
+ *
+ * @param payload - the raw JSON body from either LI.FI quote endpoint
+ * @returns the envelope, or null when a required field is missing or malformed
+ */
+const parseLifiQuoteEnvelope = (payload) => {
+    if (typeof payload !== 'object' || payload === null) {
+        return null;
+    }
+    const quote = payload;
+    const estimate = quote.estimate;
+    const action = quote.action;
+    const transactionRequest = quote.transactionRequest;
+    const toolDetails = quote.toolDetails;
+    if (typeof quote.id !== 'string' || typeof quote.tool !== 'string') {
+        return null;
+    }
+    if (!estimate || typeof estimate.fromAmount !== 'string') {
+        return null;
+    }
+    if (typeof estimate.executionDuration !== 'number') {
+        return null;
+    }
+    if (!transactionRequest) {
+        return null;
+    }
+    try {
+        return {
+            provider: 'lifi',
+            quoteId: quote.id,
+            tool: quote.tool,
+            toolName: typeof toolDetails?.name === 'string' ? toolDetails.name : quote.tool,
+            fromAmount: BigInt(estimate.fromAmount),
+            fromAmountUsd: typeof estimate.fromAmountUSD === 'string' ? estimate.fromAmountUSD : null,
+            approvalAddress: isHexString(estimate.approvalAddress) ? estimate.approvalAddress : null,
+            executionDurationSeconds: estimate.executionDuration,
+            steps: normalizeLifiSteps(quote.includedSteps),
+            fees: lifiQuoteFees(payload),
+            transactionRequest,
+            fromChainId: typeof action?.fromChainId === 'number' ? action.fromChainId : null,
+        };
+    }
+    catch {
+        // a BigInt conversion failed on a malformed numeric string
+        return null;
+    }
+};
+/**
+ * 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 const parseLifiContractCallsQuote = (payload, context) => {
+    const envelope = parseLifiQuoteEnvelope(payload);
+    if (envelope === null) {
+        return null;
+    }
+    const originDeposit = lifiEvmDeposit(envelope.transactionRequest, envelope.approvalAddress, context?.request);
+    if (originDeposit === null) {
+        return null;
+    }
+    const { transactionRequest: _request, fromChainId: _fromChainId, ...quote } = envelope;
+    return { ...quote, originDeposit, fees: lifiQuoteFees(payload) };
+};
+/**
+ * Builds what THIS APPLICATION expects a LI.FI execution transaction to
+ * contain, from the request that produced it — the only thing
+ * {@link verifyLifiEvmExecution} is allowed to check a response against.
+ *
+ * `receiver` and `minimumAmount` differ by whether `destinationCall` is
+ * present, because the two LI.FI endpoints populate `BridgeData.receiver`
+ * with DIFFERENT fields and only one endpoint accepts a requested minimum at
+ * all — see the field-semantics note atop `lifi-execution-guard.ts`.
+ */
+const lifiExecutionExpectation = (request) => {
+    const hasDestinationCall = request.destinationCall !== undefined;
+    return {
+        receiver: hasDestinationCall ? request.fallbackAddress : request.recipient,
+        destinationChainId: request.toChainId ?? Number(Chains.ETH),
+        sendingAssetId: request.fromTokenAddress,
+        hasDestinationCall,
+        minimumAmount: hasDestinationCall ? request.toAmount : null,
+    };
+};
+/**
+ * Reads LI.FI's Ethereum `transactionRequest` into an Ethereum origin deposit.
+ *
+ * A present but malformed `value` fails the parse — silently sending zero
+ * native value would produce a transaction that under-pays the provider's
+ * bridging fee.
+ *
+ * VERIFIES THE TRANSACTION BEFORE RETURNING IT. `lifiApi.quote` and
+ * `lifiApi.contractCallsQuote` are fetched through a configurable, possibly
+ * compromised host — see `lifi-execution-guard.ts`'s top-of-file doc comment
+ * for the full threat model. `request` is REQUIRED, not optional: a caller
+ * with no request to check against gets a thrown
+ * {@link LifiExecutionRefusedError} (`missing-request-context`) rather than
+ * an origin deposit nothing has verified. This is the one gap a type
+ * signature alone could not close — `ProviderQuoteContext.request` is
+ * optional on every OTHER provider, so this function still accepts
+ * `undefined` in its parameter type and refuses at the call boundary
+ * instead, keeping it assignable to `ProviderDescriptor.executionQuote.parse`.
+ *
+ * @throws {LifiExecutionRefusedError} when `request` is absent, or when the
+ *   transaction disagrees with it
+ */
+const lifiEvmDeposit = (transactionRequest, approvalAddress, request) => {
+    if (!isHexString(transactionRequest.to) ||
+        !isHexString(transactionRequest.data) ||
+        typeof transactionRequest.chainId !== 'number') {
+        return null;
+    }
+    if (transactionRequest.value !== undefined && !isHexString(transactionRequest.value)) {
+        return null;
+    }
+    if (request === undefined) {
+        throw new LifiExecutionRefusedError({
+            reason: 'missing-request-context',
+            detail: 'the LI.FI response parser was not given the request it is answering, so the execution transaction could not be verified',
+        });
+    }
+    const value = isHexString(transactionRequest.value) ? BigInt(transactionRequest.value) : 0n;
+    verifyLifiEvmExecution({
+        to: transactionRequest.to,
+        data: transactionRequest.data,
+        value,
+        chainId: transactionRequest.chainId,
+    }, approvalAddress, lifiExecutionExpectation(request));
+    return {
+        ecosystem: 'evm',
+        to: transactionRequest.to,
+        data: transactionRequest.data,
+        value,
+        chainId: transactionRequest.chainId,
+        gasLimit: isHexString(transactionRequest.gasLimit) ? BigInt(transactionRequest.gasLimit) : null,
+    };
+};
+// A partially-signed Bitcoin transaction always begins with the five-byte magic
+// "psbt\xff". Checking it keeps a base64 payload, or an Ethereum `0x` string,
+// from being handed to a Bitcoin wallet as though it were a transaction.
+const partiallySignedBitcoinMagic = '70736274ff';
+/**
+ * Reads LI.FI's Bitcoin `transactionRequest` into a Bitcoin origin deposit.
+ *
+ * LI.FI and Relay happen to agree on the encoding here — an unprefixed
+ * hexadecimal partially-signed transaction — so this lands on the same
+ * {@link BitcoinDeposit} the Relay parser produces and needs no signer change.
+ */
+const lifiBitcoinDeposit = (transactionRequest, chainId) => {
+    const { to, data, value } = transactionRequest;
+    if (typeof to !== 'string' || to.length === 0) {
+        return null;
+    }
+    if (typeof data !== 'string' || !data.toLowerCase().startsWith(partiallySignedBitcoinMagic)) {
+        return null;
+    }
+    if (typeof value !== 'string' || !/^[0-9]+$/.test(value)) {
+        return null;
+    }
+    return { ecosystem: 'bvm', psbt: data, depositAddress: to, amountSats: BigInt(value), chainId };
+};
+// Base64 without whitespace. Necessary but nowhere near sufficient on its own:
+// the hexadecimal alphabet is a SUBSET of base64's, so a Bitcoin
+// partially-signed transaction matches this pattern happily.
+const base64Pattern = /^[A-Za-z0-9+/]+={0,2}$/;
+// A single-byte compact-u16 tops out below this, and no real transaction needs
+// anything near this many signatures.
+const maxPlausibleSignatureCount = 19;
+const solanaSignatureByteLength = 64;
+// A versioned message's first byte sets the high bit; version 0 is the only one
+// that exists, so the byte is exactly 0x80.
+const solanaVersionZeroPrefix = 0x80;
+/**
+ * Checks that a base64 payload really is a serialized Solana transaction, by
+ * walking its wire layout: a compact-u16 signature count, that many 64-byte
+ * signatures, then a message whose leading byte is either the version-0 marker
+ * or (for a legacy message) the same signature count again.
+ *
+ * An alphabet check alone is not enough. Hexadecimal is a subset of base64, so
+ * a Bitcoin partially-signed transaction passes a pure pattern test and would
+ * be handed to a Solana wallet as a transaction.
+ */
+const isSerializedSolanaTransaction = (value) => {
+    if (!base64Pattern.test(value)) {
+        return false;
+    }
+    let bytes;
+    try {
+        const binary = atob(value);
+        bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+    }
+    catch {
+        return false;
+    }
+    const signatureCount = bytes[0];
+    if (signatureCount === undefined ||
+        signatureCount < 1 ||
+        signatureCount > maxPlausibleSignatureCount) {
+        return false;
+    }
+    const messageStart = 1 + signatureCount * solanaSignatureByteLength;
+    const header = bytes[messageStart];
+    if (header === undefined) {
+        return false;
+    }
+    return header === solanaVersionZeroPrefix || header === signatureCount;
+};
+/**
+ * Reads LI.FI's Solana `transactionRequest` into a Solana origin deposit.
+ *
+ * The whole payload is a single base64 compiled transaction under `data`, with
+ * no `to`, `value` or `chainId` beside it, so the chain id comes from the
+ * quote's action rather than the request.
+ */
+const lifiSolanaDeposit = (transactionRequest, chainId) => {
+    const { data } = transactionRequest;
+    if (typeof data !== 'string' || !isSerializedSolanaTransaction(data)) {
+        return null;
+    }
+    return { ecosystem: 'svm', form: 'serialized', transaction: data, chainId };
+};
+/**
+ * INTENTIONALLY UNWIRED at runtime — retained as tested, parked capability.
+ *
+ * Nothing in the app calls this; the live LI.FI path is `parseLifiContractCallsQuote`
+ * (the contract-calls endpoint), which only ever produces an Ethereum deposit.
+ * This parser is the ONE piece that can decode a NON-Ethereum LI.FI origin
+ * deposit, and it exists for a provider path that is deliberately NOT built:
+ * adding LI.FI as a competing provider for non-Ethereum origins was analysed and
+ * rejected (LI.FI can produce only leg one of the consolidated route, and every
+ * way to execute leg two is strictly worse than Relay, which already serves those
+ * origins in a single signature — see docs/consolidated-bridge-route-design.md).
+ * Do not delete this while that decision could still be revisited; its test block
+ * (`parseLifiQuote across origin ecosystems`) is its executable spec.
+ *
+ * Normalizes a quote response from LI.FI's plain `GET /v1/quote`.
+ *
+ * Unlike the contract-calls endpoint, this one accepts a non-Ethereum origin,
+ * and the shape of `transactionRequest` then varies by ecosystem: Ethereum
+ * returns the familiar `to`/`data`/`value`/`chainId`, Bitcoin returns a deposit
+ * address plus a partially-signed transaction, and Solana returns nothing but a
+ * compiled transaction. Reading the Ethereum fields off the others would
+ * produce a deposit that is structurally valid and completely wrong, so the
+ * caller states the origin ecosystem and only that reader runs.
+ *
+ * The origin ecosystem is a parameter rather than something sniffed from the
+ * payload because the caller already knows it — it decided which chain to quote
+ * — and guessing from field presence would make a malformed Ethereum response
+ * look like a valid Solana one.
+ *
+ * Note that `approvalAddress` is dropped for a non-Ethereum origin. LI.FI
+ * returns its Ethereum router there regardless of where the route starts, and
+ * that address is meaningless to a Solana or Bitcoin wallet; passing it on
+ * invites a caller to build an approval for a chain that has no such concept.
+ *
+ * @param payload - the raw JSON body from `GET /v1/quote`
+ * @param options.originEcosystem - the virtual-machine family the route starts from
+ * @returns the normalized quote, or null when the payload does not match that ecosystem
+ */
+/**
+ * What a plain LI.FI quote says arrives, and what LI.FI says it is worth.
+ *
+ * ONLY THE PLAIN ENDPOINT CARRIES THESE ONTO THE QUOTE, and that is not a
+ * convenience. A route through this endpoint is solved FORWARDS: the reader
+ * names what they spend, so every provider is handed the same `fromAmount` and
+ * the delivered amount is the ONE figure that differs. Without it:
+ *
+ *   - ranking cannot engage its forward rule — it requires every quote to carry
+ *     `toAmount` — and falls back to comparing each provider's own dollar
+ *     figure, which come from different price feeds. Measured: LI.FI $122.00
+ *     against Relay $123.71 on the same 0.05 ether, so LI.FI won on a feed.
+ *   - the route then shows the winner's delivered amount as ZERO, because the
+ *     direct candidate reads `quote.toAmount ?? 0n`.
+ *
+ * Both happened: Relay's parser set these, LI.FI's never did, and a route test
+ * built its quotes by hand with `toAmount` already filled in — so it passed.
+ * It took a live round trip to see the gap.
+ *
+ * NOT added to the shared envelope. The contract-calls endpoint uses that too,
+ * and on an omnibridge route the provider's delivered side is the ENTRY chain's
+ * tokens rather than what lands on PulseChain — see `ConsolidatedQuote.toAmount`.
+ *
+ * `estimate.toAmount` is the expected amount, matching Relay's
+ * `currencyOut.amount`, so the two rank on the same kind of figure.
+ *
+ * @param payload - the raw JSON body from `GET /v1/quote`
+ * @returns the delivered amount and its dollar value, each only when present
+ */
+const lifiDeliveredAmount = (payload) => {
+    const estimate = payload?.estimate;
+    const delivered = {};
+    if (typeof estimate?.toAmount === 'string') {
+        try {
+            delivered.toAmount = BigInt(estimate.toAmount);
+        }
+        catch {
+            // A malformed amount leaves the field absent rather than zero: zero is a
+            // real quantity and would read as "this route delivers nothing".
+        }
+    }
+    if (typeof estimate?.toAmountUSD === 'string') {
+        delivered.toAmountUsd = estimate.toAmountUSD;
+    }
+    return delivered;
+};
+/**
+ * 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 const parseLifiQuote = (payload, { originEcosystem, request }) => {
+    const envelope = parseLifiQuoteEnvelope(payload);
+    if (envelope === null) {
+        return null;
+    }
+    const { transactionRequest, fromChainId, ...envelopeFields } = envelope;
+    const quote = { ...envelopeFields, ...lifiDeliveredAmount(payload) };
+    if (originEcosystem === 'evm') {
+        const originDeposit = lifiEvmDeposit(transactionRequest, envelope.approvalAddress, request);
+        return originDeposit === null ? null : { ...quote, originDeposit };
+    }
+    if (fromChainId === null) {
+        return null;
+    }
+    const originDeposit = originEcosystem === 'svm'
+        ? lifiSolanaDeposit(transactionRequest, fromChainId)
+        : originEcosystem === 'bvm'
+            ? lifiBitcoinDeposit(transactionRequest, fromChainId)
+            : null;
+    if (originDeposit === null) {
+        return null;
+    }
+    return { ...quote, originDeposit, approvalAddress: null };
+};
+const consolidatedStatusValues = ['NOT_FOUND', 'INVALID', 'PENDING', 'DONE', 'FAILED'];
+/**
+ * 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 const lifiStatusUrl = ({ txHash, fromChainId, toChainId, }) => {
+    return defaultLifiEndpoints.status({ txHash, fromChainId, toChainId });
+};
+const isTransactionHash = (value) => typeof value === 'string' && /^0x[0-9a-fA-F]{64}$/.test(value);
+/**
+ * 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 const parseLifiStatus = (payload) => {
+    if (typeof payload !== 'object' || payload === null) {
+        return null;
+    }
+    const data = payload;
+    const status = consolidatedStatusValues.find((value) => value === data.status);
+    if (!status) {
+        return null;
+    }
+    const receiving = data.receiving;
+    return {
+        status,
+        substatus: typeof data.substatus === 'string' ? data.substatus : null,
+        receivingTxHash: isTransactionHash(receiving?.txHash) ? receiving.txHash : 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 const lifiChainsUrl = defaultLifiEndpoints.chains;
+/**
+ * Normalizes a `GET /v1/chains` response body to mainnet EVM chains.
+ *
+ * @returns the chain list, or null when the payload shape is unexpected
+ */
+export const parseLifiChains = (payload) => {
+    if (typeof payload !== 'object' || payload === null) {
+        return null;
+    }
+    const chains = payload.chains;
+    if (!Array.isArray(chains)) {
+        return null;
+    }
+    const parsed = [];
+    for (const chain of chains) {
+        if (typeof chain !== 'object' || chain === null) {
+            continue;
+        }
+        const entry = chain;
+        if (entry.chainType !== 'EVM' || entry.mainnet !== true) {
+            continue;
+        }
+        if (typeof entry.id !== 'number' || typeof entry.name !== 'string') {
+            continue;
+        }
+        parsed.push({
+            id: entry.id,
+            name: entry.name,
+            logoURI: typeof entry.logoURI === 'string' ? entry.logoURI : null,
+        });
+    }
+    return parsed;
+};
+/** Builds the per-chain token listing URL, at {@link lifiDefaultApiOrigin}. */
+export const lifiTokensUrl = defaultLifiEndpoints.tokens;
+/**
+ * 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 const parseLifiTokens = (payload, chainId) => {
+    if (typeof payload !== 'object' || payload === null) {
+        return null;
+    }
+    const tokensByChain = payload.tokens;
+    if (typeof tokensByChain !== 'object' || tokensByChain === null) {
+        return null;
+    }
+    const entries = tokensByChain[chainId.toString()];
+    if (!Array.isArray(entries) || entries.length === 0) {
+        return null;
+    }
+    const parsed = [];
+    for (const item of entries) {
+        if (typeof item !== 'object' || item === null) {
+            continue;
+        }
+        const entry = item;
+        if (!isHexString(entry.address) ||
+            typeof entry.symbol !== 'string' ||
+            typeof entry.name !== 'string' ||
+            typeof entry.decimals !== 'number') {
+            continue;
+        }
+        parsed.push({
+            chainId,
+            address: entry.address,
+            symbol: entry.symbol,
+            name: entry.name,
+            decimals: entry.decimals,
+            logoURI: typeof entry.logoURI === 'string' ? entry.logoURI : null,
+            // Preserve the inline spot price the LI.FI list carries — it is the USD
+            // price source for aggregator chains (the dapp image lists carry none).
+            priceUSD: typeof entry.priceUSD === 'string' ? entry.priceUSD : null,
+        });
+    }
+    return parsed;
+};