@gibs/bridge-sdk 1.10.1 → 1.13.0

package/dist/routing/producers.d.ts

@@ -0,0 +1,770 @@
+/**
+ * Pure route-producer helpers and constants shared by every route builder.
+ * Lives in the software development kit so the builders can relocate here in
+ * subsequent tasks without pulling user-interface dependencies into the kit.
+ *
+ * All helpers are framework-agnostic: no React, no Svelte, no display formatters.
+ */
+import { type Provider } from '../config.js';
+import type { DeliveryFee } from '../settings.js';
+import type { RouteCandidate } from './candidate.js';
+import type { Token, BridgeKey } from '../types.js';
+import type { RouteData, RouteSectionData } from './route-data.js';
+import { type Hex } from 'viem';
+/**
+ * Divisor for the MARGINAL reference swap quote. A swap's price impact cannot be
+ * read from the trade quote alone — `getAmountsOut(fullInput)` already folds the
+ * impact into its output, and the PulseChain USD prices are themselves PulseX
+ * pool quotes, so differencing them cancels the impact out (it vanishes to
+ * $0.00). Instead the estimate quotes a TINY reference input — `1/this` of the
+ * trade — whose own impact is negligible, giving the near-spot marginal rate. The
+ * gap between that marginal rate and the full trade's realized rate IS the price
+ * impact (the swap fee rides in BOTH quotes, so it cancels and the gap is impact
+ * alone). 1/10000 of the trade is small enough to be effectively marginal yet
+ * large enough that its output does not round away.
+ */
+export declare const PULSEX_MARGINAL_REFERENCE_DIVISOR = 10000n;
+/**
+ * The approximate wall-clock wait for an omnibridge crossing to settle before a
+ * DEFERRED swap leg can be signed — the same ~20 minutes whether the swap happens
+ * on the entry chain (outbound PulseChain → Ethereum/Binance Smart Chain) or on
+ * PulseChain (conversion route: bridge an anchor in, then swap on PulseX).
+ * Surfaced compactly as `~20 min` in the deferred section head, mirroring how
+ * every other section shows its estimate, rather than spelled out inside the
+ * deferred note.
+ */
+export declare const BRIDGE_SETTLEMENT_ETA_MINUTES = 20;
+/** Decimal chain id for PulseChain — the shared destination of every inbound route. */
+export declare const pulsechainChainId: number;
+/**
+ * The display name for an omnibridge crossing, fully spelled out. Narrowed to
+ * exactly {@link Provider} — the two real crossings — rather than any string,
+ * so passing an aggregator's `ProviderId` (or anything else) is a COMPILE
+ * ERROR here, not a silently wrong name.
+ *
+ * PREFER THIS OVER {@link providerDisplayName} wherever the caller already
+ * holds a genuine `Provider`. `providerDisplayName` exists only because some
+ * callers (`RouteCandidate.omnibridgeProvider`, `RouteData.headlineProviderKey`)
+ * are typed `string` at their own source and cannot be narrowed from here.
+ *
+ * @param provider - a real omnibridge provider
+ * @returns the spelled-out provider name
+ */
+export declare const omnibridgeProviderDisplayName: (provider: Provider) => string;
+/**
+ * Adds two nullable United States dollar NUMBERS. A null operand contributes
+ * nothing; two nulls yield null so an all-unpriced route keeps a null cost rather
+ * than a misleading 0.
+ *
+ * This sums the RAW values and leaves the single cent-rounding to the display
+ * adapter (round(a + b)). It deliberately differs from the pre-split
+ * `sumFormattedUsd`, which summed two already-cent-rounded strings
+ * (round(a) + round(b)); the two can diverge by a cent when both operands carry
+ * sub-cent fractions. Rounding the total once is the more accurate result and
+ * keeps this helper free of any display formatter, so the raw producers stay
+ * relocatable. See the "sums the raw total once" test for the locked behavior.
+ *
+ * @param first - the first dollar value, or null/undefined when absent
+ * @param second - the second dollar value, or null/undefined when absent
+ * @returns the sum, or null when both operands are absent
+ */
+export declare const addUsdValues: (first: number | null | undefined, second: number | null | undefined) => number | null;
+/**
+ * Subtracts a cost from a dollar value on the SAME basis — the operation every
+ * producer uses to derive what a leg delivers from what entered it.
+ *
+ * Unlike {@link addUsdValues} this is deliberately NOT symmetric about null: an
+ * unknown starting value cannot be reduced, so it stays unknown, while an unknown
+ * cost is treated as no cost. That asymmetry is what keeps a route with one
+ * unpriced leg from reporting a delivered value it never established.
+ *
+ * @param value - the dollar value entering the leg, or null/undefined when unknown
+ * @param cost - the leg's dollar cost, or null/undefined when unpriced
+ * @returns the value less the cost, or null when the starting value is unknown
+ */
+export declare const subtractUsdValues: (value: number | null | undefined, cost: number | null | undefined) => number | null;
+/**
+ * The display name for an omnibridge crossing, accepting a raw `string` rather
+ * than {@link Provider}.
+ *
+ * PREFER {@link omnibridgeProviderDisplayName} INSTEAD wherever the caller
+ * already holds a genuine `Provider` — that one is a compile error for
+ * anything else. This wide version exists only for callers whose OWN field is
+ * typed `string` at its source and so cannot be narrowed here:
+ * `RouteCandidate.omnibridgeProvider` and `RouteData.headlineProviderKey`
+ * (`routing/candidate.ts`, `routing/route-data.ts`).
+ *
+ * KEPT DELIBERATELY NON-THROWING, UNLIKE {@link providerById}. The obvious
+ * next step — throw on an unrecognized key, the way `providerById` does for
+ * an aggregator — was tried and reverted: `toRouteView.ts`'s headline
+ * resolution calls this with `RouteData.headlineProviderKey`, a `string` this
+ * repository does not otherwise guarantee is a real provider of ANY kind, and
+ * an existing, deliberate test (`toRouteView.test.ts`, "headline falls back
+ * to 'Omnibridge' for an unknown headline provider key") requires that a
+ * genuinely-unrecognized key render a generic label rather than crash the
+ * whole route card. A NEAR Intents leg being mislabeled "Omnibridge" was a
+ * real defect (see `near-intents-route.ts`), fixed there by calling the
+ * RIGHT function (`providerById(id).label`) instead of this one — not by
+ * making this one less forgiving of input nobody validates before it arrives.
+ *
+ * `'PulseX'` IS RECOGNIZED HERE TOO, unlike an aggregator `ProviderId`, and for
+ * a different reason than the omnibridge case: it needs no registry lookup —
+ * there is exactly one PulseX, the label IS the key — so there is nothing an
+ * aggregator-style `providerById(id).label` call would add. A same-chain
+ * PulseX swap route (`RouteData.kind === 'swap'`) has NO omnibridge leg at
+ * all, so falling back to "Omnibridge" for it would name a bridge that never
+ * ran.
+ *
+ * @param provider - the raw provider key (e.g. `'pulsechain'`, `'PulseX'`)
+ * @returns the spelled-out provider name, or "Omnibridge" when unregistered
+ */
+export declare const providerDisplayName: (provider: string) => string;
+/**
+ * The fully spelled-out display name of an omnibridge entry chain, or null when
+ * the chain id is null or is not one of the two entry points (Ethereum, Binance
+ * Smart Chain). A null result makes route builders return null, so an
+ * unrecognised destination leaves the strip empty rather than naming a chain it
+ * cannot bridge to.
+ *
+ * @param entryChainId - the decimal entry chain id, or null for direct routes
+ * @returns the spelled-out chain name, or null
+ */
+export declare const resolveEntryChainName: (entryChainId: number | null) => string | null;
+/**
+ * Parses one of the aggregator's own United States dollar figures —
+ * `fromAmountUsd` or `toAmountUsd` on a candidate's quote.
+ *
+ * `Number('')` IS `0`, NOT "UNKNOWN", and both the LI.FI and Relay quote
+ * parsers can hand this module a blank amount string. Read with a bare
+ * `Number()`, a blank `fromAmountUsd` priced a route's origin leg at zero
+ * cost — one measured case showed a route reporting a net gain of +$273 that
+ * had in fact cost real money, and led the strip on the strength of it — and
+ * a blank `toAmountUsd` would do the same to what a direct route (no
+ * omnibridge leg) reports as delivered. A dollar figure only means something
+ * when it is a positive, finite number: blank text, non-numeric text, zero,
+ * and a negative number are all treated as UNPRICED rather than free.
+ *
+ * @param raw - the provider's amount string, or null/undefined when absent
+ * @returns the parsed value, or null when the field cannot be trusted
+ */
+export declare const usdNumber: (raw: string | null | undefined) => number | null;
+/**
+ * What the user pays for a candidate's origin leg, in United States dollars, as
+ * the provider itself valued it (`fromAmountUsd`). This is the candidate's SOURCE
+ * BASIS: every dollar figure the route reports is derived from it, so the costs
+ * shown and the value delivered can never drift onto different price sources.
+ *
+ * @param candidate - the priced route candidate
+ * @returns the amount paid in United States dollars, or null when the provider gave none
+ */
+/**
+ * Exported so `search/plan-route-data.ts` can generalize this SAME valuation
+ * to a general-search plan's first hop, per the route-search design's
+ * `RouteScoreInputs` doc ("import and reuse them; do not write a second
+ * valuation") — a candidate-shaped module boundary, not a second formula.
+ */
+export declare const candidatePaidUsd: (candidate: RouteCandidate) => number | null;
+/**
+ * What a candidate's delivered tokens are worth, in United States dollars.
+ *
+ * TWO SOURCES, AND WHICH ONE APPLIES IS DECIDED BY WHETHER A SECOND LEG
+ * FOLLOWS — never by which one happens to be present.
+ *
+ * A route with no omnibridge leg ends where the provider drops the funds, so
+ * the provider valued the very tokens the reader receives, in the same answer
+ * and on the same feed as `fromAmountUsd`. The difference between the two is
+ * then the route's cost and nothing else. This is the case that had no price at
+ * all: the destination chain is not one the bridge's own price sources cover,
+ * so `destinationUsdPrice` arrived null and every direct route reported no fee.
+ *
+ * A route that continues through the omnibridge must NOT use it. The provider's
+ * delivered side there is the entry chain's tokens, handed to the mediator —
+ * not what finally lands on PulseChain, which is what `deliveredAmount` counts.
+ * Those two differ by the omnibridge's own fee, so reading the provider's
+ * figure would report a crossing as free.
+ *
+ * Exported because the ranking must value a route on the SAME basis the route
+ * states. The ranker used to price the delivered tokens against
+ * `destinationUsdPrice` alone, which is null on every direct route, so every
+ * direct route was unpriced and the ranker fell back to an order that could not
+ * see what each route delivers.
+ *
+ * @param candidate - the priced route candidate
+ * @returns the delivered value in United States dollars, or null when unpriced
+ */
+export declare const candidateDeliveredUsd: (candidate: RouteCandidate) => number | null;
+/**
+ * The fee inputs an omnibridge crossing's cost is built from. Shared by the
+ * direct and the outbound builders, which cross the same bridge.
+ *
+ * WHY TWO INPUTS AND NOT ONE. The route used to state its cost from the
+ * delivery fee alone. A crossing out of PulseChain to Ethereum pays the
+ * bridge 0.3% before delivery takes its 0.05%, so 1,000 WETH in showed a cost
+ * of 0.4985 ETH while 3.4985 left the reader's hands: understated about seven
+ * times. Over Tokens Express to Binance Smart Chain the bridge takes 2.97%, and
+ * the understatement was about sixty times. Each fee now arrives as its own
+ * fact, from the settings cascade that already knows it.
+ */
+export type CrossingFeeRoots = {
+    /**
+     * The bridge's own fee, in base units of the token on the side where its fee
+     * manager lives (see {@link bridgeFeeToken}). This is `bridgeCost` from the
+     * settings cascade: `amountToBridge * fee / 1 ether`, which is exactly
+     * `amountToBridge - amountAfterBridgeFee`. Null while the fee manager's rate
+     * is still loading, which makes the route's cost unknown.
+     */
+    bridgeFeeAmount: bigint | null;
+    /**
+     * The bridge fee's rate as a fraction of one ether (3e15 is 0.3%), for the
+     * fee's label only. Null or absent leaves the rate out of the label.
+     */
+    bridgeFeeRate?: bigint | null;
+    /**
+     * The Gibs delivery fee, which tells "no delivery" apart from "not priced
+     * yet". Build it with `deliveryFee` from the settings module.
+     */
+    deliveryFee: DeliveryFee;
+};
+/**
+ * Everything a candidate is charged that sits OUTSIDE `fromAmount`, in United
+ * States dollars.
+ *
+ * THIS REPLACES A PER-STEP GAS SUM that could only ever see part of the picture.
+ * That sum read `step.gasUsd`, so it was ZERO for every Relay quote — Relay
+ * publishes no per-leg breakdown — and for LI.FI it counted the network gas
+ * while missing the larger charge: a LayerZero fee of about 1.37 dollars marked
+ * `included: false`, paid on top in native currency. Reading the quote's own
+ * normalized fee list catches both, and cannot double-count the per-step gas
+ * against the aggregate the provider reports.
+ *
+ * A charge whose dollar value the provider did not give is skipped rather than
+ * guessed. It is still named in the breakdown the reader can open.
+ *
+ * Exported for the same reason {@link candidatePaidUsd} is — `search/plan-route-data.ts`
+ * reuses this exact valuation rather than restating it for a plan's last hop.
+ */
+export declare const candidateOutsideFeesUsd: (candidate: RouteCandidate) => number;
+/**
+ * The user's NET dollar outcome for a candidate: the value delivered minus
+ * everything paid to reach it. Three cost components:
+ *
+ *  - the origin tokens spent (`quote.fromAmountUsd`);
+ *  - every charge paid on top ({@link candidateOutsideFeesUsd}), NOT part of
+ *    `fromAmount` — the sender's own network gas, and any provider fee the
+ *    quote marked as charged outside the amount;
+ *  - the omnibridge CROSSING fee, already netted into `deliveredAmount`.
+ *
+ * The delivered value comes from {@link candidateDeliveredUsd}, the same figure
+ * the route's own dollar value and cost are built from. This is the one ranking
+ * rule: the route strip orders by it, so the route the reader sees costing least
+ * is the route that leads.
+ *
+ * @param candidate - the priced route candidate
+ * @returns the net outcome in United States dollars, or null when the leg or
+ *   the delivered tokens are unpriced
+ */
+export declare const candidateNetValueUsd: (candidate: RouteCandidate) => number | null;
+/**
+ * The roots the direct-route builder reads. See full documentation on
+ * {@link buildDirectRouteData}.
+ */
+export type DirectRouteRoots = CrossingFeeRoots & {
+    /** Logo url for the input (source) token, or null. */
+    assetInLogoUri?: string | null;
+    /** Logo url for the output (delivered) token, or null. */
+    assetOutLogoUri?: string | null;
+    /** Logo url for the source chain badge, or null. */
+    fromChainLogoUri?: string | null;
+    /** Logo url for the destination chain badge, or null. */
+    toChainLogoUri?: string | null;
+    /** The active bridge key tuple `[provider, fromChain, toChain]`. */
+    bridgeKey: BridgeKey;
+    /** The resolved input token, or null while the cascade is still resolving. */
+    assetIn: Token | null;
+    /** The resolved output (delivered) token, or null. */
+    assetOut: Token | null;
+    /**
+     * The estimated delivered amount in `assetOut` base units (after the bridge fee
+     * and delivery cost). Zero before the user enters an amount, which renders the
+     * route's amounts as zero.
+     */
+    estimatedAmountOut: bigint;
+    /**
+     * Per-`assetIn`-token United States dollar price, or null when unpriced. This is
+     * the route's basis: BOTH the fee and the delivered value are priced from it, so
+     * the two sides of the crossing can never be stated on different feeds.
+     */
+    assetInUsdPrice: number | null;
+    /**
+     * Per-`assetOut`-token United States dollar price, or null when unpriced. Used
+     * ONLY as the fallback basis for the delivered value when `assetInUsdPrice` is
+     * absent — never alongside it, which is what let a zero-fee crossing report a loss.
+     */
+    assetOutUsdPrice: number | null;
+    /**
+     * Per-step transaction-transparency passthrough — the bridge mediator
+     * addresses, destination router, and encoded calldata for the single direct
+     * signature. Optional; the produced section carries it verbatim when supplied.
+     */
+    advanced?: {
+        bridgeFrom?: Hex | null;
+        bridgeTo?: Hex | null;
+        destinationRouter?: Hex | null;
+        calldata?: Hex | null;
+    };
+};
+/**
+ * Builds the RAW, data-only {@link RouteData} for one priced aggregator candidate
+ * — the framework-agnostic half of the candidate path, carrying NUMBERS, raw
+ * token references, and raw provider keys ONLY. The display wrapper runs this
+ * through `toRouteView` to resolve every logo, name, formatted string, and the
+ * structural id.
+ *
+ * The candidate is a single signature (the aggregator swap auto-calls the
+ * omnibridge), so it produces exactly one {@link RouteSectionData} whose hops are
+ * the aggregator legs the provider reported (Relay reports none) followed by the
+ * omnibridge crossing leg. Each hop carries its OWN numeric fee so the user sees
+ * where cost accrues.
+ *
+ * @param candidate - one priced route candidate
+ * @returns the raw, data-only route for the candidate
+ */
+export declare const buildCandidateRouteData: (candidate: RouteCandidate) => RouteData;
+/**
+ * Builds the ALWAYS-PRESENT direct omnibridge route from the current outbound
+ * settings, so the strip is never empty for a resolvable pathway.
+ *
+ * The direct route is a SINGLE SIGNATURE — the user signs the omnibridge call
+ * once — so it is exactly ONE {@link RouteSectionData}. Returns null only when
+ * the pathway is NOT resolvable (a missing input or output asset).
+ *
+ * @param roots - the resolved settings + price + logo roots (see {@link DirectRouteRoots})
+ * @returns the single direct {@link RouteData}, or null when unresolvable
+ */
+export declare const buildDirectRouteData: (roots: DirectRouteRoots) => RouteData | null;
+/**
+ * Where an outbound route's SECOND signature lands when it leaves the entry chain
+ * rather than swapping on it.
+ *
+ * WHY THESE THREE FACTS ARRIVE TOGETHER rather than as three optional fields on
+ * the roots. Each one alone is enough to describe a route that cannot be drawn.
+ * A chain id with no name leaves section 2 labelled after the entry chain while
+ * its token sits on another; a chain with no provider leaves the hop credited to
+ * "Swap", which is the PulseX label and the wrong service. Grouping them means a
+ * caller either states the whole onward hop or states none of it, and the absent
+ * case is the existing same-chain swap, unchanged.
+ *
+ * THE OMNIBRIDGE STILL CROSSES ONLY TO ETHEREUM OR BINANCE SMART CHAIN. This
+ * widens where the SECOND leg may land, never where the first one may. The entry
+ * guard in {@link buildOutboundRouteData} is unaffected.
+ */
+export type OutboundOnwardHop = {
+    /**
+     * The decimal chain id the deferred leg delivers on. Must equal the
+     * `finalToken`'s own `chainId`; the builder returns null when they disagree
+     * rather than drawing a token on a chain it does not live on.
+     */
+    chainId: number;
+    /**
+     * The chain's fully spelled-out name, for section 2's label and the hop title.
+     * Resolved by the caller, which owns the chain table — the same threading the
+     * logo urls already use.
+     */
+    chainName: string;
+    /**
+     * The display name of the service that will quote and carry the onward hop
+     * (for example "Relay"), from the provider registry. This hop is NOT a PulseX
+     * swap and must not be credited to one.
+     */
+    providerName: string;
+    /** Pre-resolved chain-badge logo url for `chainId`; undefined lets the adapter resolve it. */
+    chainLogoUri?: string | null;
+};
+/**
+ * The roots the OUTBOUND two-signature route builder reads. See full documentation
+ * on {@link buildOutboundRouteData}.
+ */
+export type OutboundRouteRoots = CrossingFeeRoots & {
+    /** Logo url for the input (source) token, or null. */
+    assetInLogoUri?: string | null;
+    /** Logo url for the output (delivered) token, or null. */
+    assetOutLogoUri?: string | null;
+    /** Logo url for the source chain badge, or null. */
+    fromChainLogoUri?: string | null;
+    /** Logo url for the destination chain badge, or null. */
+    toChainLogoUri?: string | null;
+    /** The active outbound omnibridge pathway tuple `[provider, fromChain, toChain]`. */
+    bridgeKey: BridgeKey;
+    /** The resolved PulseChain source token, or null while the cascade resolves. */
+    assetIn: Token | null;
+    /**
+     * The token the omnibridge delivers on the entry chain (Ethereum / Binance
+     * Smart Chain). It is section 1's destination and section 2's source. Null
+     * while the cascade resolves — the builder then returns null.
+     */
+    intermediateToken: Token | null;
+    /**
+     * The token the user ultimately wants — section 2's destination. It sits on the
+     * ENTRY chain by default and on {@link OutboundOnwardHop.chainId} when `onward`
+     * is supplied. Null while the cascade resolves — the builder then returns null.
+     */
+    finalToken: Token | null;
+    /**
+     * Where section 2 lands when it is NOT a swap on the entry chain. Absent (or
+     * null) keeps today's behaviour exactly: the deferred leg is a PulseX-style swap
+     * that stays on the entry chain. See {@link OutboundOnwardHop}.
+     */
+    onward?: OutboundOnwardHop | null;
+    /**
+     * The omnibridge-delivered amount of `intermediateToken`, in its base units
+     * (leg 1's output). Zero before the user enters an amount.
+     */
+    estimatedAmountOut: bigint;
+    /** Per-`assetIn`-token United States dollar price, or null when unpriced. */
+    assetInUsdPrice: number | null;
+    /** Per-`intermediateToken` United States dollar price, or null when unpriced. */
+    intermediateUsdPrice: number | null;
+    /**
+     * Logo url for the `finalToken` (the deferred leg's destination token), or null
+     * to fall back to a placeholder glyph in section 2's token flow.
+     */
+    finalTokenLogoUri?: string | null;
+    /**
+     * Logo url for the entry chain's badge (Ethereum / Binance Smart Chain), used on
+     * the intermediate and final token nodes that both live on the entry chain, or
+     * null to omit the badge.
+     */
+    intermediateChainLogoUri?: string | null;
+};
+/**
+ * Builds the TWO-SIGNATURE OUTBOUND raw {@link RouteData} from PulseChain, across
+ * an omnibridge entry chain (Ethereum or Binance Smart Chain), to wherever the
+ * second signature lands.
+ *
+ * The route is exactly TWO {@link RouteSectionData}s:
+ *  - SECTION 1 ("Bridge to {entry chain}") — the omnibridge out.
+ *  - SECTION 2 ("Complete at {final chain}") — DEFERRED. Signed only after section
+ *    1's crossing settles, and carrying no binding quote until then.
+ *
+ * SECTION 2 HAS TWO SHAPES, and `roots.onward` is what picks between them.
+ * Without it the deferred leg is a swap that stays on the entry chain: the
+ * existing behaviour, down to its approximate ~0.29% PulseX fee. With it the
+ * deferred leg is an onward BRIDGE to `onward.chainId`, carried by the named
+ * provider, and it states NO fee — see the fee note in the body for why quoting
+ * the swap constant there would be a fabricated number.
+ *
+ * WHY THE FIRST LEG CANNOT WIDEN THE SAME WAY. The bridged message carries
+ * `(token, receiver, value, data)` and no chain id, and a mediator's counterpart
+ * is wired in at deploy time, so the omnibridge's destination is structural
+ * rather than a parameter. The reach comes from composing a second signature on
+ * the far side, which is what this builder draws.
+ *
+ * Returns null when `assetIn`, `intermediateToken`, or `finalToken` is missing,
+ * when the crossing's destination is not one of the two omnibridge entry chains,
+ * or when `onward.chainId` disagrees with the final token's own `chainId`.
+ *
+ * @param roots - the resolved settings + price + logo roots (see {@link OutboundRouteRoots})
+ * @returns the two-section raw outbound {@link RouteData}, or null when unresolvable
+ */
+export declare const buildOutboundRouteData: (roots: OutboundRouteRoots) => RouteData | null;
+/**
+ * The roots the raw PulseX swap section builder reads. See full documentation on
+ * {@link buildPulseXSwapSectionData}.
+ */
+export type PulseXSwapSectionDataRoots = {
+    /**
+     * Caller-supplied stable identity for the section, used for keys and disclosure
+     * state. The composing route owns uniqueness, so this is passed in verbatim
+     * rather than derived here.
+     */
+    id: string;
+    /** The token held on PulseChain before the swap — the swap's input. */
+    fromToken: Token;
+    /** The token the user wants on PulseChain — the swap's output. */
+    toToken: Token;
+    /**
+     * The swap's TOTAL cost in United States dollars as a NUMBER, or null when the
+     * caller could not price the swap.
+     */
+    feeUsdValue?: number | null;
+    /**
+     * The swap's price impact as a percentage NUMBER, or null when unknown.
+     */
+    priceImpactPercent?: number | null;
+    /**
+     * The `toToken` amount the swap is expected to deliver, in base units — what
+     * this step lands the user in. Null or absent leaves the step naming its landed
+     * TOKEN without an amount, which is the honest reading for a leg that carries no
+     * binding quote yet.
+     */
+    landedAmount?: bigint | null;
+    /**
+     * The landed amount's value in United States dollars, or null when unpriced.
+     * Supplied by the composing route rather than derived here, so it stays on the
+     * same basis as every other figure that route reports.
+     */
+    landedUsdValue?: number | null;
+    /** Estimated swap duration in minutes, or null to omit the time chip. */
+    etaMinutes?: number | null;
+    /**
+     * Estimated swap duration in SECONDS, for the near-instant swap leg the minute
+     * chip would round misleadingly. Takes precedence over `etaMinutes` in the view.
+     */
+    etaSeconds?: number | null;
+    /** Logo url for the `fromToken` node, or null to fall back to a placeholder. */
+    fromTokenLogoUri?: string | null;
+    /** Logo url for the `toToken` node, or null to fall back to a placeholder. */
+    toTokenLogoUri?: string | null;
+    /**
+     * Logo url for the PulseChain chain badge shown on BOTH token-flow nodes (both
+     * tokens live on PulseChain), or null to omit the badge.
+     */
+    pulsechainChainLogoUri?: string | null;
+    /**
+     * True only in the rare case where the swap is signed AFTER a prior section's
+     * async bridge crossing settles. Defaults to false.
+     */
+    deferred?: boolean;
+    /**
+     * Transaction-transparency details for the advanced disclosure, built by the
+     * caller from the SAME builder the swap button itself calls
+     * (`pulseXSwapTransactionInputs` in `settings.ts`) — never a second encoding
+     * here. Absent while the swap is not yet buildable (no connected recipient,
+     * or no router deployed for the chain), which leaves the section's
+     * `advanced` field undefined rather than half-populated.
+     */
+    advanced?: {
+        /** The PulseX router this swap calls, or null when none is deployed. */
+        destinationRouter: Hex | null;
+        /** The swap's encoded calldata from `pulseXSwapTransactionInputs`, or null. */
+        calldata: Hex | null;
+    } | null;
+};
+/**
+ * Builds a single composable raw {@link RouteSectionData} for a swap on PulseX,
+ * the decentralized exchange on PulseChain. A composing route appends this to its
+ * `sections` array. Both tokens live on PulseChain (chain id 369), so both
+ * token-flow nodes carry the PulseChain chain badge.
+ *
+ * The section carries raw numeric fields (`feePercent`, `priceImpactPercent`,
+ * `feeUsdValue`); the adapter (`toRouteView`) formats them into the display
+ * breakdown string.
+ *
+ * @param roots - the section's identity, tokens, pricing, and logos
+ * @returns one raw PulseX swap {@link RouteSectionData}
+ */
+export declare const buildPulseXSwapSectionData: (roots: PulseXSwapSectionDataRoots) => RouteSectionData;
+/**
+ * The raw numeric counterpart of the string-formatted swap estimate: every field
+ * is a number (or bigint / null) instead of a formatted string. Produced by
+ * {@link buildPulseXSwapEstimateData} so the conversion composition can flow the
+ * numbers straight into a {@link RouteData} without re-parsing formatted currency
+ * strings.
+ */
+export type PulseXSwapEstimateData = {
+    /** The wanted-token amount the swap is expected to deliver, in base units. */
+    outputAmount: bigint;
+    /**
+     * The PulseX protocol fee alone in United States dollars as a plain number — the
+     * flat ~0.29% the exchange takes on the swapped value. Null only when NEITHER
+     * side is priced.
+     */
+    feeUsdValue: number | null;
+    /**
+     * The swap's TOTAL cost in United States dollars as a plain number — the fee
+     * PLUS the price impact. Null only when neither side is priced. Clamped at zero.
+     * The fee is rounded to cents before summing (matching the pre-split builder's
+     * rounding so downstream cents-level totals stay identical).
+     */
+    costUsdValue: number | null;
+    /**
+     * The swap's price impact as a percentage (e.g. 0.8 for "0.8% price impact").
+     * Null when both sides are not priced or no reference quote is supplied.
+     */
+    priceImpactPercent: number | null;
+    /** Estimated swap duration in minutes, or null (a PulseX swap is near-instant). */
+    etaMinutes: number | null;
+};
+/**
+ * Roots for {@link buildConversionRouteData}: the base raw route that delivers
+ * the anchor token onto PulseChain, the swap's tokens, the pre-derived raw
+ * estimate, and the logos for the appended swap section's token flow.
+ */
+export type ConversionRouteComposition = {
+    /**
+     * The raw route data that bridges the LIQUID anchor token onto PulseChain. Its
+     * last section delivers the anchor; this composition appends the PulseX swap
+     * that converts it to the wanted token.
+     */
+    baseData: RouteData;
+    /**
+     * The base route's display id, computed by the user interface via `toRouteView`
+     * and injected so this producer holds no display dependency. Only the swap
+     * section's React key uses it; `routeStripHash` ignores section ids, so it
+     * never affects route identity.
+     */
+    baseRouteId: string;
+    /** The anchor token the base route delivers on PulseChain — the swap's input. */
+    anchorToken: Token;
+    /** The token the user actually wants on PulseChain — the swap's output. */
+    wantedToken: Token;
+    /** The pre-derived raw swap figures (see {@link buildPulseXSwapEstimateData}). */
+    estimate: PulseXSwapEstimateData;
+    /** Logo url for the anchor token node in the swap section's flow, or null. */
+    anchorTokenLogoUri?: string | null;
+    /** Logo url for the wanted token node in the swap section's flow, or null. */
+    wantedTokenLogoUri?: string | null;
+    /** Logo url for the PulseChain chain badge on both swap-section nodes, or null. */
+    pulsechainChainLogoUri?: string | null;
+};
+/**
+ * Composes a raw {@link RouteData} for the conversion route: bridge a liquid anchor
+ * token onto PulseChain, then a DEFERRED PulseX swap to the wanted token.
+ *
+ * Operates entirely at the raw data level — no display formatting. The caller runs
+ * the result through `toRouteView` to get the display-ready `RouteOption`.
+ *
+ * Per the owner's two locked decisions:
+ *
+ *  - **LOCKED DECISION 1 — normalise via the liquid anchor.** When the omnibridge
+ *    cannot deliver the wanted token directly (the wanted token has not yet been
+ *    bridged, or its canonical foreign-chain pair is illiquid), the rails bridge a
+ *    well-known liquid anchor token instead and a PulseX swap leg converts it on
+ *    PulseChain. The {@link ConversionRouteComposition.baseData} is the raw route
+ *    that delivers that anchor; this function appends the conversion leg. The two
+ *    combined sections represent one complete user journey: bridge to the anchor,
+ *    then swap the anchor to the wanted token.
+ *
+ *  - **LOCKED DECISION 2 — the swap is a deferred second signature.** The PulseX
+ *    swap can only be signed AFTER the PulseChain Bridge lands the anchor on
+ *    PulseChain — the funds must arrive before the user can authorise the swap. The
+ *    appended section therefore carries `deferred: true` and an ESTIMATED fee that
+ *    firms up on arrival (price impact and pool depth may shift in the ~20 minutes
+ *    the crossing takes). Do not collapse these into one signature.
+ *
+ * The composed route:
+ *  - keeps the base route's provider and entry chain (`entryChainId` / `via`) — it
+ *    is the same PulseChain Bridge crossing with a swap bolted on at the
+ *    destination;
+ *  - takes a DISTINCT identifier (`<baseRouteId>-pulsex-swap`) so React keys and
+ *    selection never collide with the bare anchor-delivery route;
+ *  - re-drives the output to the wanted token: the estimate's delivered amount, its
+ *    United States dollar value, and the wanted token's symbol (the bare anchor
+ *    route would otherwise claim the anchor as the delivered token);
+ *  - sums the swap's total cost (fee + price impact) into `totalCostUsdValue` so
+ *    the aggregate cost is honest — aggregator spread + omnibridge crossing +
+ *    PulseX swap — and subtracts it from `netValueUsd`.
+ *
+ * @param composition - the base route data, swap tokens, estimate, logos, and the
+ *   injected base route id (computed by the caller via `toRouteView`)
+ * @returns the composed raw two-section conversion route (bridge, then deferred PulseX swap)
+ */
+export declare const buildConversionRouteData: (composition: ConversionRouteComposition) => RouteData;
+/**
+ * Derives a {@link PulseXSwapEstimateData} — the raw NUMERIC form of the PulseX
+ * swap estimate — from a PulseX `getAmountsOut` quote.
+ *
+ * Returns raw numbers rather than formatted currency strings, so the conversion
+ * composition can flow them straight into a {@link RouteData} without re-parsing
+ * currency strings.
+ *
+ * Returns null when the quote is absent or empty (the router reverted or has not
+ * loaded) — the composing route then has no swap leg to append.
+ *
+ * @param params.amountsOut - the router's amounts-out array, or null when unquoted
+ * @param params.inputAmount - the anchor amount entering the swap, in its base units
+ * @param params.inputToken - the anchor token (the swap input)
+ * @param params.inputUsdPrice - the anchor token's per-token dollar price, or null
+ * @param params.outputToken - the wanted token (the swap output)
+ * @param params.outputUsdPrice - the wanted token's per-token dollar price, or null
+ * @param params.referenceAmountsOut - marginal reference quote amounts-out, or null
+ * @param params.referenceInputAmount - the reference quote's input amount
+ * @returns the derived estimate with numeric fields, or null when the quote yields no output amount
+ */
+export declare const buildPulseXSwapEstimateData: ({ amountsOut, inputAmount, inputToken, inputUsdPrice, outputToken, outputUsdPrice, referenceAmountsOut, referenceInputAmount, }: {
+    amountsOut: readonly bigint[] | null;
+    inputAmount: bigint;
+    inputToken: Token;
+    inputUsdPrice: number | null;
+    outputToken: Token;
+    outputUsdPrice: number | null;
+    /**
+     * The amounts-out of a tiny MARGINAL reference quote along the SAME path (see
+     * {@link PULSEX_MARGINAL_REFERENCE_DIVISOR}). Its near-spot rate is what lets the
+     * price impact be isolated from the fee without differencing two circular
+     * PulseX-derived prices. Null/empty → impact is unknown and the cost degrades to
+     * the flat fee.
+     */
+    referenceAmountsOut?: readonly bigint[] | null;
+    /** The reference quote's input amount (the tiny marginal input). */
+    referenceInputAmount?: bigint;
+}) => PulseXSwapEstimateData | null;
+/**
+ * Roots for {@link buildSameChainSwapRouteData}: the swap's two tokens (both
+ * live on PulseChain), the pre-derived raw estimate, and what the reader paid
+ * for the input, so the route's cost and net value are on the same basis as
+ * every other route.
+ */
+export type SameChainSwapRouteRoots = {
+    /** Caller-supplied stable identity for the route, used for the section id. */
+    id: string;
+    /** The token the reader holds before the swap — the swap's input. */
+    fromToken: Token;
+    /** The token the reader wants after the swap — the swap's output. */
+    toToken: Token;
+    /** The pre-derived raw swap figures (see {@link buildPulseXSwapEstimateData}). */
+    estimate: PulseXSwapEstimateData;
+    /**
+     * What the input side is worth in United States dollars, or null when
+     * unpriced. This is the route's OWN basis for `totalCostUsdValue` and
+     * `netValueUsd` — there is no bridge leg underneath to inherit a basis from,
+     * unlike {@link buildConversionRouteData}.
+     */
+    inputUsdValue: number | null;
+    /** Logo url for the `fromToken` node, or null to fall back to a placeholder. */
+    fromTokenLogoUri?: string | null;
+    /** Logo url for the `toToken` node, or null to fall back to a placeholder. */
+    toTokenLogoUri?: string | null;
+    /** Logo url for the PulseChain chain badge on both token-flow nodes, or null. */
+    pulsechainChainLogoUri?: string | null;
+    /**
+     * Transaction-transparency details for the advanced disclosure, built by the
+     * caller from the SAME builder the swap button itself calls
+     * (`pulseXSwapTransactionInputs` in `settings.ts`) — never a second encoding
+     * here. Absent while the swap is not yet buildable.
+     */
+    advanced?: {
+        /** The PulseX router this swap calls, or null when none is deployed. */
+        destinationRouter: Hex | null;
+        /** The swap's encoded calldata from `pulseXSwapTransactionInputs`, or null. */
+        calldata: Hex | null;
+    } | null;
+};
+/**
+ * Composes a raw {@link RouteData} for a SAME-CHAIN PulseX swap: PulseChain on
+ * both sides of the selection, one signature, no crossing at all.
+ *
+ * WHY THIS IS ITS OWN PRODUCER, RATHER THAN `buildConversionRouteData` WITH NO
+ * BASE. The conversion route APPENDS a swap section to a bridge route that
+ * already delivered the anchor onto PulseChain; its cost, its `entryChainId`,
+ * and its "deferred" swap all inherit from that base. A same-chain swap has no
+ * base — the reader already holds the input token on PulseChain before
+ * pressing anything — so the section is signed IMMEDIATELY (`deferred` stays
+ * false, the {@link buildPulseXSwapSectionData} default) and the route has no
+ * `entryChainId` at all, exactly like the direct omnibridge route it sits
+ * beside in the strip.
+ *
+ * NOT DEFERRED, AND THAT IS LOAD-BEARING FOR THE TRACKER. `deferred` means "the
+ * reader has not yet signed this" (see `sectionProgress.ts`); a same-chain swap
+ * is signed in the very press that builds it, so marking it deferred would tell
+ * the tracker a signature is still owed for a transaction already broadcast.
+ * What DOES need care downstream is the opposite failure the tracker's own
+ * `routeChainSequence` can produce for a route whose every stop shares one
+ * chain id — see `routeProgress.ts`'s `reachedChainIndex` for the fix that
+ * keeps a same-chain route from reading "delivered" the instant it is merely
+ * broadcast.
+ *
+ * @param roots - the route's identity, tokens, pricing, and logos
+ * @returns the one-section same-chain swap {@link RouteData}
+ */
+export declare const buildSameChainSwapRouteData: (roots: SameChainSwapRouteRoots) => RouteData;