@gibs/bridge-sdk 1.12.0 → 1.13.1

package/dist/routing/search/graph.d.ts

@@ -0,0 +1,653 @@
+import { type Ecosystem } from '../../ecosystems.js';
+import { type ProviderId } from '../../providers.js';
+import type { EstimateBasis } from '../route-data.js';
+/**
+ * PHASE 0 — FOUNDATION ONLY. This module fixes the pure data model for the
+ * general route search described in the route-search design (section 1). It
+ * introduces no search, no quoting, and no behaviour change: nothing outside
+ * this file constructs one of these types yet. Phase 1 (`capabilities.ts`,
+ * `enumerate.ts`) is what starts building {@link AssetNode}s, {@link HopEdge}s
+ * and {@link RoutePlan}s from live provider data.
+ *
+ * WHY A GRAPH AT ALL. Today the bridge special-cases each shape a route can
+ * take: a same-chain crossing, an aggregator fused with the bridge, a two-step
+ * NEAR Intents route, a conversion swap. Modelling every route as a walk over
+ * a small graph of {@link AssetNode}s joined by {@link HopEdge}s replaces the
+ * special cases with one search over one structure — see the design's
+ * section 6, "what it absorbs."
+ */
+/**
+ * One stop in the route graph: a specific token, on a specific chain, in a
+ * specific ecosystem. Nodes are the graph's vertices; {@link HopEdge}s are its
+ * directed edges.
+ *
+ * KEYED AS `chainId:address`, not by object identity, so two independently
+ * built references to "USD Coin on Ethereum" collapse to the same graph
+ * vertex. Use {@link assetNodeKey} to compute that key — never format the
+ * template by hand, because the key normalizes address casing per ecosystem
+ * (see {@link assetNodeKey}) and a hand-formatted string would silently skip
+ * that normalization.
+ *
+ * WHY A COIN AND ITS WRAPPED FORM ARE NOT MERGED HERE. `AssetNode` names one
+ * literal address; native ether (the zero address) and wrapped ether (WETH)
+ * are and stay two distinct nodes. The two are equivalent ONLY in one
+ * specific circumstance — the next hop is an omnibridge entry call — because
+ * the router wraps the coin on the way in and mints the SAME PulseChain token
+ * either anchor would have minted (`wrapAndRelayTokens`; see
+ * `entryChainAnchorsForPair` in `../entry-chain-anchor.js` and its module doc
+ * for the measurements behind this). That equivalence is a property of ONE
+ * EDGE (an entry call accepting either anchor), not of the node graph as a
+ * whole — a USD Coin pair gains no such alias, and neither does a native
+ * coin whose next hop is NOT a bridge entry call. So the aliasing is Phase
+ * 1's job, applied when `enumerate.ts` builds edges INTO a bridge entry hop,
+ * by trying both anchors from `entryChainAnchorsForPair` rather than by
+ * collapsing nodes here. Collapsing it into the node graph itself would make
+ * every consumer of `AssetNode` reason about an aliasing rule that applies to
+ * only one kind of edge.
+ */
+export type AssetNode = {
+    /** Decimal chain id this asset lives on. */
+    readonly chainId: number;
+    /**
+     * The token's on-chain address, in the ecosystem's own notation — hex for
+     * an EVM chain, base58 for Solana or Tron, a user-friendly string for The
+     * Open Network, and so on. Treat it as opaque; only {@link assetNodeKey}
+     * and code that already knows the ecosystem should normalize it.
+     */
+    readonly address: string;
+    /** Which ecosystem `chainId` belongs to — governs address casing and carrier support. */
+    readonly ecosystem: Ecosystem;
+    /**
+     * The number of decimal places this token's base units carry. A fixed fact
+     * about the token, kept on the node so any hop that touches it — most
+     * directly `search/compose.ts`, composing a delivered amount across hops —
+     * can check two mentions of the SAME node against each other without a
+     * second lookup.
+     *
+     * ADDED IN PHASE 1, FOR `compose.ts`. Composing amounts hop to hop must
+     * refuse rather than guess when two hops disagree about a shared token's
+     * decimals — two independent provider integrations naming the same token
+     * with two different decimal counts is exactly the kind of silent data bug
+     * `compose.ts` is required to catch instead of composing through. Carrying
+     * `decimals` on the node is what makes that check possible without adding
+     * a second, decimals-only lookup structure that could itself drift from
+     * this one. Phase 0 shipped {@link AssetNode} without this field because
+     * nothing yet constructed one; this is the first module that does.
+     */
+    readonly decimals: number;
+};
+/**
+ * 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 declare const assetNodeKey: (node: AssetNode) => string;
+/**
+ * Identifies one carrier that can move funds across a {@link HopEdge}: a
+ * plain string, NOT a closed union.
+ *
+ * FORMERLY `ProviderKey` (`ProviderId | Provider | 'PulseX'`) — a union that
+ * baked gibs's own carrier names (`'pulsechain'`, `'tokensex'`, `'PulseX'`)
+ * directly into the search engine's data model. The engine (this module,
+ * `capabilities.ts`, `enumerate.ts`, `waves.ts` — the latter three now living
+ * in `@gibs/quotes`'s `search/` directory) is a plug-in host: it takes
+ * whatever carriers it is registered with and names none of them itself. A
+ * host names its own carriers by registering objects whose `id` is one of
+ * these strings — gibs's own `'pulsechain'`, `'tokensex'` and `'PulseX'`
+ * among them, from `routing/carriers/` — and every existing lookup table
+ * keyed on a carrier's identity (a logo, a display name) stays keyed on the
+ * SAME strings as before; only the TYPE that names them widened from a
+ * closed union to `string`.
+ */
+export type CarrierId = string;
+/**
+ * @deprecated Use {@link CarrierId}. Kept as an alias so existing imports of
+ * this name keep compiling; it is no longer the closed `ProviderKey` union.
+ */
+export type HopCarrier = CarrierId;
+/**
+ * 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 declare const isRateLimitedCarrier: (carrier: HopCarrier) => carrier is ProviderId;
+/**
+ * How a hop's crossing is initiated.
+ *
+ * `'wallet'` — the reader (or a prior hop's aggregator, on arrival) signs a
+ * transaction. `'by-hand'` — the reader sends funds to a deposit address
+ * outside any wallet flow this application controls (a Zcash shielded send,
+ * for example), which is how a NEAR Intents pay-by-hand origin funds its
+ * first hop. See design section 2: "a pay-by-hand origin's first hop must be
+ * NEAR."
+ */
+export type HopEdgeOrigin = 'wallet' | 'by-hand';
+/**
+ * A known minimum amount this edge has already been refused below.
+ *
+ * EMPTY ON EVERY EDGE PHASE 0 OR PHASE 1's `enumerate.ts` PRODUCES. Floors
+ * are learned from a provider's own refusal — NEAR's `belowChainMinimum`, the
+ * bridge's `minPerTx`, a Relay or LI.FI minimum from `quote-refusals.ts` —
+ * which only happens once a real request has been made. Phase 1's
+ * `waves.ts` is what populates this, feeding a floor learned on one search
+ * into the pruning step of the next (design section 2: "a known floor must
+ * be at or below the amount"; section 3: "refusals feed a floors cache that
+ * prunes later searches"). The type is fixed here because `HopEdge` needs a
+ * concrete shape for the field, not because anything writes to it yet.
+ */
+export type HopFloor = {
+    /** Why the floor exists, e.g. `"near-chain-minimum"`, `"bridge-min-per-tx"`. */
+    readonly reason: string;
+    /** The minimum amount this edge accepts, in the edge's `from` node's base units. */
+    readonly minimumAmount: bigint;
+};
+/**
+ * One directed edge in the route graph: a single carrier moving funds from
+ * one {@link AssetNode} to another.
+ */
+export type HopEdge = {
+    /** Which carrier performs this hop. */
+    readonly carrier: HopCarrier;
+    /** The asset this hop consumes. */
+    readonly from: AssetNode;
+    /** The asset this hop produces. */
+    readonly to: AssetNode;
+    /**
+     * Whether this hop's carrier performs the NEXT hop's entry call itself on
+     * arrival, so the two hops together cost the reader only ONE signature.
+     *
+     * True only when BOTH hold: this carrier's `executesDestinationCalls` is
+     * true (see `../../providers.js`), and the next hop is a bridge entry call
+     * — `relayTokens` or `wrapAndRelayTokens` — on the chain this hop lands on.
+     * Today that means an LI.FI or Relay leg immediately followed by the
+     * omnibridge crossing; every other adjacent pair costs a second signature.
+     *
+     * NEAR IS ALWAYS FALSE. Its `executesDestinationCalls` is false — it
+     * delivers to the reader's own wallet and stops (see the head of
+     * `../../providers.js`, the `nearIntentsDescriptor` entry) — so a NEAR hop
+     * can never satisfy the first condition, whatever follows it. This is WHY
+     * every NEAR Intents route today takes two signatures, and it is also why
+     * {@link groupHopsBySignature} needs no special case for NEAR: a hop whose
+     * `fusesNext` is always false always ends its own signature group on its
+     * own, by the same rule that governs every other hop.
+     *
+     * LEAVING PULSECHAIN IS ALSO ALWAYS FALSE. The omnibridge's outbound leg
+     * delivers the anchor token to the reader's own wallet on the entry chain
+     * and stops — it has no executor of its own that could carry an aggregator
+     * call forward — so a hop that leaves PulseChain can never fuse with
+     * whatever aggregator leg follows it either. This is the existing
+     * "outbound with onward hop" case (design section 6): the bridge-out leg
+     * and the aggregator that continues from it are always two signatures.
+     */
+    readonly fusesNext: boolean;
+    /** How this hop's crossing is initiated. */
+    readonly origin: HopEdgeOrigin;
+    /** Minimum amounts already learned for this edge; empty until a search records a refusal. */
+    readonly floors: readonly HopFloor[];
+    /**
+     * Which of the carrier's own execution venues performs this hop, when the
+     * carrier has more than one between the same two assets — opaque to the
+     * graph. Two edges that differ only here are two different hops: each is
+     * quoted, ranked and signed on its own venue, never on the other's.
+     *
+     * ABSENT for a carrier with one venue. The carrier that sets it is the one
+     * that reads it back (for example, which router signs a swap), so the
+     * route search never interprets the value.
+     */
+    readonly venue?: string;
+};
+/**
+ * The provider-specific request and outcome for one planned hop.
+ *
+ * `request` is deliberately `unknown` in Phase 0: each carrier's request is a
+ * different shape (`ConsolidatedQuoteRequest` for LI.FI/Relay, NEAR's own
+ * pre-quote/quote request, a bare fee-rate read for the bridge, a
+ * `getAmountsOut` call for PulseX), and Phase 0 introduces no coupling to any
+ * one of them. Phase 1's `waves.ts` is what gives this field a real,
+ * carrier-discriminated type once the quoting waves exist to fill it.
+ */
+export type HopRequest = unknown;
+/**
+ * PHASE 3 — what GROUNDS an `'estimate'` {@link HopOutcome} (or a composed
+ * path figure, see `compose.ts`'s {@link ComposedPathBasis}): `'probe-rate'`
+ * (a real provider answered this edge, at some reference amount),
+ * `'priced-conversion'` (both endpoints carry a real United States dollar
+ * price and the figure converts value through them), or `'unpriced'` (a bare
+ * decimal rescale with no value behind it, `restateInDecimals`, `../amounts.js`).
+ *
+ * DECLARED IN `../route-data.ts`, IMPORTED HERE, NOT REDECLARED — that module
+ * is this search engine's lower, display-facing data layer (`RouteData`,
+ * `RouteLandingData.estimateBasis`, `RouteOutputData.estimateBasis`), so the
+ * union belongs where ITS consumers can read it without depending upward on
+ * `search/`; see that module's own doc for the full rule, including why
+ * `'unpriced'` never reaches a `RouteLandingData`/`RouteOutputData` field.
+ * Re-exported from here because this whole module (and `compose.ts`,
+ * `enumerate.ts`, `waves.ts`) already names it relative to `./graph.js` —
+ * one declaration, reachable both ways.
+ *
+ * THIS IS THE TYPE THE ROUTE-SEARCH DESIGN'S OWN RISK LIST WAS MISSING: a
+ * decimal-rescaled bigint and a genuinely priced one are indistinguishable BY
+ * SHAPE — both are a positive bigint — so nothing downstream could tell one
+ * from the other without this field. Shadow mode against the running search
+ * found exactly that gap: on three of five test routes the engine's
+ * top-ranked path delivered about 276 PLS where today's routing delivers
+ * about 23 million PLS, because a hop with no price-feed entry fell back to
+ * a bare decimal rescale and nothing marked that number as untrustworthy
+ * before it reached the ranking — see {@link RANKABLE_ESTIMATE_BASES}.
+ */
+export type { EstimateBasis };
+/**
+ * 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 declare const RANKABLE_ESTIMATE_BASES: ReadonlySet<EstimateBasis>;
+/**
+ * What a planned hop is expected to deliver.
+ *
+ * `'quote'` — a live, provider-confirmed answer (signature 1 must always be
+ * one of these; see design section 3, "only signature 1 must be binding").
+ * `'estimate'` — a probed or composed figure for a hop that has not been
+ * bindingly quoted yet (every later hop, until the reader returns to it),
+ * carrying the {@link EstimateBasis} that grounds it — see that type's own
+ * doc for why this field exists and what breaks without it.
+ */
+export type HopOutcome = {
+    readonly kind: 'quote';
+    /** What the carrier is bound to deliver, in the hop's `to` node's base units. */
+    readonly deliveredAmount: bigint;
+    /**
+     * The least the carrier promises to deliver after its own slippage
+     * tolerance, in the same units — present only when a provider's live
+     * answer stated one.
+     *
+     * WHY A SIGNER NEEDS IT. A provider hop that FUSES with the omnibridge
+     * entry (`HopEdge.fusesNext`) is signed as an exact-output request, and
+     * the entry call it performs embeds a fixed amount. That amount is this
+     * minimum — the owner's two-phase rule: the pre-quote's floor becomes
+     * the target, and the unspent remainder is the reader's cushion. So the
+     * hop that follows a fused one is composed from this figure, never from
+     * {@link deliveredAmount}, and the section's signer reads it back to
+     * build exactly the request the route was priced for.
+     */
+    readonly minimumDeliveredAmount?: bigint;
+    /**
+     * How far the hop's executed rate falls below its marginal rate, in
+     * percent — present only when the carrier measured it from its own
+     * pool reserves (a PulseX swap). Absent means "not measured", never zero.
+     */
+    readonly priceImpactPercent?: number;
+} | {
+    readonly kind: 'estimate';
+    /** The composed/probed figure, in the hop's `to` node's base units. */
+    readonly deliveredAmount: bigint;
+    /** What grounds this figure — see {@link EstimateBasis}. */
+    readonly basis: EstimateBasis;
+    /**
+     * Non-null when a REAL ask for this hop came back refused rather than
+     * simply never being asked (or still in flight) — `waves.ts`'s
+     * `recomposePath` is the one place that sets it, from the cached
+     * {@link @gibs/bridge-sdk/routing/search/waves!EdgeRefusal}'s own
+     * `reason` (or its `kind` when the provider gave no reason). `null` or
+     * `undefined` means "not refused": never asked, still pending, or
+     * genuinely answered.
+     *
+     * WHY THIS EXISTS, SEPARATELY FROM `basis`. `basis` says what GROUNDS
+     * `deliveredAmount` — where the number came from. It says nothing about
+     * whether a real provider has SINCE said this edge cannot carry the
+     * plan's amount at all. A hop can carry a perfectly good
+     * `'priced-conversion'` basis (a real United States dollar price on
+     * both ends) and still be refused — a shadow comparison against the
+     * live search found exactly this: a refused hop's price-feed estimate
+     * has no fees behind it and kept outranking real quotes, because
+     * nothing marked it untrustworthy once the refusal came back. See
+     * {@link planIsRankable}, which is where a non-null reason here takes
+     * effect.
+     *
+     * KEPT FOR DISPLAY, NOT HIDDEN LIKE `'unpriced'`. Reusing `'unpriced'`
+     * for a refused hop would also blank its `deliveredAmount` from every
+     * display that checks `basis === 'unpriced'` (`plan-route-data.ts`'s
+     * `hopOutcomeIsUnpriced`) — losing a real, price-feed-grounded number
+     * the reader can still usefully see, just not one bridge-sdk may rank
+     * a plan on any more.
+     */
+    readonly refusalReason?: string | null;
+    /**
+     * The price impact measured when the carrier answered this hop exactly,
+     * carried onto the rescaled estimate when an upstream amount moved and
+     * the exact figure no longer applies verbatim. Impact grows roughly in
+     * proportion to the trade, so the carried figure stays close for the
+     * small moves a live upstream quote makes. Absent means "not measured".
+     */
+    readonly priceImpactPercent?: number;
+};
+/**
+ * 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 declare const planIsRankable: (hops: readonly PlannedHop[]) => boolean;
+/**
+ * What grounds a WHOLE COMPOSED PATH's figure — {@link EstimateBasis} widened
+ * with `'quoted'`, for the one case a single hop's basis cannot express: every
+ * hop in the path was itself a live `'quote'`. `compose.ts`'s
+ * {@link @gibs/bridge-sdk/routing/search/compose!ComposedRouteDelivery} carries
+ * one of these, computed as the WORST (least-grounded) basis across every hop
+ * composed — see {@link combineComposedPathBasis} for why "worst wins" is the
+ * only correct combination rule.
+ */
+export type ComposedPathBasis = 'quoted' | EstimateBasis;
+/**
+ * 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 declare const combineComposedPathBasis: (a: ComposedPathBasis, b: ComposedPathBasis) => ComposedPathBasis;
+/**
+ * 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 declare const isRankableBasis: (basis: ComposedPathBasis) => boolean;
+/**
+ * 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 declare const isConfirmedBasis: (basis: ComposedPathBasis) => boolean;
+/**
+ * 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 declare const planComposedBasis: (hops: readonly PlannedHop[]) => ComposedPathBasis;
+/**
+ * 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 declare const hopComposedBasis: (hop: PlannedHop) => ComposedPathBasis;
+/**
+ * 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 declare const planIsConfirmed: (hops: readonly PlannedHop[]) => boolean;
+/** One hop of a {@link RoutePlan}: the edge it travels, its request, and its outcome. */
+export type PlannedHop = {
+    /** The graph edge this hop travels. */
+    readonly edge: HopEdge;
+    /** The provider-specific request that would produce (or produced) {@link outcome}. */
+    readonly request: HopRequest;
+    /** What this hop delivers — a binding quote, or an estimate awaiting one. */
+    readonly outcome: HopOutcome;
+};
+/**
+ * One complete, priced-or-estimated path through the route graph, from the
+ * reader's origin asset to their destination asset.
+ */
+export type RoutePlan = {
+    /** The plan's hops, first to last. */
+    readonly hops: readonly PlannedHop[];
+    /**
+     * The plan's hops grouped into signatures, as hop INDICES into {@link hops}.
+     * Build this with {@link groupHopsBySignature} rather than by hand — see its
+     * doc for the one rule it applies.
+     */
+    readonly signatures: readonly (readonly number[])[];
+    /**
+     * The plan's stable identity, for deduplication and for `pathKeyFor` in
+     * `journeyPlan.ts` to prefer over its current entry-chain-only key (design
+     * section 1). Build this with {@link routePlanPathKey}, never by hand.
+     */
+    readonly pathKey: string;
+};
+/**
+ * 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 declare const hopEdgeKey: (edge: HopEdge) => string;
+/**
+ * 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 declare const routePlanPathKey: (hops: readonly PlannedHop[]) => string;
+/**
+ * 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 declare const groupHopsBySignature: (hops: readonly PlannedHop[]) => readonly (readonly number[])[];
+/**
+ * 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 declare const compareRoutePlansByDeliveredAmount: (a: RoutePlan, b: RoutePlan) => number;