@gibs/bridge-sdk 1.12.0 → 1.13.0

package/dist/near-intents-conformance.js

@@ -0,0 +1,329 @@
+/**
+ * Does the live service still answer in the shape this repository parses?
+ *
+ * THIS EXISTS BECAUSE NEAR INTENTS HAS NO TEST NETWORK. The vendor states it
+ * four times in its own current material, most plainly in its list of common
+ * questions: "There is no testnet deployment and no plans for one. We
+ * recommend testing on NEAR mainnet using separate dev/test NEAR accounts."
+ * So there is no safe copy of the service to check an integration against, and
+ * the only honest substitute is a priced request against production that
+ * reserves nothing — a dry quote. See `docs/near-intents-capability-survey.md`.
+ *
+ * WHAT THIS CLOSES THAT THE FIXTURES CANNOT. `near-intents.test.ts` runs
+ * against real captures taken on 2026-09-17. A capture is a photograph: it
+ * proves the parser reads what the service sent that day, and it goes on
+ * proving that forever, including after the service stops sending it. Every
+ * parser here is tolerant by design — it returns null rather than throwing —
+ * so a field that changes type does not break a test, it removes a provider
+ * from the interface with no message anywhere. `amountOut` arriving as a
+ * number instead of a string is the whole failure: 37 green tests, and NEAR
+ * Intents silently never bids again.
+ *
+ * So these functions name every field the parsers actually depend on and
+ * report what is missing, rather than returning a normalized value. Handed a
+ * live response they answer "has production drifted away from the captures".
+ * Handed a capture they answer "is this capture still a fair stand-in".
+ *
+ * They are deliberately NOT parsers. A parser answers "can I use this"; these
+ * answer "is this what I was written against", which is a different question
+ * and needs the failures enumerated rather than collapsed into a null.
+ */
+import { chainIdByNearIntentsChain } from './near-intents.js';
+/** Which parser depends on a field, so a finding says what will break. */
+const describe = (value) => {
+    if (value === undefined) {
+        return 'absent';
+    }
+    if (value === null) {
+        return 'null';
+    }
+    if (Array.isArray(value)) {
+        return `array of ${value.length}`;
+    }
+    return typeof value;
+};
+const asRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : null;
+/**
+ * Checks one field and returns a finding when it is not the required type.
+ *
+ * A base-unit amount must be a NON-EMPTY string, because that is what
+ * `parseAmount` in `near-intents.ts` requires: it refuses an empty string and
+ * refuses a number, so either one silently collapses the whole quote to null.
+ */
+const requireField = ({ container, key, path, kind, }) => {
+    const value = container[key];
+    if (kind === 'amount') {
+        if (typeof value === 'string' && value !== '') {
+            return null;
+        }
+        return { path, expected: 'a non-empty string of base units', found: describe(value) };
+    }
+    if (kind === 'number') {
+        return typeof value === 'number'
+            ? null
+            : { path, expected: 'a number', found: describe(value) };
+    }
+    if (kind === 'array') {
+        return Array.isArray(value) ? null : { path, expected: 'an array', found: describe(value) };
+    }
+    return typeof value === 'string' && value !== ''
+        ? null
+        : { path, expected: 'a non-empty string', found: describe(value) };
+};
+const compact = (findings) => findings.filter((finding) => finding !== null);
+/**
+ * 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 const nearIntentsQuoteShapeFindings = (payload, { expectDepositAddress }) => {
+    const body = asRecord(payload);
+    if (!body) {
+        return [{ path: '', expected: 'an object', found: describe(payload) }];
+    }
+    const quote = asRecord(body.quote);
+    if (!quote) {
+        return [{ path: 'quote', expected: 'an object', found: describe(body.quote) }];
+    }
+    const findings = compact([
+        requireField({ container: quote, key: 'amountIn', path: 'quote.amountIn', kind: 'amount' }),
+        requireField({ container: quote, key: 'amountOut', path: 'quote.amountOut', kind: 'amount' }),
+        requireField({
+            container: quote,
+            key: 'minAmountOut',
+            path: 'quote.minAmountOut',
+            kind: 'amount',
+        }),
+        requireField({
+            container: quote,
+            key: 'withdrawFee',
+            path: 'quote.withdrawFee',
+            kind: 'amount',
+        }),
+        requireField({
+            container: quote,
+            key: 'timeEstimate',
+            path: 'quote.timeEstimate',
+            kind: 'number',
+        }),
+        requireField({
+            container: quote,
+            key: 'amountInUsd',
+            path: 'quote.amountInUsd',
+            kind: 'string',
+        }),
+        requireField({
+            container: quote,
+            key: 'amountOutUsd',
+            path: 'quote.amountOutUsd',
+            kind: 'string',
+        }),
+        expectDepositAddress
+            ? requireField({
+                container: quote,
+                key: 'depositAddress',
+                path: 'quote.depositAddress',
+                kind: 'string',
+            })
+            : null,
+    ]);
+    return [...findings, ...nearIntentsAppFeeFindings(body.quoteRequest)];
+};
+/**
+ * Checks the echoed request for the surcharge a key-less caller is charged.
+ *
+ * THE SERVICE INSERTS THIS, NOT US. Nothing in this repository asks for an
+ * `appFees` entry, and the fee parser only finds the twenty-five-basis-point
+ * charge because the service writes it into the request it echoes back. If it
+ * ever stops echoing it, the charge does not stop — it disappears from the
+ * fee rows and the reader is shown a route that costs a quarter of a percent
+ * more than the interface says. That is a silent understatement of cost, so it
+ * is a finding rather than a tolerated absence.
+ */
+const nearIntentsAppFeeFindings = (quoteRequest) => {
+    const request = asRecord(quoteRequest);
+    if (!request) {
+        return [
+            { path: 'quoteRequest', expected: 'an object', found: describe(quoteRequest) },
+        ];
+    }
+    const appFees = request.appFees;
+    if (!Array.isArray(appFees)) {
+        return [{ path: 'quoteRequest.appFees', expected: 'an array', found: describe(appFees) }];
+    }
+    if (appFees.length === 0) {
+        return [
+            {
+                path: 'quoteRequest.appFees',
+                expected: 'at least one entry, the surcharge the service adds to a key-less request',
+                found: 'array of 0',
+            },
+        ];
+    }
+    return compact(appFees.map((entry, index) => {
+        const record = asRecord(entry);
+        if (!record) {
+            return {
+                path: `quoteRequest.appFees[${index}]`,
+                expected: 'an object',
+                found: describe(entry),
+            };
+        }
+        return requireField({
+            container: record,
+            key: 'fee',
+            path: `quoteRequest.appFees[${index}].fee`,
+            kind: 'number',
+        });
+    }));
+};
+/**
+ * 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 const nearIntentsTokenListShapeFindings = (payload, { requiredChains }) => {
+    if (!Array.isArray(payload)) {
+        return [{ path: '', expected: 'an array of assets', found: describe(payload) }];
+    }
+    if (payload.length === 0) {
+        return [{ path: '', expected: 'at least one asset', found: 'array of 0' }];
+    }
+    const findings = [];
+    const chainsSeen = new Set();
+    payload.forEach((entry, index) => {
+        const record = asRecord(entry);
+        if (!record) {
+            findings.push({ path: `[${index}]`, expected: 'an object', found: describe(entry) });
+            return;
+        }
+        const blockchain = record.blockchain;
+        if (typeof blockchain === 'string') {
+            chainsSeen.add(blockchain);
+        }
+        findings.push(...compact([
+            requireField({
+                container: record,
+                key: 'assetId',
+                path: `[${index}].assetId`,
+                kind: 'string',
+            }),
+            requireField({
+                container: record,
+                key: 'blockchain',
+                path: `[${index}].blockchain`,
+                kind: 'string',
+            }),
+            requireField({ container: record, key: 'symbol', path: `[${index}].symbol`, kind: 'string' }),
+            requireField({
+                container: record,
+                key: 'decimals',
+                path: `[${index}].decimals`,
+                kind: 'number',
+            }),
+        ]));
+    });
+    for (const chain of requiredChains) {
+        if (chainsSeen.has(chain)) {
+            continue;
+        }
+        findings.push({
+            path: `chain "${chain}"`,
+            expected: 'present in the asset list, because chainIdByNearIntentsChain maps it',
+            found: 'absent — the service renamed or dropped it',
+        });
+    }
+    return findings;
+};
+/**
+ * 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 const nearIntentsMappedChainNames = () => [
+    ...chainIdByNearIntentsChain.keys(),
+];
+/**
+ * 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 const nearIntentsStatusShapeFindings = (payload) => {
+    const body = asRecord(payload);
+    if (!body) {
+        return [{ path: '', expected: 'an object', found: describe(payload) }];
+    }
+    const findings = compact([
+        requireField({ container: body, key: 'status', path: 'status', kind: 'string' }),
+    ]);
+    const swapDetails = asRecord(body.swapDetails);
+    if (!swapDetails) {
+        return [
+            ...findings,
+            { path: 'swapDetails', expected: 'an object', found: describe(body.swapDetails) },
+        ];
+    }
+    return [
+        ...findings,
+        ...compact([
+            requireField({
+                container: swapDetails,
+                key: 'destinationChainTxHashes',
+                path: 'swapDetails.destinationChainTxHashes',
+                kind: 'array',
+            }),
+        ]),
+    ];
+};
+/**
+ * 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 const nearIntentsRefusalShapeFindings = (payload) => {
+    const body = asRecord(payload);
+    if (!body) {
+        return [{ path: '', expected: 'an object', found: describe(payload) }];
+    }
+    return compact([
+        requireField({ container: body, key: 'message', path: 'message', kind: 'string' }),
+    ]);
+};

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

@@ -0,0 +1,47 @@
+import type { DeferredCrossing, RouteCandidate } from './routing/candidate.js';
+import type { RouteData } from './routing/route-data.js';
+/**
+ * Builds the two-signature route for a candidate whose aggregator cannot
+ * execute the omnibridge entry call.
+ *
+ * The result has exactly two sections, and the order carries the meaning:
+ *
+ *   1. The aggregator's leg, signed NOW. It ends with the anchor token sitting
+ *      in the reader's own wallet on the entry chain.
+ *   2. The omnibridge crossing, marked `deferred`, signed LATER by the reader.
+ *
+ * COSTS ARE SPLIT BETWEEN THE SECTIONS RATHER THAN POOLED, because a reader
+ * deciding whether to accept a second signature needs to know what each half
+ * costs. The first section's spread is the difference between the aggregator's
+ * own paid and delivered figures — both from the one answer that priced them,
+ * never from two feeds. The second section's cost is the omnibridge crossing
+ * fee, computed from the known on-chain rate.
+ *
+ * THE DELIVERED FIGURE IS AN ESTIMATE AND THE INTERFACE KNOWS IT. A route whose
+ * last section is deferred has not been quoted end to end, so
+ * `outputAmountIsUnsettled` blanks the received-amount field on the reader's
+ * behalf. The figure is still carried — the conversion route sets its estimate
+ * the same way — so the route can be ranked and compared.
+ *
+ * @param candidate - the route candidate, which must carry a `deferredCrossing`
+ * @returns the two-section route, or null when the candidate names no deferred
+ *   crossing or no omnibridge provider to perform it
+ */
+export declare const buildNearIntentsTwoStepRouteData: (candidate: RouteCandidate) => RouteData | null;
+/**
+ * Describes the anchor a two-signature route leaves the reader holding.
+ *
+ * A small constructor rather than an inline object literal at the call site,
+ * so the three fields are named and documented in one place and a caller
+ * cannot quietly pair one aggregator's amount with another's valuation.
+ *
+ * @param options.anchorToken - the entry-chain token the aggregator delivers
+ * @param options.anchorAmount - how much of it lands, in its base units
+ * @param options.anchorUsdValue - the AGGREGATOR'S own valuation of that landing
+ * @returns the deferred-crossing record, or null when no amount is known
+ */
+export declare const describeDeferredCrossing: ({ anchorToken, anchorAmount, anchorUsdValue, }: {
+    anchorToken: DeferredCrossing["anchorToken"] | null;
+    anchorAmount: bigint | null | undefined;
+    anchorUsdValue: string | null | undefined;
+}) => DeferredCrossing | null;

package/dist/near-intents-route.js

@@ -0,0 +1,265 @@
+import * as imageLinks from './image-links.js';
+import { BRIDGE_SETTLEMENT_ETA_MINUTES, providerDisplayName, pulsechainChainId, subtractUsdValues, } from './routing/producers.js';
+import { providerById } from './providers.js';
+import { usdValueOfAmount } from './routing/usd-value.js';
+import { chainDisplayName } from './chain-names.js';
+/**
+ * The route shape for an aggregator that cannot execute on the chain it
+ * delivers to.
+ *
+ * WHY THIS EXISTS AT ALL. Every other consolidated route in this repository is
+ * ONE signature: the aggregator carries the reader's funds to an omnibridge
+ * entry chain and its executor performs the entry call on arrival, so the
+ * crossing into PulseChain happens inside the same transaction the reader
+ * already signed. NEAR Intents cannot do that — it delivers tokens to an
+ * address and runs nothing — and no arrangement of recipients works around it,
+ * because every omnibridge entry point learns who the reader is from a data
+ * field and a plain token transfer has none. See the head of `near-intents.ts`.
+ *
+ * So the crossing becomes TWO signatures, and the honest thing is to draw it
+ * that way. The aggregator lands the anchor token in the reader's OWN wallet on
+ * the entry chain; the reader then signs the ordinary omnibridge call
+ * themselves. The interface already renders exactly this shape — a section
+ * marked `deferred` draws "You sign this later" on the route itself rather than
+ * hiding the fact in a tooltip — so nothing new had to be invented to show it.
+ *
+ * WHAT THIS MUST NEVER DO is present the second signature as optional, or let
+ * the route claim a delivered amount as though it were settled. The reader is
+ * mid-journey until they sign again, and a route that implies otherwise is
+ * selling a single-signature experience it does not deliver.
+ */
+/**
+ * Turns a token into the display node the route strip draws, resolving its logo
+ * here rather than in the view.
+ *
+ * Pre-resolved deliberately: a view-layer image fallback reaches only the nodes
+ * a builder left unset, so a builder that sets the field and a builder that
+ * does not produce different pictures for the same token.
+ *
+ * The chain badge goes through `networkOrPseudo`, not `network` — a deposit-
+ * address origin (Zcash) carries a local, invented chain id the numeric
+ * endpoint 404s on. See that helper's own note for why this lives in
+ * `image-links.ts` rather than the richer client-side resolver.
+ */
+const tokenNode = (token, chainId) => ({
+    symbol: token.symbol,
+    address: token.address,
+    chainId,
+    decimals: token.decimals,
+    // `tokenImageOrChainFallback`, NOT `image` — the ANCHOR node this call also
+    // draws can reach here before its exact address is known (the deferred
+    // crossing has not settled yet), and `image` either throws on an address it
+    // cannot checksum or draws nothing at all. See that helper's own note.
+    logoUri: imageLinks.tokenImageOrChainFallback(token),
+    chainLogoUri: imageLinks.networkOrPseudo(chainId),
+});
+/**
+ * Parses one of the aggregator's own dollar figures.
+ *
+ * They arrive as decimal strings. A figure that will not parse becomes null
+ * rather than zero, because zero is a real value that reads as "this leg is
+ * free" — which is the one thing a cost figure must never say by accident.
+ */
+const usdNumber = (value) => {
+    if (typeof value !== 'string' || value === '') {
+        return null;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+};
+/**
+ * Builds the two-signature route for a candidate whose aggregator cannot
+ * execute the omnibridge entry call.
+ *
+ * The result has exactly two sections, and the order carries the meaning:
+ *
+ *   1. The aggregator's leg, signed NOW. It ends with the anchor token sitting
+ *      in the reader's own wallet on the entry chain.
+ *   2. The omnibridge crossing, marked `deferred`, signed LATER by the reader.
+ *
+ * COSTS ARE SPLIT BETWEEN THE SECTIONS RATHER THAN POOLED, because a reader
+ * deciding whether to accept a second signature needs to know what each half
+ * costs. The first section's spread is the difference between the aggregator's
+ * own paid and delivered figures — both from the one answer that priced them,
+ * never from two feeds. The second section's cost is the omnibridge crossing
+ * fee, computed from the known on-chain rate.
+ *
+ * THE DELIVERED FIGURE IS AN ESTIMATE AND THE INTERFACE KNOWS IT. A route whose
+ * last section is deferred has not been quoted end to end, so
+ * `outputAmountIsUnsettled` blanks the received-amount field on the reader's
+ * behalf. The figure is still carried — the conversion route sets its estimate
+ * the same way — so the route can be ranked and compared.
+ *
+ * @param candidate - the route candidate, which must carry a `deferredCrossing`
+ * @returns the two-section route, or null when the candidate names no deferred
+ *   crossing or no omnibridge provider to perform it
+ */
+export const buildNearIntentsTwoStepRouteData = (candidate) => {
+    const deferredCrossing = candidate.deferredCrossing;
+    if (!deferredCrossing) {
+        return null;
+    }
+    // No omnibridge leg means there is no second signature, which means this is
+    // not the shape being built. A route the aggregator carries end to end is an
+    // ordinary one-signature route and belongs to `buildCandidateRouteData`.
+    const omnibridgeProviderKey = candidate.omnibridgeProvider;
+    if (omnibridgeProviderKey === null) {
+        return null;
+    }
+    const { originToken, destinationToken } = candidate;
+    const { anchorToken, anchorAmount, anchorUsdValue } = deferredCrossing;
+    const originNode = tokenNode(originToken, originToken.chainId);
+    const anchorNode = tokenNode(anchorToken, candidate.entryChainId);
+    const destinationNode = tokenNode(destinationToken, pulsechainChainId);
+    const paidUsd = usdNumber(candidate.quote.fromAmountUsd);
+    const landedUsd = usdNumber(anchorUsdValue);
+    // The aggregator's spread on its own leg: what the reader paid, less what the
+    // aggregator says arrives. Both figures come from the same answer, so the
+    // difference is the route and nothing else.
+    const aggregatorFeeUsd = subtractUsdValues(paidUsd, landedUsd);
+    const crossingFeeUsd = usdValueOfAmount({
+        balance: candidate.omnibridgeFeeAmount,
+        decimals: destinationToken.decimals,
+        price: candidate.destinationUsdPrice,
+    });
+    const etaSeconds = candidate.quote.executionDurationSeconds > 0 ? candidate.quote.executionDurationSeconds : null;
+    const etaMinutes = candidate.quote.executionDurationSeconds > 0
+        ? Math.ceil(candidate.quote.executionDurationSeconds / 60)
+        : null;
+    const aggregatorHop = {
+        // THIS HOP IS THE AGGREGATOR, NOT THE OMNIBRIDGE — `providerDisplayName`
+        // (used for the crossing hop below) is keyed only on `Providers.PULSECHAIN`
+        // / `Providers.TOKENSEX` and falls back to the generic "Omnibridge" for
+        // anything else. Run through it here, `candidate.quote.provider` (a
+        // `ProviderId` — 'lifi' | 'relay' | 'near-intents') had no entry, so a
+        // NEAR Intents two-step route named its first leg "Omnibridge" — the
+        // bridge, not the aggregator that actually carried it. `providerById` is
+        // total over `ProviderId` and throws on an unregistered one rather than
+        // silently naming a different provider.
+        providerName: providerById(candidate.quote.provider).label,
+        providerKey: candidate.quote.provider,
+        title: `Send to ${chainDisplayName(candidate.entryChainId)}`,
+        conversion: `→ ${anchorToken.symbol}`,
+        fromToken: originNode,
+        toToken: anchorNode,
+        feeUsdValue: aggregatorFeeUsd,
+        // The reader's own signature starts this leg; nothing runs inside it.
+        automatic: false,
+    };
+    const aggregatorSection = {
+        id: `${candidate.id}-signature-1`,
+        // Named for where the funds END UP, and pointedly NOT "Bridge to
+        // PulseChain": this signature does not reach PulseChain and a label that
+        // said so would be the single-signature claim this route exists to avoid.
+        label: `Send to ${chainDisplayName(candidate.entryChainId)}`,
+        providerKey: candidate.quote.provider,
+        tokenFlow: [originNode, anchorNode],
+        // WHAT THE READER IS LEFT HOLDING between the two signatures, in their own
+        // wallet on the entry chain. This is the step's whole point.
+        landing: {
+            amount: anchorAmount,
+            decimals: anchorToken.decimals,
+            symbol: anchorToken.symbol,
+            usdValue: landedUsd,
+        },
+        feeUsdValue: aggregatorFeeUsd,
+        fees: candidate.quote.fees,
+        etaMinutes,
+        etaSeconds,
+        hops: [aggregatorHop],
+    };
+    const crossingHop = {
+        providerName: providerDisplayName(omnibridgeProviderKey),
+        providerKey: omnibridgeProviderKey,
+        title: `Bridge to ${chainDisplayName(pulsechainChainId)}`,
+        conversion: `→ ${destinationToken.symbol}`,
+        fromToken: anchorNode,
+        toToken: destinationNode,
+        feeUsdValue: crossingFeeUsd,
+        // NOT automatic, and this is the difference the whole route turns on. On a
+        // one-signature route the aggregator's executor makes this call; here the
+        // reader does, by hand, after the anchor lands.
+        automatic: false,
+    };
+    const crossingSection = {
+        id: `${candidate.id}-signature-2`,
+        label: `Bridge to ${chainDisplayName(pulsechainChainId)}`,
+        providerKey: omnibridgeProviderKey,
+        tokenFlow: [anchorNode, destinationNode],
+        landing: {
+            amount: candidate.deliveredAmount,
+            decimals: destinationToken.decimals,
+            symbol: destinationToken.symbol,
+            usdValue: subtractUsdValues(landedUsd, crossingFeeUsd),
+        },
+        feeUsdValue: crossingFeeUsd,
+        // THE FLAG THAT MAKES THE ROUTE HONEST. It is what draws "You sign this
+        // later" on the step, what makes the primary button name the step it
+        // actually signs, and what stops any surface stating the delivered amount
+        // as settled. Removing it would turn this into a route that silently
+        // promises one signature and asks for two.
+        deferred: true,
+        // `sectionDescription` in the route strip reads `section.deferredNote ??
+        // defaultDeferredNote()`, so a note supplied HERE replaces the default
+        // sentence outright rather than adding to it. The default sentence is
+        // "Fee is approximate — quoted when you return." — the one fact that
+        // tells the reader the output figure they are looking at is not settled.
+        // A note that names only the second signature and drops that fact leaves
+        // a settled-looking figure on screen with nothing anywhere saying
+        // otherwise, so this note must carry BOTH facts itself.
+        deferredNote: `The bridge crossing is a second signature you make once the funds arrive on ${chainDisplayName(candidate.entryChainId)}. The amount shown is approximate and is quoted again when you return.`,
+        // The crossing's own settlement wait, which is the long part of the journey
+        // and has nothing to do with the aggregator's estimate above.
+        etaMinutes: BRIDGE_SETTLEMENT_ETA_MINUTES,
+        hops: [crossingHop],
+    };
+    const totalCostUsdValue = aggregatorFeeUsd === null && crossingFeeUsd === null
+        ? null
+        : (aggregatorFeeUsd ?? 0) + (crossingFeeUsd ?? 0);
+    return {
+        kind: 'aggregated',
+        entryChainId: candidate.entryChainId,
+        // Named after the omnibridge, matching the one-signature route: a route is
+        // named for the thing that performs its defining leg.
+        headlineProviderKey: omnibridgeProviderKey,
+        sections: [aggregatorSection, crossingSection],
+        output: {
+            amount: candidate.deliveredAmount,
+            decimals: destinationToken.decimals,
+            symbol: destinationToken.symbol,
+            // The source basis, carried the whole way: what was paid, less what each
+            // leg costs. Re-pricing the delivered token against its own feed would
+            // state this route's cost twice and the two would not agree.
+            usdValue: subtractUsdValues(paidUsd, totalCostUsdValue),
+        },
+        totalCostUsdValue,
+        // Ranked on the same net figure as every other route: delivered value less
+        // everything the journey costs.
+        netValueUsd: subtractUsdValues(paidUsd, totalCostUsdValue),
+        // The reader's wait is BOTH legs, not the aggregator's leg alone. A route
+        // that reported only the first would claim to finish before its second
+        // signature had even been asked for.
+        etaMinutes: (etaMinutes ?? 0) + BRIDGE_SETTLEMENT_ETA_MINUTES,
+    };
+};
+/**
+ * Describes the anchor a two-signature route leaves the reader holding.
+ *
+ * A small constructor rather than an inline object literal at the call site,
+ * so the three fields are named and documented in one place and a caller
+ * cannot quietly pair one aggregator's amount with another's valuation.
+ *
+ * @param options.anchorToken - the entry-chain token the aggregator delivers
+ * @param options.anchorAmount - how much of it lands, in its base units
+ * @param options.anchorUsdValue - the AGGREGATOR'S own valuation of that landing
+ * @returns the deferred-crossing record, or null when no amount is known
+ */
+export const describeDeferredCrossing = ({ anchorToken, anchorAmount, anchorUsdValue, }) => {
+    if (anchorToken === null) {
+        return null;
+    }
+    if (anchorAmount === null || anchorAmount === undefined || anchorAmount <= 0n) {
+        return null;
+    }
+    return { anchorToken, anchorAmount, anchorUsdValue: anchorUsdValue ?? null };
+};