@gibs/bridge-sdk 1.13.0 → 1.17.0

package/dist/cjs/lifi-execution-guard.d.ts

@@ -0,0 +1,210 @@
+import { type Hex } from 'viem';
+/**
+ * Verifies a LI.FI EVM execution transaction before a wallet ever signs it.
+ *
+ * WHY THIS EXISTS. `lifiApi.quote` and `lifiApi.contractCallsQuote` are fetched
+ * through a configurable base URL — today `lifi.gibs.finance`, a server-side
+ * proxy; the interface may point at a different host in the future. Whichever
+ * host answers, this codebase used to sign whatever `transactionRequest` came
+ * back after checking only that `to` and `data` were hexadecimal strings (see
+ * `lifiEvmDeposit` in `consolidated-quote.ts`). A COMPROMISED PROXY could
+ * return ANY `to`/`data`/`value` and a connected wallet would sign it,
+ * moving the reader's funds wherever the proxy chose.
+ *
+ * WHAT THIS MODULE PROVES INSTEAD, before signing:
+ *
+ * 1. `to` (and, when present, `estimate.approvalAddress`) is LI.FI's own
+ *    Diamond entryway contract for the chain the transaction runs on — a
+ *    fixed table, not something the response gets to assert about itself.
+ *    See {@link lifiDiamondAddressByChainId}.
+ * 2. The calldata's selector is one of a small, explicitly verified set of
+ *    LI.FI facet functions whose ABI this module carries in full. An unknown
+ *    selector is refused rather than guessed at.
+ * 3. The decoded `BridgeData` and leading `SwapData` entry agree with what
+ *    THIS APPLICATION asked for — not with other fields of the same,
+ *    potentially compromised, response. See {@link LifiExecutionExpectation}.
+ * 4. `transactionRequest.value` equals exactly the native currency the
+ *    decoded calldata implies (the amount being deposited, when that amount
+ *    is native, plus any protocol messaging fee the tool's own data
+ *    declares) — never more, never less.
+ *
+ * WHERE THE FIELD SEMANTICS CAME FROM. Every fact this module relies on —
+ * which struct field means what, and how the three verified facet functions
+ * actually populate `BridgeData` and `SwapData` — was read from REAL
+ * responses captured live from `https://li.quest`, decoded with this exact
+ * machinery, and cross-checked against the deployed contracts' Solidity
+ * source (`lifinance/contracts`, commit `025989955bb373739737ee78ddff01620638ae3b`,
+ * 2026-09-23). Two assumptions a first reading of LI.FI's own field
+ * descriptions would suggest turned out to be wrong, and are recorded here so
+ * nobody reintroduces them:
+ *
+ * - `BridgeData.receiver` is NOT "the final recipient" in general. For the
+ *   contract-calls endpoint (`hasDestinationCall: true`) it decoded to the
+ *   REQUEST'S `toFallbackAddress` — the address that receives the bridged
+ *   asset if the destination call reverts — not the destination call's own
+ *   contract or the reader's recipient. Only for the plain endpoint
+ *   (`hasDestinationCall: false`) does it equal the recipient (`toAddress`).
+ *   Verified against three independently captured quotes; see the fixtures
+ *   this module's test file reads.
+ * - `BridgeData.minAmount` is NOT the destination-side guaranteed amount for
+ *   any of the three verified tools. It is the amount of `sendingAssetId`
+ *   pulled from the depositor on the ORIGIN chain (`LibAsset.depositAsset`
+ *   in every facet's Solidity), reassigned at runtime to the real swap
+ *   output when `hasSourceSwaps` is true — a fact this module's calldata
+ *   never carries. The genuine destination-side guarantee lives in each
+ *   tool's own trailing struct (`AcrossV4Data.outputAmount`,
+ *   `StargateData.sendParams.minAmountLD`) and is read from there instead.
+ *   LayerSwap's own struct carries no on-chain amount field at all — its
+ *   guarantee is an off-chain, backend-signed attestation — so this module
+ *   cannot verify a destination minimum for it and refuses to try; see
+ *   {@link DecodedLifiFacetCall.destinationMinimum}.
+ *
+ * SCOPE, DELIBERATELY NARROW. Only the exact facet-function shapes seen in a
+ * REAL captured LI.FI response are decoded; every other selector refuses.
+ * Adding a new tool means capturing a fixture for it first — see
+ * `packages/bridge-sdk/src/__fixtures__/lifi/README.md` — and extending
+ * {@link lifiFacetDecoders} from that fixture, never from documentation
+ * alone (per the hand-built-quotes-hide-parser-gaps lesson: a decoder written
+ * from a guess passes its own hand-built test and nothing else).
+ */
+/**
+ * Every reason this module can refuse a LI.FI execution transaction.
+ *
+ * Each maps to one property of the response this module distrusts by
+ * default: `unknown-chain` and `router-mismatch` distrust `to`;
+ * `approval-address-mismatch` distrusts `estimate.approvalAddress`;
+ * `unknown-selector` and `calldata-undecodable` distrust `data`'s shape;
+ * `receiver-mismatch`, `destination-chain-mismatch`, `sending-asset-mismatch`,
+ * `destination-call-flag-mismatch` and `minimum-amount-below-requested`
+ * distrust `data`'s DECODED fields against what this application asked for;
+ * `origin-amount-mismatch` distrusts the decoded amount pulled from the
+ * depositor; `native-value-mismatch` distrusts `value`. `missing-request-context` is
+ * different in kind: it means the CALLER never supplied what this
+ * application expected, so none of the above could even be checked — see
+ * `parseLifiContractCallsQuote` and `parseLifiQuote` in `consolidated-quote.ts`.
+ */
+export type LifiExecutionRefusalReason = 'unknown-chain' | 'router-mismatch' | 'approval-address-mismatch' | 'unknown-selector' | 'calldata-undecodable' | 'receiver-mismatch' | 'destination-chain-mismatch' | 'sending-asset-mismatch' | 'destination-call-flag-mismatch' | 'minimum-amount-below-requested' | 'origin-amount-mismatch' | 'native-value-mismatch' | 'missing-request-context';
+/** Why a LI.FI execution transaction was refused before signing. */
+export type LifiExecutionRefusal = {
+    readonly reason: LifiExecutionRefusalReason;
+    /** A short, specific explanation naming the values that disagreed. */
+    readonly detail: string;
+};
+/**
+ * Thrown by {@link verifyLifiEvmExecution} instead of returning a deposit a
+ * wallet could sign.
+ *
+ * NAMED AND TYPED SO A REFUSAL IS NEVER A SILENT DROP. Every caller that
+ * catches this can read `refusal.reason` and show, or log, exactly which
+ * check failed — the same discipline `@gibs/quotes`'s `ProviderQuoteError`
+ * applies to a provider declining a quote, applied here to a provider's
+ * ANSWER disagreeing with itself.
+ */
+export declare class LifiExecutionRefusedError extends Error {
+    readonly refusal: LifiExecutionRefusal;
+    constructor(refusal: LifiExecutionRefusal);
+}
+/**
+ * LI.FI's Diamond entryway contract address, by chain id.
+ *
+ * SOURCE. `lifinance/contracts` (https://github.com/lifinance/contracts),
+ * commit `025989955bb373739737ee78ddff01620638ae3b` (2026-09-23): the
+ * `LiFiDiamond` address in `deployments/<network>.json`, matched to its
+ * chain id in `config/networks.json`, for every network whose `status` is
+ * `"active"` and `"type"` is `"mainnet"`. LI.FI's own documentation
+ * (https://docs.li.fi/introduction/lifi-architecture/smart-contract-addresses)
+ * states the address is `0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE` "on most
+ * supported networks" but differs on some — confirmed here directly against
+ * the deployment records rather than assumed: 39 of the 65 active mainnet
+ * networks use a DIFFERENT address, almost all of them newer or lower-volume
+ * chains (0G, Abstract, ApeChain, Arbitrum Nova, Berachain, Flare, zkSync
+ * Era, and more).
+ *
+ * DELIBERATELY A FIXED, BAKED-IN TABLE, NEVER A LIVE LOOKUP. LI.FI's own
+ * `/v1/chains` endpoint carries a `diamondAddress` per chain, and this
+ * codebase already fetches it for other purposes — but that endpoint is
+ * reached through the SAME configurable, potentially-compromised host this
+ * module exists to distrust. Trusting it here would make the whole guard
+ * circular: a compromised proxy could simply report its own malicious
+ * address as the "correct" one. This table is real code, reviewed and
+ * shipped with the application, and can only change through a new release.
+ *
+ * UNKNOWN CHAIN, UNKNOWN ADDRESS. A chain id absent from this table refuses
+ * rather than falling back to the common address — LI.FI adds networks
+ * continuously, and assuming a newly-added chain shares the common address
+ * would be exactly the kind of guess this module exists to avoid making.
+ */
+export declare const lifiDiamondAddressByChainId: ReadonlyMap<number, Hex>;
+/** LI.FI's `ILiFi.BridgeData` struct — identical across every facet function. */
+export type LifiBridgeData = {
+    readonly transactionId: Hex;
+    readonly bridge: string;
+    readonly integrator: string;
+    readonly referrer: Hex;
+    readonly sendingAssetId: Hex;
+    readonly receiver: Hex;
+    readonly minAmount: bigint;
+    readonly destinationChainId: bigint;
+    readonly hasSourceSwaps: boolean;
+    readonly hasDestinationCall: boolean;
+};
+/**
+ * What THIS APPLICATION asked LI.FI for, independent of anything the
+ * response itself claims — the only thing a decoded transaction is allowed
+ * to be checked against.
+ */
+export type LifiExecutionExpectation = {
+    /**
+     * Where the bridged asset lands if the route needs no destination call
+     * (the plain endpoint's recipient), or where it lands if the destination
+     * call reverts (the contract-calls endpoint's fallback address) — see the
+     * `BridgeData.receiver` note at the top of this file for why these two are
+     * NOT the same field despite the shared name.
+     */
+    readonly receiver: Hex;
+    /** The chain the entry call (or the plain delivery) must land on. */
+    readonly destinationChainId: number;
+    /** The token this application is paying with on the origin chain. */
+    readonly sendingAssetId: Hex;
+    /** Whether this application attached an omnibridge entry call. */
+    readonly hasDestinationCall: boolean;
+    /**
+     * The guaranteed minimum this application asked LI.FI to deliver, or
+     * `null` for the plain (forward-solved) endpoint, which names no such
+     * minimum — the delivered amount is read back from the response instead
+     * of constrained by the request. See `ConsolidatedQuote.toAmount`.
+     */
+    readonly minimumAmount: bigint | null;
+    /**
+     * The exact amount of the origin token this application sends, in base units,
+     * or `null` when the request names none.
+     *
+     * Compared with the decoded `swapData[0].fromAmount`, the amount pulled from
+     * the depositor. Without it a response could keep every other field honest and
+     * still pull more than the reader chose. The request, never the response,
+     * supplies this figure.
+     */
+    readonly originAmount: bigint | null;
+};
+/** The transaction fields {@link verifyLifiEvmExecution} reads off the raw response. */
+export type LifiExecutionTransactionRequest = {
+    readonly to: Hex;
+    readonly data: Hex;
+    readonly value: bigint;
+    readonly chainId: number;
+};
+/**
+ * Verifies a LI.FI EVM execution transaction against what this application
+ * asked for, throwing {@link LifiExecutionRefusedError} on any disagreement.
+ * Returns normally — carrying nothing, since the caller already holds the
+ * transaction it validated — when every check passes.
+ *
+ * See this module's top-of-file doc comment for what is checked and why.
+ *
+ * @param transactionRequest - the parsed `to`/`data`/`value`/`chainId` this
+ *   application is about to hand to a wallet
+ * @param approvalAddress - `estimate.approvalAddress` from the same
+ *   response, or `null` when the route needs no token approval
+ * @param expectation - what this application actually asked for
+ */
+export declare const verifyLifiEvmExecution: (transactionRequest: LifiExecutionTransactionRequest, approvalAddress: Hex | null, expectation: LifiExecutionExpectation) => void;

package/dist/cjs/lifi-execution-guard.js

@@ -0,0 +1,409 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyLifiEvmExecution = exports.lifiDiamondAddressByChainId = exports.LifiExecutionRefusedError = void 0;
+const viem_1 = require("viem");
+/**
+ * Thrown by {@link verifyLifiEvmExecution} instead of returning a deposit a
+ * wallet could sign.
+ *
+ * NAMED AND TYPED SO A REFUSAL IS NEVER A SILENT DROP. Every caller that
+ * catches this can read `refusal.reason` and show, or log, exactly which
+ * check failed — the same discipline `@gibs/quotes`'s `ProviderQuoteError`
+ * applies to a provider declining a quote, applied here to a provider's
+ * ANSWER disagreeing with itself.
+ */
+class LifiExecutionRefusedError extends Error {
+    refusal;
+    constructor(refusal) {
+        super(`LI.FI execution transaction refused: ${refusal.detail}`);
+        this.refusal = refusal;
+        this.name = 'LifiExecutionRefusedError';
+    }
+}
+exports.LifiExecutionRefusedError = LifiExecutionRefusedError;
+const refuse = (reason, detail) => {
+    throw new LifiExecutionRefusedError({ reason, detail });
+};
+/**
+ * LI.FI's Diamond entryway contract address, by chain id.
+ *
+ * SOURCE. `lifinance/contracts` (https://github.com/lifinance/contracts),
+ * commit `025989955bb373739737ee78ddff01620638ae3b` (2026-09-23): the
+ * `LiFiDiamond` address in `deployments/<network>.json`, matched to its
+ * chain id in `config/networks.json`, for every network whose `status` is
+ * `"active"` and `"type"` is `"mainnet"`. LI.FI's own documentation
+ * (https://docs.li.fi/introduction/lifi-architecture/smart-contract-addresses)
+ * states the address is `0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE` "on most
+ * supported networks" but differs on some — confirmed here directly against
+ * the deployment records rather than assumed: 39 of the 65 active mainnet
+ * networks use a DIFFERENT address, almost all of them newer or lower-volume
+ * chains (0G, Abstract, ApeChain, Arbitrum Nova, Berachain, Flare, zkSync
+ * Era, and more).
+ *
+ * DELIBERATELY A FIXED, BAKED-IN TABLE, NEVER A LIVE LOOKUP. LI.FI's own
+ * `/v1/chains` endpoint carries a `diamondAddress` per chain, and this
+ * codebase already fetches it for other purposes — but that endpoint is
+ * reached through the SAME configurable, potentially-compromised host this
+ * module exists to distrust. Trusting it here would make the whole guard
+ * circular: a compromised proxy could simply report its own malicious
+ * address as the "correct" one. This table is real code, reviewed and
+ * shipped with the application, and can only change through a new release.
+ *
+ * UNKNOWN CHAIN, UNKNOWN ADDRESS. A chain id absent from this table refuses
+ * rather than falling back to the common address — LI.FI adds networks
+ * continuously, and assuming a newly-added chain shares the common address
+ * would be exactly the kind of guess this module exists to avoid making.
+ */
+exports.lifiDiamondAddressByChainId = new Map([
+    [1, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // mainnet
+    [10, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // optimism
+    [14, '0x198FC70Dfe05E755C81e54bd67Bff3F729344B9b'], // flare
+    [25, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // cronos
+    [30, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // rootstock
+    [40, '0xa7cd44521903C65915648385E3FE881E49171582'], // telos
+    [50, '0x055d4612Ec74aD799C6cB4dF72C0Ab8dbDBCBAfa'], // xdc
+    [56, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // bsc
+    [88, '0x198FC70Dfe05E755C81e54bd67Bff3F729344B9b'], // viction
+    [100, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // gnosis
+    [122, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // fuse
+    [130, '0x864b314D4C5a0399368609581d3E8933a63b9232'], // unichain
+    [137, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // polygon
+    [143, '0x026F252016A7C47CDEf1F05a3Fc9E20C92a49C37'], // monad
+    [146, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // sonic
+    [196, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // xlayer
+    [204, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // opbnb
+    [232, '0xF3B20515d9B193531c48E47c18aF16d1e5d28f9a'], // lens
+    [252, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // fraxtal
+    [288, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // boba
+    [324, '0x341e94069f53234fE6DabeF707aD424830525715'], // zksync
+    [480, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // worldchain
+    [747, '0x026F252016A7C47CDEf1F05a3Fc9E20C92a49C37'], // flow
+    [988, '0x026F252016A7C47CDEf1F05a3Fc9E20C92a49C37'], // stable
+    [1088, '0x24ca98fB6972F5eE05f0dB00595c7f68D9FaFd68'], // metis
+    [1135, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // lisk
+    [1329, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // sei
+    [1480, '0x198FC70Dfe05E755C81e54bd67Bff3F729344B9b'], // vana
+    [1625, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // gravity
+    [1672, '0xFf70F4A1d11995621854F3692acF286d8aCd04b2'], // pharos
+    [1776, '0xeCeC3970Ca674278DA8D9B1c484ACaF6B20181F5'], // injective
+    [1868, '0x864b314D4C5a0399368609581d3E8933a63b9232'], // soneium
+    [2020, '0x452Cf1B8597E6319Cd21abd847312bF17E26d8d1'], // ronin
+    [2741, '0x4f8C9056bb8A3616693a76922FA35d53C056E5b3'], // abstract
+    [2818, '0xF7aB42D00D2399f8A4Fba2F15466Be40709fe307'], // morph
+    [4217, '0x2cAcAE8e22418E65dcf7651c67aEbe6288EB8243'], // tempo
+    [4326, '0x026F252016A7C47CDEf1F05a3Fc9E20C92a49C37'], // megaeth
+    [4663, '0xB477751B76CF82d00a686A1232f5fCD772414Af3'], // robinhood
+    [5000, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // mantle
+    [5031, '0x0bc413CAe89C5b3Ba3AA87FB98dCA23425E1828f'], // somnia
+    [5042, '0xA4072583658Fae592A3506A42431cb6316a8d40b'], // arc
+    [5734951, '0x026F252016A7C47CDEf1F05a3Fc9E20C92a49C37'], // jovay
+    [6900, '0x926c22Dc753E543Cf9CaB75CeEB46ecf865d006a'], // nibiru
+    [8217, '0x1255d17c1BC2f764d087536410879F2d0D8772fD'], // kaia
+    [8453, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // base
+    [9745, '0x026F252016A7C47CDEf1F05a3Fc9E20C92a49C37'], // plasma
+    [13371, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // immutablezkevm
+    [16661, '0x213A83c67E1Fc0334eF684571ABCB820708A6536'], // 0g
+    [33139, '0x2dea447e7dc6cd2f10b31bF10dCB30F87E838417'], // apechain
+    [34443, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // mode
+    [42161, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // arbitrum
+    [42170, '0xFf70F4A1d11995621854F3692acF286d8aCd04b2'], // arbitrumnova
+    [42220, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // celo
+    [42793, '0x977474593c982cFa8b197cAE302e6d01f789435b'], // etherlink
+    [43111, '0x026F252016A7C47CDEf1F05a3Fc9E20C92a49C37'], // hemi
+    [43114, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // avalanche
+    [57073, '0x864b314D4C5a0399368609581d3E8933a63b9232'], // ink
+    [59144, '0xDE1E598b81620773454588B85D6b5D4eEC32573e'], // linea
+    [60808, '0x452Cf1B8597E6319Cd21abd847312bF17E26d8d1'], // bob
+    [80094, '0xf909c4Ae16622898b885B89d7F839E0244851c66'], // berachain
+    [81457, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // blast
+    [98866, '0x6f5C8Bb0C5Fe4ECeAC40EE1C238EaB6bbb29761c'], // plume
+    [534352, '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'], // scroll
+    [747474, '0xC59fe32C9549e3E8B5dCcdAbC45BD287Bd5bA2bc'], // katana
+    [999, '0x0a0758d937d1059c356D4714e57F5df0239bce1A'], // hyperevm
+]);
+const bridgeDataAbiType = {
+    type: 'tuple',
+    components: [
+        { name: 'transactionId', type: 'bytes32' },
+        { name: 'bridge', type: 'string' },
+        { name: 'integrator', type: 'string' },
+        { name: 'referrer', type: 'address' },
+        { name: 'sendingAssetId', type: 'address' },
+        { name: 'receiver', type: 'address' },
+        { name: 'minAmount', type: 'uint256' },
+        { name: 'destinationChainId', type: 'uint256' },
+        { name: 'hasSourceSwaps', type: 'bool' },
+        { name: 'hasDestinationCall', type: 'bool' },
+    ],
+};
+const swapDataArrayAbiType = {
+    type: 'tuple[]',
+    components: [
+        { name: 'callTo', type: 'address' },
+        { name: 'approveTo', type: 'address' },
+        { name: 'sendingAssetId', type: 'address' },
+        { name: 'receivingAssetId', type: 'address' },
+        { name: 'fromAmount', type: 'uint256' },
+        { name: 'callData', type: 'bytes' },
+        { name: 'requiresDeposit', type: 'bool' },
+    ],
+};
+/** Decodes `BridgeData` and the leading `SwapData` entry, shared by every verified decoder. */
+const decodeBridgeDataAndLeadingSwap = (encodedTail) => {
+    const [bridgeData, swapData] = (0, viem_1.decodeAbiParameters)([bridgeDataAbiType, swapDataArrayAbiType], encodedTail);
+    // EVERY VERIFIED SELECTOR IS A `swapAndStartBridgeTokensViaX` FUNCTION,
+    // whose `containsSourceSwaps` modifier requires a non-empty `SwapData[]`
+    // on a genuine call. An empty array here — whether from `hasSourceSwaps`
+    // being forged false or the array itself being emptied — means this
+    // module cannot identify what was actually pulled from the depositor, so
+    // it refuses rather than reading past the end of the array.
+    const leadingSwap = swapData[0];
+    if (!bridgeData.hasSourceSwaps || leadingSwap === undefined) {
+        return null;
+    }
+    return { bridgeData, leadingSwap };
+};
+/**
+ * `swapAndStartBridgeTokensViaAcrossV4((BridgeData),(SwapData[]),(AcrossV4Data))`.
+ *
+ * Selector `0x1794958f`, verified against
+ * `packages/bridge-sdk/src/__fixtures__/lifi/contract-quote-success-eth-to-base-usdc.json`
+ * (a real `GET /v1/quote` response) — signature and struct layout read from
+ * `lifinance/contracts/src/Facets/AcrossFacetV4.sol`. `AcrossV4Data` carries
+ * no native-fee field, so {@link DecodedLifiFacetCall.extraNativeFee} is
+ * always `0n`. `outputAmount` is Across's own destination-side guarantee —
+ * confirmed equal to the SAME response's `estimate.toAmountMin`.
+ */
+const decodeAcrossV4SwapAndStart = (data) => {
+    const acrossV4DataAbiType = {
+        type: 'tuple',
+        components: [
+            { name: 'receiverAddress', type: 'bytes32' },
+            { name: 'refundAddress', type: 'bytes32' },
+            { name: 'sendingAssetId', type: 'bytes32' },
+            { name: 'receivingAssetId', type: 'bytes32' },
+            { name: 'outputAmount', type: 'uint256' },
+            { name: 'outputAmountMultiplier', type: 'uint128' },
+            { name: 'exclusiveRelayer', type: 'bytes32' },
+            { name: 'quoteTimestamp', type: 'uint32' },
+            { name: 'fillDeadline', type: 'uint32' },
+            { name: 'exclusivityParameter', type: 'uint32' },
+            { name: 'message', type: 'bytes' },
+        ],
+    };
+    const encodedTail = `0x${data.slice(10)}`;
+    const decodedHead = decodeBridgeDataAndLeadingSwap(encodedTail);
+    if (decodedHead === null) {
+        return null;
+    }
+    const [, , acrossData] = (0, viem_1.decodeAbiParameters)([bridgeDataAbiType, swapDataArrayAbiType, acrossV4DataAbiType], encodedTail);
+    return {
+        toolLabel: 'across',
+        bridgeData: decodedHead.bridgeData,
+        originSendingAssetId: decodedHead.leadingSwap.sendingAssetId,
+        originAmount: decodedHead.leadingSwap.fromAmount,
+        extraNativeFee: 0n,
+        destinationMinimum: acrossData.outputAmount,
+    };
+};
+/**
+ * `swapAndStartBridgeTokensViaLayerSwap((BridgeData),(SwapData[]),(LayerSwapData))`.
+ *
+ * Selector `0x4c279d6b`, verified against
+ * `packages/bridge-sdk/src/__fixtures__/lifi/quote-plain-base-to-polygon.json`
+ * (a real `GET /v1/quote` response) — signature and struct layout read from
+ * `lifinance/contracts/src/Facets/LayerSwapFacet.sol`. `LayerSwapData`
+ * carries no native-fee field ({@link DecodedLifiFacetCall.extraNativeFee}
+ * is always `0n`) and, unlike Across or Stargate, NO destination-amount
+ * field at all — LayerSwap's delivered amount is attested off-chain by an
+ * EIP-712 signature over `requestId`, not provable from this calldata, so
+ * {@link DecodedLifiFacetCall.destinationMinimum} is always `null`.
+ */
+const decodeLayerSwapSwapAndStart = (data) => {
+    const layerSwapDataAbiType = {
+        type: 'tuple',
+        components: [
+            { name: 'requestId', type: 'bytes32' },
+            { name: 'depositoryReceiver', type: 'address' },
+            { name: 'refundRecipient', type: 'address' },
+            { name: 'nonEVMReceiver', type: 'bytes32' },
+            { name: 'signature', type: 'bytes' },
+            { name: 'deadline', type: 'uint256' },
+        ],
+    };
+    const encodedTail = `0x${data.slice(10)}`;
+    const decodedHead = decodeBridgeDataAndLeadingSwap(encodedTail);
+    if (decodedHead === null) {
+        return null;
+    }
+    return {
+        toolLabel: 'layerswap',
+        bridgeData: decodedHead.bridgeData,
+        originSendingAssetId: decodedHead.leadingSwap.sendingAssetId,
+        originAmount: decodedHead.leadingSwap.fromAmount,
+        extraNativeFee: 0n,
+        destinationMinimum: null,
+    };
+};
+/**
+ * `swapAndStartBridgeTokensViaStargate((BridgeData),(SwapData[]),(StargateData))`.
+ *
+ * Selector `0xa6010a66`, verified against two live captures of
+ * `POST /v1/quote/contractCalls`
+ * (`packages/bridge-sdk/src/__fixtures__/lifi/contract-calls-native-base-to-eth-mediator.json`
+ * and its `-erc20-` sibling) — signature and struct layout read from
+ * `lifinance/contracts/src/Facets/StargateFacetV2.sol` and
+ * `src/Interfaces/IStargate.sol`. `StargateData.fee.nativeFee` is a
+ * LayerZero messaging fee that rides in `msg.value` ON TOP of any deposited
+ * native amount — confirmed by both fixtures: `transactionRequest.value`
+ * equalled `originAmount + fee.nativeFee` exactly (origin ETH) and
+ * `fee.nativeFee` alone when the origin amount was an ERC20 (USD Coin, no
+ * native component). `sendParams.minAmountLD` is Stargate's own
+ * destination-side guarantee.
+ */
+const decodeStargateSwapAndStart = (data) => {
+    const stargateDataAbiType = {
+        type: 'tuple',
+        components: [
+            { name: 'assetId', type: 'uint16' },
+            {
+                name: 'sendParams',
+                type: 'tuple',
+                components: [
+                    { name: 'dstEid', type: 'uint32' },
+                    { name: 'to', type: 'bytes32' },
+                    { name: 'amountLD', type: 'uint256' },
+                    { name: 'minAmountLD', type: 'uint256' },
+                    { name: 'extraOptions', type: 'bytes' },
+                    { name: 'composeMsg', type: 'bytes' },
+                    { name: 'oftCmd', type: 'bytes' },
+                ],
+            },
+            {
+                name: 'fee',
+                type: 'tuple',
+                components: [
+                    { name: 'nativeFee', type: 'uint256' },
+                    { name: 'lzTokenFee', type: 'uint256' },
+                ],
+            },
+            { name: 'refundAddress', type: 'address' },
+        ],
+    };
+    const encodedTail = `0x${data.slice(10)}`;
+    const decodedHead = decodeBridgeDataAndLeadingSwap(encodedTail);
+    if (decodedHead === null) {
+        return null;
+    }
+    const [, , stargateData] = (0, viem_1.decodeAbiParameters)([bridgeDataAbiType, swapDataArrayAbiType, stargateDataAbiType], encodedTail);
+    return {
+        toolLabel: 'stargateV2',
+        bridgeData: decodedHead.bridgeData,
+        originSendingAssetId: decodedHead.leadingSwap.sendingAssetId,
+        originAmount: decodedHead.leadingSwap.fromAmount,
+        extraNativeFee: stargateData.fee.nativeFee,
+        destinationMinimum: stargateData.sendParams.minAmountLD,
+    };
+};
+/**
+ * Every LI.FI facet function this module can decode, keyed by its four-byte
+ * selector. AN UNKNOWN SELECTOR IS NEVER DECODED — {@link verifyLifiEvmExecution}
+ * refuses it outright. Extending this table means capturing a real fixture
+ * for the new tool first; see this module's top-of-file doc comment.
+ */
+const lifiFacetDecoders = {
+    '0x1794958f': decodeAcrossV4SwapAndStart,
+    '0x4c279d6b': decodeLayerSwapSwapAndStart,
+    '0xa6010a66': decodeStargateSwapAndStart,
+};
+const sameAddress = (a, b) => a.toLowerCase() === b.toLowerCase();
+/**
+ * Verifies a LI.FI EVM execution transaction against what this application
+ * asked for, throwing {@link LifiExecutionRefusedError} on any disagreement.
+ * Returns normally — carrying nothing, since the caller already holds the
+ * transaction it validated — when every check passes.
+ *
+ * See this module's top-of-file doc comment for what is checked and why.
+ *
+ * @param transactionRequest - the parsed `to`/`data`/`value`/`chainId` this
+ *   application is about to hand to a wallet
+ * @param approvalAddress - `estimate.approvalAddress` from the same
+ *   response, or `null` when the route needs no token approval
+ * @param expectation - what this application actually asked for
+ */
+const verifyLifiEvmExecution = (transactionRequest, approvalAddress, expectation) => {
+    const router = exports.lifiDiamondAddressByChainId.get(transactionRequest.chainId);
+    if (router === undefined) {
+        refuse('unknown-chain', `no known LI.FI Diamond address for chain ${transactionRequest.chainId}`);
+        return;
+    }
+    if (!sameAddress(transactionRequest.to, router)) {
+        refuse('router-mismatch', `transactionRequest.to (${transactionRequest.to}) is not LI.FI's Diamond on chain ${transactionRequest.chainId} (${router})`);
+        return;
+    }
+    if (approvalAddress !== null && !sameAddress(approvalAddress, router)) {
+        refuse('approval-address-mismatch', `estimate.approvalAddress (${approvalAddress}) is not LI.FI's Diamond on chain ${transactionRequest.chainId} (${router})`);
+        return;
+    }
+    if (transactionRequest.data.length < 10) {
+        refuse('calldata-undecodable', 'transactionRequest.data is shorter than a function selector');
+        return;
+    }
+    const selector = transactionRequest.data.slice(0, 10).toLowerCase();
+    const decoder = lifiFacetDecoders[selector];
+    if (decoder === undefined) {
+        refuse('unknown-selector', `transactionRequest.data's selector (${selector}) is not a verified LI.FI facet function`);
+        return;
+    }
+    let decoded;
+    try {
+        decoded = decoder(transactionRequest.data);
+    }
+    catch (error) {
+        refuse('calldata-undecodable', `transactionRequest.data did not decode as ${selector}'s known parameters: ${error instanceof Error ? error.message : String(error)}`);
+        return;
+    }
+    if (decoded === null) {
+        refuse('calldata-undecodable', `${selector} decoded with no usable source-swap entry`);
+        return;
+    }
+    if (!sameAddress(decoded.bridgeData.receiver, expectation.receiver)) {
+        refuse('receiver-mismatch', `decoded BridgeData.receiver (${decoded.bridgeData.receiver}) does not match the expected receiver (${expectation.receiver})`);
+        return;
+    }
+    if (decoded.bridgeData.destinationChainId !== BigInt(expectation.destinationChainId)) {
+        refuse('destination-chain-mismatch', `decoded BridgeData.destinationChainId (${decoded.bridgeData.destinationChainId}) does not match the requested destination chain (${expectation.destinationChainId})`);
+        return;
+    }
+    if (!sameAddress(decoded.originSendingAssetId, expectation.sendingAssetId)) {
+        refuse('sending-asset-mismatch', `decoded origin sending asset (${decoded.originSendingAssetId}) does not match the requested origin token (${expectation.sendingAssetId})`);
+        return;
+    }
+    if (decoded.bridgeData.hasDestinationCall !== expectation.hasDestinationCall) {
+        refuse('destination-call-flag-mismatch', `decoded BridgeData.hasDestinationCall (${decoded.bridgeData.hasDestinationCall}) does not match whether this request attached a destination call (${expectation.hasDestinationCall})`);
+        return;
+    }
+    if (expectation.minimumAmount !== null) {
+        if (decoded.destinationMinimum === null) {
+            refuse('minimum-amount-below-requested', `${decoded.toolLabel} carries no on-chain destination-amount field to verify against the requested minimum (${expectation.minimumAmount})`);
+            return;
+        }
+        if (decoded.destinationMinimum < expectation.minimumAmount) {
+            refuse('minimum-amount-below-requested', `decoded destination minimum (${decoded.destinationMinimum}) is below the requested minimum (${expectation.minimumAmount})`);
+            return;
+        }
+    }
+    if (expectation.originAmount !== null && decoded.originAmount !== expectation.originAmount) {
+        refuse('origin-amount-mismatch', `decoded origin amount (${decoded.originAmount}) does not equal the amount to send (${expectation.originAmount})`);
+        return;
+    }
+    const nativeOriginComponent = sameAddress(decoded.originSendingAssetId, viem_1.zeroAddress)
+        ? decoded.originAmount
+        : 0n;
+    const expectedValue = nativeOriginComponent + decoded.extraNativeFee;
+    if (transactionRequest.value !== expectedValue) {
+        refuse('native-value-mismatch', `transactionRequest.value (${transactionRequest.value}) does not equal the native amount the decoded calldata implies (${expectedValue})`);
+        return;
+    }
+};
+exports.verifyLifiEvmExecution = verifyLifiEvmExecution;