@gibs/bridge-sdk 1.13.1 → 1.18.0

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

@@ -0,0 +1,285 @@
+import { type ProviderKey } from '../../providers.js';
+import type { Provider } from '../../config.js';
+import type { QuoteFee } from '../../quote-fees.js';
+import type { Token } from '../../types.js';
+import type { DeferredCrossing, RouteCandidate } from '../candidate.js';
+import type { RouteData, RouteGasByChain, RouteKind } from '../route-data.js';
+import type { RouteScoreInputs } from './score.js';
+import { type AssetNode, type RoutePlan } from './graph.js';
+/**
+ * Resolves a graph node to the full display token a `RouteTokenRef` needs.
+ *
+ * `AssetNode` (`./graph.js`) is deliberately opaque about symbol, name and
+ * logo — see that module's own doc for why a coin and its wrapped form stay
+ * two distinct nodes there. Whoever built the plan already resolved every
+ * node against a live capability index and therefore already has this
+ * mapping; this module never invents one.
+ */
+export type ResolveNodeToken = (node: AssetNode) => Token;
+/**
+ * The plan's omnibridge provider, or null when the plan crosses no bridge
+ * hop at all — exactly the derivation `RouteCandidate.plan`'s own TSDoc
+ * (`../candidate.ts`) promises: "that same hop's `carrier`... the `to` node's
+ * `chainId` of the plan's LAST hop whose carrier is `'pulsechain'` or
+ * `'tokensex'`." Reading the LAST such hop, not the first, matters for a
+ * plan with two bridge crossings (an outbound leg out of PulseChain followed
+ * later by a separate inbound one) — not a shape any of today's four
+ * builders draws, but one the general search can.
+ *
+ * @param plan - the plan to derive from
+ * @returns the omnibridge provider, or null
+ */
+export declare const deriveOmnibridgeProviderFromPlan: (plan: RoutePlan) => Provider | null;
+/**
+ * The plan's entry chain id — the chain the plan's FIRST hop lands on, when
+ * that hop is carried by an aggregator (LI.FI, Relay or NEAR Intents); null
+ * when the plan's first hop IS the omnibridge itself (a direct, same-chain
+ * crossing — `buildDirectCrossingCandidate`'s shape) or is a PulseX swap.
+ *
+ * MATCHES `RouteCandidate.entryChainId`'S EXISTING MEANING throughout the
+ * candidate-based builders — "the chain the omnibridge leg starts on" — for
+ * every candidate that carries one, including a candidate whose aggregator
+ * reaches its OWN destination with no further bridge hop at all (today's
+ * `makeCandidate` test fixtures set `entryChainId` to the destination chain
+ * in exactly that case, because it is still where the aggregator's own leg
+ * lands).
+ *
+ * @param plan - the plan to derive from
+ * @returns the entry chain id, or null for a direct crossing or a swap-only plan
+ */
+export declare const deriveEntryChainIdFromPlan: (plan: RoutePlan) => number | null;
+/**
+ * The decimal chain ids every INTERMEDIATE hop of the plan passes through,
+ * origin and destination excluded — `RouteData.viaChainIds`'s own contract.
+ * Undefined (never an empty array) when the plan has nothing to report, per
+ * that field's own "ABSENT... on any route with no intermediate chain" doc.
+ *
+ * @param plan - the plan to derive from
+ * @returns the via chain ids in hop order, or undefined
+ */
+export declare const deriveViaChainIdsFromPlan: (plan: RoutePlan) => number[] | undefined;
+/**
+ * The plan's `RouteKind`, per the route-search design's section 1: `'direct'`
+ * when signature 1 IS the omnibridge crossing itself (no aggregator prefix —
+ * `buildDirectCrossingCandidate`'s shape, and `buildOutboundRouteData`'s
+ * shape), `'conversion'` when the LAST hop is a PulseX swap
+ * (`buildConversionRouteData`'s shape), `'aggregated'` otherwise (an
+ * aggregator carries signature 1, fused with a bridge hop or not —
+ * `buildNearIntentsTwoStepRouteData`'s shape, and the general
+ * aggregator-fused shape).
+ *
+ * DIVERGES FROM TODAY'S LITERAL OUTPUT FOR ONE CASE, DELIBERATELY: a
+ * same-chain candidate built by `buildDirectCrossingCandidate` and rendered
+ * through `buildCandidateRouteData` today always comes back `kind:
+ * 'aggregated'`, because that builder hard-codes `'aggregated'`
+ * unconditionally — an artifact of `RouteCandidate.entryChainId` being
+ * non-nullable, so `buildCandidateRouteData` always assumes an
+ * aggregator-entry shape even for a candidate with no aggregator leg at all.
+ * This function instead answers `'direct'` for that exact plan, matching how
+ * `buildDirectRouteData` (the OTHER, non-candidate 'direct' family) already
+ * represents the identical real-world same-chain crossing. See this
+ * module's test file for the specific case.
+ *
+ * @param plan - the plan to derive from
+ * @returns the route's kind
+ */
+export declare const derivePlanKind: (plan: RoutePlan) => RouteKind;
+/**
+ * The plan's headline provider — the omnibridge crossing it out when it
+ * crosses one, or whichever carrier performs signature 1 when it does not.
+ * Matches every existing builder's own headline choice: the omnibridge when
+ * present (`buildCandidateRouteData`, `buildNearIntentsTwoStepRouteData`,
+ * `buildOutboundRouteData`), the aggregator's own key as the fallback
+ * (`buildCandidateRouteData`'s no-omnibridge branch).
+ *
+ * @param plan - the plan to derive from
+ * @returns the headline provider key
+ */
+export declare const deriveHeadlineProviderKeyFromPlan: (plan: RoutePlan) => ProviderKey;
+/**
+ * The anchor a two-signature plan leaves the reader holding between its
+ * first and second groups — `RouteCandidate.plan`'s own TSDoc: "the anchor
+ * the reader is left holding between signatures... taken from the first hop
+ * of the second group." Reuses `describeDeferredCrossing`
+ * (`../../near-intents-route.js`) rather than re-validating the same
+ * "positive amount, resolved token" rule a second time.
+ *
+ * Null when the plan has only one signature group (there is no deferred
+ * crossing to describe) or the plan is malformed (a signature group naming
+ * hop indices the plan does not have).
+ *
+ * @param plan - the plan to derive from
+ * @param resolveToken - resolves a graph node to its full display token
+ * @param anchorUsdValue - the anchor's own carrier's valuation of the
+ *   landing, exactly as `DeferredCrossing.anchorUsdValue` expects — supplied
+ *   by the caller, since a plan carries no United States dollar figures.
+ * @returns the deferred crossing, or null
+ */
+export declare const deriveDeferredCrossingFromPlan: (plan: RoutePlan, resolveToken: ResolveNodeToken, anchorUsdValue: string | null) => DeferredCrossing | null;
+/**
+ * The caller-supplied dollar figures and breakdown for ONE signature group —
+ * everything about a section this module cannot derive from the plan's
+ * structure alone (see this module's head doc).
+ */
+export type PlanSectionPricing = {
+    /**
+     * What this section leaves the user holding, in United States dollars, or
+     * null when unpriced — `RouteLandingData.usdValue` for this section.
+     */
+    landingUsdValue: number | null;
+    /** This section's own cost, in United States dollars, or null when unpriced. */
+    feeUsdValue: number | null;
+    /**
+     * Each hop's own share of `feeUsdValue`, one entry per hop of the group in
+     * order, or omitted when the caller cannot price every hop.
+     *
+     * WHY A FUSED SECTION NEEDS THIS. One signature can carry two legs: an
+     * aggregator lands on the bridge's entry chain and makes the entry call in
+     * the same transaction. With no per-hop figure, a display that splits the
+     * section into legs can only put the whole cost on the first leg, so the
+     * aggregator wore the bridge's fee and the bridge leg read as free. The
+     * caller passes shares that add up to `feeUsdValue`, or nothing.
+     */
+    hopFeeUsdValues?: readonly (number | null)[];
+    /**
+     * The gas split of `feeUsdValue`, from a producer that prices network gas
+     * apart: `feeExcludingGasUsdValue` is the cost without gas, `gasUsdValue` the
+     * signature's gas (null when unknown). `hopFeeExcludingGasUsdValues` splits
+     * the first the way `hopFeeUsdValues` splits the all-in figure. The gas sits
+     * on the section's first hop.
+     */
+    feeExcludingGasUsdValue?: number | null;
+    gasUsdValue?: number | null;
+    hopFeeExcludingGasUsdValues?: readonly (number | null)[];
+    /** The itemized charges behind `feeUsdValue`, passed straight through to `RouteSectionData.fees`. */
+    fees?: readonly QuoteFee[];
+    /** Estimated duration for this signature in minutes, or null/undefined to omit. */
+    etaMinutes?: number | null;
+    /** Estimated duration for this signature in seconds, or null/undefined to omit. */
+    etaSeconds?: number | null;
+    /** Explanation shown for a deferred section; omitted lets the display adapter supply its default. */
+    deferredNote?: string;
+    /**
+     * Overrides this section's `landing.amount`. Omitted (the default) uses
+     * the plan's own composed estimate — the group's last hop's
+     * `outcome.deliveredAmount` — which is always present, per design section
+     * 3 ("only signature 1 must be binding... every later hop['s] outcome" is
+     * still an estimate, never absent). Pass `null` explicitly ONLY to
+     * reproduce a builder that states no figure at all for a leg it has not
+     * yet quoted by ANY means, composed or otherwise — `buildOutboundRouteData`'s
+     * deferred section is the one target shape that does this; see this
+     * module's test file for why that is a real, if now avoidable, gap rather
+     * than a rule to keep by default.
+     */
+    landingAmountOverride?: bigint | null;
+};
+/** Everything {@link buildRouteDataFromPlan} needs beyond the plan's own structure. */
+export type PlanRouteDataInputs = {
+    /** The priced plan to render. */
+    plan: RoutePlan;
+    /** Resolves a graph node to its full display token. */
+    resolveToken: ResolveNodeToken;
+    /** Stable identity for the route's sections, mirroring `RouteCandidate.id`. */
+    routeId: string;
+    /** One entry per signature group, in `plan.signatures` order. */
+    sections: readonly PlanSectionPricing[];
+    /** The route's aggregate all-in cost in United States dollars, or null/undefined. */
+    totalCostUsdValue?: number | null;
+    /** The all-in cost without network gas, or null/undefined. */
+    costExcludingGasUsdValue?: number | null;
+    /** The route's network gas in dollars, or null/undefined when unknown. */
+    gasCostUsdValue?: number | null;
+    /** The gas by signing chain, in signing order. */
+    gasByChain?: readonly RouteGasByChain[];
+    /** The route's net United States dollar outcome — the figure routes are ranked on. */
+    netValueUsd?: number | null;
+    /** Estimated end-to-end duration in minutes, or null/undefined. */
+    etaMinutes?: number | null;
+};
+/**
+ * Turns a priced {@link RoutePlan} into a raw {@link RouteData} — one section
+ * per signature group, `deferred` on every group after the first, each
+ * section's hops and token flow drawn structurally from the plan, and the
+ * dollar figures overlaid from `inputs.sections`. See this module's head doc
+ * for why the dollar figures are caller-supplied rather than derived here.
+ *
+ * NEVER SHOWS AN UNPRICED HEADLINE FIGURE, AND MARKS EVERY OTHER ESTIMATE AS
+ * ONE — PHASE 3. A section (and the route's own `output`) whose last hop is
+ * grounded on `EstimateBasis` `'unpriced'` lands on `amount: null`, whatever
+ * the caller's own pricing says, per {@link sectionLandingAmount}'s own doc.
+ * Every OTHER estimate (`'probe-rate'`, `'priced-conversion'`) still shows
+ * its figure, with `estimateBasis` set to that basis so a reader is never
+ * shown a composed/probed number as if it were a confirmed quote — see
+ * `RouteOutputData.estimateBasis`'s own doc (`../route-data.ts`) for the
+ * full rule this reads off {@link hopEstimateBasis}.
+ *
+ * @param inputs - the plan, a token resolver, an id, and per-section pricing
+ * @returns the raw route data
+ */
+export declare const buildRouteDataFromPlan: (inputs: PlanRouteDataInputs) => RouteData;
+/** Everything {@link buildRouteCandidateFromPlan} needs beyond the plan's own structure. */
+export type PlanCandidateInputs = {
+    /** The priced plan to build a candidate for. */
+    plan: RoutePlan;
+    /** Resolves a graph node to its full display token. */
+    resolveToken: ResolveNodeToken;
+    /** Stable identity for the candidate, mirroring today's `candidate.id`. */
+    id: string;
+    /** The base-unit amount entering the plan's first hop. */
+    inputAmount: bigint;
+    /** What the reader pays for the plan's first hop, exactly as its own carrier reported it. */
+    paidUsdValue: string | null;
+    /**
+     * What the plan's LAST hop's own carrier valued its delivered side at —
+     * read only when the plan crosses no bridge hop, mirroring
+     * `candidateDeliveredUsd`'s no-omnibridge branch.
+     */
+    lastHopDeliveredUsdValue: string | null;
+    /** Per-destination-token United States dollar price, or null. */
+    destinationUsdPrice: number | null;
+    /** The omnibridge crossing fee, in destination-token base units. */
+    omnibridgeFeeAmount?: bigint;
+    /** The anchor's own carrier's valuation of the deferred-crossing landing, when the plan defers one. */
+    anchorUsdValue?: string | null;
+    /** The reader's typed amount, when it differs from `inputAmount` (see `RouteCandidate.requestedAmount`). */
+    requestedAmount?: bigint | null;
+    /** Charges the plan's carriers report outside `fromAmount`. */
+    fees?: readonly QuoteFee[];
+    /** The plan's first hop's own carrier-claimed execution duration, in seconds. */
+    executionDurationSeconds?: number;
+};
+/**
+ * Turns a priced {@link RoutePlan} into a {@link RouteCandidate}, filling
+ * `plan` and deriving `deferredCrossing`, `entryChainId` and
+ * `omnibridgeProvider` from it exactly as `RouteCandidate.plan`'s own TSDoc
+ * (`../candidate.ts`) promises.
+ *
+ * @param inputs - the plan, a token resolver, an id, and the caller's pricing
+ * @returns the route candidate
+ */
+export declare const buildRouteCandidateFromPlan: (inputs: PlanCandidateInputs) => RouteCandidate;
+/**
+ * Everything {@link buildRouteScoreInputsFromPlan} needs beyond the plan's
+ * own structure and `gaslessIntermediateChainCount`, which the design's own
+ * `RouteScoreInputs` doc says is "an input from the interface" — a live
+ * wallet balance read this pure module cannot perform.
+ */
+export type PlanValuation = PlanCandidateInputs & {
+    /** Each hop's own carrier-claimed execution duration, in seconds, in hop order. */
+    legClaimedDurationsSeconds: readonly (number | null | undefined)[];
+};
+/**
+ * Turns a priced {@link RoutePlan} into {@link RouteScoreInputs} — reusing
+ * `candidateDeliveredUsd`, `candidatePaidUsd` and `candidateOutsideFeesUsd`
+ * (`../producers.js`) against the SAME candidate
+ * {@link buildRouteCandidateFromPlan} builds, exactly as `RouteScoreInputs`'
+ * own doc in `score.ts` asks: "generalized to the plan's LAST hop and FIRST
+ * hop respectively... import and reuse them; do not write a second
+ * valuation."
+ *
+ * @param valuation - the plan, a token resolver, an id, and the caller's pricing
+ * @param gaslessIntermediateChainCount - intermediate chains the connected
+ *   account holds no gas on — supplied by the caller, never computed here
+ * @returns the plan's score inputs
+ */
+export declare const buildRouteScoreInputsFromPlan: (valuation: PlanValuation, gaslessIntermediateChainCount: number) => RouteScoreInputs;