@gibs/bridge-sdk 1.13.1 → 1.18.0

package/dist/cjs/consolidated-quote.js

@@ -0,0 +1,1048 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseLifiTokens = exports.lifiTokensUrl = exports.parseLifiChains = exports.lifiChainsUrl = exports.parseLifiStatus = exports.lifiStatusUrl = exports.parseLifiQuote = exports.parseLifiContractCallsQuote = exports.aggregatorOriginCalls = exports.evmDepositOf = exports.buildLifiContractCallsRequest = exports.buildLifiQuoteRequest = exports.lifiAttribution = exports.isNonEthereumVirtualMachineOrigin = exports.lifiRequestHeaders = exports.lifiQuoteUrl = exports.lifiContractCallsQuoteUrl = exports.lifiEndpoints = exports.lifiDefaultApiOrigin = exports.lifiReferralFeePercent = exports.lifiIntegrator = void 0;
+const url_1 = require("@gibs/common/url");
+const viem_1 = require("viem");
+const config_js_1 = require("./config.js");
+const lifi_execution_guard_js_1 = require("./lifi-execution-guard.js");
+const origin_deposit_js_1 = require("./origin-deposit.js");
+const quote_fees_js_1 = require("./quote-fees.js");
+const referral_js_1 = require("./referral.js");
+const route_steps_js_1 = require("./route-steps.js");
+const relay_depository_js_1 = require("./relay-depository.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.
+ */
+exports.lifiIntegrator = referral_js_1.referralIntegrator;
+/**
+ * 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`.
+ */
+exports.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.
+ */
+exports.lifiDefaultApiOrigin = 'https://li.quest';
+/**
+ * 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
+ */
+const lifiEndpoints = (apiOrigin) => {
+    if (!(0, url_1.isHttpUrl)(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) => (0, url_1.buildUrl)(`${base}/tokens`, { chains: chainId.toString() }),
+        status: ({ txHash, fromChainId, toChainId }) => (0, url_1.buildUrl)(`${base}/status`, {
+            txHash,
+            fromChain: fromChainId?.toString(),
+            toChain: toChainId?.toString(),
+        }),
+    });
+};
+exports.lifiEndpoints = lifiEndpoints;
+const defaultLifiEndpoints = (0, exports.lifiEndpoints)(exports.lifiDefaultApiOrigin);
+/** Quote endpoint that accepts destination contract calls, at {@link lifiDefaultApiOrigin}. */
+exports.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.
+ */
+exports.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.
+ */
+const lifiRequestHeaders = () => ({
+    'Content-Type': 'application/json',
+});
+exports.lifiRequestHeaders = lifiRequestHeaders;
+/**
+ * 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
+ */
+const isNonEthereumVirtualMachineOrigin = (request) => (request.originVmType ?? 'evm') !== 'evm';
+exports.isNonEthereumVirtualMachineOrigin = isNonEthereumVirtualMachineOrigin;
+/**
+ * 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
+ */
+const lifiAttribution = (request) => {
+    const integrator = (0, referral_js_1.resolveAttribution)(request.lifiIntegrator, undefined);
+    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 account behind the integrator label');
+    }
+    return { integrator: request.lifiIntegrator, fee: request.lifiFee };
+};
+exports.lifiAttribution = lifiAttribution;
+/**
+ * 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}
+ */
+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;
+    }
+    // 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 } = (0, exports.lifiAttribution)(request);
+    return (0, url_1.buildQuery)({
+        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,
+        // Each optional parameter is left out when it is undefined.
+        integrator,
+        fee: fee?.toString(),
+        slippage: request.slippage?.toString(),
+    });
+};
+exports.buildLifiQuoteRequest = buildLifiQuoteRequest;
+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 ((0, exports.isNonEthereumVirtualMachineOrigin)(request)) {
+        return null;
+    }
+    return {
+        fromChain: request.fromChainId,
+        fromToken: request.fromTokenAddress,
+        fromAddress: request.fromAddress,
+        toChain: request.toChainId ?? Number(config_js_1.Chains.ETH),
+        toToken: request.toTokenAddress,
+        toAmount: toAmount.toString(),
+        toFallbackAddress: request.fallbackAddress,
+        ...(0, exports.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 }),
+            },
+        ],
+    };
+};
+exports.buildLifiContractCallsRequest = buildLifiContractCallsRequest;
+/**
+ * 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.
+ */
+const evmDepositOf = (quote) => {
+    if (!(0, origin_deposit_js_1.isEvmDeposit)(quote.originDeposit)) {
+        throw new Error(`expected an Ethereum-Virtual-Machine origin deposit, received "${(0, origin_deposit_js_1.depositFamilyOf)(quote.originDeposit)}"`);
+    }
+    return quote.originDeposit;
+};
+exports.evmDepositOf = evmDepositOf;
+const refuseOrigin = (refusal) => ({ kind: 'refused', refusal });
+const sameHexAddress = (a, b) => a.toLowerCase() === b.toLowerCase();
+/**
+ * The amount of the origin token the reader sends, in base units.
+ *
+ * THE REQUEST IS THE AUTHORITY. A route with no omnibridge entry call is
+ * solved forwards: the reader names the input and the request carries it as
+ * `fromAmount`. {@link aggregatorOriginCalls} refuses a quote whose own
+ * `fromAmount` differs from it.
+ *
+ * A route WITH an entry call is solved backwards from an exact output, so the
+ * request names no input at all and the provider works one out. For that
+ * route the quote's `fromAmount` is the only figure there is. The deposit, the
+ * approval and the quote must still agree with each other, but no figure of
+ * the reader's exists to compare them with.
+ */
+const amountToSendOf = ({ quote, request }) => request.fromAmount ?? quote.fromAmount;
+const refuseAmount = ({ provider, field, expected, actual, }) => refuseVerdict({ reason: 'amount-mismatch', provider, field, expected, actual });
+const refuseRecipient = ({ provider, field, expected, actual, }) => refuseVerdict({ reason: 'recipient-mismatch', provider, field, expected, actual });
+const refuseVerdict = (refusal) => ({ kind: 'refused', refusal });
+/**
+ * The spender a provider allows, given the one contract it trusts on this
+ * chain: no approval when the quote asks for none, the trusted contract when
+ * the quote names it, and a refusal for any other address.
+ */
+const spenderVerdict = ({ provider, requested, trusted, }) => {
+    if (requested === null)
+        return { kind: 'verified', spender: null };
+    if (trusted === null || !sameHexAddress(requested, trusted)) {
+        return refuseVerdict({ reason: 'spender-not-allowed', provider, spender: requested });
+    }
+    // The one place a spender is branded verified: the trusted table entry.
+    return { kind: 'verified', spender: trusted };
+};
+/**
+ * LI.FI: the deposit and the spender must be LI.FI's Diamond, and the calldata
+ * must say what was asked: the receiver, the asset, and (through
+ * `originAmount`) the exact amount pulled from the reader.
+ */
+const lifiOriginVerdict = ({ request, quote, deposit, amountToSend }) => {
+    const diamond = lifi_execution_guard_js_1.lifiDiamondAddressByChainId.get(deposit.chainId);
+    if (diamond === undefined)
+        return refuseVerdict({ reason: 'unverified-chain', provider: 'lifi', chainId: deposit.chainId });
+    try {
+        (0, lifi_execution_guard_js_1.verifyLifiEvmExecution)(deposit, quote.approvalAddress, {
+            ...lifiExecutionExpectation(request),
+            originAmount: amountToSend,
+        });
+    }
+    catch (error) {
+        if (error instanceof lifi_execution_guard_js_1.LifiExecutionRefusedError)
+            return refuseVerdict({ reason: 'lifi-guard', detail: error.refusal.detail });
+        throw error;
+    }
+    return spenderVerdict({ provider: 'lifi', requested: quote.approvalAddress, trusted: diamond });
+};
+/**
+ * The two deposit functions Relay's depository exposes, as observed in live
+ * `POST /quote/v2` answers on 2026-10-07 (Ethereum to Base):
+ *
+ * - `depositNative(address depositor, bytes32 id)` (selector `0x49290c1c`):
+ *   the amount is `msg.value`; the calldata carries NO amount.
+ * - `depositErc20(address depositor, address token, uint256 amount, bytes32 id)`
+ *   (selector `0xe8017952`): the calldata carries the token and the amount.
+ *
+ * Any other selector is refused rather than guessed at.
+ */
+const relayDepositoryAbi = (0, viem_1.parseAbi)([
+    'function depositNative(address depositor, bytes32 id) payable',
+    'function depositErc20(address depositor, address token, uint256 amount, bytes32 id)',
+]);
+const decodeRelayDeposit = (data) => {
+    try {
+        return (0, viem_1.decodeFunctionData)({ abi: relayDepositoryAbi, data });
+    }
+    catch {
+        return null;
+    }
+};
+/** The native half of Relay's deposit: `depositNative`, with the amount as `msg.value`. */
+const relayNativeVerdict = ({ deposit, amountToSend }) => {
+    const provider = 'relay';
+    if (deposit.value !== amountToSend) {
+        return refuseAmount({ provider, field: 'deposit-value', expected: amountToSend, actual: deposit.value });
+    }
+    const decoded = decodeRelayDeposit(deposit.data);
+    if (decoded === null || decoded.functionName !== 'depositNative') {
+        return refuseVerdict({ reason: 'deposit-shape', provider, detail: 'a native deposit is not depositNative' });
+    }
+    return null;
+};
+/** The token half of Relay's deposit: no value, and `depositErc20` naming the request's token and amount. */
+const relayTokenVerdict = ({ request, deposit, amountToSend }) => {
+    const provider = 'relay';
+    if (deposit.value !== 0n) {
+        return refuseAmount({ provider, field: 'deposit-value', expected: 0n, actual: deposit.value });
+    }
+    const decoded = decodeRelayDeposit(deposit.data);
+    if (decoded === null || decoded.functionName !== 'depositErc20') {
+        return refuseVerdict({ reason: 'deposit-shape', provider, detail: 'a token deposit is not depositErc20' });
+    }
+    const [, token, amount] = decoded.args;
+    if (!sameHexAddress(token, request.fromTokenAddress)) {
+        return refuseRecipient({ provider, field: 'calldata-token', expected: request.fromTokenAddress, actual: token });
+    }
+    if (amount !== amountToSend) {
+        return refuseAmount({ provider, field: 'calldata-amount', expected: amountToSend, actual: amount });
+    }
+    return null;
+};
+/**
+ * Relay: the deposit and the spender must be Relay's depository on the
+ * deposit's chain, and the deposit must move exactly the amount to send.
+ *
+ * - A native origin: `value` equals the amount, and the calldata is
+ *   `depositNative`, which carries no amount of its own.
+ * - A token origin: `value` is 0, and the calldata is `depositErc20` for the
+ *   request's token and the amount, decoded with {@link relayDepositoryAbi}.
+ *
+ * The depositor and the order identifier inside the calldata are NOT checked.
+ * The identifier is Relay's own, and nothing in the request predicts it.
+ */
+const relayOriginVerdict = (inputs) => {
+    const { quote, request, deposit } = inputs;
+    const depository = relay_depository_js_1.relayDepositoryByChainId.get(deposit.chainId);
+    if (depository === undefined) {
+        return refuseVerdict({ reason: 'unverified-chain', provider: 'relay', chainId: deposit.chainId });
+    }
+    if (!sameHexAddress(deposit.to, depository)) {
+        return refuseVerdict({ reason: 'deposit-target-not-allowed', provider: 'relay', target: deposit.to });
+    }
+    const spender = spenderVerdict({ provider: 'relay', requested: quote.approvalAddress, trusted: depository });
+    if (spender.kind === 'refused')
+        return spender;
+    const refusal = request.fromTokenAddress === viem_1.zeroAddress ? relayNativeVerdict(inputs) : relayTokenVerdict(inputs);
+    return refusal ?? spender;
+};
+const decodeTransfer = (data) => {
+    try {
+        return (0, viem_1.decodeFunctionData)({ abi: viem_1.erc20Abi, data });
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * NEAR Intents: no contract pulls anything. The deposit is a plain payment to
+ * the quote's own deposit address, so the check is on its SHAPE and on the two
+ * figures that matter: who is paid and how much.
+ *
+ * - No approval.
+ * - A native origin: no calldata, `to` is the quote's deposit address
+ *   (`quote.quoteId`, which `parseNearIntentsQuote` sets to it), and `value`
+ *   is the amount to send.
+ * - A token origin: no value, `to` is the origin token, and the calldata is the
+ *   token's own `transfer(depositAddress, amount)` for the same two figures.
+ *
+ * The deposit address itself is per quote and cannot be checked against a
+ * fixed table; the checks bind the payment to the address the quote names.
+ */
+const nearIntentsOriginVerdict = ({ quote, request, deposit, amountToSend }) => {
+    const provider = 'near-intents';
+    // NEAR Intents trusts no spender at all.
+    const spender = spenderVerdict({ provider, requested: quote.approvalAddress, trusted: null });
+    if (spender.kind === 'refused')
+        return spender;
+    if (request.fromTokenAddress === viem_1.zeroAddress) {
+        if (deposit.data !== '0x')
+            return refuseVerdict({ reason: 'deposit-shape', provider, detail: 'a native deposit carries calldata' });
+        if (!sameHexAddress(deposit.to, quote.quoteId)) {
+            return refuseRecipient({ provider, field: 'deposit-to', expected: quote.quoteId, actual: deposit.to });
+        }
+        if (deposit.value !== amountToSend) {
+            return refuseAmount({ provider, field: 'deposit-value', expected: amountToSend, actual: deposit.value });
+        }
+        return spender;
+    }
+    if (!sameHexAddress(deposit.to, request.fromTokenAddress)) {
+        return refuseVerdict({ reason: 'deposit-target-not-allowed', provider, target: deposit.to });
+    }
+    if (deposit.value !== 0n)
+        return refuseAmount({ provider, field: 'deposit-value', expected: 0n, actual: deposit.value });
+    const decoded = decodeTransfer(deposit.data);
+    if (decoded === null || decoded.functionName !== 'transfer') {
+        return refuseVerdict({ reason: 'deposit-shape', provider, detail: 'a token deposit is not a plain transfer' });
+    }
+    const [payee, amount] = decoded.args;
+    if (!sameHexAddress(payee, quote.quoteId)) {
+        return refuseRecipient({ provider, field: 'transfer-to', expected: quote.quoteId, actual: payee });
+    }
+    if (amount !== amountToSend) {
+        return refuseAmount({ provider, field: 'calldata-amount', expected: amountToSend, actual: amount });
+    }
+    return spender;
+};
+const originVerdictByProvider = {
+    lifi: lifiOriginVerdict,
+    relay: relayOriginVerdict,
+    'near-intents': nearIntentsOriginVerdict,
+};
+/**
+ * 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
+ */
+const aggregatorOriginCalls = ({ quote, request, }) => {
+    const { originDeposit } = quote;
+    if (!(0, origin_deposit_js_1.isEvmDeposit)(originDeposit)) {
+        return refuseOrigin({ reason: 'not-evm-deposit', depositFamily: (0, origin_deposit_js_1.depositFamilyOf)(originDeposit) });
+    }
+    if (originDeposit.chainId !== request.fromChainId) {
+        return refuseOrigin({
+            reason: 'chain-mismatch',
+            depositChainId: originDeposit.chainId,
+            requestChainId: request.fromChainId,
+        });
+    }
+    const check = originVerdictByProvider[quote.provider];
+    if (check === undefined)
+        return refuseOrigin({ reason: 'unverified-provider', provider: quote.provider });
+    const amountToSend = amountToSendOf({ quote, request });
+    if (amountToSend !== quote.fromAmount) {
+        return refuseOrigin({
+            reason: 'amount-mismatch',
+            provider: quote.provider,
+            field: 'quote-from-amount',
+            expected: amountToSend,
+            actual: quote.fromAmount,
+        });
+    }
+    const verdict = check({ quote, request, deposit: originDeposit, amountToSend });
+    if (verdict.kind === 'refused')
+        return refuseOrigin(verdict.refusal);
+    // THE SPENDER COMES FROM THE VERDICT, never from `quote.approvalAddress`:
+    // only an address the provider check took from its own table can be
+    // approved, so no provider path can forget the check.
+    if (request.fromTokenAddress === viem_1.zeroAddress || verdict.spender === null) {
+        return { kind: 'calls', approval: null, deposit: originDeposit };
+    }
+    return {
+        kind: 'calls',
+        approval: {
+            chainId: request.fromChainId,
+            // An Ethereum origin; the request widens the address to `string` only
+            // for non-Ethereum origins, which were refused above.
+            token: request.fromTokenAddress,
+            spender: verdict.spender,
+            minimum: amountToSend,
+        },
+        deposit: originDeposit,
+    };
+};
+exports.aggregatorOriginCalls = aggregatorOriginCalls;
+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: (0, route_steps_js_1.normalizeLifiSteps)(quote.includedSteps),
+            fees: (0, quote_fees_js_1.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`
+ */
+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: (0, quote_fees_js_1.lifiQuoteFees)(payload) };
+};
+exports.parseLifiContractCallsQuote = parseLifiContractCallsQuote;
+/**
+ * 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(config_js_1.Chains.ETH),
+        sendingAssetId: request.fromTokenAddress,
+        hasDestinationCall,
+        minimumAmount: hasDestinationCall ? request.toAmount : null,
+        originAmount: request.fromAmount ?? 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 lifi_execution_guard_js_1.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;
+    (0, lifi_execution_guard_js_1.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
+ */
+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 };
+};
+exports.parseLifiQuote = parseLifiQuote;
+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.
+ */
+const lifiStatusUrl = ({ txHash, fromChainId, toChainId, }) => {
+    return defaultLifiEndpoints.status({ txHash, fromChainId, toChainId });
+};
+exports.lifiStatusUrl = lifiStatusUrl;
+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
+ */
+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,
+    };
+};
+exports.parseLifiStatus = parseLifiStatus;
+/**
+ * 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.
+ */
+exports.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
+ */
+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;
+};
+exports.parseLifiChains = parseLifiChains;
+/** Builds the per-chain token listing URL, at {@link lifiDefaultApiOrigin}. */
+exports.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
+ */
+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;
+};
+exports.parseLifiTokens = parseLifiTokens;