@gibs/bridge-sdk 1.13.1 → 1.17.0

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';
@@ -28,7 +28,11 @@ export { buildRouteCandidateFromPlan, buildRouteDataFromPlan, buildRouteScoreInp
 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';
@@ -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

@@ -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,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

@@ -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;
 };

package/dist/routing/swap-transactions.d.ts

@@ -0,0 +1,91 @@
+import { type Hex } from 'viem';
+import { type SignedLeg } from '../settings.js';
+import type { HopEdge, PlannedHop } from './search/graph.js';
+/**
+ * The same-chain, one-signature transaction shape every sender in this file
+ * builds: a target contract, a native-coin value, and encoded calldata.
+ */
+export type SwapCallInputs = {
+    readonly to: Hex;
+    readonly value: bigint;
+    readonly data: Hex;
+};
+/**
+ * Builds a same-chain PulseX swap transaction for one planned route-search
+ * hop. The interface's section signing (`packages/ui` `state/sectionSigning.ts`)
+ * and the SDK's execution planner (`execution.ts`) both call it, so there is
+ * exactly one place that turns "swap this hop" into calldata.
+ *
+ * SIGNS THE PATH THE HOP WAS PRICED ON. The PulseX carrier picks the best of
+ * many paths through its hub tokens and records the winner on the hop's
+ * outcome; `pulseXSwapPathForHop` (`carriers/pulsex.ts`) reads it back
+ * and checks it fits the hop's edge. This never rebuilds a path: a rebuilt
+ * path is a quote on one route and a signature on another. A hop that
+ * records no path is refused. REUSES `pulseXSwapTransactionInputs` (`settings.ts`)
+ * for the encoding, never re-implements it: that function already carries the
+ * `swapRefusal` guard (refuses to build a call for a leg the screen is not
+ * looking at) and the native-in/native-out/token-token branching.
+ *
+ * SIGNS ON THE EDGE'S OWN ROUTER. A PulseX edge names the deployment it was
+ * quoted on (`pulseXRouterForEdge`: V1 or V2, each with its own pools). The
+ * caller's `routerAddress` must be that same router — it is also the router
+ * the caller approved to spend the input token — or nothing is built. A V2
+ * quote signed on V1 would trade against a different pool than the one the
+ * reader was shown.
+ *
+ * @param options - the hop to swap, the amount and slippage-adjusted
+ *   minimum, who receives the output, the signing deadline, what the caller
+ *   believes this signature does (`signedLeg`), the chain it executes on, and
+ *   the resolved router address
+ * @returns the swap transaction inputs, or null when the hop records no
+ *   PulseX swap path, names no known router, `routerAddress` is not the
+ *   edge's own router, the leg on screen disagrees, or any of
+ *   `pulseXSwapTransactionInputs`'s own preconditions are unmet
+ */
+export declare const buildPulseXSwapTransaction: (options: {
+    readonly hop: Pick<PlannedHop, "edge" | "outcome">;
+    readonly amountIn: bigint;
+    readonly minAmountOut: bigint;
+    readonly recipient: Hex | null;
+    readonly deadline: bigint;
+    readonly signedLeg: SignedLeg | null;
+    readonly chainId: number | null;
+    readonly routerAddress: Hex | null;
+}) => SwapCallInputs | null;
+/**
+ * Builds a native-coin wrap/unwrap transaction for one route-search graph
+ * edge — PLS<->WPLS on PulseChain, ETH<->WETH on Ethereum, or the same pair
+ * on any other chain `config.ts`'s `nativeAssetOut` names one for.
+ *
+ * A WRAP IS NOT A SWAP CALL. There is no PulseX pool for native-versus-wrapped
+ * — see `routing/carriers/wrap.ts`'s own doc — so this never touches the
+ * PulseX router: wrapping sends `amountIn` native coin to the wrapped token's
+ * own `deposit()`; unwrapping calls `withdraw(amountIn)` on it with zero
+ * value. The `edge` names which direction: its `from`/`to` addresses are
+ * checked against the zero-address sentinel, never assumed from a caller
+ * flag, so a swapped/malformed edge is refused rather than guessed at.
+ *
+ * @param options - the edge to wrap or unwrap, and the amount in the SOURCE
+ *   token's base units (native units wrapping, wrapped units unwrapping —
+ *   native and wrapped share decimals on every chain this carrier covers)
+ * @returns the wrap/unwrap transaction inputs, or null when `amountIn` is not
+ *   positive or the edge is not exactly one native/wrapped pair
+ */
+export declare const buildWrapTransaction: (options: {
+    readonly edge: HopEdge;
+    readonly amountIn: bigint;
+}) => SwapCallInputs | null;
+/**
+ * The slippage floor a swap signs: the quoted output less the slippage
+ * allowance, rounded down. The interface's engine signing and the SDK's
+ * execution planner both read it, so the two never sign different floors for
+ * the same quote.
+ *
+ * @param options.quotedAmount - the hop's quoted output, in the output token's base units
+ * @param options.slippageBasisPoints - the allowance, in basis points (100 is 1%)
+ * @returns the minimum output the swap accepts
+ */
+export declare const swapMinimumOut: ({ quotedAmount, slippageBasisPoints, }: {
+    readonly quotedAmount: bigint;
+    readonly slippageBasisPoints: bigint;
+}) => bigint;

package/dist/routing/swap-transactions.js

@@ -0,0 +1,125 @@
+import { encodeFunctionData, isAddressEqual, parseAbi, zeroAddress } from 'viem';
+import { pulseXSwapTransactionInputs } from '../settings.js';
+import { pulseXRouterForEdge, pulseXSwapPathForHop } from './carriers/pulsex.js';
+/**
+ * The minimal WETH9-style wrap/unwrap interface: `deposit()` mints the
+ * wrapped token for the native coin sent with the call, `withdraw(uint256)`
+ * burns wrapped balance and returns native coin. Every wrapped-native
+ * contract this application bridges to exposes exactly this pair — see
+ * `carriers/wrap.ts`, whose own doc records the selectors as confirmed
+ * present on WPLS by bytecode inspection (2026-09-24). Kept local rather than
+ * added to `@gibs/abis`: the interface is two standard, unchanging selectors
+ * rather than a contract-specific ABI.
+ */
+const wrapAbi = parseAbi(['function deposit() payable', 'function withdraw(uint256 amount)']);
+/**
+ * Builds a same-chain PulseX swap transaction for one planned route-search
+ * hop. The interface's section signing (`packages/ui` `state/sectionSigning.ts`)
+ * and the SDK's execution planner (`execution.ts`) both call it, so there is
+ * exactly one place that turns "swap this hop" into calldata.
+ *
+ * SIGNS THE PATH THE HOP WAS PRICED ON. The PulseX carrier picks the best of
+ * many paths through its hub tokens and records the winner on the hop's
+ * outcome; `pulseXSwapPathForHop` (`carriers/pulsex.ts`) reads it back
+ * and checks it fits the hop's edge. This never rebuilds a path: a rebuilt
+ * path is a quote on one route and a signature on another. A hop that
+ * records no path is refused. REUSES `pulseXSwapTransactionInputs` (`settings.ts`)
+ * for the encoding, never re-implements it: that function already carries the
+ * `swapRefusal` guard (refuses to build a call for a leg the screen is not
+ * looking at) and the native-in/native-out/token-token branching.
+ *
+ * SIGNS ON THE EDGE'S OWN ROUTER. A PulseX edge names the deployment it was
+ * quoted on (`pulseXRouterForEdge`: V1 or V2, each with its own pools). The
+ * caller's `routerAddress` must be that same router — it is also the router
+ * the caller approved to spend the input token — or nothing is built. A V2
+ * quote signed on V1 would trade against a different pool than the one the
+ * reader was shown.
+ *
+ * @param options - the hop to swap, the amount and slippage-adjusted
+ *   minimum, who receives the output, the signing deadline, what the caller
+ *   believes this signature does (`signedLeg`), the chain it executes on, and
+ *   the resolved router address
+ * @returns the swap transaction inputs, or null when the hop records no
+ *   PulseX swap path, names no known router, `routerAddress` is not the
+ *   edge's own router, the leg on screen disagrees, or any of
+ *   `pulseXSwapTransactionInputs`'s own preconditions are unmet
+ */
+export const buildPulseXSwapTransaction = (options) => {
+    const { hop, amountIn, minAmountOut, recipient, deadline, signedLeg, chainId, routerAddress } = options;
+    const { edge } = hop;
+    const swapPath = pulseXSwapPathForHop(hop);
+    if (swapPath === null) {
+        return null;
+    }
+    const quotedRouter = pulseXRouterForEdge(edge);
+    if (quotedRouter === null || routerAddress === null || !isAddressEqual(quotedRouter, routerAddress)) {
+        return null;
+    }
+    return pulseXSwapTransactionInputs({
+        signedLeg,
+        chainId,
+        routerAddress,
+        fromTokenAddress: edge.from.address,
+        toTokenAddress: edge.to.address,
+        swapPath,
+        amountIn,
+        minAmountOut,
+        recipient,
+        deadline,
+    });
+};
+/**
+ * Builds a native-coin wrap/unwrap transaction for one route-search graph
+ * edge — PLS<->WPLS on PulseChain, ETH<->WETH on Ethereum, or the same pair
+ * on any other chain `config.ts`'s `nativeAssetOut` names one for.
+ *
+ * A WRAP IS NOT A SWAP CALL. There is no PulseX pool for native-versus-wrapped
+ * — see `routing/carriers/wrap.ts`'s own doc — so this never touches the
+ * PulseX router: wrapping sends `amountIn` native coin to the wrapped token's
+ * own `deposit()`; unwrapping calls `withdraw(amountIn)` on it with zero
+ * value. The `edge` names which direction: its `from`/`to` addresses are
+ * checked against the zero-address sentinel, never assumed from a caller
+ * flag, so a swapped/malformed edge is refused rather than guessed at.
+ *
+ * @param options - the edge to wrap or unwrap, and the amount in the SOURCE
+ *   token's base units (native units wrapping, wrapped units unwrapping —
+ *   native and wrapped share decimals on every chain this carrier covers)
+ * @returns the wrap/unwrap transaction inputs, or null when `amountIn` is not
+ *   positive or the edge is not exactly one native/wrapped pair
+ */
+export const buildWrapTransaction = (options) => {
+    const { edge, amountIn } = options;
+    if (amountIn <= 0n) {
+        return null;
+    }
+    const fromIsNative = edge.from.address.toLowerCase() === zeroAddress;
+    const toIsNative = edge.to.address.toLowerCase() === zeroAddress;
+    // Exactly one side must be the native sentinel — a token/token pair, or a
+    // native/native no-op, is not a wrap edge at all.
+    if (fromIsNative === toIsNative) {
+        return null;
+    }
+    if (fromIsNative) {
+        return {
+            to: edge.to.address,
+            value: amountIn,
+            data: encodeFunctionData({ abi: wrapAbi, functionName: 'deposit', args: [] }),
+        };
+    }
+    return {
+        to: edge.from.address,
+        value: 0n,
+        data: encodeFunctionData({ abi: wrapAbi, functionName: 'withdraw', args: [amountIn] }),
+    };
+};
+/**
+ * The slippage floor a swap signs: the quoted output less the slippage
+ * allowance, rounded down. The interface's engine signing and the SDK's
+ * execution planner both read it, so the two never sign different floors for
+ * the same quote.
+ *
+ * @param options.quotedAmount - the hop's quoted output, in the output token's base units
+ * @param options.slippageBasisPoints - the allowance, in basis points (100 is 1%)
+ * @returns the minimum output the swap accepts
+ */
+export const swapMinimumOut = ({ quotedAmount, slippageBasisPoints, }) => (quotedAmount * (10000n - slippageBasisPoints)) / 10000n;