@gibs/bridge-sdk 1.18.0 → 1.20.0

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

@@ -2,81 +2,13 @@ import * as imageLinks from '../../image-links.js';
 import { chainDisplayName } from '../../chain-names.js';
 import { findProviderById } from '../../providers.js';
 import { WRAP_CARRIER_ID, carrierProviderKey, carrierStepKind } from '../carrier-provider-key.js';
-import { describeDeferredCrossing } from '../../near-intents-route.js';
+import { describeDeferredCrossing, sendOrSwapLabel } 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) {
@@ -85,19 +17,6 @@ const resolveNodeWithAssertedDecimals = (node, resolveToken) => {
     }
     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 {
@@ -105,34 +24,10 @@ const toRouteTokenRef = (node, resolveToken) => {
         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) => {
@@ -144,49 +39,9 @@ const buildGroupTokenFlow = (hops, resolveToken) => {
     }, [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))
@@ -200,31 +55,8 @@ const sectionLabel = (group, groupIndex, plan) => {
     if (isFinalGroup) {
         return `Complete at ${chainDisplayName(destinationChainId)}`;
     }
-    return `Send to ${chainDisplayName(destinationChainId)}`;
+    return sendOrSwapLabel(hops[0].edge.from.chainId, 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);
@@ -232,38 +64,8 @@ const hopProviderName = (carrier) => {
         return 'PulseX';
     if (carrierStepKind(carrier) === 'wrap')
         return 'Wrap';
-    // 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)) {
@@ -274,33 +76,11 @@ const hopTitle = (hop, hopIndex, plan, resolveToken) => {
     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}`;
+    if (isFinalHopOfPlan(hopIndex, plan)) {
+        return `Bridge to ${chainDisplayName(hop.edge.to.chainId)}`;
+    }
+    return sendOrSwapLabel(hop.edge.from.chainId, hop.edge.to.chainId);
 };
-/**
- * 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;
@@ -311,51 +91,10 @@ const hopConversion = (hop, hopIndex, plan, resolveToken) => {
     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
- * @param feeUsdValue - the hop's own share of its section's cost, or null
- * @param gas - the hop's gas split, or null when the producer states none
- * @returns the raw hop data
- */
 const toRouteHopData = (hop, hopIndex, plan, resolveToken, feeUsdValue, gas) => ({
     providerName: hopProviderName(hop.edge.carrier),
     providerKey: carrierProviderKey(hop.edge.carrier),
@@ -364,23 +103,10 @@ const toRouteHopData = (hop, hopIndex, plan, resolveToken, feeUsdValue, gas) =>
     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 caller-supplied input (see this module's
-    // head doc); the caller passes it in, never derived here.
     feeUsdValue,
     ...(gas === null ? {} : gas),
     automatic: hopIsAutomatic(hopIndex, plan),
 });
-/**
- * The per-hop shares a section's pricing names, checked against the group
- * they describe.
- *
- * @param pricing - the section's caller-supplied pricing
- * @param group - the signature group's hop indices
- * @param groupIndex - the group's index, for the error message
- * @returns one share per hop, null where none was given
- * @throws when the caller passed a share list of the wrong length — a share
- *   matched to the wrong hop is a figure on the wrong leg
- */
 const groupHopFeeUsdValues = (pricing, group, groupIndex) => {
     const shares = pricing.hopFeeUsdValues;
     if (shares === undefined)
@@ -390,97 +116,23 @@ const groupHopFeeUsdValues = (pricing, group, groupIndex) => {
     }
     return shares;
 };
-// ---------------------------------------------------------------------------
-// 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')
@@ -490,24 +142,6 @@ export const derivePlanKind = (plan) => {
         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, PulseX, or a wrap step, which
- * {@link deriveHeadlineProviderKeyFromPlan} skips (`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;
@@ -517,48 +151,8 @@ const toHeadlineProviderKey = (carrier) => {
         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
- */
 export const deriveHeadlineProviderKeyFromPlan = (plan) => toHeadlineProviderKey(deriveOmnibridgeProviderFromPlan(plan) ?? firstHeadlineCarrier(plan));
-/**
- * The carrier of the first hop that can headline a route. A `wrap` hop
- * (native coin to its wrapped token, or back) is a step inside a route, never
- * the route itself, so it is skipped. A plan made only of wraps headlines as
- * PulseX, the same key the same-chain swap builder gives that route
- * (`buildSameChainSwapRouteData`).
- *
- * @param plan - the plan to read
- * @returns the carrier to headline
- */
 const firstHeadlineCarrier = (plan) => plan.hops.find((hop) => hop.edge.carrier !== WRAP_CARRIER_ID)?.edge.carrier ?? 'PulseX';
-/**
- * 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];
@@ -578,26 +172,7 @@ export const deriveDeferredCrossingFromPlan = (plan, resolveToken, anchorUsdValu
         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;
@@ -605,17 +180,6 @@ const hopEstimateBasis = (hop) => {
         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;
@@ -623,26 +187,6 @@ const sectionLandingAmount = (pricing, 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) {
@@ -714,25 +258,11 @@ export const buildRouteDataFromPlan = (inputs) => {
             }),
         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];
@@ -760,23 +290,6 @@ export const buildRouteCandidateFromPlan = (inputs) => {
         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 {
@@ -794,20 +307,6 @@ export const buildRouteCandidateFromPlan = (inputs) => {
         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 {
@@ -817,10 +316,6 @@ export const buildRouteScoreInputsFromPlan = (valuation, gaslessIntermediateChai
         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),
     };
 };