@gibs/bridge-sdk 1.13.0 → 1.17.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,7 +9,7 @@ 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';
@@ -22,13 +22,17 @@ export { RANKABLE_ESTIMATE_BASES, assetNodeKey, combineComposedPathBasis, compar
 export type { AssetNode, CarrierId, ComposedPathBasis, HopCarrier, HopEdge, HopEdgeOrigin, HopFloor, HopOutcome, HopRequest, PlannedHop, RoutePlan, } from './search/graph.js';
 export { composableHopBasis, composeRouteDelivery, hopOutputAmount, } from './search/compose.js';
 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, waitPenaltyPpm, zeroGasCostFor, } from './search/score.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 { 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, 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 { 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';
@@ -25,7 +25,7 @@ export { BRIDGE_SETTLEMENT_ETA_MINUTES, PULSEX_MARGINAL_REFERENCE_DIVISOR, pulse
 // under its `Carrier*` names.
 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, waitPenaltyPpm, zeroGasCostFor, } from './search/score.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';
 // 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 +38,9 @@ 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, pulseXSwapPathForHop, pulseXVenues, pulseXWrappedNativePath, } from './carriers/pulsex.js';
+export { bestPulseXPathQuote, candidatePulseXPaths, pulseXHubTokens } from './carriers/pulsex-paths.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/search/graph.d.ts

@@ -318,6 +318,20 @@ export type HopOutcome = {
      * build exactly the request the route was priced for.
      */
     readonly minimumDeliveredAmount?: bigint;
+    /**
+     * How far the hop's executed rate falls below its marginal rate, in
+     * percent — present only when the carrier measured it from its own
+     * 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. */
@@ -353,6 +367,21 @@ export type HopOutcome = {
      * a plan on any more.
      */
     readonly refusalReason?: string | null;
+    /**
+     * The price impact measured when the carrier answered this hop exactly,
+     * carried onto the rescaled estimate when an upstream amount moved and
+     * the exact figure no longer applies verbatim. Impact grows roughly in
+     * proportion to the trade, so the carried figure stays close for the
+     * 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,3 +1,4 @@
+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';
@@ -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,18 @@ 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 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. */

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

@@ -349,20 +349,41 @@ 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
  * @returns the raw hop data
  */
-const toRouteHopData = (hop, hopIndex, plan, resolveToken) => ({
+const toRouteHopData = (hop, hopIndex, plan, resolveToken, feeUsdValue) => ({
     providerName: hopProviderName(hop.edge.carrier),
     providerKey: 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,
     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 +493,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.
@@ -480,6 +502,8 @@ export const derivePlanKind = (plan) => {
  * @param carrier - the plan's headline carrier
  * @returns the same value, typed as `ProviderKey`
  */
+/** The carrier id of the native-coin wrap step (`routing/carriers/wrap.ts`). */
+const WRAP_CARRIER = 'wrap';
 const toHeadlineProviderKey = (carrier) => {
     if (isBridgeCarrier(carrier))
         return carrier;
@@ -500,7 +524,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)?.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,6 +653,7 @@ 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);
         return {
             id: `${routeId}-signature-${groupIndex + 1}`,
             label: sectionLabel(group, groupIndex, plan),
@@ -634,7 +670,7 @@ export const buildRouteDataFromPlan = (inputs) => {
             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)),
             deferred: groupIndex > 0 ? true : undefined,
             deferredNote: pricing.deferredNote,
         };

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

@@ -244,8 +244,20 @@ export type GasCostQuote = {
      * the user needs gas, then they should get it" — a gasless intermediate
      * chain is modelled as ONE MORE CHARGE against the route, exactly like the
      * gas itself, never as a refusal or an exclusion from the ranking.
+     *
+     * A SECTION THE PREVIOUS SECTION FUNDS IS NEVER CHARGED THIS. When the
+     * hop landing on this chain delivers native coin, the reader arrives
+     * holding gas — {@link gasAdjustedDeliveredAmount} drops this figure for
+     * that section (see {@link sectionIsFundedByLanding}).
      */
     readonly refuelAmount: bigint;
+    /**
+     * The native coin this signature burns, in the signing chain's own native
+     * base units (wei on an Ethereum-Virtual-Machine chain) — the amount a gas
+     * top-up has to land at minimum. Optional: a caller with no gas-price read
+     * omits it, and a served top-up then reports its native amount as unknown.
+     */
+    readonly nativeGasAmount?: bigint;
 };
 /**
  * Supplies the REAL cost of signing one step, for the chain it broadcasts on
@@ -285,12 +297,29 @@ export type GasCostFor = (chainId: number, sender: HopCarrier) => GasCostQuote;
  * has something total to call when nobody has.
  */
 export declare const zeroGasCostFor: GasCostFor;
+/**
+ * Whether the section at `sectionIndex` starts with native coin already in
+ * the reader's hand: the hop that ends the PREVIOUS section delivers the
+ * chain's native coin, so the reader arrives holding gas for this section's
+ * own signature and needs no top-up there, whatever their balance was.
+ *
+ * Always false for the first section — nothing lands before it, so its gas
+ * can only come from the reader's own balance.
+ *
+ * @param plan - the plan the section belongs to
+ * @param sectionIndex - 0-based index into `plan.signatures`
+ * @returns true when the previous section lands native coin on this
+ *   section's chain
+ */
+export declare const sectionIsFundedByLanding: (plan: RoutePlan, sectionIndex: number) => boolean;
 /**
  * `plan`'s last-hop `deliveredAmount`, minus the REAL cost of every
  * signature it needs — `gasCostFor` charged ONCE per signature group
  * (`plan.signatures`, built by `groupHopsBySignature`), on the chain and
  * carrier of that group's FIRST hop, which is the hop the reader actually
- * signs (or deposits by hand) for that group. Floored at zero: a plan whose
+ * signs (or deposits by hand) for that group. A group's refuel cost is
+ * dropped when the previous group lands native coin
+ * ({@link sectionIsFundedByLanding}). Floored at zero: a plan whose
  * gas costs exceed its own delivered amount is worth nothing, never negative.
  *
  * @param plan - the plan to charge
@@ -318,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

@@ -1,3 +1,4 @@
+import { isNativeAsset } from '../../ecosystems.js';
 import { compareRoutePlansByDeliveredAmount, planIsRankable, isRankableBasis, } from './graph.js';
 /**
  * PHASE 0 — FOUNDATION ONLY. Today this module holds exactly one function,
@@ -337,12 +338,37 @@ export const scoreRoutePlan = (inputs) => {
  * has something total to call when nobody has.
  */
 export const zeroGasCostFor = () => ({ gasAmount: 0n, refuelAmount: 0n });
+/**
+ * Whether the section at `sectionIndex` starts with native coin already in
+ * the reader's hand: the hop that ends the PREVIOUS section delivers the
+ * chain's native coin, so the reader arrives holding gas for this section's
+ * own signature and needs no top-up there, whatever their balance was.
+ *
+ * Always false for the first section — nothing lands before it, so its gas
+ * can only come from the reader's own balance.
+ *
+ * @param plan - the plan the section belongs to
+ * @param sectionIndex - 0-based index into `plan.signatures`
+ * @returns true when the previous section lands native coin on this
+ *   section's chain
+ */
+export const sectionIsFundedByLanding = (plan, sectionIndex) => {
+    if (sectionIndex < 1)
+        return false;
+    const previousGroup = plan.signatures[sectionIndex - 1];
+    const landingHop = plan.hops[previousGroup?.[previousGroup.length - 1] ?? -1];
+    if (landingHop === undefined)
+        return false;
+    return isNativeAsset(landingHop.edge.to.address, landingHop.edge.to.ecosystem);
+};
 /**
  * `plan`'s last-hop `deliveredAmount`, minus the REAL cost of every
  * signature it needs — `gasCostFor` charged ONCE per signature group
  * (`plan.signatures`, built by `groupHopsBySignature`), on the chain and
  * carrier of that group's FIRST hop, which is the hop the reader actually
- * signs (or deposits by hand) for that group. Floored at zero: a plan whose
+ * signs (or deposits by hand) for that group. A group's refuel cost is
+ * dropped when the previous group lands native coin
+ * ({@link sectionIsFundedByLanding}). Floored at zero: a plan whose
  * gas costs exceed its own delivered amount is worth nothing, never negative.
  *
  * @param plan - the plan to charge
@@ -351,13 +377,14 @@ export const zeroGasCostFor = () => ({ gasAmount: 0n, refuelAmount: 0n });
  */
 export const gasAdjustedDeliveredAmount = (plan, gasCostFor) => {
     const deliveredAmount = plan.hops[plan.hops.length - 1]?.outcome.deliveredAmount ?? 0n;
-    const totalGasCost = plan.signatures.reduce((total, group) => {
+    const totalGasCost = plan.signatures.reduce((total, group, sectionIndex) => {
         const firstHopIndex = group[0];
         const firstHop = firstHopIndex === undefined ? undefined : plan.hops[firstHopIndex];
         if (firstHop === undefined)
             return total;
         const quote = gasCostFor(firstHop.edge.from.chainId, firstHop.edge.carrier);
-        return total + quote.gasAmount + quote.refuelAmount;
+        const refuelAmount = sectionIsFundedByLanding(plan, sectionIndex) ? 0n : quote.refuelAmount;
+        return total + quote.gasAmount + refuelAmount;
     }, 0n);
     const netAmount = deliveredAmount - totalGasCost;
     return netAmount < 0n ? 0n : netAmount;
@@ -382,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
  */
@@ -394,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;
 };