@gibs/bridge-sdk 1.19.0 → 1.20.0

package/dist/routing/producers.js

@@ -1,301 +1,62 @@
-/**
- * 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 { Chains, Providers, pathway } from '../config.js';
 import { chainDisplayName } from '../chain-names.js';
 import { usdValueOfAmount } from './usd-value.js';
 import * as imageLinks from '../image-links.js';
 import { roundUsdToCents } from './format.js';
 import { formatUnits } from 'viem';
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-/**
- * The PulseX swap fee in basis points (hundredths of a percent). The deferred
- * outbound leg swaps the bridged intermediate token into the wanted token on the
- * entry chain at this rate, so the deferred section's fee is APPROXIMATE — the
- * binding quote is only known when the user returns. 29 basis points is roughly
- * 0.29%.
- */
 const PULSEX_SWAP_FEE_BASIS_POINTS = 29n;
-/** The denominator that turns {@link PULSEX_SWAP_FEE_BASIS_POINTS} into a fraction. */
 const BASIS_POINTS_DENOMINATOR = 10000n;
-/**
- * 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 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 const BRIDGE_SETTLEMENT_ETA_MINUTES = 20;
-/**
- * The approximate wall-clock duration of the SWAP itself, in seconds — a PulseX
- * swap (or an entry-chain swap) settles in roughly ten seconds once signed. This
- * is the swap leg's OWN time, distinct from the ~20-minute crossing it waits
- * behind ({@link BRIDGE_SETTLEMENT_ETA_MINUTES}): the wait belongs on the BRIDGE
- * leg, the near-instant swap on the SWAP leg, so each section reads honestly
- * ("~20 min" to cross, then "~10 sec" to swap) rather than stamping the crossing's
- * twenty minutes onto the swap.
- */
 const PULSEX_SWAP_ETA_SECONDS = 10;
-/** Decimal chain id for PulseChain — the shared destination of every inbound route. */
 export const pulsechainChainId = Number(Chains.PLS);
-// ---------------------------------------------------------------------------
-// Private backing maps
-// ---------------------------------------------------------------------------
-/**
- * The fully spelled-out display name of each omnibridge provider, keyed by the
- * raw provider identifier the builders carry. These are the headline names the
- * route strip shows as the route's bridge.
- *
- * Typed `Record<Provider, string>`, exhaustive over the two real omnibridge
- * crossings, so a third one added to `Providers` without a name here is a
- * compile error rather than a silent gap in {@link omnibridgeProviderDisplayName}.
- */
 const omnibridgeProviderDisplayNames = {
     [Providers.PULSECHAIN]: 'PulseChain Bridge',
     [Providers.TOKENSEX]: 'Tokens Express Bridge',
 };
-/**
- * Whether `value` genuinely names an omnibridge crossing, narrowing it to
- * {@link Provider}.
- *
- * @param value - a string that may or may not be a real omnibridge provider
- * @returns whether `value` is one of the two registered crossings
- */
 const isOmnibridgeProvider = (value) => value === Providers.PULSECHAIN || value === Providers.TOKENSEX;
-/**
- * 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 const omnibridgeProviderDisplayName = (provider) => omnibridgeProviderDisplayNames[provider];
-/**
- * The fully spelled-out display name of an omnibridge ENTRY chain, keyed by its
- * decimal chain id. Acronyms are spelled out rather than read from viem's terse
- * `name`. Ethereum and Binance Smart Chain are the only omnibridge entry points;
- * any other chain id has no entry and {@link resolveEntryChainName} returns null.
- */
 const entryChainDisplayName = {
     [Number(Chains.ETH)]: 'Ethereum',
     [Number(Chains.BNB)]: 'Binance Smart Chain',
 };
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-/**
- * 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 const addUsdValues = (first, second) => {
     if (first == null && second == null)
         return null;
     return (first ?? 0) + (second ?? 0);
 };
-/**
- * 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 const subtractUsdValues = (value, cost) => {
     if (value == null)
         return null;
     return value - (cost ?? 0);
 };
-/**
- * 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 const providerDisplayName = (provider) => {
     if (provider === 'PulseX')
         return 'PulseX';
     return isOmnibridgeProvider(provider) ? omnibridgeProviderDisplayName(provider) : 'Omnibridge';
 };
-/**
- * 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 const resolveEntryChainName = (entryChainId) => {
     if (entryChainId === null)
         return null;
     return entryChainDisplayName[entryChainId] ?? 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 const usdNumber = (raw) => {
     if (raw == null || raw.trim() === '')
         return null;
     const value = Number(raw);
     return Number.isFinite(value) && value > 0 ? value : 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 const candidatePaidUsd = (candidate) => usdNumber(candidate.quote.fromAmountUsd);
-/**
- * The cost of a candidate, in United States dollars, as the difference between
- * what the user pays for the aggregator leg ({@link candidatePaidUsd}) and what the
- * delivered tokens are worth. Returns null when the provider gave no
- * `fromAmountUsd` or the delivered tokens are unpriced — the fee then shows only
- * what it can. The figure is clamped at zero because a fleeting price-source
- * skew should never render a negative fee.
- *
- * @param candidate - the priced route candidate
- * @returns the fee in United States dollars, or null when either side is unpriced
- */
 const candidateFeeUsd = (candidate) => {
     const paid = candidatePaidUsd(candidate);
     if (paid === null)
         return null;
-    // Charges levied outside `fromAmount` are part of the cost even though the
-    // difference between paid and delivered cannot see them.
     const outside = candidateOutsideFeesUsd(candidate);
     const delivered = candidateDeliveredUsd(candidate);
     if (delivered === null)
         return null;
     return Math.max(0, paid + outside - delivered);
 };
-/**
- * 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 const candidateDeliveredUsd = (candidate) => {
     if (candidate.omnibridgeProvider === null) {
         const quoted = usdNumber(candidate.quote.toAmountUsd);
@@ -310,34 +71,7 @@ export const candidateDeliveredUsd = (candidate) => {
         price: candidate.destinationUsdPrice,
     });
 };
-/**
- * The share of the requested amount below which an unspent remainder is treated
- * as dust and not reported, in basis points (hundredths of a percent). Ten basis
- * points is 0.1%.
- *
- * A backward-solved quote lands a handful of base units away from the amount it
- * was asked for even when it consumes essentially all of it — the control case
- * measured eleven wei left over on a five-hundredths-of-an-ether transfer. A
- * remainder that small is rounding, not money the user gets to keep, and naming
- * it would add a line to every route that says nothing.
- */
 const UNSPENT_MATERIAL_BASIS_POINTS = 10n;
-/**
- * The origin tokens a candidate's quote does NOT consume — the difference between
- * what the user typed and what the backward-solved quote turned out to need.
- *
- * Valued from the candidate's OWN source basis (`fromAmountUsd` divided across
- * `fromAmount`) rather than from a separate price feed, for the same reason every
- * other figure on the route is: two feeds disagree, and a remainder priced against
- * a different one would reopen the gap this whole model exists to close.
- *
- * Returns null when the requested amount is unknown, when the quote consumed all
- * of it, or when the remainder is below {@link UNSPENT_MATERIAL_BASIS_POINTS} —
- * a route that spends what it was given says nothing about unspent tokens.
- *
- * @param candidate - the priced route candidate
- * @returns the unspent remainder, or null when there is none worth naming
- */
 const candidateUnspent = (candidate) => {
     const requested = candidate.requestedAmount;
     if (requested == null || requested <= 0n)
@@ -350,9 +84,6 @@ const candidateUnspent = (candidate) => {
         return null;
     }
     const paidUsd = candidatePaidUsd(candidate);
-    // The remainder's value is the paid basis scaled by the ratio of the two
-    // amounts, which is exact regardless of the origin token's decimals and needs
-    // no per-token price at all.
     const usdValue = paidUsd === null
         ? null
         : (paidUsd * Number(formatUnits(remainder, candidate.originToken.decimals))) /
@@ -364,86 +95,22 @@ const candidateUnspent = (candidate) => {
         usdValue: usdValue !== null && Number.isFinite(usdValue) ? usdValue : null,
     };
 };
-/**
- * A token address shortened for display, for example `0x1234…5678`. Preserves
- * short addresses that are already readable without truncation.
- *
- * @param address - the full token address
- * @returns the shortened address string
- */
 const shortenAddress = (address) => address.length > 11 ? `${address.slice(0, 6)}…${address.slice(-4)}` : address;
-/**
- * The token label for a step endpoint: the provider-supplied SYMBOL when present
- * (for example "USDC"), otherwise a SHORTENED address. Never the raw full address,
- * which is unreadable in the hop conversion line.
- *
- * @param symbol - the token symbol, or null when not supplied by the provider
- * @param address - the token's full on-chain address, used as fallback
- * @returns the label to display for this endpoint
- */
 const stepTokenLabel = (symbol, address) => symbol ?? shortenAddress(address);
-/**
- * The swap conversion label for a normalized aggregator route step — the
- * "from token → to token" string shown in the hop's conversion line. Returns null
- * when the step carries no token addresses (Relay steps are empty; the hop then
- * shows no conversion clause).
- *
- * @param step - one normalized aggregator route step
- * @returns the conversion string, or null when address data is absent
- */
 const stepConversion = (step) => {
     if (!step.fromToken || !step.toToken)
         return null;
     return `${stepTokenLabel(step.fromTokenSymbol, step.fromToken)} → ${stepTokenLabel(step.toTokenSymbol, step.toToken)}`;
 };
-/**
- * A fee rate as percent text: 3e15 reads "0.3%". Exact, because it scales the
- * integer and lets `formatUnits` place the point, rather than going through a
- * floating point number that prints 2.9699999999999998.
- */
 const rateAsPercentText = (rate) => `${formatUnits(rate * 100n, 18)}%`;
-/** A label, with the rate beside it when the rate is known. */
 const labelWithRate = (label, rate) => rate == null ? label : `${label} (${rateAsPercentText(rate)})`;
-/** A dollar value as the cent string a {@link QuoteFee} carries, or null when unpriced. */
 const feeAmountUsdText = (value) => value === null ? null : roundUsdToCents(value).toFixed(2);
-/**
- * The token the bridge takes its own fee in.
- *
- * The fee manager lives on the home mediator, on PulseChain, and the pathway
- * says which side of the crossing that is. Leaving PulseChain it is `'from'`:
- * the home mediator takes the fee from the tokens it receives, before it sends
- * the message. Arriving it is `'to'`: the home mediator takes the fee from the
- * tokens it releases. So the fee is always in the PulseChain side's token.
- *
- * @returns the fee's token, or null when the bridge key names no pathway
- */
 const bridgeFeeToken = ({ bridgeKey, sourceToken, arrivingToken, }) => {
-    // Not production-only: the testnet pathways live in a second map, and a
-    // mainnet key finds its own pathway in the first map either way.
     const crossing = pathway(bridgeKey, false);
     if (!crossing)
         return null;
     return crossing.feeManager === 'from' ? sourceToken : arrivingToken;
 };
-/**
- * The cost of one omnibridge crossing: the bridge's own fee plus the Gibs
- * delivery fee, both valued on the route's source basis.
- *
- * A PARTIAL SUM IS NEVER A COST. When either fee is unknown the figure is null,
- * because the known half alone would read as the whole cost and understate it.
- * A delivery the reader did not ask for is not unknown: it is a real zero.
- *
- * The delivery fee is in the ARRIVING token: the destination router takes it
- * from the value that reaches it.
- *
- * EVERY AMOUNT IS COUNTED IN SOURCE BASE UNITS, because the settings cascade
- * derives both fees from `amountToBridge`, which is. So both are valued with the
- * source token's decimals and price, the same basis the route's delivered value
- * uses. The bridge keeps a token's decimals when it creates the counterpart, so
- * that count is also the count in the arriving token each charge names.
- *
- * @returns the crossing's cost and the charges behind it
- */
 const crossingCost = ({ bridgeKey, feeRoots, sourceToken, arrivingToken, sourceUsdPrice, }) => {
     const [provider] = bridgeKey;
     const { bridgeFeeAmount, bridgeFeeRate, deliveryFee } = feeRoots;
@@ -487,25 +154,11 @@ const crossingCost = ({ bridgeKey, feeRoots, sourceToken, arrivingToken, sourceU
         : bridgeFeeUsdValue + deliveryFeeUsdValue;
     return { feeUsdValue, fees: [...bridgeFees, ...deliveryFees] };
 };
-/** A token as the fee token a {@link QuoteFee} names, on the chain it is presented on. */
 const toFeeToken = (token, chainId) => ({
     symbol: token.symbol,
     decimals: token.decimals,
     chainId,
 });
-/**
- * The raw token reference for one end of a normalized aggregator step — the shape
- * an intermediate stop is rendered from.
- *
- * The provider's own token image wins when present. When it supplies none, the
- * logo is left UNSET for a `0x` address so the adapter derives it from the image
- * service, and set to null for a non-Ethereum address (Bitcoin, Solana, Tron, The
- * Open Network), which the image service cannot key by a checksummed address.
- * Decimals are omitted: an intermediate stop formats no amount.
- *
- * @param endpoint - one end of a normalized step
- * @returns the raw token reference for that end
- */
 const stepTokenRef = (endpoint) => ({
     symbol: endpoint.symbol ?? shortenAddress(endpoint.address),
     address: endpoint.address,
@@ -513,25 +166,18 @@ const stepTokenRef = (endpoint) => ({
     logoUri: endpoint.logoUri ?? (endpoint.address.startsWith('0x') ? undefined : null),
     chainLogoUri: imageLinks.networkOrPseudo(endpoint.chainId),
 });
-/** The token a step consumes, as a raw reference. */
 const stepFromTokenRef = (step) => stepTokenRef({
     address: step.fromToken,
     symbol: step.fromTokenSymbol,
     chainId: step.fromChainId,
     logoUri: step.fromTokenLogoUri,
 });
-/** The token a step produces, as a raw reference — the stop it lands the funds on. */
 const stepToTokenRef = (step) => stepTokenRef({
     address: step.toToken,
     symbol: step.toTokenSymbol,
     chainId: step.toChainId,
     logoUri: step.toTokenLogoUri,
 });
-/**
- * True when two references name the same token on the same chain. Hex addresses
- * compare case-insensitively (providers disagree on checksum casing); anything
- * else compares exactly, because a base58 address is genuinely case-sensitive.
- */
 const isSameTokenRef = (left, right) => {
     if (left.chainId !== right.chainId)
         return false;
@@ -541,20 +187,6 @@ const isSameTokenRef = (left, right) => {
         return false;
     return left.address.toLowerCase() === right.address.toLowerCase();
 };
-/**
- * The token flow a set of hops walks: the origin, then the token each hop
- * PRODUCES. Every entry except the first is a stop the funds actually reach, and
- * the last hop's output is the destination — so the intermediate stops are exactly
- * the hops minus the last one.
- *
- * A hop that names no output token contributes nothing (the flow still reaches the
- * destination through the hops that do), and a hop that produces the token the
- * flow is already holding is collapsed rather than drawn twice.
- *
- * @param origin - the token the route starts from
- * @param hops - the hops the signature performs, first to last
- * @returns the ordered token flow, origin first and destination last
- */
 const deriveTokenFlow = (origin, hops) => hops.reduce((flow, hop) => {
     const produced = hop.toToken;
     if (!produced)
@@ -564,24 +196,6 @@ const deriveTokenFlow = (origin, hops) => hops.reduce((flow, hop) => {
         return flow;
     return [...flow, produced];
 }, [origin]);
-/**
- * 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 const candidateOutsideFeesUsd = (candidate) => {
     const fromQuote = candidate.quote.fees.reduce((total, fee) => {
         if (fee.includedInFromAmount) {
@@ -590,36 +204,12 @@ export const candidateOutsideFeesUsd = (candidate) => {
         const value = Number(fee.amountUsd);
         return Number.isFinite(value) ? total + value : total;
     }, 0);
-    // A provider that reports its network cost once, for the whole route, gives a
-    // gas row here and that row is the whole of it. One that reports gas only per
-    // leg gives no such row, and the per-step figures are then the only record of
-    // it — counting them as well when the row IS present would bill the same gas
-    // twice, so this is a fallback and never an addition.
     const reportsGasOnce = candidate.quote.fees.some((fee) => !fee.includedInFromAmount && fee.kind === 'gas');
     if (reportsGasOnce) {
         return fromQuote;
     }
     return fromQuote + candidate.quote.steps.reduce((total, step) => total + (step.gasUsd ?? 0), 0);
 };
-/**
- * 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 const candidateNetValueUsd = (candidate) => {
     const paid = candidatePaidUsd(candidate);
     if (paid === null)
@@ -629,41 +219,8 @@ export const candidateNetValueUsd = (candidate) => {
         return null;
     return delivered - paid - candidateOutsideFeesUsd(candidate);
 };
-/**
- * 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 const buildCandidateRouteData = (candidate) => {
     const feeUsdValue = candidateFeeUsd(candidate);
-    // THE PROVIDER'S OWN FIGURE, IN ITS OWN UNIT, CARRIED THROUGH UNROUNDED.
-    //
-    // This used to keep only `Math.ceil(seconds / 60)`, and that one expression
-    // erased the difference the reader most needed to see. Measured live on Base
-    // to Polygon: LI.FI claimed 29 seconds and Relay claimed 3, and both rendered
-    // "~1 min". A reader comparing them had no way to tell a route that settles
-    // before they look away from one that claims ten times the wait — so the
-    // strip handed the choice to a 0.05% difference in delivered tokens, which is
-    // nine cents on a hundred-and-twenty-six-dollar transfer.
-    //
-    // The section therefore carries the seconds and the view picks the unit (see
-    // `sectionWaitLabel` in the route strip). `etaMinutes` stays beside it for the
-    // route-level field and for every consumer that still reads minutes.
-    //
-    // It is the provider's CLAIM and nothing more. One live route ran about
-    // seventy-five times its own estimate, which is why the strip labels this the
-    // provider's estimate rather than presenting it as a fact.
     const etaSeconds = candidate.quote.executionDurationSeconds > 0 ? candidate.quote.executionDurationSeconds : null;
     const etaMinutes = candidate.quote.executionDurationSeconds > 0
         ? Math.ceil(candidate.quote.executionDurationSeconds / 60)
@@ -674,79 +231,38 @@ export const buildCandidateRouteData = (candidate) => {
             ` entryChainId=${candidate.entryChainId}` +
             ` omnibridgeProvider=${candidate.omnibridgeProvider}` +
             ` quote.fromAmountUsd=${candidate.quote.fromAmountUsd}` +
-            // BOTH delivered-value sources, because which one applies depends on
-            // whether a second leg follows — naming only one sends whoever reads
-            // this to the wrong place. See `candidateDeliveredUsd`.
             ` quote.toAmountUsd=${candidate.quote.toAmountUsd ?? null}` +
             ` destinationUsdPrice=${candidate.destinationUsdPrice}`);
     }
     const { originToken, destinationToken } = candidate;
-    // Token logos are pre-resolved here via the image service (which lives in the
-    // software development kit, so the producer stays framework-agnostic), passing
-    // the FULL token so its own `logoURI` is preferred over the address-derived
-    // fallback — matching the pre-split `buildCandidateTokenFlow` exactly.
     const originNode = {
         symbol: originToken.symbol,
         address: originToken.address,
         chainId: originToken.chainId,
         decimals: originToken.decimals,
-        // `tokenImageOrChainFallback` — see the identical note on `destinationNode`
-        // below; the same "address not resolvable yet" case applies to either end.
         logoUri: imageLinks.tokenImageOrChainFallback(originToken),
-        // A pay-by-hand origin (Zcash) carries a local, invented chain id
-        // `imageLinks.network` cannot look up by number — see `networkOrPseudo`.
         chainLogoUri: imageLinks.networkOrPseudo(originToken.chainId),
     };
-    // Read up front, before the node below, so the node itself never claims
-    // PulseChain for a candidate that does not enter the omnibridge. A candidate
-    // whose omnibridge leg is absent (NEAR Intents, or any aggregator delivering
-    // straight to its own destination chain) lands on `destinationToken.chainId`
-    // — Base, in the case that pinned this — and a node hardcoded to PulseChain
-    // named the wrong chain for every stop that reused it, including the
-    // token-flow fallback below.
     const omnibridgeProviderKey = candidate.omnibridgeProvider;
-    // THE CHAIN THIS SIGNATURE ACTUALLY ENDS ON. The label was the constant
-    // 'Bridge to PulseChain', true of every route that existed when it was
-    // written. A route the omnibridge does not carry ends somewhere else
-    // entirely, and titled that way the tracker named a chain the funds never
-    // touch — over a transfer to Base that had already landed.
     const landingChainId = omnibridgeProviderKey === null ? destinationToken.chainId : pulsechainChainId;
     const destinationNode = {
         symbol: destinationToken.symbol,
         address: destinationToken.address,
         chainId: landingChainId,
         decimals: destinationToken.decimals,
-        // `tokenImageOrChainFallback`, NOT `image` — a not-yet-bridged token's
-        // address can still be unresolved when this producer draws the DELIVERED
-        // node (see the repository's own "Not-Yet-Bridged Tokens" gotcha), and
-        // `image` either throws on it or silently draws nothing. See that
-        // helper's own note.
         logoUri: imageLinks.tokenImageOrChainFallback(destinationToken),
-        // `networkOrPseudo`, matching `originNode` — a destination is not known to
-        // ever be a deposit-address pseudo chain today, but the badge helper is the
-        // one every other node in this builder goes through, and there is no reason
-        // this one should be the exception that 404s if that ever changes.
         chainLogoUri: imageLinks.networkOrPseudo(landingChainId),
     };
     const aggregatorHops = candidate.quote.steps.map((step, index) => ({
         providerName: step.label,
-        // The aggregator step carries its tool's real logo url straight from the quote
-        // — raw data, not a derived view concern, so it rides on the raw hop.
         providerLogoUri: step.providerLogoUri,
         title: step.label,
         conversion: stepConversion(step),
-        // The tokens this leg moves between, structurally — the section's token flow is
-        // derived from these, so every stop the funds make is one the provider named.
         fromToken: stepFromTokenRef(step),
         toToken: stepToTokenRef(step),
         feeUsdValue: step.feeUsd,
-        // The first hop is the user's single signature; later hops run inside it.
         automatic: index > 0,
     }));
-    // NO BRIDGE LEG MEANS NO BRIDGE HOP. A candidate the omnibridge does not
-    // carry ends where the aggregator leaves it, so the crossing hop below simply
-    // does not exist — appending one would draw a step nobody performs and name a
-    // bridge that is not involved.
     const omnibridgeHop = omnibridgeProviderKey === null
         ? null
         : {
@@ -754,8 +270,6 @@ export const buildCandidateRouteData = (candidate) => {
             providerKey: omnibridgeProviderKey,
             title: 'Bridge to PulseChain',
             conversion: `→ ${candidate.destinationToken.symbol}`,
-            // The crossing consumes whatever the last aggregator leg produced — the anchor
-            // token on the entry chain — or the origin token when there were no legs.
             fromToken: aggregatorHops[aggregatorHops.length - 1]?.toToken ?? originNode,
             toToken: destinationNode,
             feeUsdValue: usdValueOfAmount({
@@ -763,38 +277,17 @@ export const buildCandidateRouteData = (candidate) => {
                 decimals: candidate.destinationToken.decimals,
                 price: candidate.destinationUsdPrice,
             }),
-            // The omnibridge call is always auto-called by the aggregator leg before it.
             automatic: aggregatorHops.length > 0,
         };
     const hops = omnibridgeHop === null ? aggregatorHops : [...aggregatorHops, omnibridgeHop];
-    // Origin, then every stop the funds reach on the way — NOT a collapsed pair. The
-    // last hop is the crossing, so the flow still ends on the destination, EXCEPT
-    // when the provider itemised no legs at all (Relay and NEAR Intents both report
-    // zero `quote.steps`) and there is no omnibridge hop to supply one either — a
-    // candidate delivering straight to its own destination chain. `deriveTokenFlow`
-    // then has nothing to reduce over and stops at the origin, which is the exact
-    // defect that showed a NEAR Intents route to Base USD Coin as "At ETH on
-    // Ethereum": the pill drew the one-and-only flow node it was given, and that
-    // node had never left the origin. The route's own `destinationToken` is known
-    // regardless of what got itemised, so it is appended here whenever the flow
-    // does not already end on it — deduplicated, so an itemised leg that DID reach
-    // the destination is never drawn twice.
     const rawTokenFlow = deriveTokenFlow(originNode, hops);
     const lastStop = rawTokenFlow[rawTokenFlow.length - 1];
     const tokenFlow = lastStop && isSameTokenRef(lastStop, destinationNode) ? rawTokenFlow : [...rawTokenFlow, destinationNode];
     const section = {
-        // The section id stays a stable string key derived from the candidate id —
-        // section ids are within-route keys and do not need to be structural hashes.
         id: `${candidate.id}-signature-1`,
         label: `Bridge to ${chainDisplayName(landingChainId)}`,
-        // The signature is executed by the cross-chain AGGREGATOR (LI.FI / Relay) that
-        // carries the bridge leg — that is the provider to surface on this section, not
-        // the omnibridge headline.
         providerKey: candidate.quote.provider,
         tokenFlow,
-        // What this signature leaves the user holding on PulseChain. Valued on the
-        // same source basis as the route's output so the step's landing figure and
-        // the route's delivered figure are the same number, not two derivations of it.
         landing: {
             amount: candidate.deliveredAmount,
             decimals: candidate.destinationToken.decimals,
@@ -803,8 +296,6 @@ export const buildCandidateRouteData = (candidate) => {
         },
         unspent: candidateUnspent(candidate),
         feeUsdValue,
-        // The itemization behind `feeUsdValue`, plus the charges that difference
-        // cannot see: anything the provider levies outside `fromAmount`.
         fees: candidate.quote.fees,
         etaMinutes,
         etaSeconds,
@@ -812,26 +303,13 @@ export const buildCandidateRouteData = (candidate) => {
     };
     return {
         kind: 'aggregated',
-        // The entry chain this aggregator route crosses through (Ethereum or Binance
-        // Smart Chain), carried explicitly so Bridge.tsx can link the selected route
-        // back to its quoted entry candidate without string-parsing the id.
         entryChainId: candidate.entryChainId,
-        // The route's headline provider is the omnibridge it crosses on — or, when
-        // it crosses none, the aggregator that carries the whole journey. A route
-        // has to be named after something that actually performs it.
         headlineProviderKey: omnibridgeProviderKey ?? candidate.quote.provider,
         sections: [section],
         output: {
             amount: candidate.deliveredAmount,
             decimals: candidate.destinationToken.decimals,
             symbol: candidate.destinationToken.symbol,
-            // Valued on the SOURCE basis — what was paid, less this route's cost — NOT by
-            // re-pricing the delivered token against its own feed. The two differ whenever
-            // the destination asset trades away from its origin-chain counterpart, and that
-            // difference used to land silently in this figure: the page then stated the
-            // route's cost twice and the two never agreed. Deriving it keeps the fee clamp
-            // above from opening a gap too. Falls back to the destination feed only when
-            // the provider gave no `fromAmountUsd`, so an unpriced leg still shows what it can.
             usdValue: subtractUsdValues(candidatePaidUsd(candidate), feeUsdValue) ??
                 usdValueOfAmount({
                     balance: candidate.deliveredAmount,
@@ -839,36 +317,16 @@ export const buildCandidateRouteData = (candidate) => {
                     price: candidate.destinationUsdPrice,
                 }),
         },
-        // The aggregate cost is the single section's spread (this route is one
-        // signature), so it equals the section fee; null when the leg is unpriced.
         totalCostUsdValue: feeUsdValue,
-        // The net dollar outcome this route is ranked on (delivered value minus origin
-        // tokens paid, network gas, and the omnibridge crossing fee).
         netValueUsd: candidateNetValueUsd(candidate),
         etaMinutes,
     };
 };
-// ---------------------------------------------------------------------------
-// Producer: direct route
-// ---------------------------------------------------------------------------
-/**
- * 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 const buildDirectRouteData = (roots) => {
     const { bridgeKey, assetIn, assetOut, estimatedAmountOut, assetInUsdPrice, assetOutUsdPrice, assetInLogoUri, assetOutLogoUri, fromChainLogoUri, toChainLogoUri, advanced, } = roots;
     if (!assetIn || !assetOut)
         return null;
     const [provider, fromChain, toChain] = bridgeKey;
-    // The bridge's own fee plus the delivery fee, valued on the source basis; null
-    // when either is unknown or the input asset is unpriced.
     const { feeUsdValue, fees } = crossingCost({
         bridgeKey,
         feeRoots: roots,
@@ -878,30 +336,15 @@ export const buildDirectRouteData = (roots) => {
     });
     const hop = {
         providerName: omnibridgeProviderDisplayName(provider),
-        // The direct route's provider is the omnibridge it crosses on; the adapter
-        // resolves its logo from this key.
         providerKey: provider,
         title: omnibridgeProviderDisplayName(provider),
         conversion: `${assetIn.symbol} → ${assetOut.symbol}`,
         feeUsdValue,
-        // Delivery auto-calls the completion on the PulseChain side, so the user's
-        // single signature covers the whole leg.
         automatic: true,
     };
     const section = {
         id: `direct-${provider}-${fromChain}-signature-1`,
-        // NAMED FROM `toChain`, NOT HARD-CODED. A direct crossing runs both ways —
-        // a foreign chain into PulseChain, or PulseChain out to a foreign chain —
-        // and a literal "Bridge to PulseChain" on every direct route named the
-        // wrong destination on every outbound crossing: the label read "Bridge to
-        // PulseChain" while the arrival stage it produces (derived correctly, from
-        // the section's own last token-flow node — see `tracker/trackerView.ts`'s
-        // `sectionArrivalStage`) correctly read "Arrive on Ethereum" for the exact
-        // same signature. One route, two destinations stated for it.
         label: `Bridge to ${chainDisplayName(Number(toChain))}`,
-        // The direct section carries NO section provider (matching the pre-split
-        // builder): the route strip falls back to the hop's provider for the badge,
-        // and the structural id stays identical.
         providerKey: null,
         tokenFlow: [
             {
@@ -921,9 +364,6 @@ export const buildDirectRouteData = (roots) => {
                 chainLogoUri: toChainLogoUri,
             },
         ],
-        // The direct crossing IS the whole route, so what this step lands in is what
-        // the route delivers — priced on the source basis for the same reason the
-        // output is (see the output note below).
         landing: {
             amount: estimatedAmountOut,
             decimals: assetOut.decimals,
@@ -935,22 +375,13 @@ export const buildDirectRouteData = (roots) => {
             }),
         },
         feeUsdValue,
-        // Who takes what: the bridge, then the delivery service.
         fees,
-        // The direct crossing waits on the SAME omnibridge settlement as the
-        // outbound route's own "Bridge to {entry chain}" section
-        // ({@link buildOutboundRouteData}), which quotes this identical constant for
-        // the identical wait. Leaving it null here was the one crossing section that
-        // never got it, so the strip and the tracker both had no duration to show for
-        // the most common route in the product.
         etaMinutes: BRIDGE_SETTLEMENT_ETA_MINUTES,
         hops: [hop],
         advanced,
     };
     return {
         kind: 'direct',
-        // The direct omnibridge route IS the crossing — it does not pivot through a
-        // distinct aggregator entry chain — so `entryChainId` is null.
         entryChainId: null,
         headlineProviderKey: provider,
         sections: [section],
@@ -958,65 +389,18 @@ export const buildDirectRouteData = (roots) => {
             amount: estimatedAmountOut,
             decimals: assetOut.decimals,
             symbol: assetOut.symbol,
-            // Priced with the SOURCE asset's price, deliberately, even though the amount is
-            // counted in the destination token's units. A direct crossing hands back the
-            // same asset on another chain, and the bridged counterpart routinely trades at
-            // a discount to it — pricing the two sides from their own feeds made a
-            // zero-fee crossing report a loss (100 USDC in, 100 USDC out, "$100.03" paid
-            // and "$99.42" received). The delivered COUNT still comes from the destination
-            // token's decimals; only the basis is shared. The destination's own price
-            // remains the fallback so a route whose SOURCE side is unpriced still shows a
-            // value rather than nothing.
             usdValue: usdValueOfAmount({
                 balance: estimatedAmountOut,
                 decimals: assetOut.decimals,
                 price: assetInUsdPrice ?? assetOutUsdPrice ?? null,
             }),
         },
-        // The direct route is a single signature, so its aggregate cost is that one
-        // section's fee: the bridge's own fee plus delivery. Null when either is unknown.
         totalCostUsdValue: feeUsdValue,
-        // THE SAME BASIS AGGREGATED ROUTES ARE RANKED ON: delivered value less what
-        // was paid. The delivered amount is what is sent less both fees, and both
-        // sides are priced on the source token, so the difference is exactly the
-        // negated cost. It leaves out the sender's own network gas, which this
-        // route does not know; an aggregated route counts it when its quote does.
         netValueUsd: feeUsdValue === null ? null : -feeUsdValue,
-        // The direct route is the only option for now, so it is always the best.
         isBest: true,
         deltaPercent: 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 const buildOutboundRouteData = (roots) => {
     const { bridgeKey, assetIn, intermediateToken, finalToken, estimatedAmountOut, assetInUsdPrice, intermediateUsdPrice, assetInLogoUri, assetOutLogoUri, finalTokenLogoUri, fromChainLogoUri, intermediateChainLogoUri, onward = null, } = roots;
     if (!assetIn || !intermediateToken || !finalToken)
@@ -1026,21 +410,10 @@ export const buildOutboundRouteData = (roots) => {
     const entryChainName = resolveEntryChainName(entryChainId);
     if (entryChainName === null)
         return null;
-    // A TOKEN DOES NOT CARRY A CHAIN, so the caller states the onward chain and the
-    // token states its own, and the two must agree. Reading one from the other is
-    // the cross-chain address mistake this codebase has already paid for: an origin
-    // address asked for on the destination chain fails silently, and succeeds by
-    // coincidence when some unrelated contract answers at the same address.
-    // Disagreement here means one of the two is wrong and there is no way to tell
-    // which, so the route is not drawn at all.
     if (onward !== null && onward.chainId !== finalToken.chainId)
         return null;
-    // Where the SECOND signature leaves the user. Same as the crossing's landing
-    // when the deferred leg is a swap; the onward chain when it is a bridge.
     const finalChainId = onward === null ? entryChainId : onward.chainId;
     const finalChainName = onward === null ? entryChainName : onward.chainName;
-    // SECTION 1 fee: the crossing's bridge fee plus its delivery fee, priced in the
-    // source token. Null when either is unknown.
     const { feeUsdValue: sectionOneFeeValue, fees: sectionOneFees } = crossingCost({
         bridgeKey,
         feeRoots: roots,
@@ -1048,16 +421,6 @@ export const buildOutboundRouteData = (roots) => {
         arrivingToken: toFeeToken(intermediateToken, entryChainId),
         sourceUsdPrice: assetInUsdPrice,
     });
-    // SECTION 2's swap fee is APPROXIMATE: PulseX takes ~0.29% of the swapped value,
-    // applied here to the bridged intermediate amount.
-    //
-    // AN ONWARD HOP GETS NO FIGURE AT ALL, and that is the honest answer rather
-    // than a gap. `PULSEX_SWAP_FEE_BASIS_POINTS` prices a PulseX swap; an
-    // aggregator bridge to another chain charges its own spread plus that chain's
-    // gas, and neither is 0.29%. Reusing the constant would print a number that
-    // looks measured and is not, beside section 1's fee, which really is measured.
-    // The aggregator quotes the leg when the user returns to sign it, and until
-    // then null is what we know.
     const sectionTwoFeeValue = onward !== null
         ? null
         : usdValueOfAmount({
@@ -1071,8 +434,6 @@ export const buildOutboundRouteData = (roots) => {
         title: omnibridgeProviderDisplayName(provider),
         conversion: `${assetIn.symbol} → ${intermediateToken.symbol}`,
         feeUsdValue: sectionOneFeeValue,
-        // Delivery auto-completes on the entry chain, so the single signature covers
-        // the whole omnibridge leg.
         automatic: true,
     };
     const sectionOne = {
@@ -1096,9 +457,6 @@ export const buildOutboundRouteData = (roots) => {
                 chainLogoUri: intermediateChainLogoUri,
             },
         ],
-        // The crossing lands the user in the INTERMEDIATE token on the entry chain —
-        // the whole point of naming a step's landing, since this is exactly the stop
-        // a two-signature route leaves you sitting at while you wait to sign again.
         landing: {
             amount: estimatedAmountOut,
             decimals: intermediateToken.decimals,
@@ -1110,16 +468,10 @@ export const buildOutboundRouteData = (roots) => {
             }),
         },
         feeUsdValue: sectionOneFeeValue,
-        // Who takes what on the crossing: the bridge, then the delivery service.
         fees: sectionOneFees,
-        // The omnibridge crossing out is the ~20-minute wait the deferred swap sits
-        // behind, so the wait is shown HERE, on the crossing leg.
         etaMinutes: BRIDGE_SETTLEMENT_ETA_MINUTES,
         hops: [bridgeHop],
     };
-    // SECTION 2 — DEFERRED. Signed only after section 1 settles. A swap on the entry
-    // chain (approximate ~0.29% fee), or an onward bridge carried by a named
-    // aggregator (no fee stated until it is quoted).
     const deferredHop = onward === null
         ? {
             providerName: 'Swap',
@@ -1129,9 +481,6 @@ export const buildOutboundRouteData = (roots) => {
             automatic: false,
         }
         : {
-            // THE SERVICE THAT WILL ACTUALLY CARRY IT. "Swap" names PulseX, and a
-            // reader who saw it beside a Base destination would be told the wrong
-            // thing about who holds their funds for the second leg.
             providerName: onward.providerName,
             title: `Bridge to ${onward.chainName}`,
             conversion: `${intermediateToken.symbol} → ${finalToken.symbol}`,
@@ -1154,17 +503,11 @@ export const buildOutboundRouteData = (roots) => {
                 symbol: finalToken.symbol,
                 address: finalToken.address,
                 decimals: finalToken.decimals,
-                // THE LINE THIS WHOLE CHANGE IS ABOUT. Pinned to `entryChainId`, the
-                // deferred leg could only ever be a swap where the crossing landed, and
-                // the route strip drew a Base token wearing Ethereum's badge.
                 chainId: finalChainId,
                 logoUri: finalTokenLogoUri,
                 chainLogoUri: onward === null ? intermediateChainLogoUri : onward.chainLogoUri,
             },
         ],
-        // The deferred swap names the token it will land in but NOT an amount: it is
-        // quoted only when the user returns, and stating a figure now would present an
-        // estimate with the same weight as the crossing's real one.
         landing: {
             amount: null,
             decimals: finalToken.decimals,
@@ -1172,13 +515,6 @@ export const buildOutboundRouteData = (roots) => {
             usdValue: null,
         },
         feeUsdValue: sectionTwoFeeValue,
-        // The swap itself is near-instant (~10 seconds); the ~20-minute wait it sits
-        // behind is shown on section 1 (the crossing).
-        //
-        // AN ONWARD HOP STATES NO ESTIMATE, for the same reason it states no fee. Ten
-        // seconds is how long a PulseX swap takes. How long an aggregator takes to
-        // carry value to another chain depends on the pair and on the route it picks,
-        // so the figure would be borrowed from a different operation.
         ...(onward === null ? { etaSeconds: PULSEX_SWAP_ETA_SECONDS } : {}),
         deferred: true,
         deferredNote: onward === null
@@ -1187,71 +523,36 @@ export const buildOutboundRouteData = (roots) => {
         hops: [deferredHop],
     };
     return {
-        // 'direct' EVEN WHEN THE SECOND LEG IS AN AGGREGATOR, and this is a decision
-        // rather than a leftover. `kind` is what the interface dispatches EXECUTION
-        // on: `executesViaConsolidated` sends a 'direct' route through the omnibridge
-        // sender and everything else through the aggregator sender. The only
-        // signature this route asks for now is section 1 — a plain omnibridge
-        // crossing out of PulseChain — so the omnibridge sender is the correct one.
-        // Calling it 'aggregated' would hand the button to a sender holding no quote
-        // for it, because the onward leg is not quoted until the user returns and
-        // starts a fresh route from the entry chain.
         kind: 'direct',
         entryChainId: null,
-        // The route is shown crossing VIA the chain it bridges to. Already correct
-        // for an onward hop: PulseChain to Base really does travel via Ethereum.
         viaChainId: entryChainId,
         headlineProviderKey: provider,
         sections: [sectionOne, sectionTwo],
         output: {
-            // The final amount is quoted on return (deferred leg) — unknown at display time.
             amount: null,
             decimals: finalToken.decimals,
             symbol: finalToken.symbol,
             usdValue: null,
         },
-        // Aggregate cost is section 1's crossing fees plus section 2's APPROXIMATE swap
-        // fee (~0.29%). Section 2 drops out when it states no figure (an onward hop
-        // is quoted only on return). Section 1 cannot: it is the signature the reader
-        // makes now, so without its cost there is no total, only the swap's guess.
         totalCostUsdValue: sectionOneFeeValue === null ? null : addUsdValues(sectionOneFeeValue, sectionTwoFeeValue),
         isBest: true,
         deltaPercent: 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 const buildPulseXSwapSectionData = (roots) => {
     const { id, fromToken, toToken, feeUsdValue = null, priceImpactPercent = null, landedAmount = null, landedUsdValue = null, etaMinutes = null, etaSeconds = null, fromTokenLogoUri, toTokenLogoUri, pulsechainChainLogoUri, deferred = false, advanced = null, } = roots;
     const swapHop = {
         providerName: 'PulseX',
-        // Resolve the PulseX logo via the provider key in the adapter; the raw hop
-        // carries only the key, not the url.
         providerKey: 'PulseX',
         title: `Swap to ${toToken.symbol}`,
         conversion: `${fromToken.symbol} → ${toToken.symbol}`,
         feeUsdValue,
-        // A standalone PulseX swap is the user's own signature, not an automatic hop.
         automatic: false,
     };
     const tokenFlow = [
         { symbol: fromToken.symbol, address: fromToken.address, chainId: pulsechainChainId, decimals: fromToken.decimals, logoUri: fromTokenLogoUri, chainLogoUri: pulsechainChainLogoUri },
         { symbol: toToken.symbol, address: toToken.address, chainId: pulsechainChainId, decimals: toToken.decimals, logoUri: toTokenLogoUri, chainLogoUri: pulsechainChainLogoUri },
     ];
-    // The swap section always shows the flat PulseX fee in its breakdown; the price
-    // impact clause is added by the adapter only when the impact is present and
-    // non-trivial. Round the impact to two decimals and drop it when it is <= 0.
     const roundedImpact = priceImpactPercent === null || Number(priceImpactPercent.toFixed(2)) <= 0
         ? null
         : Number(priceImpactPercent.toFixed(2));
@@ -1260,8 +561,6 @@ export const buildPulseXSwapSectionData = (roots) => {
         label: 'Swap on PulseX',
         providerKey: 'PulseX',
         tokenFlow,
-        // The swap is the last step of whatever composes it, so what it lands in is
-        // what the user ends up holding.
         landing: {
             amount: landedAmount,
             decimals: toToken.decimals,
@@ -1269,175 +568,62 @@ export const buildPulseXSwapSectionData = (roots) => {
             usdValue: landedUsdValue,
         },
         feeUsdValue,
-        // 0.29 — the flat PulseX fee percentage, kept in lockstep with the basis-point
-        // constant so the breakdown line tracks the rate the estimate applies.
         feePercent: Number(PULSEX_SWAP_FEE_BASIS_POINTS) / 100,
         priceImpactPercent: roundedImpact,
         etaMinutes,
         etaSeconds,
         hops: [swapHop],
-        // A PulseX swap is normally an immediate signature; deferred only when it sits
-        // behind a prior section's crossing.
         deferred: deferred ? true : undefined,
-        // NO `bridgeFrom`/`bridgeTo` — a same-chain swap crosses no bridge, and
-        // leaving them unset (rather than null) keeps the disclosure from naming a
-        // mediator that never runs. `destinationRouter` is the PulseX router
-        // itself here, not a delivery leg inside a crossing — see the field's own
-        // note on `RouteSectionData`.
         advanced: advanced === null ? undefined : advanced,
     };
 };
-/**
- * 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 const buildConversionRouteData = (composition) => {
     const { baseData, baseRouteId, anchorToken, wantedToken, estimate, anchorTokenLogoUri, wantedTokenLogoUri, pulsechainChainLogoUri, } = composition;
-    // The anchor bridges the two legs: it is BOTH the base route's delivered node and
-    // the swap's input node. Reuse the delivered node's pre-resolved logo so the same
-    // token shows ONE icon across the boundary; fall back to the threaded anchor logo.
     const deliveredAnchorNode = baseData.sections.at(-1)?.tokenFlow.at(-1);
     const boundaryAnchorLogoUri = deliveredAnchorNode?.logoUri ?? anchorTokenLogoUri;
     const swapSection = buildPulseXSwapSectionData({
         id: `${baseRouteId}-pulsex-swap`,
         fromToken: anchorToken,
         toToken: wantedToken,
-        // The section cost is the swap's TOTAL value loss (fee + price impact) so the
-        // route reconciles: input value − each step's cost = delivered output.
         feeUsdValue: estimate.costUsdValue,
         priceImpactPercent: estimate.priceImpactPercent,
-        // The swap lands the user in the wanted token. Its value is the bridge leg's
-        // landing less what the swap costs — the same subtraction the route's output
-        // uses, so the last step's landing figure and the route's delivered figure
-        // cannot drift apart.
         landedAmount: estimate.outputAmount,
         landedUsdValue: subtractUsdValues(baseData.output.usdValue, estimate.costUsdValue),
-        // The swap is near-instant (~10s); the ~20-minute wait sits on the crossing below.
         etaSeconds: PULSEX_SWAP_ETA_SECONDS,
         fromTokenLogoUri: boundaryAnchorLogoUri,
         toTokenLogoUri: wantedTokenLogoUri,
         pulsechainChainLogoUri,
-        // The bridge must land on PulseChain before the swap can be signed.
         deferred: true,
     });
-    // The ~20-minute crossing wait belongs on the section that LANDS THE FUNDS ON
-    // PULSECHAIN, replacing whatever entry-chain-only estimate that section carried.
-    //
-    // THE INDEX IS NOT A PROXY HERE, and the difference is worth stating because
-    // this project has been bitten by one. A positional "last section" stood in for
-    // "the section Gibs delivers" elsewhere and broke the moment a deferred leg
-    // appeared. This is the other case: a base route is BUILT to end on PulseChain —
-    // that is what makes it a base a swap can be appended to — so its final section
-    // IS the landing section by construction, for a one-signature base and for the
-    // two-signature NEAR Intents base alike. The name says which fact is meant, so a
-    // future base that ends somewhere else fails a test rather than a reader.
     const pulsechainLandingSectionIndex = baseData.sections.length - 1;
     const bridgeSections = baseData.sections.map((section, index) => index === pulsechainLandingSectionIndex
         ? { ...section, etaMinutes: BRIDGE_SETTLEMENT_ETA_MINUTES, etaSeconds: null }
         : section);
     return {
         ...baseData,
-        // The conversion route crosses the aggregator entry chain then swaps on PulseX.
         kind: 'conversion',
-        // Carry the aggregator entry chain so Bridge.tsx can link back to the candidate.
         entryChainId: baseData.entryChainId ?? null,
         sections: [...bridgeSections, swapSection],
         output: {
             amount: estimate.outputAmount,
             decimals: wantedToken.decimals,
             symbol: wantedToken.symbol,
-            // The wanted token's COUNT comes from the swap quote, but its value continues
-            // the base route's basis: what the anchor was worth on arrival, less the swap's
-            // cost. Re-pricing the wanted token against its own feed — which is what this
-            // used to do — sets the figure by the router's realized rate instead, and that
-            // rate routinely disagrees with the ratio of the two feeds by about a dollar on
-            // a hundred. The route then appeared to deliver more than its own cost rows allowed.
             usdValue: subtractUsdValues(baseData.output.usdValue, estimate.costUsdValue),
         },
-        // Aggregate cost = base cost + the swap's total loss; null only when both unknown.
         totalCostUsdValue: addUsdValues(baseData.totalCostUsdValue, estimate.costUsdValue),
-        // Net = base net − the swap's total loss; null when either is unknown.
         netValueUsd: baseData.netValueUsd == null || estimate.costUsdValue == null
             ? null
             : baseData.netValueUsd - estimate.costUsdValue,
     };
 };
-/**
- * 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 const buildPulseXSwapEstimateData = ({ amountsOut, inputAmount, inputToken, inputUsdPrice, outputToken, outputUsdPrice, referenceAmountsOut = null, referenceInputAmount = 0n, }) => {
     if (!amountsOut || amountsOut.length === 0)
         return null;
     const outputAmount = amountsOut[amountsOut.length - 1];
     if (typeof outputAmount !== 'bigint')
         return null;
-    // The swap fee is APPROXIMATE: PulseX takes a flat ~0.29% of the trade. Apply that
-    // rate to the swapped value, preferring the input (anchor) side and falling back
-    // to the output (wanted) side, so the fee still shows when only ONE side is priced.
     const feeUsdValue = usdValueOfAmount({ balance: (inputAmount * PULSEX_SWAP_FEE_BASIS_POINTS) / BASIS_POINTS_DENOMINATOR, decimals: inputToken.decimals, price: inputUsdPrice }) ??
         usdValueOfAmount({ balance: (outputAmount * PULSEX_SWAP_FEE_BASIS_POINTS) / BASIS_POINTS_DENOMINATOR, decimals: outputToken.decimals, price: outputUsdPrice });
-    // PRICE IMPACT comes from the MARGINAL reference quote, NOT from differencing the
-    // two PulseChain USD prices: those prices are themselves PulseX pool quotes, so
-    // value-in minus value-out cancels the fee and impact to ~$0 (the bug this
-    // replaces). Instead compare the full trade's realized rate against the tiny
-    // reference quote's near-spot rate. The swap fee rides in BOTH `getAmountsOut`
-    // results, so it cancels in the ratio and the gap is price impact ALONE.
     const marginalRate = (() => {
         if (!referenceAmountsOut || referenceAmountsOut.length === 0)
             return null;
@@ -1454,18 +640,11 @@ export const buildPulseXSwapEstimateData = ({ amountsOut, inputAmount, inputToke
     })();
     const inputWhole = Number(formatUnits(inputAmount, inputToken.decimals));
     const outputWhole = Number(formatUnits(outputAmount, outputToken.decimals));
-    // The output the trade WOULD deliver at the marginal (near-spot) rate with no
-    // price impact — fee still applied, since the marginal rate carries it too.
     const idealOutputWhole = marginalRate !== null ? inputWhole * marginalRate : null;
-    // The impact loss in OUTPUT-token units: what the marginal rate promised minus
-    // what the curve actually delivered. The fee is in both, so this is impact only.
     const impactLossOutput = idealOutputWhole !== null ? Math.max(0, idealOutputWhole - outputWhole) : null;
     const priceImpactPercent = impactLossOutput !== null && idealOutputWhole !== null && idealOutputWhole > 0
         ? Math.max(0, (impactLossOutput / idealOutputWhole) * 100)
         : null;
-    // Value the impact loss in dollars — preferring the output token's price, falling
-    // back to the input side via the marginal rate so the impact still shows when
-    // only the anchor is priced.
     const impactUsd = (() => {
         if (impactLossOutput === null)
             return null;
@@ -1476,9 +655,6 @@ export const buildPulseXSwapEstimateData = ({ amountsOut, inputAmount, inputToke
         }
         return null;
     })();
-    // Total cost is the flat fee PLUS the price impact — both real, neither cancelled.
-    // Round the fee to cents the SAME way the pre-split builder did (it summed the
-    // already-formatted fee string), so the total cost is identical to the cent.
     const feeRounded = feeUsdValue === null ? null : roundUsdToCents(feeUsdValue);
     const costUsdValue = feeRounded !== null && Number.isFinite(feeRounded)
         ? feeRounded + (impactUsd ?? 0)
@@ -1497,33 +673,6 @@ export const buildPulseXSwapEstimateData = ({ amountsOut, inputAmount, inputToke
         etaMinutes: 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 const buildSameChainSwapRouteData = (roots) => {
     const { id, fromToken, toToken, estimate, inputUsdValue, fromTokenLogoUri, toTokenLogoUri, pulsechainChainLogoUri, advanced, } = roots;
     const swapSection = buildPulseXSwapSectionData({
@@ -1538,13 +687,11 @@ export const buildSameChainSwapRouteData = (roots) => {
         fromTokenLogoUri,
         toTokenLogoUri,
         pulsechainChainLogoUri,
-        // Signed immediately — see the function doc above for why this must stay false.
         deferred: false,
         advanced,
     });
     return {
         kind: 'swap',
-        // No aggregator entry chain: the whole journey is one signature on PulseChain.
         entryChainId: null,
         headlineProviderKey: 'PulseX',
         sections: [swapSection],
@@ -1558,7 +705,6 @@ export const buildSameChainSwapRouteData = (roots) => {
         netValueUsd: inputUsdValue == null || estimate.costUsdValue == null
             ? null
             : inputUsdValue - estimate.costUsdValue,
-        // The swap's own near-instant duration; there is no crossing wait to add.
         etaMinutes: null,
     };
 };