@gibs/bridge-sdk 1.12.0 → 1.13.1

package/dist/lifi-execution-guard.js

@@ -0,0 +1,400 @@
+import { decodeAbiParameters, zeroAddress } from '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.
+ */
+export class LifiExecutionRefusedError extends Error {
+    refusal;
+    constructor(refusal) {
+        super(`LI.FI execution transaction refused: ${refusal.detail}`);
+        this.refusal = refusal;
+        this.name = '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.
+ */
+export const 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] = 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] = 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] = 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
+ */
+export const verifyLifiEvmExecution = (transactionRequest, approvalAddress, expectation) => {
+    const router = 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;
+        }
+    }
+    const nativeOriginComponent = sameAddress(decoded.originSendingAssetId, 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;
+    }
+};

package/dist/near-intents-conformance.d.ts

@@ -0,0 +1,85 @@
+/**
+ * One way a payload departs from the shape the parsers were written against.
+ *
+ * `found` is a description rather than the value itself, so a finding can be
+ * printed in a continuous-integration log without carrying an address, an
+ * amount or anything else from a real response into it.
+ */
+export type NearIntentsShapeFinding = {
+    /** Where in the payload, as a dotted path from the root. */
+    readonly path: string;
+    /** What the parsers require there. */
+    readonly expected: string;
+    /** What was there instead, described rather than quoted. */
+    readonly found: string;
+};
+/**
+ * Checks a `POST /v0/quote` answer against everything the quote parsers read.
+ *
+ * THE DOLLAR FIGURES ARE CHECKED THOUGH THE PARSER TOLERATES THEIR ABSENCE.
+ * `parseNearIntentsQuote` turns a missing `amountInUsd` into null and carries
+ * on, which is right for a quote and wrong for a conformance check: losing the
+ * dollar figure leaves the reader a route with no price beside it, and nothing
+ * else in the system would report that the service stopped sending one.
+ *
+ * @param payload - the raw JSON body the service answered with
+ * @param options.expectDepositAddress - true for an executable (`dry: false`)
+ *   answer, false for a dry one. A dry answer omits the deposit address by
+ *   design, so requiring it there would report a finding on a healthy service
+ * @returns every departure from the expected shape; empty means conformant
+ */
+export declare const nearIntentsQuoteShapeFindings: (payload: unknown, { expectDepositAddress }: {
+    expectDepositAddress: boolean;
+}) => readonly NearIntentsShapeFinding[];
+/**
+ * Checks a `GET /v0/tokens` answer, including the chain names we map by hand.
+ *
+ * AN UNMAPPED CHAIN NAME IS THE DRIFT MOST LIKELY TO HAPPEN AND LEAST LIKELY
+ * TO BE NOTICED. `chainIdByNearIntentsChain` is a hand-written table, and
+ * `findNearIntentsAsset` matches through it — so if the service renames a
+ * chain or adds one, every asset on that chain becomes invisible to this
+ * repository while the asset list parses perfectly and every test stays green.
+ * The names are reported rather than the assets, because a new chain we do not
+ * carry is ordinary and a renamed chain we DO carry is the emergency.
+ *
+ * @param payload - the raw JSON body from the asset endpoint
+ * @param options.requiredChains - the service's own names for the chains this
+ *   repository must keep reaching. A name missing from the answer means the
+ *   service renamed or dropped it
+ * @returns every departure from the expected shape; empty means conformant
+ */
+export declare const nearIntentsTokenListShapeFindings: (payload: unknown, { requiredChains }: {
+    requiredChains: readonly string[];
+}) => readonly NearIntentsShapeFinding[];
+/**
+ * The service's own names for every chain this repository maps to a chain
+ * identifier, which is exactly the set whose renaming would be invisible.
+ */
+export declare const nearIntentsMappedChainNames: () => readonly string[];
+/**
+ * Checks a `GET /v0/status` answer against what the status parser reads.
+ *
+ * THE DELIVERY HASH IS NOT REQUIRED, and that is not laxity. A route awaiting
+ * its deposit has genuinely not produced one, and the captured
+ * `status-pending-deposit.json` is exactly that case — so requiring it would
+ * report a finding on a perfectly healthy in-flight transfer. What is required
+ * is that the ARRAY exists, because its absence is the difference between "no
+ * hash yet" and "the service stopped telling us where the funds landed".
+ *
+ * @param payload - the raw JSON body from the status endpoint
+ * @returns every departure from the expected shape; empty means conformant
+ */
+export declare const nearIntentsStatusShapeFindings: (payload: unknown) => readonly NearIntentsShapeFinding[];
+/**
+ * Checks a refusal body carries the message the refusal parser reads.
+ *
+ * BOTH SIZE FLOORS ARRIVE ONLY AS PROSE IN THIS FIELD. There is no code, no
+ * limits endpoint and no structured figure — `parseNearIntentsQuoteRefusal`
+ * runs a regular expression over the sentence. So if the wording changes, a
+ * refusal that should withdraw the route from the competition instead reads as
+ * `other`, and the reader waits for a bid that will never come.
+ *
+ * @param payload - the raw JSON body of a refused quote
+ * @returns every departure from the expected shape; empty means conformant
+ */
+export declare const nearIntentsRefusalShapeFindings: (payload: unknown) => readonly NearIntentsShapeFinding[];