@gibs/bridge-sdk 1.12.0 → 1.13.1

package/dist/relay-quote.js

@@ -0,0 +1,983 @@
+import { decodeFunctionData, encodeFunctionData, erc20Abi, maxUint256, zeroAddress, } from 'viem';
+import { Chains } from './config.js';
+import { isNonEthereumVirtualMachineOrigin, } from './consolidated-quote.js';
+import { defaultReferralFeeBasisPoints, referralIntegrator, resolveAttribution } from './referral.js';
+import { depositAddressChainIds, relayChainIds, } from './chain-names.js';
+import { normalizeRelaySteps } from './route-steps.js';
+import { relayQuoteFees } from './quote-fees.js';
+/**
+ * Relay (relay.link) as a second consolidated-route quote provider, competing
+ * with LI.FI on price. Relay quotes the same backwards-from-destination route:
+ * deliver exactly `toAmount` of the Ethereum-side token, then run our omnibridge
+ * entry call against it.
+ *
+ * One semantic differs from LI.FI and the difference is load-bearing. Relay has
+ * NO destination-chain fallback address. When the destination call cannot fill,
+ * Relay refunds on the ORIGIN chain to `refundTo`, in the origin currency — the
+ * user ends up back where they started, not holding the Ethereum-side token at
+ * a fallback. We therefore map our `fallbackAddress` onto `refundTo`; a failed
+ * Relay route is recovered on the origin chain, never stranded on Ethereum.
+ */
+/**
+ * Relay's API root. Steps carry RELATIVE post endpoints (`/authorize`), so a
+ * caller completing one has to resolve it against this.
+ */
+export const relayApiBaseUrl = 'https://api.relay.link';
+/** Relay quote endpoint. Anonymous access works at a 50-requests-per-minute tier. */
+export const relayQuoteUrl = `${relayApiBaseUrl}/quote/v2`;
+/** Relay requests endpoint; filters by origin or destination transaction hash. */
+/**
+ * The request-lookup endpoint, used to poll a route's progress.
+ *
+ * v3 RATHER THAN v2 BECAUSE v2 IS GOING AWAY. Relay began staged rate limiting
+ * of `/requests/v2` on 2026-09-01 and retires it on 2026-11-24, saying so in a
+ * `deprecation` block on every v2 response. v3 REQUIRES `x-api-key` - it
+ * answers 400 without one, where v2 served anonymous callers from a shared
+ * pool - so a caller must send `relayRequestHeaders(yourRelayApiKey)`.
+ */
+export const relayRequestsUrl = 'https://api.relay.link/requests/v3';
+/**
+ * Builds the headers for a Relay request. `apiKey` is Relay's `x-api-key`
+ * value. This package ships no key: the caller supplies its own (the Gibs
+ * interface keeps its key in `packages/ui/src/lib/config.ts`).
+ * Relay raises the account's rate limit and attributes traffic to it when the
+ * header is present.
+ *
+ * When `apiKey` is absent or an empty string, the returned headers carry NO
+ * `x-api-key` entry at all — not an empty one.
+ *
+ * WHETHER THAT IS SURVIVABLE DEPENDS ENTIRELY ON WHICH ENDPOINT IS BEING CALLED,
+ * and this note used to say only the reassuring half. Measured against the live
+ * service:
+ *
+ *     POST /quote            no key -> 200   routing works anonymously
+ *     GET  /requests/v3      no key -> 400   "headers must have required
+ *                                             property 'x-api-key'"
+ *
+ * So a missing key is a normal operating state for ROUTING — a reader on a
+ * local build or the anonymous InterPlanetary File System deployment still gets
+ * real quotes, and clearing the key disables attribution rather than the
+ * product. It is NOT survivable for STATUS. Every status poll from a keyless
+ * build fails, which means a consolidated record never learns its provider
+ * finished, never records the entry-chain transaction, and never releases from
+ * the pending list. That is not a degraded rate limit; it is the feature not
+ * working at all, silently.
+ */
+export const relayRequestHeaders = (apiKey) => {
+    const headers = { 'Content-Type': 'application/json' };
+    if (apiKey) {
+        headers['x-api-key'] = apiKey;
+    }
+    return headers;
+};
+/**
+ * Gibs Finance's own Relay `referrer`, for callers that want to attribute to
+ * Gibs Finance. The request builders do NOT default to it: pass it, or your
+ * own, as `relayReferrer` on the request. Relay reads any `referrer` as "a
+ * referrer was supplied" and then requires an API key, so a default would
+ * break every caller without one.
+ */
+export const relayReferrer = referralIntegrator;
+/**
+ * Application fee in basis points charged on Relay routes. Ten basis points is
+ * one tenth of a percent. Sent as `appFees[0].fee` when a payout recipient is
+ * configured; absent entirely when the recipient is missing.
+ */
+export const relayReferralFeeBasisPoints = defaultReferralFeeBasisPoints;
+export { relayReferralRecipient } from './referral.js';
+/** Extra gas added to the destination budget to cover a prepended approval call. */
+export const relayApprovalGasBuffer = 60000n;
+/**
+ * Relay's chain identifiers and their display names live in `chain-names.ts`
+ * so the route-step normalizer can name a Relay chain without importing this
+ * module, which imports it. Re-exported here because callers reach for them
+ * alongside the rest of the Relay surface.
+ */
+export { relayChainIds, relayChainNames } from './chain-names.js';
+/**
+ * Relay's pseudo chain identifiers, mapped to the ecosystem each belongs to.
+ * Data rather than a branch chain, so registering another Relay origin is one
+ * entry here instead of another conditional.
+ */
+const ecosystemByRelayChainId = new Map([
+    [relayChainIds.solana, 'svm'],
+    // two chain ids, one ecosystem: the mapping is many-to-one by design
+    [relayChainIds.eclipse, 'svm'],
+    [relayChainIds.bitcoin, 'bvm'],
+    [relayChainIds.tron, 'tvm'],
+    [relayChainIds.ton, 'tonvm'],
+    [relayChainIds.hyperliquid, 'hypevm'],
+]);
+/**
+ * The chains a reader pays by hand, mapped to the ecosystem each belongs to.
+ *
+ * KEPT APART FROM THE RELAY MAP ABOVE, because none of these is a Relay chain
+ * and a map named for Relay should not claim one. They are here at all because
+ * {@link ecosystemByChainId} answers `evm` for every identifier it does not
+ * know. An unregistered Zcash identifier would therefore read as an Ethereum
+ * chain — which has a wallet, a signer and a transaction — and the reader would
+ * be asked to sign on a chain they do not hold.
+ *
+ * Typed `Record<DepositAddressChain, Ecosystem>` rather than `Map<number, …>`
+ * so a chain added to {@link depositAddressChainIds} without an ecosystem
+ * here is a compile error. This is the table finding this danger is about: a
+ * silent miss is exactly the "reads as Ethereum" failure the comment above
+ * warns against, and a compile error is the only guard that cannot be
+ * forgotten.
+ */
+const ecosystemByDepositAddressChain = {
+    zcash: 'zcash',
+};
+/** {@link ecosystemByDepositAddressChain}, keyed by chain id for lookup. */
+const ecosystemByDepositAddressChainId = new Map(Object.keys(depositAddressChainIds).map((chain) => [
+    depositAddressChainIds[chain],
+    ecosystemByDepositAddressChain[chain],
+]));
+/**
+ * Maps a chain identifier to its virtual-machine ecosystem. Relay's non-Ethereum
+ * pseudo chain identifiers map to their own ecosystem; every other identifier
+ * (every Ethereum Virtual Machine chain) maps to `evm`. Total — never throws.
+ *
+ * Lives here rather than in `ecosystems.ts` because it depends on
+ * `relayChainIds` (defined in this file); the `Ecosystem` import is type-only,
+ * so `ecosystems.ts` stays a dependency-free leaf and no import cycle is formed.
+ *
+ * @param chainId - a chain identifier (an Ethereum chain id, or a Relay pseudo id)
+ * @returns the ecosystem that chain belongs to
+ */
+export const ecosystemByChainId = (chainId) => ecosystemByRelayChainId.get(chainId) ?? ecosystemByDepositAddressChainId.get(chainId) ?? 'evm';
+/**
+ * Relay's native-currency address strings, used verbatim as `originCurrency`
+ * when the origin pays in the chain's native asset.
+ *
+ * Source: https://api.relay.link/chains.
+ */
+export const relayNativeCurrencyAddresses = {
+    /**
+     * Ethereum Virtual Machine native currency (Ether, native gas tokens). The
+     * all-zero address Relay uses across every Ethereum Virtual Machine chain.
+     */
+    ethereumVirtualMachine: '0x0000000000000000000000000000000000000000',
+    /**
+     * Solana native currency (SOL), addressed by the System Program. Nine
+     * decimals.
+     */
+    solana: '11111111111111111111111111111111',
+    /** Bitcoin native currency (BTC). Eight decimals. */
+    bitcoin: 'bc1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqmql8k8',
+    /** Tron native currency (TRX). Six decimals. */
+    tron: 'T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb',
+    /**
+     * The Open Network's native currency as Relay reports it: Gram, NOT the
+     * Toncoin gas asset. Nine decimals.
+     */
+    ton: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
+    /**
+     * Hyperliquid's native currency as Relay reports it: USD Coin, NOT the Hype
+     * gas asset, addressed by a sixteen-byte HyperCore token identifier. Eight
+     * decimals. Deliberately NOT the twenty-byte all-zero Ethereum address.
+     */
+    hyperliquid: '0x00000000000000000000000000000000',
+};
+/**
+ * Converts a slippage fraction into the basis-point string Relay expects.
+ *
+ * @param slippage - tolerance as a fraction (0.005 means half a percent)
+ * @returns basis points as a string (0.005 becomes "50")
+ */
+export const slippageToBasisPoints = (slippage) => Math.round(slippage * 10_000).toString();
+/**
+ * The `referrer` field of a Relay request body, present only when the caller
+ * named one. Relay reads any `referrer`, an empty one included, as "a referrer
+ * was supplied" and then requires an API key, so absence is the safe default.
+ *
+ * @param request - carries the caller's `relayReferrer`, if any
+ * @returns `{ referrer }`, or an empty object
+ */
+export const relayReferrerField = (request) => {
+    const referrer = resolveAttribution(request.relayReferrer, undefined);
+    return referrer === undefined ? {} : { referrer };
+};
+/**
+ * Builds the Relay contract-call quote request from a provider-agnostic
+ * consolidated request. The omnibridge entry call becomes the final `txs`
+ * entry; when it needs an ERC20 allowance (the relayTokens shape, where
+ * `approvalTarget` is set) an `approve` call is prepended so Relay's executor
+ * grants it before relaying.
+ *
+ * @returns the request body, or null when the inputs cannot form a valid call
+ */
+export const buildRelayQuoteRequest = (request) => {
+    const { destinationCall, toAmount } = request;
+    // A DIRECT ROUTE — no omnibridge leg, so nothing to call on arrival.
+    //
+    // Solved FORWARDS rather than backwards, which is the whole difference. A
+    // route into the omnibridge must deliver an exact amount to the entry call,
+    // so it asks Relay for an exact OUTPUT. Here the reader says what they are
+    // spending and the delivered amount is whatever the market gives, so it asks
+    // for an exact INPUT and names a `recipient` instead of a transaction to run.
+    if (destinationCall === undefined) {
+        const fromAmount = request.fromAmount;
+        if (fromAmount === undefined || fromAmount <= 0n) {
+            return null;
+        }
+        const nonEthereumOriginDirect = isNonEthereumVirtualMachineOrigin(request);
+        return {
+            user: request.fromAddress,
+            originChainId: request.fromChainId,
+            originCurrency: request.fromTokenAddress,
+            destinationChainId: request.toChainId ?? Number(Chains.ETH),
+            destinationCurrency: request.toTokenAddress,
+            amount: fromAmount.toString(),
+            tradeType: 'EXACT_INPUT',
+            // Where the funds land. On a route through the omnibridge this is encoded
+            // inside the entry call; with no call to carry it, Relay is told directly.
+            recipient: request.recipient,
+            // Same rule as the omnibridge path below: Relay refunds on the ORIGIN
+            // chain, so a non-Ethereum origin cannot be refunded to an Ethereum
+            // fallback address and must name its own.
+            refundTo: nonEthereumOriginDirect ? request.fromAddress : request.fallbackAddress,
+            ...relayReferrerField(request),
+            ...(request.slippage === undefined
+                ? {}
+                : { slippageTolerance: slippageToBasisPoints(request.slippage) }),
+            ...(request.originVmType === 'svm' && request.solanaFeePayer !== undefined
+                ? { depositFeePayer: request.solanaFeePayer }
+                : {}),
+            ...(request.originVmType === 'bvm' && request.bitcoinPublicKey !== undefined
+                ? { additionalData: { userPublicKey: request.bitcoinPublicKey } }
+                : {}),
+            ...(request.relayAppFee &&
+                request.relayAppFee.basisPoints > 0n &&
+                request.relayAppFee.recipient
+                ? {
+                    appFees: [
+                        {
+                            recipient: request.relayAppFee.recipient,
+                            fee: request.relayAppFee.basisPoints.toString(),
+                        },
+                    ],
+                }
+                : {}),
+        };
+    }
+    if (toAmount <= 0n) {
+        return null;
+    }
+    // A NATIVE ENTRY (`wrapAndRelayTokens`) CARRIES VALUE, and Relay's solver
+    // attaches it: a dry quote with this exact call simulates it on the entry
+    // chain (see `providers.ts`'s `destinationCallCarriesNativeValue` for the
+    // measurement). Relay delivers the native coin itself, so no approval is
+    // prepended — the call's own `approvalTarget` is null for this shape.
+    const entryCall = {
+        to: destinationCall.to,
+        value: destinationCall.value.toString(),
+        data: destinationCall.data,
+    };
+    const needsApproval = destinationCall.approvalTarget !== null;
+    // grant an unbounded allowance, the standard executor pattern: Relay's
+    // Multicaller holds the bridged tokens only transiently during the call
+    // sequence, and an exact allowance would strand funds if the entry call ever
+    // pulls a balance rather than the fixed amount encoded in its calldata
+    const approvalCall = needsApproval
+        ? {
+            to: request.toTokenAddress,
+            value: '0',
+            data: encodeFunctionData({
+                abi: erc20Abi,
+                functionName: 'approve',
+                args: [destinationCall.approvalTarget, maxUint256],
+            }),
+        }
+        : null;
+    const txs = approvalCall ? [approvalCall, entryCall] : [entryCall];
+    const txsGasLimit = destinationCall.gasLimit + (needsApproval ? relayApprovalGasBuffer : 0n);
+    // The omnibridge has two entry points: Ethereum and Binance Smart Chain. The
+    // destination chain MUST track the entry chain the request targets, because
+    // `destinationCurrency` is the entry-chain token address — pairing a
+    // Binance-side token with a hardcoded Ethereum destination makes Relay reject
+    // the quote with "Invalid input or output currency" (that token does not exist
+    // on Ethereum). Defaults to Ethereum, preserving the original single-entry
+    // behavior when `toChainId` is omitted.
+    const destinationChainId = request.toChainId ?? Number(Chains.ETH);
+    const nonEthereumOrigin = isNonEthereumVirtualMachineOrigin(request);
+    // Relay always refunds a failed route on the ORIGIN chain. For an Ethereum
+    // Virtual Machine origin the user's Ethereum-side fallback address doubles as
+    // that origin refund target (unchanged behavior). For a non-Ethereum origin
+    // the fallback address is an Ethereum address Relay cannot refund to on the
+    // origin chain, so the refund must go to the user's own origin-chain address.
+    const refundTo = nonEthereumOrigin ? request.fromAddress : request.fallbackAddress;
+    // Relay's Solana fee sponsorship; only included for a Solana origin that names a payer.
+    const includeDepositFeePayer = request.originVmType === 'svm' && request.solanaFeePayer !== undefined;
+    // Relay's Bitcoin pay-to-script-hash public key; only for a Bitcoin origin that supplies one.
+    const includeBitcoinPublicKey = request.originVmType === 'bvm' && request.bitcoinPublicKey !== undefined;
+    return {
+        user: request.fromAddress,
+        originChainId: request.fromChainId,
+        originCurrency: request.fromTokenAddress,
+        destinationChainId,
+        destinationCurrency: request.toTokenAddress,
+        amount: toAmount.toString(),
+        tradeType: 'EXACT_OUTPUT',
+        // origin-chain refund target — Relay's only failure remedy for this route
+        refundTo,
+        ...relayReferrerField(request),
+        txs,
+        txsGasLimit: Number(txsGasLimit),
+        ...(request.slippage === undefined
+            ? {}
+            : { slippageTolerance: slippageToBasisPoints(request.slippage) }),
+        ...(includeDepositFeePayer ? { depositFeePayer: request.solanaFeePayer } : {}),
+        ...(includeBitcoinPublicKey
+            ? { additionalData: { userPublicKey: request.bitcoinPublicKey } }
+            : {}),
+        ...(request.relayAppFee && request.relayAppFee.basisPoints > 0n && request.relayAppFee.recipient
+            ? { appFees: [{ recipient: request.relayAppFee.recipient, fee: request.relayAppFee.basisPoints.toString() }] }
+            : {}),
+    };
+};
+const isHexString = (value) => typeof value === 'string' && value.startsWith('0x');
+/**
+ * Parses a quantity Relay may report as a hex string, a decimal string, or a
+ * number into a bigint.
+ *
+ * @returns the bigint value, or null when the input is not a parseable quantity
+ */
+const parseQuantity = (value) => {
+    if (typeof value === 'number' && Number.isInteger(value)) {
+        return BigInt(value);
+    }
+    if (typeof value !== 'string' || value === '') {
+        return null;
+    }
+    try {
+        return BigInt(value);
+    }
+    catch {
+        return null;
+    }
+};
+const asRecord = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return null;
+    }
+    return value;
+};
+/**
+ * Pulls the signable transaction out of a Relay step item.
+ *
+ * @returns the transaction data, or null when the item has no usable transaction
+ */
+const stepItemTransaction = (item) => {
+    const record = asRecord(item);
+    const data = asRecord(record?.data);
+    if (!data) {
+        return null;
+    }
+    if (!isHexString(data.to) || !isHexString(data.data)) {
+        return null;
+    }
+    return data;
+};
+/**
+ * Pulls a Solana instruction set out of a Relay deposit step item. A Solana
+ * deposit carries `data.instructions[]` plus the address-lookup-table addresses
+ * to compile a versioned transaction, and no `to`/`data` hex fields.
+ *
+ * @returns the instruction set, or null when the item is not a Solana deposit
+ */
+const stepItemSolanaInstructions = (item) => {
+    const data = asRecord(asRecord(item)?.data);
+    if (!data || !Array.isArray(data.instructions)) {
+        return null;
+    }
+    const instructions = data.instructions.filter((instruction) => {
+        const value = asRecord(instruction);
+        return (Array.isArray(value?.keys) &&
+            typeof value?.programId === 'string' &&
+            typeof value?.data === 'string');
+    });
+    if (instructions.length === 0) {
+        return null;
+    }
+    const lookupTables = Array.isArray(data.addressLookupTableAddresses)
+        ? data.addressLookupTableAddresses.filter((address) => typeof address === 'string')
+        : [];
+    return { instructions, addressLookupTableAddresses: lookupTables };
+};
+/**
+ * Pulls a Bitcoin partially-signed transaction out of a Relay deposit step
+ * item. Relay hex-encodes it (the "psbt\xff" magic, `70736274ff…`) and it is not
+ * `0x`-prefixed, so the Ethereum hex gate does not match it.
+ *
+ * @returns the partially-signed transaction, or null when the item is not a Bitcoin deposit
+ */
+const stepItemBitcoinPsbt = (item) => {
+    const data = asRecord(asRecord(item)?.data);
+    if (!data || typeof data.psbt !== 'string' || data.psbt === '') {
+        return null;
+    }
+    return { psbt: data.psbt };
+};
+/**
+ * Normalizes a typed-data type table, keeping only well-formed `{name, type}`
+ * fields. Shared by the Hyperliquid action and its authorization, which carry
+ * the same table shape under different keys.
+ *
+ * @returns the type table; empty when the payload carries none
+ */
+const typedDataTypes = (value) => {
+    const record = asRecord(value);
+    if (!record) {
+        return {};
+    }
+    const entries = Object.entries(record).flatMap(([name, fields]) => {
+        if (!Array.isArray(fields)) {
+            return [];
+        }
+        const parsed = fields.flatMap((field) => {
+            const candidate = asRecord(field);
+            return typeof candidate?.name === 'string' && typeof candidate?.type === 'string'
+                ? [{ name: candidate.name, type: candidate.type }]
+                : [];
+        });
+        return [[name, parsed]];
+    });
+    return Object.fromEntries(entries);
+};
+/**
+ * Pulls a Tron contract call out of a Relay deposit step item. Tron's wire shape
+ * nests snake_case fields under `parameter` and names the contract kind in
+ * `type`; its `data` is bare hex with no `0x` prefix, so the Ethereum hex gate
+ * never claims it.
+ *
+ * @returns the contract call, or null when the item is not a Tron deposit
+ */
+const stepItemTronContract = (item) => {
+    const data = asRecord(asRecord(item)?.data);
+    if (!data || typeof data.type !== 'string') {
+        return null;
+    }
+    const parameter = asRecord(data.parameter);
+    if (!parameter) {
+        return null;
+    }
+    const ownerAddress = parameter.owner_address;
+    const contractAddress = parameter.contract_address;
+    const callData = parameter.data;
+    // require every field we map, so a wire-shape change fails closed rather than
+    // producing a deposit with silently empty addresses
+    if (typeof ownerAddress !== 'string' ||
+        typeof contractAddress !== 'string' ||
+        typeof callData !== 'string') {
+        return null;
+    }
+    return {
+        contractType: data.type,
+        ownerAddress,
+        contractAddress,
+        // a call that sends no TRX omits the field rather than sending zero
+        callValue: parseQuantity(parameter.call_value) ?? 0n,
+        data: callData,
+    };
+};
+/**
+ * Pulls a TON message list out of a Relay deposit step item. TON wallets send a
+ * list of messages rather than one transaction, and each payload is a base64
+ * bag-of-cells rather than hex.
+ *
+ * @returns the message list, or null when the item is not a TON deposit
+ */
+const stepItemTonMessages = (item) => {
+    const data = asRecord(asRecord(item)?.data);
+    if (!data || !Array.isArray(data.messages)) {
+        return null;
+    }
+    const messages = data.messages.flatMap((entry) => {
+        const record = asRecord(entry);
+        if (!record || typeof record.to !== 'string' || typeof record.body !== 'string') {
+            return [];
+        }
+        const value = parseQuantity(record.value);
+        if (value === null) {
+            return [];
+        }
+        return [
+            {
+                to: record.to,
+                value,
+                body: record.body,
+                // mode 0 sends with no special flags, TON's own default
+                mode: typeof record.mode === 'number' ? record.mode : 0,
+                // absent means non-bouncing; only an explicit true bounces
+                bounce: record.bounce === true,
+                from: typeof record.from === 'string' ? record.from : null,
+            },
+        ];
+    });
+    if (messages.length === 0) {
+        return null;
+    }
+    return { messages };
+};
+/**
+ * Pulls the typed-data action out of a Relay Hyperliquid deposit step item.
+ * Nothing here is broadcast: the action is signed and posted to Hyperliquid's
+ * API, so there is no `to`, no calldata, and no gas for the Ethereum hex gate to
+ * match.
+ *
+ * @returns the action, or null when the item is not a Hyperliquid deposit
+ */
+const stepItemHyperliquidAction = (item) => {
+    const data = asRecord(asRecord(item)?.data);
+    if (!data || typeof data.eip712PrimaryType !== 'string') {
+        return null;
+    }
+    const action = asRecord(data.action);
+    if (!action || typeof action.type !== 'string') {
+        return null;
+    }
+    return {
+        action: { type: action.type, parameters: asRecord(action.parameters) ?? {} },
+        eip712Types: typedDataTypes(data.eip712Types),
+        eip712PrimaryType: data.eip712PrimaryType,
+        nonce: parseQuantity(data.nonce) ?? 0n,
+    };
+};
+/**
+ * Finds the authorization a Hyperliquid deposit must complete before its action
+ * can be submitted. It arrives as its own `signature` step ahead of the deposit,
+ * which the deposit scan skips because it carries no deposit shape — so it is
+ * collected separately and attached to the deposit, rather than lost.
+ *
+ * @param steps - every step on the quote
+ * @returns the authorization, or null when the quote carries none
+ */
+const stepAuthorization = (steps) => {
+    for (const step of steps) {
+        if (step.kind !== 'signature' || !Array.isArray(step.items)) {
+            continue;
+        }
+        for (const item of step.items) {
+            const data = asRecord(asRecord(item)?.data);
+            const sign = asRecord(data?.sign);
+            const post = asRecord(data?.post);
+            if (!sign || !post || typeof sign.primaryType !== 'string') {
+                continue;
+            }
+            if (typeof post.endpoint !== 'string' || typeof post.method !== 'string') {
+                continue;
+            }
+            return {
+                sign: {
+                    signatureKind: typeof sign.signatureKind === 'string' ? sign.signatureKind : '',
+                    domain: asRecord(sign.domain) ?? {},
+                    types: typedDataTypes(sign.types),
+                    value: asRecord(sign.value) ?? {},
+                    primaryType: sign.primaryType,
+                },
+                post: {
+                    endpoint: post.endpoint,
+                    method: post.method,
+                    body: asRecord(post.body) ?? {},
+                },
+            };
+        }
+    }
+    return null;
+};
+/**
+ * Recognizes the one deposit shape a Relay step item carries, trying the
+ * Ethereum transaction shape first (the only one gated on hex `to`/`data`), then
+ * each non-Ethereum shape in turn. Every shape is keyed on a field the others do
+ * not carry, so the recognizers are mutually exclusive and the order is a
+ * cheapest-check-first convenience rather than a correctness requirement — a
+ * property the tests pin, because a future overlap would silently mis-route a
+ * deposit to the wrong ecosystem's signer.
+ *
+ * @returns the discriminated deposit, or null when the item carries none
+ */
+const stepItemDeposit = (item) => {
+    const transaction = stepItemTransaction(item);
+    if (transaction) {
+        return { kind: 'evm', transaction };
+    }
+    const solana = stepItemSolanaInstructions(item);
+    if (solana) {
+        return { kind: 'svm', ...solana };
+    }
+    const bitcoin = stepItemBitcoinPsbt(item);
+    if (bitcoin) {
+        return { kind: 'bvm', psbt: bitcoin.psbt };
+    }
+    const tron = stepItemTronContract(item);
+    if (tron) {
+        return { kind: 'tvm', contract: tron };
+    }
+    const ton = stepItemTonMessages(item);
+    if (ton) {
+        return { kind: 'tonvm', messages: ton.messages };
+    }
+    const hyperliquid = stepItemHyperliquidAction(item);
+    if (hyperliquid) {
+        return { kind: 'hypevm', action: hyperliquid };
+    }
+    return null;
+};
+/**
+ * Extracts the ERC20 spender from a Relay `approve` step so our own approval
+ * machinery can grant it. The origin token, not Relay, decides the spender, so
+ * we decode it from the ready-made approval calldata rather than guessing.
+ *
+ * @returns the spender address, or null when the step is absent or undecodable
+ */
+const approvalSpender = (steps) => {
+    const approveStep = steps.find((step) => step.id === 'approve');
+    if (!approveStep) {
+        return null;
+    }
+    const items = approveStep.items;
+    if (!Array.isArray(items)) {
+        return null;
+    }
+    for (const item of items) {
+        const transaction = stepItemTransaction(item);
+        if (!transaction) {
+            continue;
+        }
+        try {
+            const decoded = decodeFunctionData({ abi: erc20Abi, data: transaction.data });
+            if (decoded.functionName === 'approve') {
+                return decoded.args[0];
+            }
+        }
+        catch {
+            // not an approve call we recognize; keep scanning
+        }
+    }
+    return null;
+};
+/**
+ * Finds the deposit the user signs after any approval — the first
+ * deposit-bearing item on a step that is not the `approve` step — and reports
+ * which source ecosystem's shape it carries.
+ *
+ * @returns the step and its discriminated deposit, or null when none is present
+ */
+const depositStep = (steps) => {
+    for (const step of steps) {
+        if (step.id === 'approve') {
+            continue;
+        }
+        const items = step.items;
+        if (!Array.isArray(items)) {
+            continue;
+        }
+        for (const item of items) {
+            const deposit = stepItemDeposit(item);
+            if (deposit) {
+                return { step, deposit };
+            }
+        }
+    }
+    return null;
+};
+/**
+ * Maps a discriminated Relay deposit onto the shared `OriginDeposit` union.
+ * Ethereum reads its chain id from the deposit transaction; the non-Ethereum
+ * variants have no chain id on the deposit payload, so they read it from the
+ * quote's origin currency (`details.currencyIn.currency.chainId`).
+ *
+ * The non-Ethereum variants are matched by an EXHAUSTIVE switch rather than a
+ * trailing fallback: an unhandled variant must be a compile error, because
+ * quietly treating one ecosystem's deposit as another's would hand a payload to
+ * the wrong signer.
+ *
+ * @param found - the deposit and the step it was found on
+ * @param currencyIn - the quote's `details.currencyIn`, the only source of an
+ *   origin chain id for a non-Ethereum deposit
+ * @param steps - every step on the quote, needed to collect the Hyperliquid
+ *   authorization that arrives as its own step
+ * @returns the origin deposit, or null when a required field is unparseable
+ */
+const relayOriginDeposit = (found, currencyIn, steps) => {
+    const { step, deposit } = found;
+    if (deposit.kind === 'evm') {
+        const chainId = parseQuantity(deposit.transaction.chainId);
+        if (chainId === null) {
+            return null;
+        }
+        return {
+            ecosystem: 'evm',
+            to: deposit.transaction.to,
+            data: deposit.transaction.data,
+            value: parseQuantity(deposit.transaction.value) ?? 0n,
+            chainId: Number(chainId),
+            gasLimit: parseQuantity(deposit.transaction.gas),
+        };
+    }
+    const originCurrency = asRecord(currencyIn.currency);
+    if (typeof originCurrency?.chainId !== 'number') {
+        return null;
+    }
+    const chainId = originCurrency.chainId;
+    switch (deposit.kind) {
+        case 'svm':
+            return {
+                ecosystem: 'svm',
+                form: 'instructions',
+                instructions: deposit.instructions,
+                addressLookupTableAddresses: deposit.addressLookupTableAddresses,
+                chainId,
+            };
+        case 'tvm':
+            return { ecosystem: 'tvm', ...deposit.contract, chainId };
+        case 'tonvm':
+            return { ecosystem: 'tonvm', messages: deposit.messages, chainId };
+        case 'hypevm':
+            return {
+                ecosystem: 'hypevm',
+                ...deposit.action,
+                authorization: stepAuthorization(steps),
+                chainId,
+            };
+        case 'bvm': {
+            const amountSats = parseQuantity(currencyIn.amount);
+            if (amountSats === null) {
+                return null;
+            }
+            return {
+                ecosystem: 'bvm',
+                psbt: deposit.psbt,
+                depositAddress: typeof step.depositAddress === 'string' ? step.depositAddress : '',
+                amountSats,
+                chainId,
+            };
+        }
+    }
+};
+/**
+ * Normalizes a Relay `/quote/v2` response into the shared consolidated quote
+ * shape. The origin approval Relay returns as its own step is folded back into
+ * `approvalAddress` so the executor raises it through the same path as LI.FI;
+ * the deposit step becomes the single `originDeposit`.
+ *
+ * @returns the normalized quote, or null when the payload shape is unexpected
+ */
+export const parseRelayQuote = (payload) => {
+    const quote = asRecord(payload);
+    if (!quote) {
+        return null;
+    }
+    const steps = Array.isArray(quote.steps)
+        ? quote.steps.filter((step) => asRecord(step) !== null)
+        : null;
+    if (!steps || steps.length === 0) {
+        return null;
+    }
+    const details = asRecord(quote.details);
+    const currencyIn = asRecord(details?.currencyIn);
+    if (!currencyIn) {
+        return null;
+    }
+    const fromAmount = parseQuantity(currencyIn.amount);
+    if (fromAmount === null) {
+        return null;
+    }
+    if (typeof details?.timeEstimate !== 'number') {
+        return null;
+    }
+    const found = depositStep(steps);
+    if (!found) {
+        return null;
+    }
+    // the identifier lives on the steps in the verified response shape; fall back
+    // through a top-level field so a future nesting change does not reject quotes
+    const requestId = typeof quote.requestId === 'string'
+        ? quote.requestId
+        : steps.map((step) => step.requestId).find((id) => typeof id === 'string');
+    if (typeof requestId !== 'string') {
+        return null;
+    }
+    const originDeposit = relayOriginDeposit(found, currencyIn, steps);
+    if (originDeposit === null) {
+        return null;
+    }
+    const spender = approvalSpender(steps);
+    return {
+        provider: 'relay',
+        quoteId: requestId,
+        tool: 'relay',
+        toolName: 'Relay',
+        fromAmount,
+        // WHAT THE ROUTE DELIVERS, WHEN ONLY RELAY KNOWS. An omnibridge route names
+        // its own delivered amount in the request and asks for an exact output, so
+        // this repeats what the caller already said. A direct route asks for an
+        // exact input, and the delivered amount exists nowhere until this answer.
+        // Undefined rather than zero when the field is missing: zero is a real
+        // quantity and would read as "this route delivers nothing".
+        ...(() => {
+            const out = parseQuantity(asRecord(details?.currencyOut)?.amount);
+            return out === null ? {} : { toAmount: out };
+        })(),
+        fromAmountUsd: typeof currencyIn.amountUsd === 'string' ? currencyIn.amountUsd : null,
+        // The delivered side valued by the same answer that valued the paid side —
+        // see `ConsolidatedQuote.toAmountUsd` for why it may not come from anywhere
+        // else. Omitted rather than nulled when Relay leaves it out.
+        ...(() => {
+            const outUsd = asRecord(details?.currencyOut)?.amountUsd;
+            return typeof outUsd === 'string' ? { toAmountUsd: outUsd } : {};
+        })(),
+        // a native origin token is pulled with no allowance, so no spender applies
+        approvalAddress: spender !== null && spender !== zeroAddress ? spender : null,
+        executionDurationSeconds: details.timeEstimate,
+        // Relay's `steps` are operational (approve + deposit); the per-leg route
+        // lives in `details.route`, so the whole quote is normalized, not `steps`.
+        steps: normalizeRelaySteps(quote),
+        originDeposit,
+        fees: relayQuoteFees(payload),
+    };
+};
+/**
+ * Builds the requests-lookup address for a Relay route BY ITS QUOTE
+ * IDENTIFIER.
+ *
+ * IT USED TO ASK BY ORIGIN TRANSACTION HASH, AND THAT RETURNED OTHER PEOPLE'S
+ * TRANSFERS. `/requests/v3` does not accept a `hash` filter: it ignores the
+ * parameter entirely and answers with the twenty most recent requests ACROSS
+ * ALL USERS. Measured, with two different origin hashes a minute apart:
+ *
+ *     ?hash=0x447149ed…  -> 20 requests, first is 8453:0x7d7c3de2… -> 4663:…
+ *     ?hash=0xa650d2d7…  -> the SAME 20 requests, same first entry
+ *
+ * `parseRelayStatus` reads `requests[0]`, so both of this account's transfers
+ * were updated from a stranger's — they took the same entry-chain transaction
+ * hash, and neither was their own. A transfer was reported finished because
+ * somebody else's had finished.
+ *
+ * `id` is the filter v3 actually honours. The same lookup by quote identifier
+ * returns exactly ONE request, and its `inTxs` name the origin transaction the
+ * reader really signed. The caller should assert that correspondence rather
+ * than trust it — see `checkConsolidatedRecord`.
+ */
+export const relayStatusUrl = ({ quoteId }) => {
+    const url = new URL(relayRequestsUrl);
+    url.searchParams.set('id', quoteId);
+    return url.toString();
+};
+/**
+ * Relay's request lifecycle states. Terminal states are `success` (the
+ * destination call filled), `failure`, and `refund` (made whole on the origin
+ * chain). Every other state is still in flight.
+ */
+const relayInFlightStatuses = ['waiting', 'depositing', 'pending', 'submitted', 'delayed'];
+const isEthereumTransactionHash = (value) => typeof value === 'string' && /^0x[0-9a-fA-F]{64}$/.test(value);
+/**
+ * Finds the destination-chain transaction hash among a Relay request's output
+ * transactions — the hash that gates the handover to the omnibridge indexer.
+ * The destination chain is the omnibridge entry chain the route targeted
+ * (Ethereum or Binance Smart Chain), so it is supplied by the caller rather
+ * than assumed.
+ *
+ * @param request - a Relay request record
+ * @param destinationChainId - the omnibridge entry chain the route targeted
+ * @returns the destination-chain transaction hash, or null when none recorded
+ */
+const outputTransactions = (request) => {
+    // RELAY NESTS THESE UNDER `data`. An earlier version read `request.outTxs`,
+    // which no response has ever carried: measured 2026-09-01 across a hundred
+    // live records, `request.outTxs` was present on ZERO and `request.data.outTxs`
+    // on every one. So this returned null for every completed route, and the
+    // interface reported DONE while linking nothing. The unit tests missed it
+    // because they were written to the same wrong shape as the parser.
+    const data = asRecord(request.data);
+    if (Array.isArray(data?.outTxs)) {
+        return data.outTxs;
+    }
+    // Kept as a fallback rather than deleted: it costs one array check, and a
+    // response that does flatten them still reads correctly.
+    if (Array.isArray(request.outTxs)) {
+        return request.outTxs;
+    }
+    return [];
+};
+/**
+ * The transaction hash on one output entry. `/requests/v2` names the field
+ * `hash` and `/requests/v3` names it `txHash`; both appear in the wild, so both
+ * are read rather than choosing by endpoint version.
+ */
+const outputHashOf = (entry) => {
+    const record = asRecord(entry);
+    if (isEthereumTransactionHash(record?.txHash)) {
+        return record.txHash;
+    }
+    if (isEthereumTransactionHash(record?.hash)) {
+        return record.hash;
+    }
+    return null;
+};
+const destinationOutputHash = (request, destinationChainId) => {
+    for (const entry of outputTransactions(request)) {
+        if (Number(asRecord(entry)?.chainId) !== destinationChainId) {
+            continue;
+        }
+        const hash = outputHashOf(entry);
+        if (hash) {
+            return hash;
+        }
+    }
+    const txHashes = request.txHashes;
+    if (Array.isArray(txHashes)) {
+        const hash = txHashes.find((entry) => isEthereumTransactionHash(entry));
+        if (isEthereumTransactionHash(hash)) {
+            return hash;
+        }
+    }
+    return null;
+};
+/**
+ * Maps a Relay request status onto the provider-agnostic consolidated status.
+ * `success` reports `DONE`/`COMPLETED` because for this route the destination
+ * fill IS our omnibridge entry call; `refund` reports `DONE`/`REFUNDED` because
+ * the user was made whole on the origin chain. Relay never strands funds on
+ * Ethereum, so the partial/stranded status LI.FI can return has no analogue.
+ *
+ * @param payload - a `/requests/v2?hash=` response body
+ * @param options.destinationChainId - the omnibridge entry chain the route
+ *   targeted (Ethereum or Binance Smart Chain); defaults to Ethereum,
+ *   preserving the original single-entry behavior
+ * @returns the normalized status, or null when no matching request is present
+ */
+export const parseRelayStatus = (payload, { destinationChainId = Number(Chains.ETH) } = {}) => {
+    const data = asRecord(payload);
+    if (!data) {
+        return null;
+    }
+    const requests = data.requests;
+    if (!Array.isArray(requests) || requests.length === 0) {
+        return { status: 'NOT_FOUND', substatus: null, receivingTxHash: null };
+    }
+    const request = asRecord(requests[0]);
+    if (!request) {
+        return null;
+    }
+    const status = request.status;
+    if (typeof status !== 'string') {
+        return null;
+    }
+    const receivingTxHash = destinationOutputHash(request, destinationChainId);
+    if (status === 'success') {
+        return { status: 'DONE', substatus: 'COMPLETED', receivingTxHash };
+    }
+    if (status === 'refund') {
+        return { status: 'DONE', substatus: 'REFUNDED', receivingTxHash: null };
+    }
+    if (status === 'failure') {
+        return { status: 'FAILED', substatus: status, receivingTxHash: null };
+    }
+    if (relayInFlightStatuses.some((inFlight) => inFlight === status)) {
+        return { status: 'PENDING', substatus: status, receivingTxHash };
+    }
+    // an unrecognized status is treated as still indexing rather than terminal
+    return { status: 'NOT_FOUND', substatus: status, receivingTxHash };
+};