@gibs/bridge-sdk 1.13.1 → 1.18.0

package/dist/routing/composed-route-quality.d.ts

@@ -47,6 +47,26 @@ export declare const COMPOSED_ROUTE_MAX_PRICE_IMPACT_PERCENT = 3;
  * of the reader's money.
  */
 export declare const COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT = 5;
+/**
+ * The end-to-end value GAIN above which a composed route is withdrawn, in
+ * percent of what the reader pays.
+ *
+ * A ROUTE CANNOT MAKE MONEY. Every leg charges a fee, so a route that
+ * delivers more value than it takes says one of its figures is wrong. Only a
+ * disagreement between the two price feeds can make a gain look real, and the
+ * value-loss ceiling already trusts those feeds to within the same five
+ * percent. So the bound is symmetric with
+ * {@link COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT}.
+ *
+ * THE DEFECT THIS STOPS. On 2026-10-03 the engine served 0.0002 BNB to HEX at
+ * 495,256 HEX, about seven thousand times the rate of the next tier. The
+ * value-loss test read that as a loss of minus seven hundred thousand percent
+ * and passed it. A PulseX hop rescaled from an upstream live answer keeps the
+ * price impact measured at its original, smaller input
+ * (`recomposePath` in `@gibs/quotes`'s `search/waves.ts`), so the impact test
+ * cannot see an inflated amount either. Only the two ends of the journey can.
+ */
+export declare const COMPOSED_ROUTE_MAX_VALUE_GAIN_PERCENT = 5;
 /**
  * The verdict on one composed route.
  *
@@ -62,18 +82,20 @@ export type ComposedRouteVerdict = {
     readonly missing: 'price-impact' | 'route-value';
 } | {
     readonly state: 'rejected';
-    readonly reason: 'price-impact' | 'value-loss';
+    readonly reason: 'price-impact' | 'value-loss' | 'value-gain';
     /** The measured figure, in percent, that failed its ceiling. */
     readonly measuredPercent: number;
     /** The ceiling it failed. */
     readonly ceilingPercent: number;
 };
 /**
- * Judges a composed route against both ceilings.
+ * Judges a composed route against its three ceilings.
  *
- * Checks price impact first and value loss second, because impact names the
- * specific leg at fault while value loss only says the journey as a whole went
- * wrong — so reporting impact when both fail is the more useful answer.
+ * Checks price impact first, then value loss, then value gain. Impact names
+ * the specific leg at fault, while the two value tests only say the journey as
+ * a whole went wrong, so impact is the more useful answer when several fail.
+ * In the measured percent of a `'value-gain'` rejection, the gain is a
+ * positive number.
  *
  * @param options.priceImpactPercent - the swap leg's price impact, from the
  *   estimate's marginal reference quote; null when not yet quoted
@@ -98,6 +120,6 @@ export declare const assessComposedRoute: ({ priceImpactPercent, paidUsdValue, d
  * pricing" rather than "no route", which a boolean alone could not.
  *
  * @param verdict - the verdict from {@link assessComposedRoute}
- * @returns true only when the route passed both ceilings
+ * @returns true only when the route passed every ceiling
  */
 export declare const composedRouteMayBeOffered: (verdict: ComposedRouteVerdict) => boolean;

package/dist/routing/composed-route-quality.js

@@ -48,11 +48,33 @@ export const COMPOSED_ROUTE_MAX_PRICE_IMPACT_PERCENT = 3;
  */
 export const COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT = 5;
 /**
- * Judges a composed route against both ceilings.
+ * The end-to-end value GAIN above which a composed route is withdrawn, in
+ * percent of what the reader pays.
+ *
+ * A ROUTE CANNOT MAKE MONEY. Every leg charges a fee, so a route that
+ * delivers more value than it takes says one of its figures is wrong. Only a
+ * disagreement between the two price feeds can make a gain look real, and the
+ * value-loss ceiling already trusts those feeds to within the same five
+ * percent. So the bound is symmetric with
+ * {@link COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT}.
+ *
+ * THE DEFECT THIS STOPS. On 2026-10-03 the engine served 0.0002 BNB to HEX at
+ * 495,256 HEX, about seven thousand times the rate of the next tier. The
+ * value-loss test read that as a loss of minus seven hundred thousand percent
+ * and passed it. A PulseX hop rescaled from an upstream live answer keeps the
+ * price impact measured at its original, smaller input
+ * (`recomposePath` in `@gibs/quotes`'s `search/waves.ts`), so the impact test
+ * cannot see an inflated amount either. Only the two ends of the journey can.
+ */
+export const COMPOSED_ROUTE_MAX_VALUE_GAIN_PERCENT = 5;
+/**
+ * Judges a composed route against its three ceilings.
  *
- * Checks price impact first and value loss second, because impact names the
- * specific leg at fault while value loss only says the journey as a whole went
- * wrong — so reporting impact when both fail is the more useful answer.
+ * Checks price impact first, then value loss, then value gain. Impact names
+ * the specific leg at fault, while the two value tests only say the journey as
+ * a whole went wrong, so impact is the more useful answer when several fail.
+ * In the measured percent of a `'value-gain'` rejection, the gain is a
+ * positive number.
  *
  * @param options.priceImpactPercent - the swap leg's price impact, from the
  *   estimate's marginal reference quote; null when not yet quoted
@@ -91,6 +113,15 @@ export const assessComposedRoute = ({ priceImpactPercent, paidUsdValue, delivere
             ceilingPercent: COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT,
         };
     }
+    const gainPercent = -lossPercent;
+    if (gainPercent > COMPOSED_ROUTE_MAX_VALUE_GAIN_PERCENT) {
+        return {
+            state: 'rejected',
+            reason: 'value-gain',
+            measuredPercent: gainPercent,
+            ceilingPercent: COMPOSED_ROUTE_MAX_VALUE_GAIN_PERCENT,
+        };
+    }
     return { state: 'acceptable' };
 };
 /**
@@ -103,6 +134,6 @@ export const assessComposedRoute = ({ priceImpactPercent, paidUsdValue, delivere
  * pricing" rather than "no route", which a boolean alone could not.
  *
  * @param verdict - the verdict from {@link assessComposedRoute}
- * @returns true only when the route passed both ceilings
+ * @returns true only when the route passed every ceiling
  */
 export const composedRouteMayBeOffered = (verdict) => verdict.state === 'acceptable';

package/dist/routing/entry-chain-anchor.d.ts

@@ -74,7 +74,7 @@ export type EntryChainAnchor = {
  * PulseChain token. A USD Coin pair does not gain an ether anchor here —
  * ether would land as bridged ether, a different token, needing a different
  * swap path. That is a different DESTINATION PAIR, and choosing between pairs
- * already has a home in `selectAnchorDestinationPair`.
+ * is made by the route engine, which holds every destination pair.
  *
  * @param options.entryChainToken - the destination pair's entry-chain side
  * @param options.pulsechainToken - the destination pair's PulseChain side

package/dist/routing/entry-chain-anchor.js

@@ -15,7 +15,7 @@ import { sameAddress } from '../ecosystems.js';
  * PulseChain token. A USD Coin pair does not gain an ether anchor here —
  * ether would land as bridged ether, a different token, needing a different
  * swap path. That is a different DESTINATION PAIR, and choosing between pairs
- * already has a home in `selectAnchorDestinationPair`.
+ * is made by the route engine, which holds every destination pair.
  *
  * @param options.entryChainToken - the destination pair's entry-chain side
  * @param options.pulsechainToken - the destination pair's PulseChain side

package/dist/routing/index.d.ts

@@ -9,11 +9,11 @@ export { omnibridgeProviderForEntryChain, pulseXConversionSwapPath } from './pro
 export { buildDirectCrossingCandidate } from './candidate.js';
 export type { RouteCandidate, DeferredCrossing, DirectCrossingCandidateInputs } from './candidate.js';
 export { buildRouteDataForCandidate, routeSignatureCount } from './candidate-route.js';
-export { COMPOSED_ROUTE_MAX_PRICE_IMPACT_PERCENT, COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT, assessComposedRoute, composedRouteMayBeOffered, } from './composed-route-quality.js';
+export { COMPOSED_ROUTE_MAX_PRICE_IMPACT_PERCENT, COMPOSED_ROUTE_MAX_VALUE_GAIN_PERCENT, COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT, assessComposedRoute, composedRouteMayBeOffered, } from './composed-route-quality.js';
 export type { ComposedRouteVerdict } from './composed-route-quality.js';
 export { entryChainAnchorsForPair } from './entry-chain-anchor.js';
 export type { EntryChainAnchor, EntryChainCrossingCall } from './entry-chain-anchor.js';
-export type { EstimateBasis, RouteData, RouteHopData, RouteKind, RouteOutputData, RouteSectionData, RouteTokenRef, } from './route-data.js';
+export type { EstimateBasis, RouteData, RouteGasByChain, RouteHopData, RouteKind, RouteOutputData, RouteSectionData, RouteTokenRef, } from './route-data.js';
 export { usdValueOfAmount } from './usd-value.js';
 export { formatUsd, formatUsdNullable } from './format.js';
 export { BRIDGE_SETTLEMENT_ETA_MINUTES, PULSEX_MARGINAL_REFERENCE_DIVISOR, pulsechainChainId, addUsdValues, providerDisplayName, resolveEntryChainName, buildCandidateRouteData, buildConversionRouteData, buildDirectRouteData, buildPulseXSwapEstimateData, buildPulseXSwapSectionData, buildOutboundRouteData, buildSameChainSwapRouteData, candidateDeliveredUsd, candidateNetValueUsd, candidateOutsideFeesUsd, candidatePaidUsd, } from './producers.js';
@@ -24,11 +24,19 @@ export { composableHopBasis, composeRouteDelivery, hopOutputAmount, } from './se
 export type { ComposableHop, ComposableHopFigure, ComposeRefusalReason, ComposedRouteDelivery, ExchangeRate, } from './search/compose.js';
 export { GAS_TOPUP_PENALTY_FLOOR_USD, GAS_TOPUP_PENALTY_PPM, SIGNATURE_PENALTY_FLOOR_USD, SIGNATURE_PENALTY_PPM, compareRoutePlansByGasAdjustedDeliveredAmount, compareRoutePlansByScoreAdjustedDeliveredAmount, gasAdjustedDeliveredAmount, scoreRoutePlan, sectionIsFundedByLanding, waitPenaltyPpm, zeroGasCostFor, } from './search/score.js';
 export type { GasCostFor, GasCostQuote, RouteScoreInputs } from './search/score.js';
+export { WRAP_CARRIER_ID, carrierProviderKey, carrierStepKind } from './carrier-provider-key.js';
+export type { CarrierStepKind } from './carrier-provider-key.js';
 export { buildRouteCandidateFromPlan, buildRouteDataFromPlan, buildRouteScoreInputsFromPlan, deriveDeferredCrossingFromPlan, deriveEntryChainIdFromPlan, deriveOmnibridgeProviderFromPlan, deriveViaChainIdsFromPlan, derivePlanKind, } from './search/plan-route-data.js';
 export type { PlanCandidateInputs, PlanRouteDataInputs, PlanSectionPricing, PlanValuation, ResolveNodeToken, } from './search/plan-route-data.js';
 export { createOmnibridgeCarrier, withOmnibridgeEntryFusing, } from './carriers/omnibridge.js';
 export type { BridgeablePair, CreateOmnibridgeCarrierOptions, } from './carriers/omnibridge.js';
-export { createPulseXCarrier, pulseXPoolPath, pulseXRouterForEdge, pulseXVenues } from './carriers/pulsex.js';
+export { createPulseXCarrier, pulseXRouterForEdge, venueForEdge, pulseXSwapPathForHop, pulseXVenues, pulseXWrappedNativePath, } from './carriers/pulsex.js';
 export type { CreatePulseXCarrierOptions, PulseXVenue } from './carriers/pulsex.js';
+export { bestPulseXPathQuote, candidatePulseXPaths, pulseXHubTokens } from './carriers/pulsex-paths.js';
+export type { PulseXHubToken, PulseXPathQuote } from './carriers/pulsex-paths.js';
+export { findSwapVenue, resolveSwapVenues } from '../swap-venues.js';
+export type { SwapVenue, SwapVenues } from '../swap-venues.js';
 export { createWrapCarrier } from './carriers/wrap.js';
 export type { CarrierAskAnswer, CarrierExactResult } from './carriers/ask-answer.js';
+export { buildPulseXSwapTransaction, buildWrapTransaction, swapMinimumOut } from './swap-transactions.js';
+export type { SwapCallInputs } from './swap-transactions.js';

package/dist/routing/index.js

@@ -8,7 +8,7 @@ export { netDeliveredAmount, restateInDecimals, valueEquivalentAmount } from './
 export { omnibridgeProviderForEntryChain, pulseXConversionSwapPath } from './providers.js';
 export { buildDirectCrossingCandidate } from './candidate.js';
 export { buildRouteDataForCandidate, routeSignatureCount } from './candidate-route.js';
-export { COMPOSED_ROUTE_MAX_PRICE_IMPACT_PERCENT, COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT, assessComposedRoute, composedRouteMayBeOffered, } from './composed-route-quality.js';
+export { COMPOSED_ROUTE_MAX_PRICE_IMPACT_PERCENT, COMPOSED_ROUTE_MAX_VALUE_GAIN_PERCENT, COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT, assessComposedRoute, composedRouteMayBeOffered, } from './composed-route-quality.js';
 export { entryChainAnchorsForPair } from './entry-chain-anchor.js';
 export { usdValueOfAmount } from './usd-value.js';
 export { formatUsd, formatUsdNullable } from './format.js';
@@ -26,6 +26,7 @@ export { BRIDGE_SETTLEMENT_ETA_MINUTES, PULSEX_MARGINAL_REFERENCE_DIVISOR, pulse
 export { RANKABLE_ESTIMATE_BASES, assetNodeKey, combineComposedPathBasis, compareRoutePlansByDeliveredAmount, groupHopsBySignature, hopComposedBasis, hopEdgeKey, isConfirmedBasis, isRankableBasis, isRateLimitedCarrier, planComposedBasis, planIsConfirmed, planIsRankable, routePlanPathKey, } from './search/graph.js';
 export { composableHopBasis, composeRouteDelivery, hopOutputAmount, } from './search/compose.js';
 export { GAS_TOPUP_PENALTY_FLOOR_USD, GAS_TOPUP_PENALTY_PPM, SIGNATURE_PENALTY_FLOOR_USD, SIGNATURE_PENALTY_PPM, compareRoutePlansByGasAdjustedDeliveredAmount, compareRoutePlansByScoreAdjustedDeliveredAmount, gasAdjustedDeliveredAmount, scoreRoutePlan, sectionIsFundedByLanding, waitPenaltyPpm, zeroGasCostFor, } from './search/score.js';
+export { WRAP_CARRIER_ID, carrierProviderKey, carrierStepKind } from './carrier-provider-key.js';
 // General route search — Phase 1: plan-route-data.ts. Turns a priced
 // RoutePlan into the same RouteData/RouteCandidate/RouteScoreInputs shapes
 // today's four hand-written producers emit — see that module's head doc.
@@ -38,5 +39,10 @@ export { buildRouteCandidateFromPlan, buildRouteDataFromPlan, buildRouteScoreInp
 // `searchRouteWaves` and their types from `@gibs/quotes/search`. Gibs's own
 // carriers (the omnibridge crossing, PulseX) live in `./carriers/`, below.
 export { createOmnibridgeCarrier, withOmnibridgeEntryFusing, } from './carriers/omnibridge.js';
-export { createPulseXCarrier, pulseXPoolPath, pulseXRouterForEdge, pulseXVenues } from './carriers/pulsex.js';
+export { createPulseXCarrier, pulseXRouterForEdge, venueForEdge, pulseXSwapPathForHop, pulseXVenues, pulseXWrappedNativePath, } from './carriers/pulsex.js';
+export { bestPulseXPathQuote, candidatePulseXPaths, pulseXHubTokens } from './carriers/pulsex-paths.js';
+export { findSwapVenue, resolveSwapVenues } from '../swap-venues.js';
 export { createWrapCarrier } from './carriers/wrap.js';
+// The same-chain swap and wrap builders. The interface's section signing and
+// the SDK's execution planner (`../execution.ts`) share them.
+export { buildPulseXSwapTransaction, buildWrapTransaction, swapMinimumOut } from './swap-transactions.js';

package/dist/routing/producers.js

@@ -1182,7 +1182,7 @@ export const buildOutboundRouteData = (roots) => {
         ...(onward === null ? { etaSeconds: PULSEX_SWAP_ETA_SECONDS } : {}),
         deferred: true,
         deferredNote: onward === null
-            ? `Fee is approximate — quoted at ${entryChainName} when you return.`
+            ? `The fee shown is an estimate. You get a new quote at ${entryChainName} when you come back.`
             : `Quoted by ${onward.providerName} at ${entryChainName} when you return.`,
         hops: [deferredHop],
     };

package/dist/routing/providers.d.ts

@@ -8,6 +8,11 @@ import { type Provider } from '../config.js';
  * IS WPLS (no point hopping through WPLS to reach WPLS). The router prices the path
  * with `getAmountsOut`, so a path with no liquidity simply yields no quote.
  *
+ * A FIXED PATH, NOT THE BEST ONE. The route search's PulseX carrier prices
+ * this path alongside others through its hub tokens and signs whichever
+ * delivers most (`carriers/pulsex-paths.ts`). This one remains the
+ * carrier's asynchronous `ask` path (`pulseXWrappedNativePath`).
+ *
  * @param anchorAddress - the bridged anchor token (the swap input)
  * @param wantedAddress - the token the user wants (the swap output)
  * @param wplsAddress - the wrapped-native intermediary (WPLS)

package/dist/routing/providers.js

@@ -8,6 +8,11 @@ import { sameAddress } from '../ecosystems.js';
  * IS WPLS (no point hopping through WPLS to reach WPLS). The router prices the path
  * with `getAmountsOut`, so a path with no liquidity simply yields no quote.
  *
+ * A FIXED PATH, NOT THE BEST ONE. The route search's PulseX carrier prices
+ * this path alongside others through its hub tokens and signs whichever
+ * delivers most (`carriers/pulsex-paths.ts`). This one remains the
+ * carrier's asynchronous `ask` path (`pulseXWrappedNativePath`).
+ *
  * @param anchorAddress - the bridged anchor token (the swap input)
  * @param wantedAddress - the token the user wants (the swap output)
  * @param wplsAddress - the wrapped-native intermediary (WPLS)

package/dist/routing/route-data.d.ts

@@ -1,6 +1,7 @@
 import type { Hex } from 'viem';
 import type { QuoteFee } from '../quote-fees.js';
 import type { ProviderKey } from '../providers.js';
+import type { CarrierStepKind } from './carrier-provider-key.js';
 /**
  * The executing engine family a route runs through.
  *
@@ -91,7 +92,12 @@ export type RouteHopData = {
     /** Display name for the hop's provider, e.g. "LI.FI", "PulseChain Bridge". */
     providerName: string;
     /** Raw provider key for logo resolution when no `providerLogoUri` is supplied. */
-    providerKey?: string | null;
+    providerKey?: ProviderKey | null;
+    /**
+     * What the hop does when no provider performs it (a native wrap). Such a hop
+     * has a null `providerKey`; the adapter draws its mark from this kind.
+     */
+    stepKind?: CarrierStepKind | null;
     /** Quote-supplied provider logo url (aggregator legs); preferred when present. */
     providerLogoUri?: string | null;
     /** Human-readable hop title, e.g. "Bridge to PulseChain". */
@@ -110,11 +116,27 @@ export type RouteHopData = {
      * completes. Null/undefined when the provider named no output token.
      */
     toToken?: RouteTokenRef | null;
-    /** Per-hop fee in United States dollars as a NUMBER, or null when unknown. */
+    /** Per-hop fee in United States dollars as a NUMBER, or null when unknown. A search route's figure INCLUDES the signature's network gas (carried on the section's first hop). */
     feeUsdValue?: number | null;
+    /** The part of {@link feeUsdValue} that is not network gas: what the hop costs in value. Absent when the producer states no gas split. */
+    feeExcludingGasUsdValue?: number | null;
+    /** The network gas of the signature this hop opens, in dollars; null or absent on every hop that opens none, and when gas is unknown. */
+    gasUsdValue?: number | null;
     /** True when this hop runs automatically inside the section's single signature. */
     automatic?: boolean;
 };
+/**
+ * The network gas a route needs on one signing chain, summed across the
+ * signatures it signs there.
+ */
+export type RouteGasByChain = {
+    /** The chain the signatures broadcast on. */
+    chainId: number;
+    /** The native coin they burn, in base units (wei), or null when the chain's gas price is unknown. */
+    amountWei: bigint | null;
+    /** The same gas in dollars, or null when the amount or the native price is unknown. */
+    usdValue: number | null;
+};
 /**
  * What a signature section's funds LAND IN when that step completes — the stop
  * the money actually comes to rest at, named in tokens rather than only drawn as
@@ -181,7 +203,9 @@ export type RouteSectionData = {
     /** Short label naming what this signature does, e.g. "Bridge to PulseChain". */
     label: string;
     /** Raw provider key for the service executing this signature, or null. */
-    providerKey?: string | null;
+    providerKey?: ProviderKey | null;
+    /** What the signature does when no provider performs it (a native wrap); see {@link RouteHopData.stepKind}. */
+    stepKind?: CarrierStepKind | null;
     /**
      * The token-icon flow this signature walks, in raw references: the source, then
      * every INTERMEDIATE stop the funds pass through, then the destination. A
@@ -202,8 +226,12 @@ export type RouteSectionData = {
      * a cost.
      */
     unspent?: RouteUnspentData | null;
-    /** Section total fee in United States dollars as a NUMBER, or null. */
+    /** Section total fee in United States dollars as a NUMBER, or null. A search route's figure INCLUDES this signature's network gas. */
     feeUsdValue?: number | null;
+    /** The part of {@link feeUsdValue} that is not network gas. Absent when the producer states no gas split. */
+    feeExcludingGasUsdValue?: number | null;
+    /** This signature's network gas in dollars, or null/absent when unknown. */
+    gasUsdValue?: number | null;
     /** Numeric inputs for an optional fee breakdown line (conversion mode). */
     feePercent?: number | null;
     /** Price-impact percentage for an optional fee breakdown line (conversion mode). */
@@ -316,8 +344,22 @@ export type RouteData = {
     sections: RouteSectionData[];
     /** What the route delivers — used for ranking and the output row. */
     output: RouteOutputData;
-    /** Aggregate all-in cost in United States dollars as a NUMBER, or null. */
+    /**
+     * Aggregate ALL-IN cost in United States dollars as a NUMBER, or null:
+     * value lost plus network gas. The ranking reads this figure. For the
+     * figure without gas, read {@link costExcludingGasUsdValue}.
+     */
     totalCostUsdValue?: number | null;
+    /** {@link totalCostUsdValue} without network gas: the value the reader gives up. Absent when the producer states no gas split. */
+    costExcludingGasUsdValue?: number | null;
+    /**
+     * The network gas the reader pays across every signature, in dollars, or
+     * null/absent when no signing chain has a gas reading. Never zero for
+     * "unknown".
+     */
+    gasCostUsdValue?: number | null;
+    /** The gas by signing chain, in signing order: what to hold, and in which coin. */
+    gasByChain?: RouteGasByChain[];
     /** The user's net United States dollar outcome; the figure routes are ranked on. */
     netValueUsd?: number | null;
     /** Estimated end-to-end duration in minutes, or null when unknown. */

package/dist/routing/search/graph.d.ts

@@ -324,6 +324,14 @@ export type HopOutcome = {
      * pool reserves (a PulseX swap). Absent means "not measured", never zero.
      */
     readonly priceImpactPercent?: number;
+    /**
+     * The token addresses the carrier's execution passes through, in order,
+     * when the carrier chose among several (a PulseX swap path). The figure
+     * was priced along exactly this path, and the signer must sign exactly
+     * this path — never rebuild one. Opaque to the search, like
+     * {@link HopEdge.venue}. Absent when the carrier makes no such choice.
+     */
+    readonly swapPath?: readonly string[];
 } | {
     readonly kind: 'estimate';
     /** The composed/probed figure, in the hop's `to` node's base units. */
@@ -367,6 +375,13 @@ export type HopOutcome = {
      * small moves a live upstream quote makes. Absent means "not measured".
      */
     readonly priceImpactPercent?: number;
+    /**
+     * The swap path the hop was priced along when the carrier answered it
+     * exactly, carried onto the rescaled estimate like
+     * {@link priceImpactPercent}. The rescale changes the amount, not the
+     * path, so this is still the path to sign.
+     */
+    readonly swapPath?: readonly string[];
 };
 /**
  * Whether every hop of `hops` carries a figure a ranking may trust: a live

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

@@ -1,8 +1,9 @@
+import { type ProviderKey } from '../../providers.js';
 import type { Provider } from '../../config.js';
 import type { QuoteFee } from '../../quote-fees.js';
 import type { Token } from '../../types.js';
 import type { DeferredCrossing, RouteCandidate } from '../candidate.js';
-import type { RouteData, RouteKind } from '../route-data.js';
+import type { RouteData, RouteGasByChain, RouteKind } from '../route-data.js';
 import type { RouteScoreInputs } from './score.js';
 import { type AssetNode, type RoutePlan } from './graph.js';
 /**
@@ -83,6 +84,18 @@ export declare const deriveViaChainIdsFromPlan: (plan: RoutePlan) => number[] |
  * @returns the route's kind
  */
 export declare const derivePlanKind: (plan: RoutePlan) => RouteKind;
+/**
+ * The plan's headline provider — the omnibridge crossing it out when it
+ * crosses one, or whichever carrier performs signature 1 when it does not.
+ * Matches every existing builder's own headline choice: the omnibridge when
+ * present (`buildCandidateRouteData`, `buildNearIntentsTwoStepRouteData`,
+ * `buildOutboundRouteData`), the aggregator's own key as the fallback
+ * (`buildCandidateRouteData`'s no-omnibridge branch).
+ *
+ * @param plan - the plan to derive from
+ * @returns the headline provider key
+ */
+export declare const deriveHeadlineProviderKeyFromPlan: (plan: RoutePlan) => ProviderKey;
 /**
  * The anchor a two-signature plan leaves the reader holding between its
  * first and second groups — `RouteCandidate.plan`'s own TSDoc: "the anchor
@@ -116,6 +129,28 @@ export type PlanSectionPricing = {
     landingUsdValue: number | null;
     /** This section's own cost, in United States dollars, or null when unpriced. */
     feeUsdValue: number | null;
+    /**
+     * Each hop's own share of `feeUsdValue`, one entry per hop of the group in
+     * order, or omitted when the caller cannot price every hop.
+     *
+     * WHY A FUSED SECTION NEEDS THIS. One signature can carry two legs: an
+     * aggregator lands on the bridge's entry chain and makes the entry call in
+     * the same transaction. With no per-hop figure, a display that splits the
+     * section into legs can only put the whole cost on the first leg, so the
+     * aggregator wore the bridge's fee and the bridge leg read as free. The
+     * caller passes shares that add up to `feeUsdValue`, or nothing.
+     */
+    hopFeeUsdValues?: readonly (number | null)[];
+    /**
+     * The gas split of `feeUsdValue`, from a producer that prices network gas
+     * apart: `feeExcludingGasUsdValue` is the cost without gas, `gasUsdValue` the
+     * signature's gas (null when unknown). `hopFeeExcludingGasUsdValues` splits
+     * the first the way `hopFeeUsdValues` splits the all-in figure. The gas sits
+     * on the section's first hop.
+     */
+    feeExcludingGasUsdValue?: number | null;
+    gasUsdValue?: number | null;
+    hopFeeExcludingGasUsdValues?: readonly (number | null)[];
     /** The itemized charges behind `feeUsdValue`, passed straight through to `RouteSectionData.fees`. */
     fees?: readonly QuoteFee[];
     /** Estimated duration for this signature in minutes, or null/undefined to omit. */
@@ -150,6 +185,12 @@ export type PlanRouteDataInputs = {
     sections: readonly PlanSectionPricing[];
     /** The route's aggregate all-in cost in United States dollars, or null/undefined. */
     totalCostUsdValue?: number | null;
+    /** The all-in cost without network gas, or null/undefined. */
+    costExcludingGasUsdValue?: number | null;
+    /** The route's network gas in dollars, or null/undefined when unknown. */
+    gasCostUsdValue?: number | null;
+    /** The gas by signing chain, in signing order. */
+    gasByChain?: readonly RouteGasByChain[];
     /** The route's net United States dollar outcome — the figure routes are ranked on. */
     netValueUsd?: number | null;
     /** Estimated end-to-end duration in minutes, or null/undefined. */

package/dist/routing/search/plan-route-data.js

@@ -1,6 +1,7 @@
 import * as imageLinks from '../../image-links.js';
 import { chainDisplayName } from '../../chain-names.js';
 import { findProviderById } from '../../providers.js';
+import { WRAP_CARRIER_ID, carrierProviderKey, carrierStepKind } from '../carrier-provider-key.js';
 import { describeDeferredCrossing } from '../../near-intents-route.js';
 import { candidateDeliveredUsd, candidateOutsideFeesUsd, candidatePaidUsd, pulsechainChainId, providerDisplayName, } from '../producers.js';
 import { assetNodeKey, planComposedBasis, } from './graph.js';
@@ -229,6 +230,8 @@ const hopProviderName = (carrier) => {
         return providerDisplayName(carrier);
     if (carrier === 'PulseX')
         return 'PulseX';
+    if (carrierStepKind(carrier) === 'wrap')
+        return 'Wrap';
     // TOTAL OVER EVERY CARRIER. The engine plans hops for carriers the provider
     // registry does not hold (a local wrap, a host's own plug-in). Casting such
     // an id to a provider id and asking the throwing lookup crashed the whole
@@ -349,20 +352,44 @@ const hopIsAutomatic = (hopIndex, plan) => {
  * @param hopIndex - the hop's index into `plan.hops`
  * @param plan - the plan the hop belongs to
  * @param resolveToken - resolves a graph node to its full display token
+ * @param feeUsdValue - the hop's own share of its section's cost, or null
+ * @param gas - the hop's gas split, or null when the producer states none
  * @returns the raw hop data
  */
-const toRouteHopData = (hop, hopIndex, plan, resolveToken) => ({
+const toRouteHopData = (hop, hopIndex, plan, resolveToken, feeUsdValue, gas) => ({
     providerName: hopProviderName(hop.edge.carrier),
-    providerKey: hop.edge.carrier,
+    providerKey: carrierProviderKey(hop.edge.carrier),
+    stepKind: carrierStepKind(hop.edge.carrier),
     title: hopTitle(hop, hopIndex, plan, resolveToken),
     conversion: hopConversion(hop, hopIndex, plan, resolveToken),
     fromToken: toRouteTokenRef(hop.edge.from, resolveToken),
     toToken: toRouteTokenRef(hop.edge.to, resolveToken),
-    // The per-hop dollar figure is a section-level, caller-supplied input (see
-    // this module's head doc); a raw hop carries none of its own here.
-    feeUsdValue: null,
+    // The per-hop dollar figure is a caller-supplied input (see this module's
+    // head doc); the caller passes it in, never derived here.
+    feeUsdValue,
+    ...(gas === null ? {} : gas),
     automatic: hopIsAutomatic(hopIndex, plan),
 });
+/**
+ * The per-hop shares a section's pricing names, checked against the group
+ * they describe.
+ *
+ * @param pricing - the section's caller-supplied pricing
+ * @param group - the signature group's hop indices
+ * @param groupIndex - the group's index, for the error message
+ * @returns one share per hop, null where none was given
+ * @throws when the caller passed a share list of the wrong length — a share
+ *   matched to the wrong hop is a figure on the wrong leg
+ */
+const groupHopFeeUsdValues = (pricing, group, groupIndex) => {
+    const shares = pricing.hopFeeUsdValues;
+    if (shares === undefined)
+        return group.map(() => null);
+    if (shares.length !== group.length) {
+        throw new Error(`buildRouteDataFromPlan: section ${groupIndex + 1} has ${group.length} hop(s) but ${shares.length} hop fee(s)`);
+    }
+    return shares;
+};
 // ---------------------------------------------------------------------------
 // Route-level derivations — candidate.ts's promised derivation, made real
 // ---------------------------------------------------------------------------
@@ -472,7 +499,8 @@ export const derivePlanKind = (plan) => {
  *
  * A GIBS PLAN NEVER CARRIES ANYTHING ELSE. Every carrier a `RoutePlan` this
  * module renders can name is one gibs itself registered — the three built-in
- * aggregators, the omnibridge, or PulseX (`routing/carriers/`,
+ * aggregators, the omnibridge, PulseX, or a wrap step, which
+ * {@link deriveHeadlineProviderKeyFromPlan} skips (`routing/carriers/`,
  * `packages/ui/src/lib/state/useRouteSearch.ts`) — so this throws rather than
  * guessing when it sees anything else: a plan naming an unrecognized carrier
  * is a bug in whatever built it, not a display gap to paper over silently.
@@ -500,7 +528,18 @@ const toHeadlineProviderKey = (carrier) => {
  * @param plan - the plan to derive from
  * @returns the headline provider key
  */
-const deriveHeadlineProviderKeyFromPlan = (plan) => toHeadlineProviderKey(deriveOmnibridgeProviderFromPlan(plan) ?? plan.hops[0].edge.carrier);
+export const deriveHeadlineProviderKeyFromPlan = (plan) => toHeadlineProviderKey(deriveOmnibridgeProviderFromPlan(plan) ?? firstHeadlineCarrier(plan));
+/**
+ * The carrier of the first hop that can headline a route. A `wrap` hop
+ * (native coin to its wrapped token, or back) is a step inside a route, never
+ * the route itself, so it is skipped. A plan made only of wraps headlines as
+ * PulseX, the same key the same-chain swap builder gives that route
+ * (`buildSameChainSwapRouteData`).
+ *
+ * @param plan - the plan to read
+ * @returns the carrier to headline
+ */
+const firstHeadlineCarrier = (plan) => plan.hops.find((hop) => hop.edge.carrier !== WRAP_CARRIER_ID)?.edge.carrier ?? 'PulseX';
 /**
  * The anchor a two-signature plan leaves the reader holding between its
  * first and second groups — `RouteCandidate.plan`'s own TSDoc: "the anchor
@@ -618,10 +657,14 @@ export const buildRouteDataFromPlan = (inputs) => {
         const lastHop = hops[hops.length - 1];
         const landing = resolveNodeWithAssertedDecimals(lastHop.edge.to, resolveToken);
         const landingIsUnpriced = hopOutcomeIsUnpriced(lastHop);
+        const hopFeeUsdValues = groupHopFeeUsdValues(pricing, group, groupIndex);
+        const statesGasSplit = pricing.feeExcludingGasUsdValue !== undefined;
+        const hopFeeExcludingGasUsdValues = pricing.hopFeeExcludingGasUsdValues;
         return {
             id: `${routeId}-signature-${groupIndex + 1}`,
             label: sectionLabel(group, groupIndex, plan),
-            providerKey: hops[0].edge.carrier,
+            providerKey: carrierProviderKey(hops[0].edge.carrier),
+            stepKind: carrierStepKind(hops[0].edge.carrier),
             tokenFlow: buildGroupTokenFlow(hops, resolveToken),
             landing: {
                 amount: sectionLandingAmount(pricing, lastHop),
@@ -631,10 +674,19 @@ export const buildRouteDataFromPlan = (inputs) => {
                 estimateBasis: hopEstimateBasis(lastHop),
             },
             feeUsdValue: pricing.feeUsdValue,
+            ...(statesGasSplit
+                ? { feeExcludingGasUsdValue: pricing.feeExcludingGasUsdValue, gasUsdValue: pricing.gasUsdValue ?? null }
+                : {}),
             fees: pricing.fees ? [...pricing.fees] : undefined,
             etaMinutes: pricing.etaMinutes,
             etaSeconds: pricing.etaSeconds,
-            hops: group.map((hopIndex) => toRouteHopData(plan.hops[hopIndex], hopIndex, plan, resolveToken)),
+            hops: group.map((hopIndex, positionInGroup) => toRouteHopData(plan.hops[hopIndex], hopIndex, plan, resolveToken, hopFeeUsdValues[positionInGroup] ?? null, statesGasSplit
+                ? {
+                    feeExcludingGasUsdValue: hopFeeExcludingGasUsdValues?.[positionInGroup] ??
+                        (group.length === 1 ? (pricing.feeExcludingGasUsdValue ?? null) : null),
+                    gasUsdValue: positionInGroup === 0 ? (pricing.gasUsdValue ?? null) : null,
+                }
+                : null)),
             deferred: groupIndex > 0 ? true : undefined,
             deferredNote: pricing.deferredNote,
         };
@@ -653,6 +705,13 @@ export const buildRouteDataFromPlan = (inputs) => {
             estimateBasis: lastSection.landing?.estimateBasis ?? null,
         },
         totalCostUsdValue,
+        ...(inputs.costExcludingGasUsdValue === undefined
+            ? {}
+            : {
+                costExcludingGasUsdValue: inputs.costExcludingGasUsdValue,
+                gasCostUsdValue: inputs.gasCostUsdValue ?? null,
+                gasByChain: [...(inputs.gasByChain ?? [])],
+            }),
         netValueUsd,
         etaMinutes,
         // The single legacy `viaChainId` a not-yet-migrated consumer may still

package/dist/routing/search/score.d.ts

@@ -347,6 +347,9 @@ export declare const gasAdjustedDeliveredAmount: (plan: RoutePlan, gasCostFor: G
  * own real charges.
  *
  * @param gasCostFor - supplies each signature's real cost; see {@link GasCostFor}
+ * TIE-BREAK: when the gas-adjusted amounts are equal, the plan with fewer
+ * signatures ranks first.
+ *
  * @returns a comparator: negative when `a` ranks ahead of `b`, positive when
  *   `b` ranks ahead of `a`, zero when they tie
  */

package/dist/routing/search/score.js

@@ -409,6 +409,9 @@ export const gasAdjustedDeliveredAmount = (plan, gasCostFor) => {
  * own real charges.
  *
  * @param gasCostFor - supplies each signature's real cost; see {@link GasCostFor}
+ * TIE-BREAK: when the gas-adjusted amounts are equal, the plan with fewer
+ * signatures ranks first.
+ *
  * @returns a comparator: negative when `a` ranks ahead of `b`, positive when
  *   `b` ranks ahead of `a`, zero when they tie
  */
@@ -421,7 +424,12 @@ export const compareRoutePlansByGasAdjustedDeliveredAmount = (gasCostFor) => (a,
         return compareRoutePlansByDeliveredAmount(a, b);
     const adjustedA = gasAdjustedDeliveredAmount(a, gasCostFor);
     const adjustedB = gasAdjustedDeliveredAmount(b, gasCostFor);
-    if (adjustedA === adjustedB)
-        return 0;
-    return adjustedA > adjustedB ? -1 : 1;
+    if (adjustedA !== adjustedB)
+        return adjustedA > adjustedB ? -1 : 1;
+    // EQUAL FIGURES: FEWER SIGNATURES RANKS FIRST. Two plans that deliver the
+    // same amount cost the reader different effort — each signature is one more
+    // wallet prompt. Without this the stable sort kept the depth-first walk
+    // order, so a three-signature plan could be selected over a two-signature
+    // plan showing the same figure.
+    return a.signatures.length - b.signatures.length;
 };