@gibs/bridge-sdk 1.12.0 → 1.13.1

package/dist/routing/producers.js

@@ -0,0 +1,1564 @@
+/**
+ * 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);
+        if (quoted !== null)
+            return quoted;
+    }
+    if (candidate.destinationUsdPrice === null)
+        return null;
+    return usdValueOfAmount({
+        balance: candidate.deliveredAmount,
+        decimals: candidate.destinationToken.decimals,
+        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)
+        return null;
+    const spent = candidate.quote.fromAmount;
+    if (spent <= 0n || spent >= requested)
+        return null;
+    const remainder = requested - spent;
+    if ((remainder * BASIS_POINTS_DENOMINATOR) / requested < UNSPENT_MATERIAL_BASIS_POINTS) {
+        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))) /
+            Number(formatUnits(spent, candidate.originToken.decimals));
+    return {
+        amount: remainder,
+        decimals: candidate.originToken.decimals,
+        symbol: candidate.originToken.symbol,
+        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;
+    const bridgeToken = bridgeFeeToken({ bridgeKey, sourceToken, arrivingToken });
+    const bridgeFeeUsdValue = bridgeFeeAmount === null || bridgeToken === null
+        ? null
+        : usdValueOfAmount({ balance: bridgeFeeAmount, decimals: sourceToken.decimals, price: sourceUsdPrice });
+    const bridgeFees = bridgeFeeAmount === null || bridgeToken === null || bridgeFeeAmount === 0n
+        ? []
+        : [
+            {
+                kind: 'service',
+                label: labelWithRate(`${omnibridgeProviderDisplayName(provider)} fee`, bridgeFeeRate),
+                amount: bridgeFeeAmount,
+                token: bridgeToken,
+                amountUsd: feeAmountUsdText(bridgeFeeUsdValue),
+                includedInFromAmount: true,
+            },
+        ];
+    if (deliveryFee.status === 'not-requested') {
+        return { feeUsdValue: bridgeFeeUsdValue, fees: bridgeFees };
+    }
+    const deliveryAmount = deliveryFee.amount;
+    const deliveryFeeUsdValue = deliveryAmount === null
+        ? null
+        : usdValueOfAmount({ balance: deliveryAmount, decimals: sourceToken.decimals, price: sourceUsdPrice });
+    const deliveryFees = deliveryAmount === null || deliveryAmount === 0n
+        ? []
+        : [
+            {
+                kind: 'service',
+                label: labelWithRate('Gibs delivery fee', deliveryFee.rate),
+                amount: deliveryAmount,
+                token: arrivingToken,
+                amountUsd: feeAmountUsdText(deliveryFeeUsdValue),
+                includedInFromAmount: true,
+            },
+        ];
+    const feeUsdValue = bridgeFeeUsdValue === null || deliveryFeeUsdValue === null
+        ? null
+        : 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,
+    chainId: endpoint.chainId,
+    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;
+    if (left.address === right.address)
+        return true;
+    if (!left.address.startsWith('0x') || !right.address.startsWith('0x'))
+        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)
+        return flow;
+    const held = flow[flow.length - 1];
+    if (held && isSameTokenRef(held, produced))
+        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) {
+            return total;
+        }
+        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)
+        return null;
+    const delivered = candidateDeliveredUsd(candidate);
+    if (delivered === null)
+        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)
+        : null;
+    if (feeUsdValue === null) {
+        console.warn(`[route-strip] fee unavailable: candidate=${candidate.id}` +
+            ` provider=${candidate.quote.provider}` +
+            ` 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
+        : {
+            providerName: providerDisplayName(omnibridgeProviderKey),
+            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({
+                balance: candidate.omnibridgeFeeAmount,
+                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,
+            symbol: candidate.destinationToken.symbol,
+            usdValue: subtractUsdValues(candidatePaidUsd(candidate), feeUsdValue),
+        },
+        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,
+        hops,
+    };
+    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,
+                    decimals: candidate.destinationToken.decimals,
+                    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,
+        sourceToken: toFeeToken(assetIn, Number(fromChain)),
+        arrivingToken: toFeeToken(assetOut, Number(toChain)),
+        sourceUsdPrice: assetInUsdPrice,
+    });
+    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: [
+            {
+                symbol: assetIn.symbol,
+                address: assetIn.address,
+                chainId: Number(fromChain),
+                decimals: assetIn.decimals,
+                logoUri: assetInLogoUri,
+                chainLogoUri: fromChainLogoUri,
+            },
+            {
+                symbol: assetOut.symbol,
+                address: assetOut.address,
+                chainId: Number(toChain),
+                decimals: assetOut.decimals,
+                logoUri: assetOutLogoUri,
+                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,
+            symbol: assetOut.symbol,
+            usdValue: usdValueOfAmount({
+                balance: estimatedAmountOut,
+                decimals: assetOut.decimals,
+                price: assetInUsdPrice ?? assetOutUsdPrice ?? null,
+            }),
+        },
+        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],
+        output: {
+            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)
+        return null;
+    const [provider, fromChain, toChain] = bridgeKey;
+    const entryChainId = Number(toChain);
+    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,
+        sourceToken: toFeeToken(assetIn, Number(fromChain)),
+        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({
+            balance: (estimatedAmountOut * PULSEX_SWAP_FEE_BASIS_POINTS) / BASIS_POINTS_DENOMINATOR,
+            decimals: intermediateToken.decimals,
+            price: intermediateUsdPrice,
+        });
+    const bridgeHop = {
+        providerName: omnibridgeProviderDisplayName(provider),
+        providerKey: provider,
+        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 = {
+        id: `outbound-${provider}-${fromChain}-${toChain}-signature-1`,
+        label: `Bridge to ${entryChainName}`,
+        tokenFlow: [
+            {
+                symbol: assetIn.symbol,
+                address: assetIn.address,
+                decimals: assetIn.decimals,
+                chainId: Number(fromChain),
+                logoUri: assetInLogoUri,
+                chainLogoUri: fromChainLogoUri,
+            },
+            {
+                symbol: intermediateToken.symbol,
+                address: intermediateToken.address,
+                decimals: intermediateToken.decimals,
+                chainId: entryChainId,
+                logoUri: assetOutLogoUri,
+                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,
+            symbol: intermediateToken.symbol,
+            usdValue: usdValueOfAmount({
+                balance: estimatedAmountOut,
+                decimals: intermediateToken.decimals,
+                price: intermediateUsdPrice,
+            }),
+        },
+        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',
+            title: `Swap to ${finalToken.symbol}`,
+            conversion: `${intermediateToken.symbol} → ${finalToken.symbol}`,
+            feeUsdValue: sectionTwoFeeValue,
+            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}`,
+            feeUsdValue: null,
+            automatic: false,
+        };
+    const sectionTwo = {
+        id: `outbound-${provider}-${fromChain}-${toChain}-signature-2`,
+        label: `Complete at ${finalChainName}`,
+        tokenFlow: [
+            {
+                symbol: intermediateToken.symbol,
+                address: intermediateToken.address,
+                decimals: intermediateToken.decimals,
+                chainId: entryChainId,
+                logoUri: assetOutLogoUri,
+                chainLogoUri: intermediateChainLogoUri,
+            },
+            {
+                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,
+            symbol: finalToken.symbol,
+            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
+            ? `Fee is approximate — quoted at ${entryChainName} when you return.`
+            : `Quoted by ${onward.providerName} at ${entryChainName} when you return.`,
+        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));
+    return {
+        id,
+        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,
+            symbol: toToken.symbol,
+            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;
+        if (referenceInputAmount <= 0n)
+            return null;
+        const referenceOutput = referenceAmountsOut[referenceAmountsOut.length - 1];
+        if (typeof referenceOutput !== 'bigint' || referenceOutput <= 0n)
+            return null;
+        const referenceInputWhole = Number(formatUnits(referenceInputAmount, inputToken.decimals));
+        const referenceOutputWhole = Number(formatUnits(referenceOutput, outputToken.decimals));
+        if (!(referenceInputWhole > 0) || !(referenceOutputWhole > 0))
+            return null;
+        return referenceOutputWhole / referenceInputWhole;
+    })();
+    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;
+        if (outputUsdPrice !== null)
+            return impactLossOutput * outputUsdPrice;
+        if (inputUsdPrice !== null && marginalRate !== null && marginalRate > 0) {
+            return (impactLossOutput / marginalRate) * inputUsdPrice;
+        }
+        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)
+        : impactUsd;
+    if (costUsdValue === null) {
+        console.warn(`[route-strip] fee unavailable: PulseX swap leg` +
+            ` wantedToken=${outputToken.symbol}` +
+            ` anchorTokenUsdPrice=${inputUsdPrice}` +
+            ` wantedTokenUsdPrice=${outputUsdPrice}`);
+    }
+    return {
+        outputAmount,
+        feeUsdValue,
+        costUsdValue,
+        priceImpactPercent,
+        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({
+        id: `${id}-pulsex-swap`,
+        fromToken,
+        toToken,
+        feeUsdValue: estimate.costUsdValue,
+        priceImpactPercent: estimate.priceImpactPercent,
+        landedAmount: estimate.outputAmount,
+        landedUsdValue: subtractUsdValues(inputUsdValue, estimate.costUsdValue),
+        etaSeconds: PULSEX_SWAP_ETA_SECONDS,
+        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],
+        output: {
+            amount: estimate.outputAmount,
+            decimals: toToken.decimals,
+            symbol: toToken.symbol,
+            usdValue: subtractUsdValues(inputUsdValue, estimate.costUsdValue),
+        },
+        totalCostUsdValue: estimate.costUsdValue,
+        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,
+    };
+};