@gibs/bridge-sdk 1.12.0 → 1.13.0

package/dist/routing/search/plan-route-data.js

@@ -0,0 +1,767 @@
+import * as imageLinks from '../../image-links.js';
+import { chainDisplayName } from '../../chain-names.js';
+import { findProviderById } from '../../providers.js';
+import { describeDeferredCrossing } from '../../near-intents-route.js';
+import { candidateDeliveredUsd, candidateOutsideFeesUsd, candidatePaidUsd, pulsechainChainId, providerDisplayName, } from '../producers.js';
+import { assetNodeKey, planComposedBasis, } from './graph.js';
+/**
+ * PHASE 1 — turns a priced {@link RoutePlan} into the SAME `RouteData` /
+ * `RouteCandidate` / `RouteScoreInputs` shapes today's four hand-written
+ * producers emit: {@link buildNearIntentsTwoStepRouteData} (`../../near-intents-route.js`),
+ * {@link buildConversionRouteData}, {@link buildOutboundRouteData} and
+ * {@link buildDirectCrossingCandidate} (paired with `buildCandidateRouteData`)
+ * — all in `../producers.js` and `../candidate.js`. See the route-search
+ * design's section 6, "what it absorbs," and this module's own tests
+ * (`plan-route-data.test.ts`) for the parity checks against each of the four.
+ *
+ * WHAT THIS MODULE DOES NOT DO: PRICE A PLAN. Every existing builder prices
+ * a section from carrier-specific knowledge this module has no access to — a
+ * bridge's own fee-manager rate (`crossingCost` in `../producers.js`), a
+ * PulseX swap's estimate (`buildPulseXSwapEstimateData`), or an aggregator's
+ * own paid/delivered spread (`candidatePaidUsd` / `candidateDeliveredUsd`,
+ * both reused here rather than restated). A `RoutePlan` (`./graph.js`) names
+ * the STRUCTURE of a path and a base-unit delivered amount per hop; it
+ * carries no United States dollar figure at all. So every dollar figure this
+ * module places on a `RouteData` — a section's fee, a section's landing
+ * value, the route's total cost — is a CALLER-SUPPLIED input
+ * ({@link PlanSectionPricing}), never a formula computed here. This mirrors
+ * `RouteScoreInputs`' own doc in `score.ts`: "the caller is responsible for
+ * turning a priced RoutePlan into these fields."
+ *
+ * WHAT THIS MODULE DOES DO: compose the STRUCTURE — which section a hop
+ * belongs to, whether that section is deferred, what it is labelled, what
+ * its hops are titled, and what its token flow is — directly from the
+ * plan's graph shape, using exactly the same conventions today's four
+ * builders use. Where those four builders DISAGREE with each other (and two
+ * of them genuinely do — see `hopIsAutomatic` below), this module picks ONE
+ * rule and documents which existing convention it follows and which it
+ * knowingly departs from, per this project's "surface conflicts, don't
+ * average them" rule. Every departure is named in this module's tests.
+ */
+// ---------------------------------------------------------------------------
+// Carrier classification
+// ---------------------------------------------------------------------------
+/**
+ * Whether `carrier` is an omnibridge crossing (`'pulsechain'` or
+ * `'tokensex'`) — a genuine type predicate, not a plain boolean, so every
+ * call site narrows `carrier` from the wide {@link HopCarrier} union down to
+ * {@link Provider}. `providerDisplayName` (`../producers.js`) is total only
+ * over `Provider`'s two keys and falls back to the generic string
+ * "Omnibridge" for anything else; a plain-boolean guard left the call sites
+ * below typed as `HopCarrier` and accepting a bare `string`, which is the
+ * SAME shape of fault that let a NEAR Intents leg display as "Omnibridge"
+ * (see `plan-route-data.test.ts`'s now-fixed "documented divergence" case).
+ * Narrowing here makes that class of mistake fail to compile instead of
+ * silently mis-naming a hop.
+ */
+const isBridgeCarrier = (carrier) => carrier === 'pulsechain' || carrier === 'tokensex';
+/** Whether `carrier` is a consolidated-route aggregator (LI.FI, Relay, NEAR Intents). */
+const isAggregatorCarrier = (carrier) => carrier === 'lifi' || carrier === 'relay' || carrier === 'near-intents';
+/** Whether a hop lands on PulseChain — the signal every label/title rule below keys on. */
+const hopLandsOnPulsechain = (hop) => hop.edge.to.chainId === pulsechainChainId;
+/** Whether `hopIndex` is the plan's LAST hop overall — a completing leg, not a starting one. */
+const isFinalHopOfPlan = (hopIndex, plan) => hopIndex === plan.hops.length - 1;
+/**
+ * Resolves a node's display token and asserts its `decimals` agree with the
+ * NODE's own `decimals` — the field `graph.ts` added specifically so a hop
+ * touching two independently-resolved mentions of the same token can be
+ * checked against each other without a second lookup (see `AssetNode`'s own
+ * doc). A name is a hypothesis, not evidence: `resolveToken` is a caller
+ * hook this module does not control, and trusting its `decimals` blind would
+ * silently misplace a decimal point in a real amount exactly the way
+ * `compose.ts`'s `decimals-mismatch` refusal exists to prevent one hop
+ * downstream. The NODE's decimals wins as the returned, asserted value.
+ *
+ * @param node - the graph node to resolve
+ * @param resolveToken - resolves the node to its full display token
+ * @returns the resolved token and the node's own, asserted decimals
+ */
+const resolveNodeWithAssertedDecimals = (node, resolveToken) => {
+    const token = resolveToken(node);
+    if (token.decimals !== node.decimals) {
+        throw new Error(`resolveToken disagrees with the graph node about ${assetNodeKey(node)}'s decimals: ` +
+            `node says ${node.decimals}, the resolved token says ${token.decimals}`);
+    }
+    return { token, decimals: node.decimals };
+};
+/**
+ * Builds the raw `RouteTokenRef` for one graph node, resolving its logo the
+ * same way every existing builder's own token-node helper does
+ * (`tokenNode` in `../../near-intents-route.js`, the inline node literals in
+ * `buildCandidateRouteData`): the token's own image first, the chain badge
+ * from `imageLinks.networkOrPseudo` second — which is what makes a
+ * pay-by-hand origin's invented chain id resolve to a real badge instead of
+ * a 404ing numeric lookup.
+ *
+ * @param node - the graph node to render
+ * @param resolveToken - resolves the node to its full display token
+ * @returns the raw token reference
+ */
+const toRouteTokenRef = (node, resolveToken) => {
+    const { token, decimals } = resolveNodeWithAssertedDecimals(node, resolveToken);
+    return {
+        symbol: token.symbol,
+        address: token.address,
+        chainId: node.chainId,
+        decimals,
+        // NOT `image`, which checksums the address as an Ethereum one and throws
+        // for anything else. A plan can start on a pay-by-hand chain (Zcash's
+        // native sentinel is `t1Hsc…`), and that throw blanked the whole bridge
+        // form the moment such a route was served. A token's own logo still wins;
+        // an address no picture can be asked for draws its chain's mark.
+        logoUri: token.logoURI ? token.logoURI : imageLinks.tokenImageOrChainFallback(token),
+        chainLogoUri: imageLinks.networkOrPseudo(node.chainId),
+    };
+};
+/**
+ * The distinct stops a signature group's hops walk: the origin, then every
+ * node a hop lands on, collapsing a hop that lands back on the node the
+ * flow already holds — generalizing `deriveTokenFlow` in `../producers.js`
+ * from RAW ADDRESS-STRING comparison (`isSameTokenRef`) to
+ * {@link assetNodeKey}, which is already the collision-free, casing-normalized
+ * identity every other part of the graph model uses.
+ *
+ * THIS IS WHERE THE RECENTLY-FIXED BUG STAYS FIXED. `deriveTokenFlow` used to
+ * leave a route showing only its origin when a candidate itemized no hops at
+ * all — see `../producers.js`'s own note on the defect. A `RoutePlan` always
+ * carries at least one hop for a real crossing, and this walk always ends on
+ * that hop's `to` node, so the flow can never stop short of the plan's own
+ * declared destination for its group.
+ *
+ * @param hops - one signature group's hops, first to last
+ * @param resolveToken - resolves a graph node to its full display token
+ * @returns the group's token flow, origin first
+ */
+const buildGroupTokenFlow = (hops, resolveToken) => {
+    const originNode = hops[0].edge.from;
+    const nodeFlow = hops.reduce((flow, hop) => {
+        const produced = hop.edge.to;
+        const held = flow[flow.length - 1];
+        if (assetNodeKey(held) === assetNodeKey(produced))
+            return flow;
+        return [...flow, produced];
+    }, [originNode]);
+    return nodeFlow.map((node) => toRouteTokenRef(node, resolveToken));
+};
+// ---------------------------------------------------------------------------
+// Section-level labelling
+// ---------------------------------------------------------------------------
+/**
+ * A signature group's own hop-index list, resolved to its hops.
+ *
+ * @param group - one entry of `plan.signatures` — hop indices into `plan.hops`
+ * @param plan - the plan those indices are drawn from
+ * @returns the group's hops, first to last
+ */
+const groupHops = (group, plan) => group.map((hopIndex) => plan.hops[hopIndex]);
+/**
+ * Whether every hop of a group is carried by PulseX — the standalone-swap
+ * shape `buildPulseXSwapSectionData` draws, labelled "Swap on PulseX"
+ * regardless of the group's position in the plan.
+ */
+const isPulseXOnlyGroup = (hops) => hops.every((hop) => hop.edge.carrier === 'PulseX');
+/** Whether a group's LAST hop is the omnibridge crossing — the fact that decides "Bridge to X". */
+const groupEndsWithBridgeHop = (hops) => isBridgeCarrier(hops[hops.length - 1].edge.carrier);
+/**
+ * A signature section's label, generalizing the four distinct conventions
+ * found across today's producers into one rule:
+ *
+ *  - **"Swap on PulseX"** — every hop in the group is carried by PulseX.
+ *    Matches `buildPulseXSwapSectionData`'s hard-coded label.
+ *  - **"Bridge to {X}"** — the WHOLE plan is one signature (matches
+ *    `buildCandidateRouteData`, which always uses this label for its one
+ *    section, omnibridge leg or not), OR the group's last hop IS the
+ *    omnibridge crossing (matches `buildNearIntentsTwoStepRouteData`'s
+ *    second section AND `buildOutboundRouteData`'s first section).
+ *  - **"Complete at {X}"** — the group is the plan's LAST signature and does
+ *    NOT end on a bridge hop. Matches `buildOutboundRouteData`'s second
+ *    section, in BOTH its shapes (the entry-chain swap and the onward
+ *    aggregator hop) — the section label names where the journey finishes
+ *    regardless of which service carries the last leg.
+ *  - **"Send to {X}"** — every other case: a non-final, non-bridge-ending
+ *    group. Matches `buildNearIntentsTwoStepRouteData`'s first section.
+ *
+ * @param group - the group's hop indices
+ * @param groupIndex - the group's position in `plan.signatures`
+ * @param plan - the plan the group belongs to
+ * @returns the section's label
+ */
+const sectionLabel = (group, groupIndex, plan) => {
+    const hops = groupHops(group, plan);
+    if (isPulseXOnlyGroup(hops))
+        return 'Swap on PulseX';
+    const destinationChainId = hops[hops.length - 1].edge.to.chainId;
+    const isOnlyGroup = plan.signatures.length === 1;
+    if (isOnlyGroup || groupEndsWithBridgeHop(hops)) {
+        return `Bridge to ${chainDisplayName(destinationChainId)}`;
+    }
+    const isFinalGroup = groupIndex === plan.signatures.length - 1;
+    if (isFinalGroup) {
+        return `Complete at ${chainDisplayName(destinationChainId)}`;
+    }
+    return `Send to ${chainDisplayName(destinationChainId)}`;
+};
+// ---------------------------------------------------------------------------
+// Hop-level rendering
+// ---------------------------------------------------------------------------
+/**
+ * A hop's display provider name.
+ *
+ * A bridge carrier resolves through {@link providerDisplayName} (the same
+ * "PulseChain Bridge" / "Tokens Express Bridge" table every builder reads).
+ * PulseX is named directly. An aggregator carrier resolves through the
+ * PROVIDER REGISTRY's own label (`providerById(id).label`) — DELIBERATELY,
+ * not through `providerDisplayName`, because that function's table only
+ * ever held the two omnibridge providers. `buildNearIntentsTwoStepRouteData`
+ * calls `providerDisplayName(candidate.quote.provider)` for its aggregator
+ * hop today, and `'near-intents'` is not a key in that table, so it silently
+ * falls back to the generic string `'Omnibridge'` — naming NEAR Intents
+ * after the bridge it is not. That reads as an unintentional defect in the
+ * existing code, not a convention worth reproducing; this function returns
+ * `'NEAR Intents'` instead. See this module's test file and the report back
+ * to the owner for the specific call-out.
+ *
+ * @param carrier - the hop's carrier
+ * @returns the display name for that carrier
+ */
+const hopProviderName = (carrier) => {
+    if (isBridgeCarrier(carrier))
+        return providerDisplayName(carrier);
+    if (carrier === 'PulseX')
+        return 'PulseX';
+    // TOTAL OVER EVERY CARRIER. The engine plans hops for carriers the provider
+    // registry does not hold (a local wrap, a host's own plug-in). Casting such
+    // an id to a provider id and asking the throwing lookup crashed the whole
+    // bridge form the first time a plan began with a wrap. A carrier with no
+    // registered label is named by its own id.
+    return findProviderById(carrier)?.label ?? carrier;
+};
+/**
+ * A hop's title, generalizing the title conventions of every existing
+ * builder:
+ *
+ *  - a bridge hop landing on PulseChain → `"Bridge to PulseChain"` (matches
+ *    `buildCandidateRouteData`'s omnibridge hop and
+ *    `buildNearIntentsTwoStepRouteData`'s crossing hop);
+ *  - a bridge hop landing elsewhere (leaving PulseChain) →
+ *    `providerDisplayName(carrier)`, e.g. `"PulseChain Bridge"` (matches
+ *    `buildOutboundRouteData`'s bridge hop exactly);
+ *  - a PulseX hop → `"Swap to {toSymbol}"` (matches `buildPulseXSwapSectionData`);
+ *  - an aggregator hop that is the plan's FINAL hop (nothing follows it,
+ *    so this signature is the one that COMPLETES the journey) →
+ *    `"Bridge to {toChainName}"` (matches `buildOutboundRouteData`'s onward
+ *    hop, which names the chain it finishes on even though an aggregator,
+ *    not the omnibridge, carries it);
+ *  - any other aggregator hop (something follows it) → `"Send to {toChainName}"`
+ *    (matches `buildNearIntentsTwoStepRouteData`'s aggregator hop).
+ *
+ * @param hop - the hop to title
+ * @param hopIndex - the hop's index into `plan.hops`
+ * @param plan - the plan the hop belongs to
+ * @param resolveToken - resolves a graph node to its full display token
+ * @returns the hop's title
+ */
+const hopTitle = (hop, hopIndex, plan, resolveToken) => {
+    const carrier = hop.edge.carrier;
+    if (isBridgeCarrier(carrier)) {
+        return hopLandsOnPulsechain(hop)
+            ? `Bridge to ${chainDisplayName(pulsechainChainId)}`
+            : providerDisplayName(carrier);
+    }
+    if (carrier === 'PulseX') {
+        return `Swap to ${resolveToken(hop.edge.to).symbol}`;
+    }
+    const destinationChainName = chainDisplayName(hop.edge.to.chainId);
+    return isFinalHopOfPlan(hopIndex, plan)
+        ? `Bridge to ${destinationChainName}`
+        : `Send to ${destinationChainName}`;
+};
+/**
+ * A hop's conversion subtitle.
+ *
+ * The source data has two conventions for this string: the candidate-based
+ * builders (`buildCandidateRouteData`'s omnibridge hop,
+ * `buildNearIntentsTwoStepRouteData`'s both hops) write an ARROW-ONLY clause
+ * (`"→ USDC"`), leaving the origin side implicit; the settings-based
+ * builders (`buildOutboundRouteData`, `buildPulseXSwapSectionData`) write
+ * the FULL two-sided clause (`"PLS → USDC"`). Both are correct prose for
+ * their own hop; this function reproduces BOTH conventions rather than
+ * picking one, keyed on the exact same signal {@link hopTitle} already uses
+ * to distinguish a starting/intermediate leg from a completing one: arrow-only
+ * for a bridge hop landing on PulseChain or an aggregator hop that is NOT the
+ * plan's final hop (there is more journey to draw, so the origin side is
+ * already on screen from the previous hop); full two-sided otherwise.
+ *
+ * @param hop - the hop to describe
+ * @param hopIndex - the hop's index into `plan.hops`
+ * @param plan - the plan the hop belongs to
+ * @param resolveToken - resolves a graph node to its full display token
+ * @returns the hop's conversion subtitle
+ */
+const hopConversion = (hop, hopIndex, plan, resolveToken) => {
+    const carrier = hop.edge.carrier;
+    const toSymbol = resolveToken(hop.edge.to).symbol;
+    const usesArrowOnly = (isBridgeCarrier(carrier) && hopLandsOnPulsechain(hop)) ||
+        (isAggregatorCarrier(carrier) && !isFinalHopOfPlan(hopIndex, plan));
+    if (usesArrowOnly)
+        return `→ ${toSymbol}`;
+    const fromSymbol = resolveToken(hop.edge.from).symbol;
+    return `${fromSymbol} → ${toSymbol}`;
+};
+/**
+ * Whether a hop runs AUTOMATICALLY inside a signature a PRECEDING hop
+ * already signed — true exactly when the hop is not the first hop of its
+ * own signature group, per `RouteHopData.automatic`'s own doc ("runs
+ * automatically inside the SECTION's single signature").
+ *
+ * THIS MATCHES THREE OF THE FOUR TARGET SHAPES EXACTLY —
+ * `buildCandidateRouteData` (an aggregator hop with index > 0 inside its
+ * section, and the omnibridge hop only when an aggregator hop preceded it),
+ * `buildNearIntentsTwoStepRouteData` (both of its hops are their own
+ * section's first and only hop, so both are `false`), and
+ * `buildPulseXSwapSectionData` (its one hop is always `false`, hard-coded
+ * for the same reason).
+ *
+ * IT DOES NOT MATCH `buildOutboundRouteData`'s BRIDGE HOP, which hard-codes
+ * `true` even though it is that section's own first and only hop — a SECOND,
+ * DIFFERENT reading of "automatic" that describes the omnibridge's own
+ * far-side auto-completion (no reader signature needed to FINISH the
+ * crossing once signed) rather than whether the hop itself needed no
+ * signature to START. `buildDirectRouteData` (a separate, non-plan family
+ * this module does not otherwise touch) hard-codes the same reading. This
+ * function follows the field's own documented meaning and the majority
+ * convention (three of four builders) rather than that reading — see this
+ * module's test file for the specific, deliberate divergence this produces
+ * against `buildOutboundRouteData`'s bridge hop.
+ *
+ * @param hopIndex - the hop's index into `plan.hops`
+ * @param plan - the plan the hop belongs to
+ * @returns whether the hop is automatic
+ */
+const hopIsAutomatic = (hopIndex, plan) => {
+    const group = plan.signatures.find((candidateGroup) => candidateGroup.includes(hopIndex));
+    return group !== undefined && group[0] !== hopIndex;
+};
+/**
+ * Builds the raw `RouteHopData` for one planned hop.
+ *
+ * @param hop - the hop to render
+ * @param hopIndex - the hop's index into `plan.hops`
+ * @param plan - the plan the hop belongs to
+ * @param resolveToken - resolves a graph node to its full display token
+ * @returns the raw hop data
+ */
+const toRouteHopData = (hop, hopIndex, plan, resolveToken) => ({
+    providerName: hopProviderName(hop.edge.carrier),
+    providerKey: hop.edge.carrier,
+    title: hopTitle(hop, hopIndex, plan, resolveToken),
+    conversion: hopConversion(hop, hopIndex, plan, resolveToken),
+    fromToken: toRouteTokenRef(hop.edge.from, resolveToken),
+    toToken: toRouteTokenRef(hop.edge.to, resolveToken),
+    // The per-hop dollar figure is a section-level, caller-supplied input (see
+    // this module's head doc); a raw hop carries none of its own here.
+    feeUsdValue: null,
+    automatic: hopIsAutomatic(hopIndex, plan),
+});
+// ---------------------------------------------------------------------------
+// Route-level derivations — candidate.ts's promised derivation, made real
+// ---------------------------------------------------------------------------
+/**
+ * The plan's omnibridge provider, or null when the plan crosses no bridge
+ * hop at all — exactly the derivation `RouteCandidate.plan`'s own TSDoc
+ * (`../candidate.ts`) promises: "that same hop's `carrier`... the `to` node's
+ * `chainId` of the plan's LAST hop whose carrier is `'pulsechain'` or
+ * `'tokensex'`." Reading the LAST such hop, not the first, matters for a
+ * plan with two bridge crossings (an outbound leg out of PulseChain followed
+ * later by a separate inbound one) — not a shape any of today's four
+ * builders draws, but one the general search can.
+ *
+ * @param plan - the plan to derive from
+ * @returns the omnibridge provider, or null
+ */
+export const deriveOmnibridgeProviderFromPlan = (plan) => {
+    const bridgeHop = [...plan.hops].reverse().find((hop) => isBridgeCarrier(hop.edge.carrier));
+    if (bridgeHop === undefined)
+        return null;
+    // `Array.prototype.find`'s own predicate narrowing does not flow back out
+    // of the callback into the found element's type — only `isBridgeCarrier`
+    // called again, directly on the plain `carrier` binding, narrows it here.
+    // Re-declaring the return type as the real `Provider | null` (rather than
+    // the wide `string | null` this used to widen to) is what surfaces a
+    // mismatch at the source the moment a caller narrows further downstream,
+    // instead of a silent `string` riding all the way to `providerDisplayName`.
+    const { carrier } = bridgeHop.edge;
+    return isBridgeCarrier(carrier) ? carrier : null;
+};
+/**
+ * The plan's entry chain id — the chain the plan's FIRST hop lands on, when
+ * that hop is carried by an aggregator (LI.FI, Relay or NEAR Intents); null
+ * when the plan's first hop IS the omnibridge itself (a direct, same-chain
+ * crossing — `buildDirectCrossingCandidate`'s shape) or is a PulseX swap.
+ *
+ * MATCHES `RouteCandidate.entryChainId`'S EXISTING MEANING throughout the
+ * candidate-based builders — "the chain the omnibridge leg starts on" — for
+ * every candidate that carries one, including a candidate whose aggregator
+ * reaches its OWN destination with no further bridge hop at all (today's
+ * `makeCandidate` test fixtures set `entryChainId` to the destination chain
+ * in exactly that case, because it is still where the aggregator's own leg
+ * lands).
+ *
+ * @param plan - the plan to derive from
+ * @returns the entry chain id, or null for a direct crossing or a swap-only plan
+ */
+export const deriveEntryChainIdFromPlan = (plan) => {
+    const firstHop = plan.hops[0];
+    if (!firstHop)
+        return null;
+    return isAggregatorCarrier(firstHop.edge.carrier) ? firstHop.edge.to.chainId : null;
+};
+/**
+ * The decimal chain ids every INTERMEDIATE hop of the plan passes through,
+ * origin and destination excluded — `RouteData.viaChainIds`'s own contract.
+ * Undefined (never an empty array) when the plan has nothing to report, per
+ * that field's own "ABSENT... on any route with no intermediate chain" doc.
+ *
+ * @param plan - the plan to derive from
+ * @returns the via chain ids in hop order, or undefined
+ */
+export const deriveViaChainIdsFromPlan = (plan) => {
+    const intermediateChainIds = plan.hops.slice(0, -1).map((hop) => hop.edge.to.chainId);
+    return intermediateChainIds.length > 0 ? intermediateChainIds : undefined;
+};
+/**
+ * The plan's `RouteKind`, per the route-search design's section 1: `'direct'`
+ * when signature 1 IS the omnibridge crossing itself (no aggregator prefix —
+ * `buildDirectCrossingCandidate`'s shape, and `buildOutboundRouteData`'s
+ * shape), `'conversion'` when the LAST hop is a PulseX swap
+ * (`buildConversionRouteData`'s shape), `'aggregated'` otherwise (an
+ * aggregator carries signature 1, fused with a bridge hop or not —
+ * `buildNearIntentsTwoStepRouteData`'s shape, and the general
+ * aggregator-fused shape).
+ *
+ * DIVERGES FROM TODAY'S LITERAL OUTPUT FOR ONE CASE, DELIBERATELY: a
+ * same-chain candidate built by `buildDirectCrossingCandidate` and rendered
+ * through `buildCandidateRouteData` today always comes back `kind:
+ * 'aggregated'`, because that builder hard-codes `'aggregated'`
+ * unconditionally — an artifact of `RouteCandidate.entryChainId` being
+ * non-nullable, so `buildCandidateRouteData` always assumes an
+ * aggregator-entry shape even for a candidate with no aggregator leg at all.
+ * This function instead answers `'direct'` for that exact plan, matching how
+ * `buildDirectRouteData` (the OTHER, non-candidate 'direct' family) already
+ * represents the identical real-world same-chain crossing. See this
+ * module's test file for the specific case.
+ *
+ * @param plan - the plan to derive from
+ * @returns the route's kind
+ */
+export const derivePlanKind = (plan) => {
+    const lastHop = plan.hops[plan.hops.length - 1];
+    if (lastHop && lastHop.edge.carrier === 'PulseX')
+        return 'conversion';
+    const firstHop = plan.hops[0];
+    if (firstHop && isBridgeCarrier(firstHop.edge.carrier))
+        return 'direct';
+    return 'aggregated';
+};
+/**
+ * Narrows a plan's {@link HopCarrier} (a plain string, since `HopEdge.carrier`
+ * moved off the closed `ProviderKey` union) down to `RouteData.headlineProviderKey`'s
+ * own closed {@link ProviderKey} type, for the display/logo lookup tables that
+ * type exists to protect (`resolveProviderLogoUri` / `resolveProviderDisplayName`
+ * — see `ProviderKey`'s own doc in `../../providers.js`).
+ *
+ * A GIBS PLAN NEVER CARRIES ANYTHING ELSE. Every carrier a `RoutePlan` this
+ * module renders can name is one gibs itself registered — the three built-in
+ * aggregators, the omnibridge, or PulseX (`routing/carriers/`,
+ * `packages/ui/src/lib/state/useRouteSearch.ts`) — so this throws rather than
+ * guessing when it sees anything else: a plan naming an unrecognized carrier
+ * is a bug in whatever built it, not a display gap to paper over silently.
+ *
+ * @param carrier - the plan's headline carrier
+ * @returns the same value, typed as `ProviderKey`
+ */
+const toHeadlineProviderKey = (carrier) => {
+    if (isBridgeCarrier(carrier))
+        return carrier;
+    if (isAggregatorCarrier(carrier))
+        return carrier;
+    if (carrier === 'PulseX')
+        return carrier;
+    throw new Error(`toHeadlineProviderKey: unrecognized carrier "${carrier}"`);
+};
+/**
+ * The plan's headline provider — the omnibridge crossing it out when it
+ * crosses one, or whichever carrier performs signature 1 when it does not.
+ * Matches every existing builder's own headline choice: the omnibridge when
+ * present (`buildCandidateRouteData`, `buildNearIntentsTwoStepRouteData`,
+ * `buildOutboundRouteData`), the aggregator's own key as the fallback
+ * (`buildCandidateRouteData`'s no-omnibridge branch).
+ *
+ * @param plan - the plan to derive from
+ * @returns the headline provider key
+ */
+const deriveHeadlineProviderKeyFromPlan = (plan) => toHeadlineProviderKey(deriveOmnibridgeProviderFromPlan(plan) ?? plan.hops[0].edge.carrier);
+/**
+ * The anchor a two-signature plan leaves the reader holding between its
+ * first and second groups — `RouteCandidate.plan`'s own TSDoc: "the anchor
+ * the reader is left holding between signatures... taken from the first hop
+ * of the second group." Reuses `describeDeferredCrossing`
+ * (`../../near-intents-route.js`) rather than re-validating the same
+ * "positive amount, resolved token" rule a second time.
+ *
+ * Null when the plan has only one signature group (there is no deferred
+ * crossing to describe) or the plan is malformed (a signature group naming
+ * hop indices the plan does not have).
+ *
+ * @param plan - the plan to derive from
+ * @param resolveToken - resolves a graph node to its full display token
+ * @param anchorUsdValue - the anchor's own carrier's valuation of the
+ *   landing, exactly as `DeferredCrossing.anchorUsdValue` expects — supplied
+ *   by the caller, since a plan carries no United States dollar figures.
+ * @returns the deferred crossing, or null
+ */
+export const deriveDeferredCrossingFromPlan = (plan, resolveToken, anchorUsdValue) => {
+    const secondGroup = plan.signatures[1];
+    const firstGroup = plan.signatures[0];
+    if (!secondGroup || !firstGroup)
+        return null;
+    const anchorHopIndex = secondGroup[0];
+    const landingHopIndex = firstGroup[firstGroup.length - 1];
+    if (anchorHopIndex === undefined || landingHopIndex === undefined)
+        return null;
+    const anchorHop = plan.hops[anchorHopIndex];
+    const landingHop = plan.hops[landingHopIndex];
+    if (!anchorHop || !landingHop)
+        return null;
+    return describeDeferredCrossing({
+        anchorToken: resolveToken(anchorHop.edge.from),
+        anchorAmount: landingHop.outcome.deliveredAmount,
+        anchorUsdValue,
+    });
+};
+/**
+ * Whether `hop`'s own figure carries no value at all — an `EstimateBasis`
+ * (`graph.ts`) of `'unpriced'`: a bare decimal rescale with nothing behind
+ * it (see that type's own doc). {@link sectionLandingAmount} is what a
+ * `true` result means for the section's (and the route's) headline figure:
+ * it is left OUT of `amount` entirely, never shown at all.
+ */
+const hopOutcomeIsUnpriced = (hop) => hop.outcome.kind === 'estimate' && hop.outcome.basis === 'unpriced';
+/**
+ * What `hop` reports for `RouteLandingData.estimateBasis` /
+ * `RouteOutputData.estimateBasis` (`../route-data.ts`): the hop's own
+ * `EstimateBasis` string when it is a composed/probed figure, `null` for a
+ * bound quote — and `null` for `'unpriced'` too, per that field's own doc
+ * ("'unpriced' never reaches here"), since {@link sectionLandingAmount}
+ * already leaves an unpriced hop's `amount` out entirely rather than
+ * labelling it.
+ *
+ * @param hop - the hop to read
+ * @returns the estimate basis to report, or null
+ */
+const hopEstimateBasis = (hop) => {
+    if (hop.outcome.kind !== 'estimate')
+        return null;
+    if (hop.outcome.basis === 'unpriced')
+        return null;
+    return hop.outcome.basis;
+};
+/**
+ * A section's landing amount: the caller's explicit override when given
+ * ({@link PlanSectionPricing.landingAmountOverride}'s own doc), else `null`
+ * when the section's last hop is `'unpriced'` (see {@link hopOutcomeIsUnpriced}
+ * — a figure with no value behind it is never shown, marked or not), else
+ * the hop's own composed delivered amount.
+ *
+ * @param pricing - the section's caller-supplied pricing
+ * @param lastHop - the section's last hop
+ * @returns the amount to land the section on, or null
+ */
+const sectionLandingAmount = (pricing, lastHop) => {
+    if ('landingAmountOverride' in pricing)
+        return pricing.landingAmountOverride ?? null;
+    if (hopOutcomeIsUnpriced(lastHop))
+        return null;
+    return lastHop.outcome.deliveredAmount;
+};
+/**
+ * Turns a priced {@link RoutePlan} into a raw {@link RouteData} — one section
+ * per signature group, `deferred` on every group after the first, each
+ * section's hops and token flow drawn structurally from the plan, and the
+ * dollar figures overlaid from `inputs.sections`. See this module's head doc
+ * for why the dollar figures are caller-supplied rather than derived here.
+ *
+ * NEVER SHOWS AN UNPRICED HEADLINE FIGURE, AND MARKS EVERY OTHER ESTIMATE AS
+ * ONE — PHASE 3. A section (and the route's own `output`) whose last hop is
+ * grounded on `EstimateBasis` `'unpriced'` lands on `amount: null`, whatever
+ * the caller's own pricing says, per {@link sectionLandingAmount}'s own doc.
+ * Every OTHER estimate (`'probe-rate'`, `'priced-conversion'`) still shows
+ * its figure, with `estimateBasis` set to that basis so a reader is never
+ * shown a composed/probed number as if it were a confirmed quote — see
+ * `RouteOutputData.estimateBasis`'s own doc (`../route-data.ts`) for the
+ * full rule this reads off {@link hopEstimateBasis}.
+ *
+ * @param inputs - the plan, a token resolver, an id, and per-section pricing
+ * @returns the raw route data
+ */
+export const buildRouteDataFromPlan = (inputs) => {
+    const { plan, resolveToken, routeId, sections, totalCostUsdValue, netValueUsd, etaMinutes } = inputs;
+    if (plan.hops.length === 0) {
+        throw new Error('buildRouteDataFromPlan: a plan needs at least one hop');
+    }
+    if (sections.length !== plan.signatures.length) {
+        throw new Error(`buildRouteDataFromPlan: expected ${plan.signatures.length} section(s) of pricing, got ${sections.length}`);
+    }
+    const routeSections = plan.signatures.map((group, groupIndex) => {
+        const hops = groupHops(group, plan);
+        const pricing = sections[groupIndex];
+        const lastHop = hops[hops.length - 1];
+        const landing = resolveNodeWithAssertedDecimals(lastHop.edge.to, resolveToken);
+        const landingIsUnpriced = hopOutcomeIsUnpriced(lastHop);
+        return {
+            id: `${routeId}-signature-${groupIndex + 1}`,
+            label: sectionLabel(group, groupIndex, plan),
+            providerKey: hops[0].edge.carrier,
+            tokenFlow: buildGroupTokenFlow(hops, resolveToken),
+            landing: {
+                amount: sectionLandingAmount(pricing, lastHop),
+                decimals: landing.decimals,
+                symbol: landing.token.symbol,
+                usdValue: landingIsUnpriced ? null : pricing.landingUsdValue,
+                estimateBasis: hopEstimateBasis(lastHop),
+            },
+            feeUsdValue: pricing.feeUsdValue,
+            fees: pricing.fees ? [...pricing.fees] : undefined,
+            etaMinutes: pricing.etaMinutes,
+            etaSeconds: pricing.etaSeconds,
+            hops: group.map((hopIndex) => toRouteHopData(plan.hops[hopIndex], hopIndex, plan, resolveToken)),
+            deferred: groupIndex > 0 ? true : undefined,
+            deferredNote: pricing.deferredNote,
+        };
+    });
+    const lastSection = routeSections[routeSections.length - 1];
+    return {
+        kind: derivePlanKind(plan),
+        entryChainId: deriveEntryChainIdFromPlan(plan),
+        headlineProviderKey: deriveHeadlineProviderKeyFromPlan(plan),
+        sections: routeSections,
+        output: {
+            amount: lastSection.landing?.amount ?? null,
+            decimals: lastSection.landing?.decimals ?? 0,
+            symbol: lastSection.landing?.symbol ?? '',
+            usdValue: lastSection.landing?.usdValue ?? null,
+            estimateBasis: lastSection.landing?.estimateBasis ?? null,
+        },
+        totalCostUsdValue,
+        netValueUsd,
+        etaMinutes,
+        // The single legacy `viaChainId` a not-yet-migrated consumer may still
+        // read (`RouteOption`, `journeyPlan.ts`'s current `pathKeyFor` — see the
+        // route-search design's section 1) — the first intermediate chain, when
+        // there is one. `buildOutboundRouteData` sets this to the chain its one
+        // bridge hop lands on, which is exactly this plan's first via chain.
+        viaChainId: deriveViaChainIdsFromPlan(plan)?.[0],
+        pathKey: plan.pathKey,
+        viaChainIds: deriveViaChainIdsFromPlan(plan),
+    };
+};
+/**
+ * Turns a priced {@link RoutePlan} into a {@link RouteCandidate}, filling
+ * `plan` and deriving `deferredCrossing`, `entryChainId` and
+ * `omnibridgeProvider` from it exactly as `RouteCandidate.plan`'s own TSDoc
+ * (`../candidate.ts`) promises.
+ *
+ * @param inputs - the plan, a token resolver, an id, and the caller's pricing
+ * @returns the route candidate
+ */
+export const buildRouteCandidateFromPlan = (inputs) => {
+    const { plan, resolveToken, id, inputAmount, paidUsdValue, lastHopDeliveredUsdValue, destinationUsdPrice, omnibridgeFeeAmount = 0n, anchorUsdValue = null, requestedAmount, fees = [], executionDurationSeconds = 0, } = inputs;
+    const firstHop = plan.hops[0];
+    const lastHop = plan.hops[plan.hops.length - 1];
+    if (!firstHop || !lastHop) {
+        throw new Error('buildRouteCandidateFromPlan: a plan needs at least one hop');
+    }
+    const omnibridgeProvider = deriveOmnibridgeProviderFromPlan(plan);
+    const entryChainId = deriveEntryChainIdFromPlan(plan) ?? lastHop.edge.to.chainId;
+    const originToken = resolveNodeWithAssertedDecimals(firstHop.edge.from, resolveToken).token;
+    const destinationToken = resolveNodeWithAssertedDecimals(lastHop.edge.to, resolveToken).token;
+    const deferredCrossing = deriveDeferredCrossingFromPlan(plan, resolveToken, anchorUsdValue);
+    const carrier = firstHop.edge.carrier;
+    const quote = {
+        provider: carrier,
+        quoteId: id,
+        tool: carrier,
+        toolName: hopProviderName(carrier),
+        fromAmount: inputAmount,
+        fromAmountUsd: paidUsdValue,
+        ...(omnibridgeProvider === null && lastHopDeliveredUsdValue !== null
+            ? { toAmount: lastHop.outcome.deliveredAmount, toAmountUsd: lastHopDeliveredUsdValue }
+            : {}),
+        approvalAddress: null,
+        executionDurationSeconds,
+        steps: [],
+        fees: [...fees],
+        // A PRICED-BUT-NOT-RESERVED deposit (`UnreservedDeposit`,
+        // `../../origin-deposit.js`) — the variant that EXISTS for exactly this
+        // case: "a route on display... priced with a dry quote, which carries
+        // figures and no address" (that type's own doc). This candidate exists
+        // for scoring and for `RouteData`/`RouteCandidate` shape assembly, never
+        // for a real signature, so it has nothing to reserve.
+        //
+        // THIS IS NOT A STAND-IN FOR THE ORIGIN'S REAL ECOSYSTEM. An earlier
+        // version of this line hard-coded `{ ecosystem: 'evm', ... }`
+        // unconditionally, which is wrong for any non-Ethereum-Virtual-Machine
+        // origin a general-search plan can now represent (a Zcash or Solana
+        // first hop, for example) — a deposit's ecosystem must come from the
+        // chain, never asserted past it. `UnreservedDeposit` sidesteps the
+        // question honestly instead of answering it wrongly: it is
+        // discriminated by `kind`, not by `ecosystem`, and carries no
+        // ecosystem-specific fields at all, so there is no wrong shape to pick
+        // regardless of which ecosystem `firstHop.edge.from` names.
+        originDeposit: { kind: 'unreserved', chainId: firstHop.edge.from.chainId },
+    };
+    return {
+        id,
+        quote,
+        omnibridgeProvider,
+        entryChainId,
+        originToken,
+        destinationToken,
+        deliveredAmount: lastHop.outcome.deliveredAmount,
+        omnibridgeFeeAmount,
+        destinationUsdPrice,
+        requestedAmount,
+        deferredCrossing,
+        plan,
+    };
+};
+/**
+ * Turns a priced {@link RoutePlan} into {@link RouteScoreInputs} — reusing
+ * `candidateDeliveredUsd`, `candidatePaidUsd` and `candidateOutsideFeesUsd`
+ * (`../producers.js`) against the SAME candidate
+ * {@link buildRouteCandidateFromPlan} builds, exactly as `RouteScoreInputs`'
+ * own doc in `score.ts` asks: "generalized to the plan's LAST hop and FIRST
+ * hop respectively... import and reuse them; do not write a second
+ * valuation."
+ *
+ * @param valuation - the plan, a token resolver, an id, and the caller's pricing
+ * @param gaslessIntermediateChainCount - intermediate chains the connected
+ *   account holds no gas on — supplied by the caller, never computed here
+ * @returns the plan's score inputs
+ */
+export const buildRouteScoreInputsFromPlan = (valuation, gaslessIntermediateChainCount) => {
+    const candidate = buildRouteCandidateFromPlan(valuation);
+    return {
+        deliveredUsd: candidateDeliveredUsd(candidate) ?? 0,
+        paidUsd: candidatePaidUsd(candidate) ?? 0,
+        outsideFeesUsd: candidateOutsideFeesUsd(candidate),
+        legClaimedDurationsSeconds: valuation.legClaimedDurationsSeconds,
+        readerActionCount: valuation.plan.signatures.length,
+        gaslessIntermediateChainCount,
+        // PHASE 3 — read directly off the plan's own hops, never re-derived: see
+        // `planComposedBasis`'s own doc (`graph.ts`) for why this always agrees
+        // with `planIsRankable`, and `RouteScoreInputs.basis`'s own doc for what
+        // `scoreRoutePlan` does with it.
+        basis: planComposedBasis(valuation.plan.hops),
+    };
+};