@gibs/quotes 1.13.0

package/dist/quote-service-contract.js

@@ -0,0 +1,247 @@
+import { z } from 'zod';
+/**
+ * The wire contract for `POST /v1/display-quotes` — the one endpoint a
+ * display-quote service (or a browser calling providers directly under the
+ * same contract) answers. See `docs/quote-service.md`'s "Endpoint" and
+ * "Cache" sections, which this module implements exactly.
+ *
+ * NOTHING HERE NAMES A HOST, A KEY, OR A CHAIN. This module carries the
+ * SHAPE of a request and an answer, never a fact about who asks it or what
+ * they ask about — see `docs/quote-service.md`'s "Library" section for why:
+ * this package runs for any host, with its own providers, its own chains and
+ * its own tripwires, all supplied through a configuration object a later
+ * module in this package defines.
+ */
+// ---------------------------------------------------------------------------
+// Base-units amounts: the bigint <-> decimal-string wire codec
+// ---------------------------------------------------------------------------
+/**
+ * A decimal string of digits only — the wire spelling of a base-units
+ * amount. No sign, no decimal point, no leading `0x`: `BigInt` reads it
+ * directly.
+ */
+export const baseUnitsAmountSchema = z
+    .string()
+    .regex(/^\d+$/, 'must be a decimal, non-negative base-units amount');
+/**
+ * A decimal-string amount that answers EXACTLY the amount it was asked for
+ * — a genuine, un-scaled reply, safe to hand to an execution builder as the
+ * delivery target. Branded so it cannot be confused with {@link EstimatedDelivery}
+ * at the type level, even though both are, at runtime, the same shape of
+ * string.
+ *
+ * See `quote-service-contract.test-d.ts` for the type-level proof this
+ * brand exists to make possible: an {@link EstimatedDelivery} cannot reach
+ * {@link decodeExactAmount}, and therefore cannot reach a bigint-typed
+ * execution field such as `ConsolidatedQuoteRequest.toAmount`.
+ */
+export const exactAmountSchema = baseUnitsAmountSchema.brand();
+/**
+ * A decimal-string amount SCALED from a nearby, already-cached amount's
+ * real answer — never the provider's own answer for the amount asked. See
+ * `docs/quote-service.md`'s "Rules that never bend": "A figure from a
+ * nearby amount is never presented as the user's exact quote."
+ *
+ * THIS IS THE BRAND `docs/quote-service.md` CALLS FOR BY NAME. It exists so
+ * a scaled figure is a DIFFERENT TYPE from an exact one, not merely a
+ * different runtime value that happens to carry the same shape — the two
+ * are interchangeable as plain strings, which is exactly the danger: a
+ * refactor that quietly widens a parameter from {@link ExactAmount} to
+ * `string` would let a scaled estimate slip through unnoticed. Kept
+ * distinct, `decodeExactAmount` refuses to compile against this brand, and
+ * nothing that only accepts {@link ExactAmount} can be handed one.
+ */
+export const estimatedDeliverySchema = baseUnitsAmountSchema.brand();
+/**
+ * Encodes a bigint amount as the wire's plain decimal-string form. The
+ * inverse of {@link decodeBaseUnitsAmount}.
+ *
+ * @param amount - a non-negative amount in base units
+ * @returns the decimal-string wire spelling
+ */
+export const encodeBaseUnitsAmount = (amount) => amount.toString();
+/**
+ * Decodes a wire decimal-string amount into bigint base units.
+ *
+ * @param amount - the wire string
+ * @returns the bigint value
+ * @throws when `amount` is not a plain, non-negative decimal integer string
+ */
+export const decodeBaseUnitsAmount = (amount) => {
+    const parsed = baseUnitsAmountSchema.safeParse(amount);
+    if (!parsed.success) {
+        throw new Error(`not a base-units amount: ${amount}`);
+    }
+    return BigInt(parsed.data);
+};
+/**
+ * Marks a bigint as an ask's genuine, EXACT answer, ready for the wire.
+ *
+ * @param amount - the exact delivered (or minimum) amount, in base units
+ * @returns the branded {@link ExactAmount}
+ */
+export const toExactAmount = (amount) => exactAmountSchema.parse(encodeBaseUnitsAmount(amount));
+/**
+ * Marks a bigint as a SCALED estimate, ready for the wire — never a
+ * genuine answer to the amount actually asked.
+ *
+ * @param amount - the scaled delivered (or minimum) amount, in base units
+ * @returns the branded {@link EstimatedDelivery}
+ */
+export const toEstimatedDelivery = (amount) => estimatedDeliverySchema.parse(encodeBaseUnitsAmount(amount));
+/**
+ * Decodes an amount an execution builder may spend as an EXACT figure.
+ *
+ * Only {@link ExactAmount} decodes here. Passing an {@link EstimatedDelivery}
+ * is a compile-time error — see `quote-service-contract.test-d.ts` — which is
+ * what makes `docs/quote-service.md`'s rule ("a scaled figure is unsafe" for
+ * `precision: 'exact'`) impossible to violate by accident rather than merely
+ * documented.
+ *
+ * @param amount - a branded exact amount
+ * @returns the bigint value
+ */
+export const decodeExactAmount = (amount) => decodeBaseUnitsAmount(amount);
+// ---------------------------------------------------------------------------
+// The request: POST /v1/display-quotes
+// ---------------------------------------------------------------------------
+const providerIdSchema = z.enum(['lifi', 'relay', 'near-intents']);
+/**
+ * A chain-and-token pair a {@link DisplayAsk} names on one side of the
+ * transfer.
+ */
+export const assetRefSchema = z
+    .object({
+    chainId: z.number().int().positive(),
+    token: z.string().min(1),
+})
+    .strict();
+/**
+ * One question inside a display-quote request: what every eligible
+ * provider expects to deliver for `amount` of `from.token` sent as
+ * `to.token`.
+ *
+ * See `docs/quote-service.md`'s "Endpoint" section for the field-by-field
+ * contract this schema encodes exactly.
+ */
+export const displayAskSchema = z
+    .object({
+    from: assetRefSchema,
+    to: assetRefSchema,
+    /** Decimal string, base units of `from.token`. */
+    amount: baseUnitsAmountSchema,
+    /**
+     * Defaults to the ecosystem `to.chainId` belongs to when omitted — see
+     * `ecosystemByChainId` in `@gibs/bridge-sdk`.
+     */
+    recipientEcosystem: z
+        .enum(['evm', 'svm', 'bvm', 'tvm', 'tonvm', 'hypevm', 'zcash'])
+        .optional(),
+    /** Defaults to every provider eligible for this pair when omitted. */
+    providers: z.array(providerIdSchema).min(1).optional(),
+    /** Defaults to `'estimate-ok'` when omitted. */
+    precision: z.enum(['estimate-ok', 'exact']).optional(),
+})
+    .strict();
+/** The body of `POST /v1/display-quotes`: 1 to 24 asks, answered in order. */
+export const displayQuoteRequestSchema = z
+    .object({
+    asks: z.array(displayAskSchema).min(1).max(24),
+})
+    .strict();
+// ---------------------------------------------------------------------------
+// The response: one answer per ask, one slot per provider that was asked
+// ---------------------------------------------------------------------------
+/** Why a `no-quote`, `could-not-ask`, `cannot-carry` or `invalid-api-key` slot answered as it did. Shared with `quote-refusals.ts`'s {@link QuoteRefusalKind}. */
+const quoteRefusalKindSchema = z.enum(['no-quote', 'could-not-ask', 'cannot-carry', 'invalid-api-key']);
+/** Where an answer came from, relative to this service's cache. */
+export const displayAnswerCacheStateSchema = z.enum(['miss', 'hit', 'joined']);
+const quotedDisplayAnswerCommonShape = {
+    status: z.literal('quoted'),
+    /**
+     * The amount this answer is FOR: always the asker's own requested amount
+     * (`DisplayAsk.amount`), never the nearby amount a scaled answer was
+     * actually derived from — that pair lives in `scaledFrom` below.
+     */
+    askedAmount: baseUnitsAmountSchema,
+    /** When the underlying provider answer was recorded, ISO 8601. */
+    quotedAt: z.string(),
+    /** Milliseconds between `quotedAt` and now. */
+    ageMs: z.number().nonnegative(),
+    cache: displayAnswerCacheStateSchema,
+};
+/** A genuine answer to exactly the amount asked. */
+export const exactQuotedDisplayAnswerSchema = z
+    .object({
+    ...quotedDisplayAnswerCommonShape,
+    basis: z.literal('exact'),
+    expectedAmount: exactAmountSchema,
+    minimumAmount: exactAmountSchema.optional(),
+})
+    .strict();
+/**
+ * An answer SCALED from a nearby cached amount's real answer — see
+ * `docs/quote-service.md`'s "Cache" section, "Scaling". `scaledFrom` carries
+ * the RAW pair the scaling was computed from (the amount actually asked
+ * upstream, and its own unscaled answer), so a client can audit or
+ * re-derive the figure; `expectedAmount`/`minimumAmount` are the SCALED
+ * estimate for this ask's own `askedAmount`.
+ */
+export const scaledQuotedDisplayAnswerSchema = z
+    .object({
+    ...quotedDisplayAnswerCommonShape,
+    basis: z.literal('scaled-from-nearby-amount'),
+    expectedAmount: estimatedDeliverySchema,
+    minimumAmount: estimatedDeliverySchema.optional(),
+    scaledFrom: z
+        .object({
+        askedAmount: baseUnitsAmountSchema,
+        expectedAmount: baseUnitsAmountSchema,
+    })
+        .strict(),
+})
+    .strict();
+export const quotedDisplayAnswerSchema = z.union([
+    exactQuotedDisplayAnswerSchema,
+    scaledQuotedDisplayAnswerSchema,
+]);
+/** The provider was asked and declined, could not be asked, or was never asked at all. */
+export const refusedDisplayAnswerSchema = z
+    .object({
+    status: z.literal('refused'),
+    kind: quoteRefusalKindSchema,
+    reason: z.string().nullable(),
+    minimumAmount: baseUnitsAmountSchema.optional(),
+})
+    .strict();
+/** The provider's own call is still in flight; ask again after `retryAfterMs`. */
+export const pendingDisplayAnswerSchema = z
+    .object({
+    status: z.literal('pending'),
+    retryAfterMs: z.number().nonnegative(),
+})
+    .strict();
+/** One provider's answer to one {@link DisplayAsk} — the three shapes `docs/quote-service.md`'s "Endpoint" section names. */
+export const displayProviderSlotSchema = z.union([
+    quotedDisplayAnswerSchema,
+    refusedDisplayAnswerSchema,
+    pendingDisplayAnswerSchema,
+]);
+/** Every provider slot answered for one {@link DisplayAsk}, keyed by provider id. */
+export const displayAnswerSchema = z
+    .object({
+    providers: z
+        .object({
+        lifi: displayProviderSlotSchema.optional(),
+        relay: displayProviderSlotSchema.optional(),
+        'near-intents': displayProviderSlotSchema.optional(),
+    })
+        .strict(),
+})
+    .strict();
+/** The body of a `POST /v1/display-quotes` response: one answer per ask, in ask order. */
+export const displayQuoteResponseSchema = z
+    .object({
+    answers: z.array(displayAnswerSchema),
+})
+    .strict();

package/dist/search/capabilities.d.ts

@@ -0,0 +1,68 @@
+import { type AssetNode } from '@gibs/bridge-sdk/routing';
+import type { Carrier, CarrierFusesWithNextOptions, CarrierId } from '../types.js';
+/**
+ * The route-search maximization engine's carrier-agnostic capability index:
+ * "which registered carriers connect this pair of assets, and does the
+ * carrier performing one hop fuse its signature with the next." See
+ * `docs/quote-service.md`'s "Carriers" section.
+ *
+ * NOTHING HERE NAMES A HOST'S OWN CARRIER. Every fact this module used to
+ * hard-code about LI.FI, Relay, NEAR Intents, the omnibridge crossing or
+ * PulseX now lives on the {@link Carrier} objects a caller registers —
+ * `carriersFrom` composes their own `edgesFrom`, and `fusesWithBridgeEntry`
+ * consults the acting carrier's own optional `fusesWithNext`. A host that
+ * wants "an executing aggregator fuses with its own bridge's entry call"
+ * (gibs's rule) supplies that as a `fusesWithNext` on the carrier IT
+ * registers (`packages/bridge-sdk/src/routing/carriers/`,
+ * `packages/ui/src/lib/state/useRouteSearch.ts`) — this module never learns
+ * what "the bridge" or "PulseChain" means.
+ */
+/** What {@link CapabilityIndex.fusesWithBridgeEntry} needs to decide one fuse question. */
+export type FusesWithBridgeEntryOptions = CarrierFusesWithNextOptions & {
+    /** The carrier performing the hop that might fuse with what follows it. */
+    readonly carrier: CarrierId;
+};
+/**
+ * What {@link buildCapabilityIndex} hands back: three total, pure lookups over
+ * the carriers it was built from.
+ */
+export type CapabilityIndex = {
+    /**
+     * Every carrier id that can move funds directly from `from` to `to`, in
+     * registration order, deduped. Empty when nothing connects them, including
+     * when `from` and `to` name the same asset.
+     */
+    readonly carriersFrom: (from: AssetNode, to: AssetNode) => readonly CarrierId[];
+    /**
+     * Whether a hop travelling `options.carrier` can FUSE with a following
+     * hop, so the two cost the reader one signature instead of two — read off
+     * the ACTING carrier's own `fusesWithNext`, or `false` when it declares
+     * none (the correct default for a carrier that never executes a
+     * destination call on arrival).
+     */
+    readonly fusesWithBridgeEntry: (options: FusesWithBridgeEntryOptions) => boolean;
+    /**
+     * The full registered {@link Carrier} behind one id — its `depositMode`,
+     * `exact`, `estimate`, `sender`, `settlementSeconds` — or `undefined` when
+     * `carrierId` names no registered carrier. `enumerate.ts` is the one caller
+     * today: it reads `depositMode` to decide whether a carrier may fill a
+     * pay-by-hand origin's first hop (replacing a former hard-coded
+     * `carrier !== 'near-intents'` check), and reads `exact`/`estimate` to
+     * price a candidate hop without a network call before falling back to a
+     * caller-supplied price-feed estimate.
+     *
+     * SHOULD NEVER RETURN `undefined` FOR AN ID {@link carriersFrom} ITSELF
+     * RETURNED — both are built from the same registration map — but the
+     * return type stays optional because a caller can ask about ANY string,
+     * not only one this index has ever produced.
+     */
+    readonly carrierById: (carrierId: CarrierId) => Carrier | undefined;
+};
+/**
+ * Builds the pure {@link CapabilityIndex} the route search prunes against,
+ * from the carriers a caller registers.
+ *
+ * @param carriers - every carrier this search may use, built-in or a host's own
+ * @returns the index: `carriersFrom` and `fusesWithBridgeEntry`
+ */
+export declare const buildCapabilityIndex: (carriers: readonly Carrier[]) => CapabilityIndex;

package/dist/search/capabilities.js

@@ -0,0 +1,28 @@
+import { assetNodeKey } from '@gibs/bridge-sdk/routing';
+/**
+ * Builds the pure {@link CapabilityIndex} the route search prunes against,
+ * from the carriers a caller registers.
+ *
+ * @param carriers - every carrier this search may use, built-in or a host's own
+ * @returns the index: `carriersFrom` and `fusesWithBridgeEntry`
+ */
+export const buildCapabilityIndex = (carriers) => {
+    const byId = new Map(carriers.map((carrier) => [carrier.id, carrier]));
+    const carriersFrom = (from, to) => {
+        if (assetNodeKey(from) === assetNodeKey(to)) {
+            return [];
+        }
+        const ids = [];
+        for (const carrier of carriers) {
+            for (const edge of carrier.edgesFrom(from, to)) {
+                if (!ids.includes(edge.carrier)) {
+                    ids.push(edge.carrier);
+                }
+            }
+        }
+        return ids;
+    };
+    const fusesWithBridgeEntry = ({ carrier, ...nextHop }) => byId.get(carrier)?.fusesWithNext?.(nextHop) ?? false;
+    const carrierById = (carrierId) => byId.get(carrierId);
+    return { carriersFrom, fusesWithBridgeEntry, carrierById };
+};

package/dist/search/enumerate.d.ts

@@ -0,0 +1,162 @@
+import { type AssetNode, type EstimateBasis, type HopEdge, type HopFloor, type RoutePlan } from '@gibs/bridge-sdk/routing';
+import type { CapabilityIndex } from './capabilities.js';
+import type { CollectedRefusal } from './waves.js';
+/**
+ * Depth-first search over a fixed node universe, pruning BEFORE anything is
+ * asked over the network (route search design, section 2). Everything here
+ * is pure: the node universe, the {@link CapabilityIndex}, the starting
+ * amount and the estimate function all arrive as arguments, and nothing is
+ * fetched — but a hop whose carrier answers through {@link Carrier.exact}
+ * (a synchronous LOCAL read, never a network call) carries a real `'quote'`
+ * outcome straight out of this module; every other hop carries an
+ * `'estimate'`, refined later by `waves.ts`'s live network asks.
+ *
+ * CARRIER-AGNOSTIC. Every prior version of this module special-cased ONE
+ * host's carriers directly (a hard-coded PulseX-only-runs-on-PulseChain
+ * check, and a hard-coded "only NEAR Intents may open a pay-by-hand
+ * origin"). Both are now the registering carrier's OWN job: `edgesFrom` only
+ * ever returns an edge for the pairs it can actually carry
+ * (`routing/carriers/pulsex.ts`'s own scoping, for gibs), and
+ * {@link Carrier.depositMode} states whether a carrier accepts a by-hand
+ * deposit — so this module never needs to know any carrier's NAME to enforce
+ * either rule, only the vocabulary every registered `Carrier` speaks.
+ */
+/** Depth cap: at most this many hops in one plan (design section 2, item 3). */
+export declare const DEFAULT_MAX_HOPS = 4;
+/** Signature cap: at most this many signature groups in one plan. */
+export declare const DEFAULT_MAX_SIGNATURES = 3;
+/**
+ * A hard, absolute ceiling on how many finished plans one
+ * {@link enumerateRoutes} call collects — a SAFETY VALVE, not a ranking cut.
+ * The owner's own routing model is "iterate through each possible pathway
+ * and order them by output": every path within `maxHops`/`maxSignatures` is
+ * enumerated and returned, sorted, with nothing trimmed to a top-N slice.
+ * This constant exists only to bound the search on a node universe
+ * pathological enough that the hop/signature caps alone do not keep it
+ * finite in practice; hitting it is a signal to revisit the node universe or
+ * the caps, not evidence that ranking picked correctly among what remained.
+ */
+export declare const MAX_ENUMERATED_PATHS = 10000;
+/**
+ * What {@link enumerateRoutes} needs to search: the endpoints, the amount, the
+ * node universe to branch through, the capability index to prune against, and
+ * an optimistic per-hop estimate function the caller supplies.
+ *
+ * THIS MODULE DOES NOT DECIDE THE NODE UNIVERSE. Building the hub set is a
+ * host concern — see `CapabilityIndexInputs.lifiHubTokens`'s doc in the
+ * former `bridge-sdk` version of this file, whose "never resolve a token by
+ * matching its `symbol`" rule still governs whoever builds `nodes`. The
+ * caller builds `nodes` from its own address list; this module only ever
+ * walks the graph it is handed.
+ */
+export type EnumerateRoutesOptions = {
+    /** The asset the reader is starting from. */
+    readonly origin: AssetNode;
+    /** The asset the reader wants delivered. */
+    readonly destination: AssetNode;
+    /** The reader's typed amount, in `origin`'s base units. */
+    readonly amount: bigint;
+    /**
+     * Every intermediate node the search may branch through. `origin` and
+     * `destination` are always available as endpoints whether or not this list
+     * repeats them.
+     */
+    readonly nodes: readonly AssetNode[];
+    /** The capability index to prune every candidate hop against. */
+    readonly capabilities: CapabilityIndex;
+    /**
+     * An OPTIMISTIC estimate of what one hop delivers, given what it consumes.
+     * Threaded through the search to (a) prune against a known floor and (b)
+     * rank finished plans — see design section 2.3: "price feed × fee priors,
+     * with the bridge fee and PulseX output computed exactly." This module
+     * invents no pricing rule of its own; it only calls the one it is given.
+     *
+     * RETURNS A BASIS ALONGSIDE THE AMOUNT. A price-feed estimate and a bare
+     * decimal rescale (no price known for one side) look identical as a
+     * bigint; the caller MUST say which one it produced, per
+     * {@link EstimateBasis}'s own doc, or this module has no way to keep an
+     * ungrounded number out of {@link compareRoutePlans}'s default ranking.
+     */
+    readonly estimateHopOutput: (edge: HopEdge, inputAmount: bigint) => {
+        readonly deliveredAmount: bigint;
+        readonly basis: EstimateBasis;
+    };
+    /**
+     * Minimum amounts already learned for a prospective edge, keyed by its
+     * carrier and endpoints. Defaults to "nothing known yet" — every edge this
+     * module produces on its own carries empty `floors`, matching
+     * `HopEdge.floors`'s own doc. `waves.ts` is what feeds a floor learned on
+     * one search into a LATER call's pruning step here.
+     */
+    readonly knownFloors?: (edge: Pick<HopEdge, 'carrier' | 'from' | 'to'>) => readonly HopFloor[];
+    /** Depth cap. Defaults to {@link DEFAULT_MAX_HOPS}. */
+    readonly maxHops?: number;
+    /** Signature cap. Defaults to {@link DEFAULT_MAX_SIGNATURES}. */
+    readonly maxSignatures?: number;
+    /**
+     * Called once for each distinct candidate hop (edge and input amount) a
+     * carrier's own {@link Carrier.exact} REFUSED during the walk — a local
+     * read saying "this amount cannot cross", with the carrier's reason and any
+     * minimum it names. The refused hop is still pruned, exactly as before;
+     * this only stops the reason from being thrown away.
+     *
+     * WHY IT EXISTS. A search whose only crossing is refused below its minimum
+     * returns no plan and, without this, no refusal either — indistinguishable
+     * from a search that never found the pair at all. The waves' own
+     * `refusals` list only ever held LIVE asks, so a floor read locally was the
+     * one refusal nobody could see. Omitted, nothing is reported.
+     */
+    readonly onExactRefusal?: (refusal: CollectedRefusal) => void;
+    /**
+     * How to rank two finished plans, best first. Defaults to
+     * {@link compareRoutePlansByScoreAdjustedDeliveredAmount} (`@gibs/bridge-sdk/routing`) —
+     * rankable beats unrankable regardless of raw magnitude, then the larger
+     * SIGNATURE-PENALTY-DISCOUNTED last-hop delivered amount wins within a
+     * group, so a plan needing an extra signature for a marginal gain does not
+     * automatically win the cut. PASS A DIFFERENT COMPARATOR ONLY WHEN IT
+     * STILL RESPECTS THE RANKABLE-BEATS-UNRANKABLE RULE: this default is the
+     * SAME function `waves.ts`'s own default imports, precisely so the
+     * rankability rule cannot drift out of sync between the two — see that
+     * function's own doc.
+     */
+    readonly compareRoutePlans?: (a: RoutePlan, b: RoutePlan) => number;
+};
+/**
+ * Depth-first search from `options.origin` to `options.destination` over
+ * `options.nodes`, pruning every candidate hop before it is added and
+ * collecting every finished plan the hop/signature caps allow, up to the
+ * {@link MAX_ENUMERATED_PATHS} safety valve.
+ *
+ * PRUNING, APPLIED BEFORE A CANDIDATE HOP IS EVER ADDED (design section 2,
+ * item 2):
+ * - the carrier must support both nodes ({@link CapabilityIndex.carriersFrom});
+ * - no node is revisited within one plan;
+ * - the same carrier never runs twice in a row, whatever venue each hop names
+ *   (so one carrier never splits a hop across two of its own venues);
+ * - a pay-by-hand origin's first hop must be filled by a carrier whose
+ *   {@link Carrier.depositMode} accepts a by-hand deposit — `'by-hand-deposit'`
+ *   or `'either'`, never `'wallet-signed'` alone
+ *   ({@link isDepositAddressChain} is the pay-by-hand test);
+ * - a hop that starts a DEFERRED leg (every signature group after the first)
+ *   must start on an Ethereum-Virtual-Machine chain;
+ * - a known floor, if any, must be at or below the amount flowing into that
+ *   hop;
+ * - the acting carrier's own {@link Carrier.exact}, when it has one, must not
+ *   refuse the amount flowing into that hop ({@link resolveHopOutcome}); a
+ *   refusal it does give is handed to `onExactRefusal`, once per edge and
+ *   amount;
+ * - the plan must not exceed `maxHops` hops or `maxSignatures` signature
+ *   groups (grouped with {@link groupHopsBySignature}, reused rather than
+ *   re-derived, so a fused pair always counts as one signature here exactly
+ *   as it does everywhere else that reads a `RoutePlan`).
+ *
+ * A HOP'S `fusesNext` CANNOT BE KNOWN WHEN IT IS BUILT — it depends on the hop
+ * that follows it, which does not exist yet in a depth-first walk. So each
+ * hop is built provisionally with `fusesNext: false`, and is replaced with an
+ * updated copy (never mutated) the moment its successor is chosen, once
+ * {@link CapabilityIndex.fusesWithBridgeEntry} can actually answer.
+ *
+ * @param options - the search's endpoints, node universe, capability index and estimate function
+ * @returns every plan the caps allow, best first, never exceeding {@link MAX_ENUMERATED_PATHS}
+ */
+export declare const enumerateRoutes: (options: EnumerateRoutesOptions) => readonly RoutePlan[];