@gibs/bridge-sdk 1.19.0 → 1.20.0

package/dist/routing/providers.js

@@ -1,38 +1,11 @@
 import { Chains, Providers, toChain } from '../config.js';
 import { sameAddress } from '../ecosystems.js';
-/**
- * Builds the PulseX swap path for a conversion leg, from the bridged anchor to the
- * wanted token. Routes through WPLS (`[anchor, WPLS, wanted]`) by default because
- * most PulseChain tokens have a deep WPLS pool but rarely a direct pool with the USD
- * anchor; it collapses to a direct `[anchor, wanted]` hop only when one side already
- * IS WPLS (no point hopping through WPLS to reach WPLS). The router prices the path
- * with `getAmountsOut`, so a path with no liquidity simply yields no quote.
- *
- * A FIXED PATH, NOT THE BEST ONE. The route search's PulseX carrier prices
- * this path alongside others through its hub tokens and signs whichever
- * delivers most (`carriers/pulsex-paths.ts`). This one remains the
- * carrier's asynchronous `ask` path (`pulseXWrappedNativePath`).
- *
- * @param anchorAddress - the bridged anchor token (the swap input)
- * @param wantedAddress - the token the user wants (the swap output)
- * @param wplsAddress - the wrapped-native intermediary (WPLS)
- * @returns the ordered swap path for `getAmountsOut`
- */
 export const pulseXConversionSwapPath = (anchorAddress, wantedAddress, wplsAddress) => {
     const isWpls = (address) => sameAddress(address, wplsAddress, 'evm');
     if (isWpls(anchorAddress) || isWpls(wantedAddress))
         return [anchorAddress, wantedAddress];
     return [anchorAddress, wplsAddress, wantedAddress];
 };
-/**
- * The bridge provider that crosses each omnibridge entry point to PulseChain.
- *
- * Typed `Provider | null` rather than `string | null` — this is the root
- * source `RouteCandidate.omnibridgeProvider` and `RouteData.headlineProviderKey`
- * both derive from, so a widened return type here forced every caller downstream
- * to re-widen too, which is what let a wrong-kind key reach `providerDisplayName`
- * unnoticed. See `routing/candidate.ts` and `routing/route-data.ts`.
- */
 export const omnibridgeProviderForEntryChain = (entryChainId) => {
     const entryChain = toChain(entryChainId);
     if (entryChain === Chains.ETH)

package/dist/routing/search/compose.js

@@ -1,35 +1,6 @@
 import { assetNodeKey, combineComposedPathBasis } from './graph.js';
-/** The {@link ComposedPathBasis} one hop's figure contributes: `'quoted'` for a bound quote, its own basis for a `'probeRate'`. */
 export const composableHopBasis = (figure) => figure.kind === 'quote' ? 'quoted' : figure.basis;
-/**
- * Applies one {@link ExchangeRate} to an actual input amount, as an exact
- * bigint multiply-then-divide (floor division — the same rounding direction
- * a real on-chain quote would apply against the reader). Never routes the
- * amount through a float.
- *
- * @param inputAmount - the actual base-unit amount arriving at the hop
- * @param rate - the hop's observed {@link ExchangeRate}
- * @returns the estimated base-unit output
- */
 const applyExchangeRate = (inputAmount, rate) => (inputAmount * rate.numerator) / rate.denominator;
-/**
- * Composes a path's per-hop figures into one end-to-end estimated delivered
- * amount, applying design section 3's rule: a later hop's output is its
- * probe rate applied to the ACTUAL amount arriving at that hop — never the
- * reference amount the probe itself was taken at.
- *
- * REFUSES RATHER THAN GUESSES in three cases, checked hop by hop so the
- * refusal names the exact hop responsible: the path is empty
- * ({@link ComposeRefusalReason} `'empty-path'`); a hop does not connect to the
- * one before it (`'discontinuous-path'`); two hops disagree about a shared
- * asset's decimals (`'decimals-mismatch'`); or a `'probeRate'` figure names
- * no real ratio (`'missing-rate'`). See {@link ComposeRefusalReason} for why
- * each of these is a refusal and not a best-effort answer.
- *
- * @param inputAmount - the base-unit amount entering the path's first hop
- * @param hops - the path's hops, first to last
- * @returns the composed estimate, or the refusal that stopped composition
- */
 export const composeRouteDelivery = (inputAmount, hops) => {
     if (hops.length === 0) {
         return { kind: 'refused', reason: 'empty-path', hopIndex: 0 };
@@ -51,15 +22,6 @@ export const composeRouteDelivery = (inputAmount, hops) => {
     }
     return { kind: 'estimate', deliveredAmount: actualInput, basis };
 };
-/**
- * Checks that hop `hopIndex` connects to the hop before it: the same asset,
- * by {@link assetNodeKey}, with the same declared decimals. The first hop has
- * nothing before it and always passes.
- *
- * @param hops - the full path being composed
- * @param hopIndex - the hop to check against its predecessor
- * @returns the refusal reason, or null when the hop connects cleanly
- */
 const checkContinuity = (hops, hopIndex) => {
     if (hopIndex === 0)
         return null;
@@ -71,24 +33,6 @@ const checkContinuity = (hops, hopIndex) => {
         return 'decimals-mismatch';
     return null;
 };
-/**
- * One hop's output amount for the actual amount arriving at it: the quote's
- * own `outputAmount` when the figure is a real quote, or the probe rate
- * applied to `actualInput` when it is a `'probeRate'`. Returns null — never a
- * guessed number — when a `'probeRate'` figure's rate names no positive
- * denominator.
- *
- * EXPORTED SO `waves.ts` REUSES THIS MATH RATHER THAN RESTATING IT.
- * `recomposePath` (`waves.ts`) needs each hop's OWN output amount, not just
- * the path's final total {@link composeRouteDelivery} returns, to refresh
- * every hop's individual `outcome` — this is the one place that division
- * happens, so both call sites agree by construction instead of by two
- * separately-maintained copies of `numerator * input / denominator`.
- *
- * @param hop - the hop to price
- * @param actualInput - the actual base-unit amount arriving at this hop
- * @returns the hop's output amount, or null when its rate is missing
- */
 export const hopOutputAmount = (hop, actualInput) => {
     if (hop.figure.kind === 'quote')
         return hop.figure.outputAmount;

package/dist/routing/search/graph.js

@@ -1,236 +1,30 @@
 import { ecosystemById } from '../../ecosystems.js';
 import { providerRegistry } from '../../providers.js';
-/**
- * The stable, collision-free key for one {@link AssetNode}.
- *
- * Normalizes address casing through the ecosystem registry
- * (`ecosystemById(...).addressCasing`) before keying, so a checksummed and a
- * lower-cased reference to the SAME Ethereum address produce the SAME key —
- * two representations of one asset must key identically, or the search would
- * treat one node as two and silently duplicate work. An ecosystem whose
- * addresses are case-SIGNIFICANT (Solana, Tron, The Open Network, Bitcoin,
- * Zcash — see `ecosystems.ts`) is left exactly as given, because lower-casing
- * a case-significant address can turn it into a different, unrelated one.
- *
- * Collision-free for any two distinct `(chainId, normalizedAddress)` pairs:
- * `chainId` renders as a plain decimal numeral (never containing `:`), so the
- * FIRST `:` in the key always marks the same boundary a caller would expect,
- * and no two distinct pairs can render the same string.
- *
- * @param node - the asset to key
- * @returns the node's graph key, e.g. `"1:0xa0b8...eb48"`
- */
 export const assetNodeKey = (node) => {
     const casing = ecosystemById(node.ecosystem).addressCasing;
     const normalizedAddress = casing === 'insensitive' ? node.address.toLowerCase() : node.address;
     return `${node.chainId}:${normalizedAddress}`;
 };
-/** Every registered rate-limited provider id (LI.FI, Relay, NEAR Intents), as a lookup set. */
 const registeredProviderIds = new Set(providerRegistry.map((descriptor) => descriptor.id));
-/**
- * Whether `carrier` is one of the three rate-limited aggregators
- * (`ProviderId`) rather than a FREE local read (the omnibridge crossing or a
- * PulseX swap). Free carriers are asked on EVERY wave without counting
- * against `waves.ts`'s own request budget or per-provider concurrency cap —
- * design section 3: "Bridge and PulseX hops are free local reads ... done
- * exactly at any amount."
- *
- * CANONICAL HOME FOR THIS CHECK — PHASE 3. Moved here from `waves.ts` (which
- * re-exports it) because {@link compareRoutePlansByDeliveredAmount}'s own
- * tiebreak among unpriced plans needs it too (see that function's doc): a
- * free-carrier first hop is guaranteed a real answer, a rate-limited one is
- * not, and that distinction belongs on `HopCarrier` itself, not inside the
- * one module that happened to need it first.
- *
- * @param carrier - the carrier to classify
- * @returns true for `'lifi'`, `'relay'` or `'near-intents'`
- */
 export const isRateLimitedCarrier = (carrier) => registeredProviderIds.has(carrier);
-/**
- * The bases a ranking may compare a hop's `deliveredAmount` on — every
- * {@link EstimateBasis} except `'unpriced'`. `'unpriced'` is EXCLUDED ON
- * PURPOSE: it names a figure with no value behind it (see that member's own
- * doc), and a ranking that compared on it would be comparing one path's real
- * number against another path's decimal-shifted guess — exactly the defect
- * shadow mode found. A caller checking whether a hop or a whole plan may
- * enter a ranking reads this set (or calls {@link planIsRankable}), never a
- * hand-rolled `!== 'unpriced'` check, so the one rule lives in one place.
- *
- * THIS IS A SEARCH-ORDER RULE, NOT A REPORTING RULE — PHASE 3, SECOND ROUND.
- * `'priced-conversion'` stays in this set on purpose: `enumerate.ts`'s own
- * cut and `waves.ts`'s between-wave top-candidate selection both need SOME
- * way to compare two not-yet-quoted plans, and a price-feed conversion is a
- * far better signal for THAT purpose than no signal at all. It is a
- * DIFFERENT question whether a plan may be handed back to a reader as the
- * winner while still carrying `'priced-conversion'` on any hop — it may not;
- * see {@link isConfirmedBasis} and {@link planIsConfirmed}, the stricter pair
- * `waves.ts`'s own final return step applies, for that rule and the live
- * shadow-mode finding it closes (1 Zcash reported as 131.6 million Wrapped
- * Pulse via `'priced-conversion'`, against a real 33.3 million from the
- * pool's own `getAmountsOut` — a thin-pool price-impact gap `'priced-conversion'`
- * cannot see, because it never asks the pool at all).
- */
 export const RANKABLE_ESTIMATE_BASES = new Set([
     'probe-rate',
     'priced-conversion',
     'provider-model',
 ]);
-/**
- * Whether every hop of `hops` carries a figure a ranking may trust: a live
- * quote, or an estimate whose {@link EstimateBasis} is in
- * {@link RANKABLE_ESTIMATE_BASES} AND was never refused
- * ({@link HopOutcome.refusalReason} is `null`/`undefined`). False the moment
- * ANY hop is `'unpriced'` — one ungrounded hop taints the whole path's
- * composed figure, because composition multiplies every hop's figure into
- * the next (`compose.ts`), so a single meaningless number anywhere in the
- * chain makes the FINAL delivered amount meaningless too, however real the
- * other hops were.
- *
- * A REFUSED HOP IS UNRANKABLE EVEN WITH A GOOD BASIS. A hop that carries
- * `'priced-conversion'` or `'probe-rate'` still fails this check once a real
- * ask for it came back declined — see {@link HopOutcome.refusalReason}'s own
- * doc for the shadow-mode finding this closes: a refused hop's leftover
- * price-feed estimate has no fees behind it and kept beating real quotes,
- * because a provider's own refusal was never checked before the hop's
- * ORIGINAL basis was trusted again.
- *
- * A plan that fails this check is never dropped by this function — it is the
- * CALLER's job to decide what "not yet known" means for it (excluded from
- * being the ranked winner, but still held back in the list; see
- * `waves.ts`'s and `useRouteSearch.ts`'s own comparators, both of which sort
- * every unrankable plan below every rankable one rather than comparing raw
- * amounts across the two groups).
- *
- * @param hops - the plan's hops
- * @returns true when every hop's figure is trustworthy enough to rank on
- */
 export const planIsRankable = (hops) => hops.every((hop) => hop.outcome.kind === 'quote' ||
     (RANKABLE_ESTIMATE_BASES.has(hop.outcome.basis) && (hop.outcome.refusalReason ?? null) === null));
-/** How much a ranking trusts each {@link ComposedPathBasis}, highest first — private to this module's own combination and rankability logic. */
 const COMPOSED_PATH_BASIS_RANK = {
     quoted: 3,
     'probe-rate': 2,
     'priced-conversion': 1,
-    // SAME TIER AS `'priced-conversion'`, ON PURPOSE — both are rankable (see
-    // `RANKABLE_ESTIMATE_BASES`) but neither ever asked a real provider for
-    // THIS edge, so neither may report as a confirmed winner
-    // (`isConfirmedBasis` requires rank 2 or higher, `probe-rate`'s own tier).
     'provider-model': 1,
     unpriced: 0,
 };
-/**
- * Combines two hops' (or two paths') bases into the basis their COMPOSITION
- * deserves: the WORSE of the two, never the better one and never an average.
- * A composed figure is a chain — `hop2`'s output is computed FROM `hop1`'s
- * output — so if either link is `'unpriced'`, the number at the far end
- * carries no value regardless of how solid the other link was. "Worst wins"
- * is the only rule that keeps that true; picking the better basis (or the
- * LAST hop's own basis, which an earlier draft of this reasoning tried) would
- * let one grounded hop launder an ungrounded one earlier in the same chain.
- *
- * @param a - one basis being combined
- * @param b - the other
- * @returns whichever of `a`/`b` a ranking trusts less
- */
 export const combineComposedPathBasis = (a, b) => (COMPOSED_PATH_BASIS_RANK[a] <= COMPOSED_PATH_BASIS_RANK[b] ? a : b);
-/**
- * Whether a ranking may compare on `basis` — true for every
- * {@link ComposedPathBasis} except `'unpriced'`. The whole-path counterpart to
- * {@link RANKABLE_ESTIMATE_BASES}; see that constant's doc for the rule both
- * enforce.
- *
- * @param basis - the composed path basis to check
- * @returns false only for `'unpriced'`
- */
 export const isRankableBasis = (basis) => basis !== 'unpriced';
-/**
- * Whether a ranking may report `basis` as a WINNER — true only for
- * `'quoted'` and `'probe-rate'`, i.e. {@link COMPOSED_PATH_BASIS_RANK} of 2 or
- * higher. FALSE for `'priced-conversion'`, even though {@link isRankableBasis}
- * accepts it — see that function's own "SEARCH-ORDER RULE, NOT A REPORTING
- * RULE" note for why the two disagree on that one basis, on purpose.
- *
- * THE DEFECT THIS CLOSES. A live shadow comparison found 1 Zcash routed to
- * Pulse (Wrapped) through the Binance Smart Chain omnibridge reported 131.6
- * million Wrapped Pulse on `'priced-conversion'` — a United States dollar
- * price-feed conversion that never asks the destination PulseX pool at all
- * — while the pool's OWN `getAmountsOut` answers 33.3 million for the same
- * size (86,540 per unit at 1 unit, 13,121 per unit at 1,500 units: an 84.8%
- * worse rate at real size). `isRankableBasis` treated the two bases as
- * equally trustworthy, so the price-feed number stood as the reported
- * winner. `'priced-conversion'` IGNORES PRICE IMPACT BY CONSTRUCTION
- * (`buildEstimateHopOutput`, `packages/ui/src/lib/state/useRouteSearch.ts`,
- * converts through a flat United States dollar rate on each side, with no
- * pool, no depth and no size in the computation) — it is not merely
- * unconfirmed, it is blind to the one thing that broke here, so no amount of
- * "it is probably close enough" reasoning can rescue it.
- *
- * WHY `'probe-rate'` IS STILL ACCEPTED HERE. A hop's basis is `'probe-rate'`
- * ONLY WHEN A REAL PROVIDER (or a free local read — `getAmountsOut` included)
- * ANSWERED THAT EXACT EDGE — see {@link HopOutcome}'s own doc and
- * `waves.ts`'s `recomposePath`, whose fallback branch always carries forward
- * a hop's ORIGINAL, pre-network basis (`'priced-conversion'`/`'unpriced'`,
- * NEVER `'probe-rate'`) rather than inventing one. So a `'probe-rate'` hop is
- * always grounded in a real, size-aware answer for SOME amount — the one
- * residual imprecision is that `waves.ts`'s early waves may have asked it at
- * an amount close to, but not exactly, the plan's final fully-propagated
- * figure (see `waves.ts`'s own "confirmation pass" doc for how the final
- * return step narrows that gap for a plan's TOP candidates before this
- * function is ever consulted). A real answer at a slightly-off size still
- * beats a number no provider was ever asked for at any size.
- *
- * @param basis - the composed path basis to check
- * @returns true only for `'quoted'` and `'probe-rate'`
- */
 export const isConfirmedBasis = (basis) => COMPOSED_PATH_BASIS_RANK[basis] >= COMPOSED_PATH_BASIS_RANK['probe-rate'];
-/**
- * What grounds a WHOLE PLAN's delivered figure, read directly off its hops'
- * own `outcome`s — the WORST (least-grounded) {@link ComposedPathBasis} across
- * every hop, folded with {@link combineComposedPathBasis} exactly as
- * `compose.ts`'s `composeRouteDelivery` folds one while a path is being
- * actively composed.
- *
- * USE THIS ONCE A PLAN'S HOPS ALREADY CARRY THEIR FINAL `outcome`S — a
- * finished `enumerate.ts`/`waves.ts` plan — rather than re-deriving a fresh
- * `ComposedRouteDelivery` from scratch. `buildRouteScoreInputsFromPlan`
- * (`plan-route-data.ts`) is the first caller, feeding `scoreRoutePlan`
- * (`score.ts`) the one figure it needs to refuse ever scoring an unpriced
- * plan as if its `deliveredUsd` meant anything.
- *
- * AGREES WITH {@link planIsRankable} BY CONSTRUCTION, NEVER BY COINCIDENCE:
- * `isRankableBasis(planComposedBasis(hops)) === planIsRankable(hops)` for
- * every plan, because "worst wins" and "true unless any hop is unpriced" are
- * the same rule read two ways — see `graph.test.ts`'s own test pinning that
- * equivalence so the two can never quietly drift apart.
- *
- * A REFUSED HOP FOLDS AS `'unpriced'`, WHATEVER ITS OWN `basis` SAYS — the
- * same rule {@link planIsRankable} applies, read through
- * {@link combineComposedPathBasis}'s "worst wins": a hop a real provider has
- * declined is worse-grounded than any {@link EstimateBasis}, refused or not.
- * This is WHY {@link isRankableBasis}`(planComposedBasis(hops)) === planIsRankable(hops)`
- * still holds for every plan — see this function's own "AGREES WITH..." note
- * below.
- *
- * @param hops - the plan's hops
- * @returns the plan's composed basis; `'quoted'` (the fold's identity value)
- *   for an empty plan
- */
 export const planComposedBasis = (hops) => hops.reduce((basis, hop) => combineComposedPathBasis(basis, hopComposedBasis(hop)), 'quoted');
-/**
- * The {@link ComposedPathBasis} one hop contributes to
- * {@link planComposedBasis}'s fold: `'quoted'` for a live quote, `'unpriced'`
- * for a REFUSED estimate regardless of its own `basis` (see
- * {@link planComposedBasis}'s own "REFUSED HOP" note), else the estimate's
- * own `basis`.
- *
- * EXPORTED FOR `waves.ts`'s OWN "confirmation pass" — the final step,
- * described on {@link isConfirmedBasis}'s own doc, that upgrades a
- * TOP-ranked plan's still-estimated free-carrier hops to a real quote before
- * the search returns. That pass needs the SAME per-hop fold this function
- * already applies (a hop a real provider has since refused is no better
- * grounded than one that was never asked) to decide WHICH hops still need
- * upgrading, so it reuses this rather than re-deriving the fold by hand.
- */
 export const hopComposedBasis = (hop) => {
     if (hop.outcome.kind === 'quote')
         return 'quoted';
@@ -238,90 +32,12 @@ export const hopComposedBasis = (hop) => {
         return 'unpriced';
     return hop.outcome.basis;
 };
-/**
- * Whether every hop of `hops` carries a CONFIRMED figure — read straight off
- * {@link planComposedBasis} through {@link isConfirmedBasis}, so this agrees
- * with that function BY CONSTRUCTION, never by coincidence, exactly as
- * {@link planIsRankable} agrees with {@link isRankableBasis} (see that pair's
- * own "AGREES WITH" note above). STRICTER than {@link planIsRankable}: every
- * confirmed plan is rankable, but a rankable plan carrying `'priced-conversion'`
- * on any hop is not confirmed — see {@link isConfirmedBasis}'s own doc for why.
- *
- * USE THIS TO DECIDE WHAT A SEARCH MAY REPORT AS A WINNER. `waves.ts`'s own
- * final return step is the one caller that PARTITIONS on this (confirmed
- * plans ahead of unconfirmed ones, each group's own search-order preserved)
- * — see that module's "confirmation pass" doc. NEVER use this to prune or
- * rank DURING search: `planIsRankable` is still the correct predicate for
- * `enumerate.ts`'s cut and `waves.ts`'s between-wave top-candidate
- * selection, so `'priced-conversion'` keeps doing its job there exactly as
- * before — see {@link RANKABLE_ESTIMATE_BASES}'s own "SEARCH-ORDER RULE, NOT
- * A REPORTING RULE" note.
- *
- * @param hops - the plan's hops
- * @returns true when every hop's figure is confirmed by a real ask
- */
 export const planIsConfirmed = (hops) => isConfirmedBasis(planComposedBasis(hops));
-/**
- * Encodes one string as a length-prefixed ("netstring") segment: `"3:abc"`.
- *
- * WHY THIS AND NOT A DELIMITER. Joining segments with a fixed delimiter
- * (`"|"`, `":"`, ...) collides whenever a segment can itself contain that
- * delimiter — and a `HopEdge` key is built FROM asset addresses, which this
- * module does not control the alphabet of. Prefixing each segment with its
- * own length makes the boundary self-describing: reconstructing the segment
- * count from the encoded string requires no assumption about what characters
- * appear inside a segment, so two different segment sequences can never
- * encode to the same string. See `graph.test.ts` for a worked collision that
- * a plain delimiter join would produce and this does not.
- *
- * @param value - the segment to encode
- * @returns the length-prefixed segment
- */
 const netstringEncode = (value) => `${value.length}:${value}`;
-/**
- * The stable, collision-free key for one {@link HopEdge}.
- *
- * The {@link HopEdge.venue}, when present, is a fourth segment: two venues
- * between the same assets are two edges, so they must never share a key (a
- * path deduplication or an answer cache would otherwise merge them). An edge
- * with no venue keeps its three-segment key unchanged.
- *
- * @param edge - the edge to key
- * @returns the edge's key, built from its carrier, its two node keys, and its venue when it has one
- */
 export const hopEdgeKey = (edge) => [edge.carrier, assetNodeKey(edge.from), assetNodeKey(edge.to), ...(edge.venue === undefined ? [] : [edge.venue])]
     .map(netstringEncode)
     .join('');
-/**
- * The stable, collision-free key for a whole path — the value
- * {@link RoutePlan.pathKey} must hold.
- *
- * Two DIFFERENT hop sequences never produce the same key, and the SAME
- * sequence always produces the same key, because each hop's key is
- * length-prefixed before joining (see {@link netstringEncode}). This is what
- * makes the key usable for deduplicating plans found by different search
- * paths that happen to walk the same edges.
- *
- * @param hops - the plan's hops, first to last
- * @returns the path's key
- */
 export const routePlanPathKey = (hops) => hops.map((hop) => netstringEncode(hopEdgeKey(hop.edge))).join('');
-/**
- * Groups a plan's hops into signature groups, as hop indices.
- *
- * THE ONE RULE: a hop whose PREDECESSOR fused it (`fusesNext` was true on the
- * hop before it) joins that predecessor's group; every other hop — including
- * the first — starts a new one. A pay-by-hand hop needs no special case
- * either: {@link HopEdge.origin} only says how a hop is FUNDED, not whether it
- * groups with what follows, and design section 1 is explicit that a
- * pay-by-hand deposit "counts as one reader action but needs no wallet
- * signature" — a fact for the ACTION count Phase 1's `score.ts` will compute
- * (design section 4, the `A` term), not a fact about signature grouping.
- *
- * @param hops - the plan's hops, first to last
- * @returns the hop index groups, in signature order — the outer array's
- *   length is the plan's signature count
- */
 export const groupHopsBySignature = (hops) => {
     const groups = [];
     hops.forEach((_currentHop, index) => {
@@ -335,57 +51,10 @@ export const groupHopsBySignature = (hops) => {
     });
     return groups;
 };
-/**
- * Whether `plan`'s FIRST hop is a FREE carrier (the omnibridge crossing or a
- * PulseX swap) rather than a rate-limited aggregator ({@link isRateLimitedCarrier}).
- * A free first hop is asked on every wave of `waves.ts`'s own search
- * unconditionally — never skipped for a spent request budget — so a plan
- * with one is guaranteed a real answer; a rate-limited first hop competes
- * with every other rate-limited ask for `WAVE_0_MAX_REQUESTS` and can be
- * silently skipped when the budget runs out before it. {@link compareUnrankablePlans}
- * is the one place this distinguishes two plans neither of which has a
- * trustworthy figure yet.
- *
- * @param plan - the plan to classify
- * @returns true when the plan's first hop is free, false for a rate-limited
- *   first hop or an empty plan
- */
 const firstHopIsFreeCarrier = (plan) => {
     const firstHop = plan.hops[0];
     return firstHop !== undefined && !isRateLimitedCarrier(firstHop.edge.carrier);
 };
-/**
- * Orders two UNRANKABLE plans (both fail {@link planIsRankable}) — PHASE 3,
- * closing the gap `compareRoutePlansByDeliveredAmount` left: within this
- * group `deliveredAmount` is not a real signal at all, it is a bare decimal
- * rescale with no value behind it (`EstimateBasis`'s own doc), so an earlier
- * version of that comparator fell back to comparing it anyway — an EMERGENT
- * tiebreak that happened to work only because nothing else was tried. That
- * let an entirely unrelated, equally-ungrounded plan win the enumeration
- * cut's remaining slots (and `waves.ts`'s wave-0 request-budget priority,
- * which reads plans in this same order) purely because its decimal point
- * happened to land somewhere bigger — discarding, in the worst case, the
- * price-feed-blind but perfectly real DIRECT omnibridge crossing in favour
- * of aggregator noise.
- *
- * THE EXPLICIT RESERVATION, IN RANK ORDER:
- *
- * 1. A plan whose first hop is a FREE carrier ({@link firstHopIsFreeCarrier})
- *    sorts ahead of one whose first hop is rate-limited — a free hop is
- *    GUARANTEED a real wave-0 answer; a rate-limited one is only a maybe,
- *    gated by a shared, exhaustible budget.
- * 2. Within the same free-or-not group, fewer hops sorts first — a shorter
- *    plan costs less of that shared budget to try and is simpler to execute,
- *    matching this search's own hop/signature caps (design section 2).
- * 3. A final, purely COSMETIC tiebreak — the plan's own stable `pathKey`,
- *    lexicographically — keeps the comparator total and deterministic.
- *    Never `deliveredAmount`: see this function's own head note for why.
- *
- * @param a - one unrankable plan being compared
- * @param b - the other
- * @returns negative when `a` ranks ahead of `b`, positive when `b` ranks
- *   ahead of `a`, zero when they tie
- */
 const compareUnrankablePlans = (a, b) => {
     const freeFirstHopA = firstHopIsFreeCarrier(a);
     const freeFirstHopB = firstHopIsFreeCarrier(b);
@@ -397,39 +66,6 @@ const compareUnrankablePlans = (a, b) => {
         return 0;
     return a.pathKey < b.pathKey ? -1 : 1;
 };
-/**
- * THE ONE PLACE THIS COMPARATOR IS WRITTEN. Every rankable plan
- * ({@link planIsRankable}) sorts ahead of every unrankable one, whatever its
- * raw `deliveredAmount` claims to be — a QUOTABLE plan never loses its slot
- * to one that is not, at the enumeration cut or anywhere else this
- * comparator runs. Within the same rankability group: two RANKABLE plans
- * compare on the larger last-hop delivered amount, a real signal; two
- * UNRANKABLE plans compare with {@link compareUnrankablePlans} instead, per
- * that function's own doc, because `deliveredAmount` carries no signal for
- * that group at all. Bigint-safe throughout for the rankable branch — never
- * widens to `Number`, which would lose precision on a large delivered amount
- * long before the comparison needed it to.
- *
- * IMPORTED, NEVER RESTATED — PHASE 3's OWN CLOSE-THE-GAP RULE. Three
- * independent call sites need exactly this rule: `enumerate.ts`'s own
- * default (its top-N keep, applied to freshly enumerated plans — the SAME
- * cut that decides which plans even reach `waves.ts`'s request budget),
- * `waves.ts`'s default (its between-wave re-ranking), and
- * `packages/ui/src/lib/state/useRouteSearch.ts`'s final sort. Before this
- * function existed, two of those three each carried their own hand-written
- * copy of the identical rule — a DRY violation that is also a correctness
- * risk: a future edit to one copy (say, widening `RANKABLE_ESTIMATE_BASES`)
- * could silently fail to reach the other, reopening the exact defect shadow
- * mode measured (an unpriced 276 PLS outranking a priced 23 million PLS).
- * Importing this one function everywhere a plan-to-plan comparison happens
- * is what makes that drift structurally impossible rather than merely
- * against convention.
- *
- * @param a - one plan being compared
- * @param b - the other
- * @returns negative when `a` ranks ahead of `b`, positive when `b` ranks
- *   ahead of `a`, zero when they tie
- */
 export const compareRoutePlansByDeliveredAmount = (a, b) => {
     const rankableA = planIsRankable(a.hops);
     const rankableB = planIsRankable(b.hops);