@gibs/bridge-sdk 1.13.1 → 1.18.0

package/dist/cjs/routing/providers.d.ts

@@ -0,0 +1,31 @@
+import type { Hex } from 'viem';
+import { type Provider } from '../config.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 declare const pulseXConversionSwapPath: (anchorAddress: Hex, wantedAddress: Hex, wplsAddress: Hex) => readonly Hex[];
+/**
+ * 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 declare const omnibridgeProviderForEntryChain: (entryChainId: number) => Provider | null;

package/dist/cjs/routing/providers.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.omnibridgeProviderForEntryChain = exports.pulseXConversionSwapPath = void 0;
+const config_js_1 = require("../config.js");
+const ecosystems_js_1 = require("../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`
+ */
+const pulseXConversionSwapPath = (anchorAddress, wantedAddress, wplsAddress) => {
+    const isWpls = (address) => (0, ecosystems_js_1.sameAddress)(address, wplsAddress, 'evm');
+    if (isWpls(anchorAddress) || isWpls(wantedAddress))
+        return [anchorAddress, wantedAddress];
+    return [anchorAddress, wplsAddress, wantedAddress];
+};
+exports.pulseXConversionSwapPath = pulseXConversionSwapPath;
+/**
+ * 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`.
+ */
+const omnibridgeProviderForEntryChain = (entryChainId) => {
+    const entryChain = (0, config_js_1.toChain)(entryChainId);
+    if (entryChain === config_js_1.Chains.ETH)
+        return config_js_1.Providers.PULSECHAIN;
+    if (entryChain === config_js_1.Chains.BNB)
+        return config_js_1.Providers.TOKENSEX;
+    return null;
+};
+exports.omnibridgeProviderForEntryChain = omnibridgeProviderForEntryChain;

package/dist/cjs/routing/route-data.d.ts

@@ -0,0 +1,397 @@
+import type { Hex } from 'viem';
+import type { QuoteFee } from '../quote-fees.js';
+import type { ProviderKey } from '../providers.js';
+import type { CarrierStepKind } from './carrier-provider-key.js';
+/**
+ * The executing engine family a route runs through.
+ *
+ * `'swap'` is a same-chain PulseX swap: one signature, no crossing, no
+ * `entryChainId`, headlined by the PulseX provider rather than an omnibridge
+ * or aggregator one. It exists as its own kind rather than being folded into
+ * `'direct'` because a swap and a crossing are refused by two DIFFERENT
+ * guards (`swapRefusal` versus `crossingRefusal` in `@gibs/bridge-sdk/settings`)
+ * — collapsing the kinds would collapse the distinction the guards exist to
+ * keep honest.
+ */
+export type RouteKind = 'direct' | 'aggregated' | 'conversion' | 'swap';
+/**
+ * What grounds a figure that is NOT a live, provider-confirmed quote.
+ *
+ * DECLARED HERE, NOT IN `routing/search/graph.ts`, even though the general
+ * route search is what produces every estimate today. `RouteData` (this
+ * module) is the lower layer that `graph.ts` already depends on for
+ * `RouteKind` and the rest of the raw route shape — so the union belongs
+ * where the module that needs it already reaches, rather than forcing this
+ * one to import upward from the module that depends on it. `graph.ts` imports
+ * this type and re-exports it rather than declaring its own; there is exactly
+ * one definition.
+ *
+ * - `'probe-rate'` — a tiny reference trade's realized rate, scaled up.
+ * - `'priced-conversion'` — a currency conversion applied to a priced figure.
+ * - `'provider-model'` — an aggregator carrier's own provider-model estimate
+ *   (`@gibs/quotes`'s `Carrier.estimate`): a price ratio times (one minus its
+ *   typical fee) minus a fixed cost, calibrated against observed history.
+ *   RANKABLE, same as `'probe-rate'` and `'priced-conversion'` — see
+ *   {@link RANKABLE_ESTIMATE_BASES} in `routing/search/graph.ts` — but NEVER
+ *   CONFIRMED (see {@link isConfirmedBasis} there): it never asked a real
+ *   provider for this exact edge, only modeled one, so a search may prune and
+ *   rank on it but may never report it as the final winner without a live
+ *   quote first.
+ * - `'unpriced'` — a bare decimal rescale with no value behind it at all. This
+ *   basis never reaches {@link RouteLandingData.estimateBasis} or
+ *   {@link RouteOutputData.estimateBasis} — a figure grounded on nothing is
+ *   left out of `amount` entirely rather than labelled; see that field's own
+ *   note.
+ */
+export type EstimateBasis = 'probe-rate' | 'priced-conversion' | 'provider-model' | 'unpriced';
+/**
+ * A token reference in raw form — symbol, on-chain address, decimal chain id, and
+ * token decimals. Token and chain logos are OPTIONAL pre-resolved passthroughs: a
+ * producer that already has the correct image url for its route family (for
+ * example the direct path, whose token logos come from the multi-source asset
+ * resolver and chain metadata) sets them; a producer that does not leaves them
+ * undefined and the user-interface adapter resolves them from `chainId` + `address`
+ * via the image service. A field set to `null` means "deliberately no logo" and is
+ * preserved as-is (distinct from undefined, which triggers adapter resolution).
+ */
+export type RouteTokenRef = {
+    /** Token ticker symbol, e.g. "USDC". */
+    symbol: string;
+    /**
+     * Token contract address on `chainId`.
+     *
+     * Typed as `string` rather than `Hex` because a route can pass through a
+     * non-Ethereum chain, where the token identifier is not `0x`-prefixed — a
+     * Bitcoin address, a Solana or Tron base58 address, a The Open Network
+     * user-friendly address. Treat it as an opaque identifier; anything deriving an
+     * image or a checksum from it must check for the `0x` prefix first.
+     */
+    address: string;
+    /** Decimal chain identifier this reference is presented on. */
+    chainId: number;
+    /**
+     * Token decimals, for amount formatting downstream. Optional because an
+     * INTERMEDIATE stop carries no amount to format — it renders as an icon only,
+     * and the provider quote that named it does not always report its decimals.
+     */
+    decimals?: number;
+    /** Pre-resolved token logo url; undefined → adapter resolves, null → no logo. */
+    logoUri?: string | null;
+    /** Pre-resolved chain-badge logo url; undefined → adapter resolves, null → none. */
+    chainLogoUri?: string | null;
+};
+/**
+ * One underlying hop within a signature section, in raw form. United States dollar
+ * cost is a NUMBER (`feeUsdValue`); the adapter formats it. Provider identity is a
+ * raw display `providerName` plus, when the hop resolves its logo from a provider
+ * key rather than a quote-supplied url, an optional `providerKey`. When the hop's
+ * logo comes straight from the aggregator quote, `providerLogoUri` carries it and
+ * the adapter prefers it over key resolution.
+ */
+export type RouteHopData = {
+    /** Display name for the hop's provider, e.g. "LI.FI", "PulseChain Bridge". */
+    providerName: string;
+    /** Raw provider key for logo resolution when no `providerLogoUri` is supplied. */
+    providerKey?: ProviderKey | null;
+    /**
+     * What the hop does when no provider performs it (a native wrap). Such a hop
+     * has a null `providerKey`; the adapter draws its mark from this kind.
+     */
+    stepKind?: CarrierStepKind | null;
+    /** Quote-supplied provider logo url (aggregator legs); preferred when present. */
+    providerLogoUri?: string | null;
+    /** Human-readable hop title, e.g. "Bridge to PulseChain". */
+    title: string;
+    /** Token conversion subtitle derived from symbols, e.g. "ETH → USDC", or null. */
+    conversion?: string | null;
+    /**
+     * The token this hop CONSUMES, when the provider named it. Present alongside
+     * {@link conversion} rather than replacing it: the conversion line is prose for
+     * the hop detail, while these references are structural, so the section's token
+     * flow can be derived from the hops instead of guessing at the endpoints.
+     */
+    fromToken?: RouteTokenRef | null;
+    /**
+     * The token this hop PRODUCES — the stop the funds actually reach when the hop
+     * completes. Null/undefined when the provider named no output token.
+     */
+    toToken?: RouteTokenRef | null;
+    /** Per-hop fee in United States dollars as a NUMBER, or null when unknown. A search route's figure INCLUDES the signature's network gas (carried on the section's first hop). */
+    feeUsdValue?: number | null;
+    /** The part of {@link feeUsdValue} that is not network gas: what the hop costs in value. Absent when the producer states no gas split. */
+    feeExcludingGasUsdValue?: number | null;
+    /** The network gas of the signature this hop opens, in dollars; null or absent on every hop that opens none, and when gas is unknown. */
+    gasUsdValue?: number | null;
+    /** True when this hop runs automatically inside the section's single signature. */
+    automatic?: boolean;
+};
+/**
+ * The network gas a route needs on one signing chain, summed across the
+ * signatures it signs there.
+ */
+export type RouteGasByChain = {
+    /** The chain the signatures broadcast on. */
+    chainId: number;
+    /** The native coin they burn, in base units (wei), or null when the chain's gas price is unknown. */
+    amountWei: bigint | null;
+    /** The same gas in dollars, or null when the amount or the native price is unknown. */
+    usdValue: number | null;
+};
+/**
+ * What a signature section's funds LAND IN when that step completes — the stop
+ * the money actually comes to rest at, named in tokens rather than only drawn as
+ * an icon in the flow. Every step of a route ends somewhere, and until this
+ * existed only the route's FINAL delivery was stated in words: an intermediate
+ * step showed its cost but never how much of what it left the user holding.
+ *
+ * `amount` is null when the step is quoted only on return (a deferred leg), in
+ * which case the step still names the token it will land in.
+ */
+export type RouteLandingData = {
+    /** Amount landed in base units, or null when the step is not yet quoted. */
+    amount: bigint | null;
+    /** Landed token decimals, for formatting. */
+    decimals: number;
+    /** Landed token symbol, e.g. "USDC". */
+    symbol: string;
+    /** Landed value in United States dollars as a NUMBER, or null when unpriced. */
+    usdValue?: number | null;
+    /**
+     * What grounds `amount` when it is NOT a live, provider-confirmed quote —
+     * absent (or null) for an ordinary quoted figure. See {@link EstimateBasis}
+     * for the members and why it is declared in this module.
+     *
+     * `'unpriced'` never reaches here: a figure grounded on no value at all is
+     * left out of `amount` entirely rather than labelled.
+     */
+    estimateBasis?: EstimateBasis | null;
+};
+/**
+ * Origin tokens a step does NOT consume, which therefore stay in the user's
+ * wallet.
+ *
+ * This exists because a route is quoted in two phases: the first solves FORWARD
+ * for the amount the user typed and reports the provider's guaranteed delivery
+ * floor, and the second solves BACKWARD to that floor. Backward-solving to a
+ * floor that sits below the forward expectation needs LESS origin token than was
+ * typed, so the difference — the slippage cushion, whatever the provider's
+ * tolerance happens to be — is simply never spent.
+ *
+ * It is deliberately NOT modelled as a cost and never enters `totalCostUsdValue`:
+ * the user keeps this money. Folding it into either the amount paid or the amount
+ * delivered would make one of those figures state something untrue, which is why
+ * it is carried as its own fact for the step's breakdown to name.
+ */
+export type RouteUnspentData = {
+    /** Unspent amount in ORIGIN token base units. */
+    amount: bigint;
+    /** Origin token decimals, for formatting. */
+    decimals: number;
+    /** Origin token symbol, e.g. "ETH". */
+    symbol: string;
+    /** Unspent value in United States dollars as a NUMBER, or null when unpriced. */
+    usdValue: number | null;
+};
+/**
+ * One signature section of a route, in raw form. One section per manual wallet
+ * signature. Token flow is raw references; the section fee is a NUMBER. Provider
+ * identity is an optional raw `providerKey` the adapter resolves to name + logo.
+ */
+export type RouteSectionData = {
+    /** Stable within-route key, e.g. "candidate-1-signature-1". */
+    id: string;
+    /** Short label naming what this signature does, e.g. "Bridge to PulseChain". */
+    label: string;
+    /** Raw provider key for the service executing this signature, or null. */
+    providerKey?: ProviderKey | null;
+    /** What the signature does when no provider performs it (a native wrap); see {@link RouteHopData.stepKind}. */
+    stepKind?: CarrierStepKind | null;
+    /**
+     * The token-icon flow this signature walks, in raw references: the source, then
+     * every INTERMEDIATE stop the funds pass through, then the destination. A
+     * producer that knows its hops derives this from them (source, then each hop's
+     * output token) so the stops shown are the ones the route actually makes; a
+     * producer with a single hop emits just source → destination.
+     */
+    tokenFlow: RouteTokenRef[];
+    /**
+     * What this step leaves the user holding when it completes. Absent on a step
+     * whose producer cannot say — the step then shows its cost alone, as before.
+     */
+    landing?: RouteLandingData | null;
+    /**
+     * Origin tokens this step does not consume; they stay in the user's wallet.
+     * Absent on every step that spends exactly what it was given, which is all of
+     * them but the aggregator leg. See {@link RouteUnspentData} for why this is not
+     * a cost.
+     */
+    unspent?: RouteUnspentData | null;
+    /** Section total fee in United States dollars as a NUMBER, or null. A search route's figure INCLUDES this signature's network gas. */
+    feeUsdValue?: number | null;
+    /** The part of {@link feeUsdValue} that is not network gas. Absent when the producer states no gas split. */
+    feeExcludingGasUsdValue?: number | null;
+    /** This signature's network gas in dollars, or null/absent when unknown. */
+    gasUsdValue?: number | null;
+    /** Numeric inputs for an optional fee breakdown line (conversion mode). */
+    feePercent?: number | null;
+    /** Price-impact percentage for an optional fee breakdown line (conversion mode). */
+    priceImpactPercent?: number | null;
+    /** Estimated duration for this signature in minutes, or null to omit. */
+    etaMinutes?: number | null;
+    /** Estimated duration for this signature in seconds (sub-minute legs), or null. */
+    etaSeconds?: number | null;
+    /** The underlying hops this signature performs, first to last. */
+    hops: RouteHopData[];
+    /** True when signed only after a prior section's crossing settles (deferred). */
+    deferred?: boolean;
+    /** Explanation shown for a deferred section; the adapter supplies a default. */
+    deferredNote?: string;
+    /**
+     * Per-step transaction-transparency details for the advanced disclosure: the
+     * contract address(es) this signature touches and its encoded calldata.
+     * Absent until known. The direct route populates {@link bridgeFrom},
+     * {@link bridgeTo} and {@link destinationRouter} from the resolved omnibridge
+     * pathway; the same-chain PulseX swap route populates {@link destinationRouter}
+     * (the PulseX router, never a bridge mediator) and {@link calldata} from the
+     * SAME builder its own signing button calls
+     * (`pulseXSwapTransactionInputs` in `settings.ts`) — never a second encoding.
+     * Every other producer leaves it undefined until its execute path is wired.
+     */
+    advanced?: {
+        /** Source-side bridge mediator address for this step, or null. */
+        bridgeFrom?: Hex | null;
+        /** Destination-side bridge mediator address for this step, or null. */
+        bridgeTo?: Hex | null;
+        /**
+         * The destination-side router this step's delivery calls, or null when
+         * none. For the same-chain swap route this IS the PulseX router — the
+         * whole signature, not a delivery leg inside a crossing.
+         */
+        destinationRouter?: Hex | null;
+        /** Encoded calldata for this step's signature, or null when unknown. */
+        calldata?: Hex | null;
+    };
+    /**
+     * What the aggregator carrying this signature charges, itemized.
+     *
+     * The single `feeUsdValue` above is the difference between what the sender
+     * pays and what lands, which is a true total and says nothing about where it
+     * went. This is the breakdown behind it - and it is the only place a charge
+     * levied OUTSIDE `fromAmount` can appear at all, because such a charge never
+     * shows up in that difference.
+     */
+    fees?: QuoteFee[];
+};
+/** What a route delivers, in raw form. `amount` is null when not yet known. */
+export type RouteOutputData = {
+    /** Delivered amount in base units, or null when unknown at quote time. */
+    amount: bigint | null;
+    /** Delivered token decimals, for formatting. */
+    decimals: number;
+    /** Delivered token symbol. */
+    symbol: string;
+    /** Delivered value in United States dollars as a NUMBER, or null when unpriced. */
+    usdValue?: number | null;
+    /**
+     * What grounds `amount` when it is NOT a live, provider-confirmed quote. See
+     * {@link RouteLandingData.estimateBasis} for the full rule — this is the
+     * same field, on the route's final delivery rather than one step's landing.
+     */
+    estimateBasis?: EstimateBasis | null;
+};
+/**
+ * One route in raw, data-only form — the framework-agnostic shape route builders
+ * produce. Carries bigint amounts, numeric United States dollar values, chain
+ * identifiers, and raw provider keys ONLY: no logo urls, no pre-formatted strings,
+ * and no human-readable chain names. The user-interface adapter `toRouteView`
+ * derives all of those to produce the display-ready route.
+ */
+export type RouteData = {
+    /**
+     * Structural id. Unset by raw producers in this phase; the user-interface
+     * adapter assigns it from the assembled display option so shared links stay
+     * stable. Optional so producers need not compute it.
+     */
+    id?: string;
+    /** The executing engine family this route runs through. */
+    kind: RouteKind;
+    /** The omnibridge entry chain id for non-direct routes; null for direct. */
+    entryChainId: number | null;
+    /**
+     * Optional override for the chain shown as the route's "via" crossing, when it
+     * differs from {@link entryChainId}. The outbound route sets this to the chain it
+     * bridges TO while keeping `entryChainId` null (it has no aggregator entry chain).
+     * Unset on every other route, where the adapter falls back to `entryChainId`.
+     */
+    viaChainId?: number | null;
+    /**
+     * Raw provider key for the route's headline provider — the omnibridge crossing
+     * when the route has one, otherwise the aggregator that carries the whole
+     * journey.
+     *
+     * Typed `ProviderKey`, not `string`. Every producer always supplies a real
+     * one (an omnibridge `Provider` when there is a bridge leg, the aggregator's
+     * own `ProviderId` otherwise — see `producers.ts`'s `omnibridgeProviderKey ??
+     * candidate.quote.provider`), so there is no case where a route has none.
+     * `providerDisplayName` (`producers.ts`) still accepts a bare `string`
+     * itself, deliberately: display code reading a STORED or otherwise
+     * deserialized `RouteData` cannot rely on this type annotation to have
+     * survived the round trip, and must render something rather than throw on a
+     * value it no longer recognizes.
+     */
+    headlineProviderKey: ProviderKey;
+    /** The signature sections of the route, top to bottom. */
+    sections: RouteSectionData[];
+    /** What the route delivers — used for ranking and the output row. */
+    output: RouteOutputData;
+    /**
+     * Aggregate ALL-IN cost in United States dollars as a NUMBER, or null:
+     * value lost plus network gas. The ranking reads this figure. For the
+     * figure without gas, read {@link costExcludingGasUsdValue}.
+     */
+    totalCostUsdValue?: number | null;
+    /** {@link totalCostUsdValue} without network gas: the value the reader gives up. Absent when the producer states no gas split. */
+    costExcludingGasUsdValue?: number | null;
+    /**
+     * The network gas the reader pays across every signature, in dollars, or
+     * null/absent when no signing chain has a gas reading. Never zero for
+     * "unknown".
+     */
+    gasCostUsdValue?: number | null;
+    /** The gas by signing chain, in signing order: what to hold, and in which coin. */
+    gasByChain?: RouteGasByChain[];
+    /** The user's net United States dollar outcome; the figure routes are ranked on. */
+    netValueUsd?: number | null;
+    /** Estimated end-to-end duration in minutes, or null when unknown. */
+    etaMinutes?: number | null;
+    /** True for the single best route; set by the ranker. */
+    isBest?: boolean;
+    /** Percentage difference versus the best route, negative; set by the ranker. */
+    deltaPercent?: number | null;
+    /**
+     * The general-search plan's stable path identity, when this route came
+     * from one — see the route-search design, section 1, and
+     * `RoutePlan.pathKey` in `routing/search/graph.ts`.
+     *
+     * ABSENT ON EVERY ROUTE PHASE 0 PRODUCES. `journeyPlan.ts`'s `pathKeyFor`
+     * derives a route's path key from `entryChainId` alone today; once a route
+     * carries this field, Phase 3's `journeyPlan.ts` work prefers it, because
+     * `entryChainId` alone cannot tell two plans that share an entry chain but
+     * cross through different intermediate assets or carriers apart.
+     */
+    pathKey?: string;
+    /**
+     * The decimal chain ids every intermediate hop of the route passes
+     * through, origin and destination excluded, in hop order.
+     *
+     * ABSENT ON EVERY ROUTE PHASE 0 PRODUCES, and on any route with no
+     * intermediate chain (a same-chain crossing, or a route with exactly one
+     * hop). {@link viaChainId} on `RouteOption` already names the SINGLE entry
+     * chain today's two-hop routes pass through; this field exists because a
+     * general-search plan can pass through MORE than one intermediate chain
+     * (for example Zcash → NEAR's Ethereum settlement → the omnibridge entry
+     * chain → PulseChain), and a single `viaChainId` cannot name more than one
+     * of them.
+     */
+    viaChainIds?: number[];
+};

package/dist/cjs/routing/route-data.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/routing/search/compose.d.ts

@@ -0,0 +1,168 @@
+import { type ComposedPathBasis, type EstimateBasis, type HopEdge } from './graph.js';
+/**
+ * PHASE 1 — composes a path's per-hop figures into one end-to-end delivered
+ * amount, as design section 3 describes ("Composition"): "A later hop's
+ * output is estimated as its probe rate × the actual input. Rank on that
+ * estimate."
+ *
+ * WHY THIS IS ITS OWN MODULE, SEPARATE FROM `graph.ts` AND `score.ts`. A
+ * {@link HopEdge} names WHO carries a hop and WHICH two assets it connects;
+ * it says nothing about a delivered amount, because Phase 0 introduced no
+ * quoting. `PlannedHop.outcome` (`graph.ts`) says what a hop delivers ONCE
+ * something has already computed that figure. This module is the thing that
+ * computes it: given a starting amount and a sequence of hop figures — each
+ * either a REAL QUOTE (an exact amount) or a PROBE RATE (a ratio observed at
+ * some other, unrelated amount) — it walks the path and produces the single
+ * number a search ranks on.
+ *
+ * WHY EVERY RESULT IS AN ESTIMATE. Only the route's first signature has to be
+ * a binding quote (design section 3: "Only signature 1 must be binding").
+ * Composing a chain of figures — even a chain where every individual figure
+ * happens to be a real quote — is not itself something any provider quoted
+ * end to end, so the composed, path-level figure is never treated as a
+ * binding quote. It is always an ESTIMATE, which is what keeps a later leg
+ * honestly labelled until the reader returns to it and it is re-quoted for
+ * real (design section 3; section 4's `D` still uses this estimate for
+ * RANKING, which is a different thing from promising it).
+ *
+ * WHY BASE-UNIT BIGINTS, NEVER A FLOAT. A composed figure is money. Every
+ * amount here is kept as a bigint in the token's own base units all the way
+ * through; a rate is an exact bigint ratio ({@link ExchangeRate}), and
+ * applying it is one bigint multiply followed by one bigint divide — never a
+ * floating-point multiply, which would round a real amount away from what
+ * the chain will actually move.
+ */
+/**
+ * An exact exchange rate, expressed as a bigint ratio: `numerator` output
+ * base units per `denominator` input base units, at the amount the rate was
+ * observed. Never a float — see this module's doc.
+ *
+ * This is what a Phase 1 "probe" produces: one carrier asked, once, "what
+ * would this hop return for a REFERENCE amount," and the ratio of that
+ * reference's output to its input is the rate. The reference amount itself
+ * plays no further part once the ratio is taken; only the ratio composes.
+ */
+export type ExchangeRate = {
+    /** Output base units the rate implies, per {@link denominator} input base units. */
+    readonly numerator: bigint;
+    /** Input base units the rate is quoted against. Must be a positive number. */
+    readonly denominator: bigint;
+};
+/**
+ * What one hop knows about its own pricing, before composition applies it to
+ * the amount actually arriving at that hop.
+ *
+ * `'quote'` — the carrier returned an exact `outputAmount` for the exact
+ * amount that arrives at this hop in THIS path. Used as given; composition
+ * does no further math on it.
+ *
+ * `'probeRate'` — the carrier was asked at some other, reference amount, and
+ * only the resulting {@link ExchangeRate} survived. Composition multiplies
+ * this rate by the ACTUAL amount arriving at the hop, per design section 3.
+ * Carries the {@link EstimateBasis} that grounds it (`graph.ts`) — PHASE 3:
+ * a `'probeRate'` figure is not always a genuine probe; `waves.ts` also uses
+ * this kind to carry forward a hop's pre-network `'priced-conversion'` or
+ * `'unpriced'` estimate when no fresh answer landed, and the basis is what
+ * tells the two apart.
+ */
+export type ComposableHopFigure = {
+    readonly kind: 'quote';
+    readonly outputAmount: bigint;
+} | {
+    readonly kind: 'probeRate';
+    readonly rate: ExchangeRate;
+    readonly basis: EstimateBasis;
+};
+/** The {@link ComposedPathBasis} one hop's figure contributes: `'quoted'` for a bound quote, its own basis for a `'probeRate'`. */
+export declare const composableHopBasis: (figure: ComposableHopFigure) => ComposedPathBasis;
+/**
+ * One hop of a path being composed: the edge it travels (which carries the
+ * two {@link AssetNode}s composition checks for a decimals disagreement) and
+ * what is known about its pricing.
+ */
+export type ComposableHop = {
+    /** The graph edge this hop travels — supplies both endpoints' decimals. */
+    readonly edge: HopEdge;
+    /** What this hop knows about its own pricing. */
+    readonly figure: ComposableHopFigure;
+};
+/**
+ * Why {@link composeRouteDelivery} refused to compose a path, rather than
+ * guess at an answer it cannot stand behind.
+ *
+ * `'empty-path'` — there were no hops to compose across.
+ *
+ * `'discontinuous-path'` — one hop's `to` asset is not the next hop's `from`
+ * asset, so there is no single amount that "arrives" at the second hop; the
+ * hops given do not describe one connected path.
+ *
+ * `'decimals-mismatch'` — two hops name the SAME asset (by
+ * {@link assetNodeKey}) with two DIFFERENT decimal counts. This is a data
+ * bug — one asset has one true decimals count — and composing through it
+ * would silently misplace a decimal point in real money.
+ *
+ * `'missing-rate'` — a hop's figure is a {@link ComposableHopFigure} of kind
+ * `'probeRate'` whose {@link ExchangeRate.denominator} is not a positive
+ * number, so the rate names no real ratio.
+ */
+export type ComposeRefusalReason = 'empty-path' | 'discontinuous-path' | 'decimals-mismatch' | 'missing-rate';
+/**
+ * The result of composing a path: either the estimated delivered amount, or
+ * why composition refused to produce one.
+ */
+export type ComposedRouteDelivery = {
+    readonly kind: 'estimate';
+    /** The composed delivered amount, in the LAST hop's `to` asset's base units. */
+    readonly deliveredAmount: bigint;
+    /**
+     * What grounds {@link deliveredAmount} — the WORST (least-grounded)
+     * {@link ComposedPathBasis} among every hop composed (see
+     * {@link combineComposedPathBasis}). PHASE 3: a ranking must check this
+     * before comparing {@link deliveredAmount} against another path's — see
+     * `graph.ts`'s {@link isRankableBasis} for the rule.
+     */
+    readonly basis: ComposedPathBasis;
+} | {
+    readonly kind: 'refused';
+    readonly reason: ComposeRefusalReason;
+    /** Which hop (0-based, into the `hops` argument) triggered the refusal. */
+    readonly hopIndex: number;
+};
+/**
+ * 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 declare const composeRouteDelivery: (inputAmount: bigint, hops: readonly ComposableHop[]) => ComposedRouteDelivery;
+/**
+ * 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 declare const hopOutputAmount: (hop: ComposableHop, actualInput: bigint) => bigint | null;