@gibs/bridge-sdk 1.17.0 → 1.19.0

package/dist/routing/carriers/pulsex.js

@@ -2,8 +2,9 @@ import { multicallRead } from '@gibs/common/multicall';
 import { getAddress, isAddress, parseAbi, zeroAddress } from 'viem';
 import * as abis from '../../abis.js';
 import { chainsMetadata } from '../../chains.js';
-import { Chains, nativeAssetOut, toChain, uniV2Factories, uniV2Routers } from '../../config.js';
+import { defaultSwapVenues, nativeAssetOut, toChain } from '../../config.js';
 import { sameAddress } from '../../ecosystems.js';
+import { findSwapVenue, resolveSwapVenues } from '../../swap-venues.js';
 import { pulseXConversionSwapPath } from '../providers.js';
 import { PULSEX_MARGINAL_REFERENCE_DIVISOR, pulsechainChainId } from '../producers.js';
 import { assetNodeKey } from '../search/graph.js';
@@ -18,57 +19,73 @@ import { bestPulseXPathQuote, candidatePulseXPaths, pulseXHubTokens } from './pu
  * See `omnibridge.ts`'s head doc for why this returns a plain object shaped
  * like `Carrier` rather than importing that type.
  */
-/** WPLS, the wrapped-native intermediary {@link pulseXConversionSwapPath} routes conversions through. */
-const wplsAddress = nativeAssetOut[Chains.PLS];
-/** The hub addresses every candidate path is built from — see {@link pulseXHubTokens}. */
+/** The hub addresses every candidate path on PulseChain is built from — see {@link pulseXHubTokens}. */
 const hubAddresses = pulseXHubTokens.map((hub) => hub.address);
 /**
- * Every PulseX deployment on PulseChain, V1 first: `uniV2Routers` paired with
- * `uniV2Factories` by index. Each factory is the router's own
- * `router.factory()` read on chain — see `uniV2Factories`'s own doc in
- * `config.ts`. A router with no recorded factory is left out, because its
- * pools cannot be read.
+ * The wrapped-native token a chain's swaps route through, or undefined when
+ * this package does not know one for the chain. Without it a path on that
+ * chain can only be direct.
+ *
+ * @param chainId - the numeric chain id
  */
-export const pulseXVenues = (uniV2Routers[Chains.PLS] ?? []).flatMap((router, index) => {
-    const factory = uniV2Factories[Chains.PLS]?.[index];
-    return factory === undefined ? [] : [{ router: getAddress(router), factory: getAddress(factory) }];
-});
+const wrappedNativeFor = (chainId) => {
+    const wrapped = nativeAssetOut[toChain(chainId)];
+    return wrapped === undefined ? undefined : getAddress(wrapped);
+};
 /**
- * The venue an edge with no {@link HopEdge.venue} runs on: V1, index 0. Every
- * PulseX edge built before venues existed was quoted and signed on V1 — the
- * same-chain swap sender's own hand-built edge still is — so this keeps that
- * meaning rather than guessing a new one.
+ * The hub tokens a path on `chainId` may pass through. PulseChain has the
+ * full list; any other chain has only its wrapped-native token, because this
+ * package knows no other hubs.
  */
-const defaultPulseXVenue = pulseXVenues[0];
+const hubsFor = (chainId) => {
+    if (chainId === pulsechainChainId)
+        return hubAddresses;
+    const wrapped = wrappedNativeFor(chainId);
+    return wrapped === undefined ? [] : [wrapped];
+};
 /**
- * The router a PulseX edge must be signed on — the one its figure was quoted
- * against. Reads the edge's own {@link HopEdge.venue}; an edge with none is a
- * V1 edge (see {@link defaultPulseXVenue}).
- *
- * @param edge - the edge to sign
- * @returns the router, or null when the edge is not a PulseX edge or names a venue that is not a known PulseX router
+ * Every PulseX deployment on PulseChain, V1 first: the PulseChain entry of
+ * {@link defaultSwapVenues}. Frozen. It lists the DEFAULTS only — a carrier
+ * built with its own `venues` offers those instead.
  */
-export const pulseXRouterForEdge = (edge) => pulseXVenueForEdge(edge)?.router ?? null;
+export const pulseXVenues = defaultSwapVenues[pulsechainChainId] ?? [];
 /**
- * The {@link PulseXVenue} a PulseX edge runs on — see {@link pulseXRouterForEdge}.
+ * The {@link SwapVenue} a swap edge runs on: the one its figure was quoted
+ * against. Reads the edge's own {@link HopEdge.venue}; an edge with none runs
+ * on the FIRST venue of its chain (V1 for PulseX) — every swap edge built
+ * before venues existed was quoted and signed there, and the same-chain swap
+ * sender's own hand-built edge still is.
  *
- * @param edge - the edge
- * @returns the venue, or null when there is none
+ * NEVER FALLS BACK TO ANOTHER CHAIN OR ANOTHER ROUTER. An edge that names a
+ * router `venues` does not list gets null, so the caller can refuse it.
+ *
+ * @param venues - the venues the caller allows
+ * @param edge - the edge to sign; `from` names the chain, and defaults to PulseChain when absent
+ * @returns the venue, or null when the edge is not a swap edge or names a router that is not in `venues`
  */
-const pulseXVenueForEdge = (edge) => {
+export const venueForEdge = (venues, edge) => {
     if (edge.carrier !== 'PulseX')
         return null;
+    const chainId = edge.from?.chainId ?? pulsechainChainId;
     if (edge.venue === undefined)
-        return defaultPulseXVenue ?? null;
-    const venue = edge.venue;
-    return pulseXVenues.find((candidate) => sameAddress(candidate.router, venue, 'evm')) ?? null;
+        return venues[chainId]?.[0] ?? null;
+    return findSwapVenue(venues, chainId, edge.venue);
 };
 /**
- * A node's own address for a PulseX pool lookup: native PLS (the zero
- * address) is not a token the router or its factory ever holds a pool for —
- * only Wrapped PLS is — so a native node resolves to {@link wplsAddress}
+ * The router a PulseX edge must be signed on, judged against the DEFAULT
+ * venues only. Prefer {@link venueForEdge} with the venues your host passes.
+ *
+ * @param edge - the edge to sign
+ * @returns the router, or null when the edge is not a swap edge or names a router that is not a default
+ */
+export const pulseXRouterForEdge = (edge) => venueForEdge(defaultSwapVenues, edge)?.router ?? null;
+/**
+ * A node's own address for a pool lookup: native (the zero address) is not a
+ * token the router or its factory ever holds a pool for — only the chain's
+ * wrapped-native token is — so a native node resolves to that wrapped token
  * before it ever reaches {@link pulseXConversionSwapPath}. Every other node
- * is unchanged.
+ * is unchanged. A chain with no known wrapped-native token leaves a native
+ * node as it is; it has no pool, so no path prices.
  *
  * MIRRORS `useRouteSearch.ts`'s `quotePathAddress` (the UI's async `ask`
  * already resolves native this way through that function) — this is the
@@ -76,9 +93,9 @@ const pulseXVenueForEdge = (edge) => {
  * UI's `readAmountOut` at all; see {@link pulseXCandidatePaths}'s own doc.
  *
  * @param node - the node to resolve
- * @returns the node's own address, or {@link wplsAddress} for native PLS
+ * @returns the node's own address, or its chain's wrapped-native address for a native node
  */
-const poolTokenAddress = (node) => (sameAddress(node.address, zeroAddress, 'evm') ? wplsAddress : node.address);
+const poolTokenAddress = (node) => sameAddress(node.address, zeroAddress, 'evm') ? (wrappedNativeFor(node.chainId) ?? zeroAddress) : node.address;
 /**
  * The fixed Wrapped-PLS path from `from` to `to` — `[from, WPLS, to]`, or
  * `[from, to]` when one side is WPLS — or null when both ends resolve to the
@@ -103,7 +120,8 @@ export const pulseXWrappedNativePath = (from, to) => {
     const toAddress = poolTokenAddress(to);
     if (sameAddress(fromAddress, toAddress, 'evm'))
         return null;
-    return pulseXConversionSwapPath(fromAddress, toAddress, wplsAddress);
+    const wrappedNative = wrappedNativeFor(from.chainId);
+    return wrappedNative === undefined ? [fromAddress, toAddress] : pulseXConversionSwapPath(fromAddress, toAddress, wrappedNative);
 };
 /**
  * Every path a PulseX hop from `from` to `to` may be priced along, or none
@@ -122,21 +140,27 @@ const pulseXCandidatePaths = (from, to) => {
     const toAddress = poolTokenAddress(to);
     if (sameAddress(fromAddress, toAddress, 'evm'))
         return [];
-    return candidatePulseXPaths({ from: fromAddress, to: toAddress, wrappedNative: wplsAddress, hubs: hubAddresses });
+    const wrappedNative = wrappedNativeFor(from.chainId);
+    // No known wrapped-native token: the direct pool is the only path.
+    if (wrappedNative === undefined)
+        return [[fromAddress, toAddress]];
+    return candidatePulseXPaths({ from: fromAddress, to: toAddress, wrappedNative, hubs: hubsFor(from.chainId) });
 };
 /**
- * Whether PulseX can carry funds directly from `from` to `to`: both must be
- * Ethereum-Virtual-Machine tokens on PulseChain itself — PulseX runs only on
- * PulseChain, never on an entry chain — that resolve to two different pool
- * tokens, so there is at least one path to price.
+ * Whether a swap venue in `venues` can carry funds directly from `from` to
+ * `to`: both must be Ethereum-Virtual-Machine tokens on the SAME chain, that
+ * chain must have at least one venue, and the two must resolve to different
+ * pool tokens, so there is at least one path to price.
  *
  * NO TOKEN ALLOWLIST IS CONSULTED, on purpose: whether a pool exists is the
  * reserve read's question, answered in `prepare`, not this one's.
  */
-const pulseXCarries = (from, to) => {
+const pulseXCarries = (venues, from, to) => {
     if (from.ecosystem !== 'evm' || to.ecosystem !== 'evm')
         return false;
-    if (from.chainId !== pulsechainChainId || to.chainId !== pulsechainChainId)
+    if (from.chainId !== to.chainId)
+        return false;
+    if ((venues[from.chainId] ?? []).length === 0)
         return false;
     return pulseXCandidatePaths(from, to).length > 0;
 };
@@ -173,8 +197,9 @@ export const pulseXSwapPathForHop = (hop) => {
     return path;
 };
 /**
- * PulseX's own constant-product swap fee, as a numerator over
- * {@link PULSEX_FEE_DENOMINATOR} — the SAME `getAmountOut` formula every
+ * PulseX's own constant-product swap fee in basis points (29 of 10000, a
+ * numerator of 9971) — the default for {@link amountOutAlongPath}; a
+ * venue carries its own `feeBasisPoints`. The SAME `getAmountOut` formula every
  * Uniswap-V2-style router uses: `amountOut = floor(amountIn * feeNumerator *
  * reserveOut / (reserveIn * feeDenominator + amountIn * feeNumerator))`.
  *
@@ -187,16 +212,16 @@ export const pulseXSwapPathForHop = (hop) => {
  * this claim against live chain data rather than trusting the arithmetic
  * alone.
  */
-const PULSEX_FEE_NUMERATOR = 9971n;
-/** The denominator {@link PULSEX_FEE_NUMERATOR} is a fraction of. */
-const PULSEX_FEE_DENOMINATOR = 10000n;
+const PULSEX_FEE_BASIS_POINTS = 29;
+/** Basis points in a whole: the denominator of every venue's fee. */
+const BASIS_POINTS_DENOMINATOR = 10000n;
 /** The minimal read-only factory ABI `prepare` needs — just enough to resolve a pool's address from its two tokens. */
 const univ2FactoryAbi = parseAbi([
     'function getPair(address tokenA, address tokenB) external view returns (address pair)',
 ]);
 /**
  * The Uniswap-V2-style constant-product `getAmountOut`, applied with
- * {@link PULSEX_FEE_NUMERATOR}. Reproduces the router's own on-chain formula
+ * the venue's fee. Reproduces the router's own on-chain formula
  * exactly — see `pulsex-carrier.fork.test.ts` — so PRICE IMPACT IS ALREADY
  * IN HERE: this is the same nonlinear function the router evaluates, not a
  * flat-fee approximation with an impact correction bolted on afterward.
@@ -204,14 +229,15 @@ const univ2FactoryAbi = parseAbi([
  * @param amountIn - the input amount, in `reserveIn`'s token's base units
  * @param reserveIn - the pool's reserve of the input token
  * @param reserveOut - the pool's reserve of the output token
+ * @param feeBasisPoints - the venue's swap fee, in basis points
  * @returns the output amount, in `reserveOut`'s token's base units; 0 when either reserve is 0
  */
-const constantProductAmountOut = (amountIn, reserveIn, reserveOut) => {
+const constantProductAmountOut = (amountIn, reserveIn, reserveOut, feeBasisPoints) => {
     if (reserveIn <= 0n || reserveOut <= 0n || amountIn <= 0n)
         return 0n;
-    const amountInWithFee = amountIn * PULSEX_FEE_NUMERATOR;
+    const amountInWithFee = amountIn * (BASIS_POINTS_DENOMINATOR - BigInt(feeBasisPoints));
     const numerator = amountInWithFee * reserveOut;
-    const denominator = reserveIn * PULSEX_FEE_DENOMINATOR + amountInWithFee;
+    const denominator = reserveIn * BASIS_POINTS_DENOMINATOR + amountInWithFee;
     return numerator / denominator;
 };
 /**
@@ -220,9 +246,10 @@ const constantProductAmountOut = (amountIn, reserveIn, reserveOut) => {
  *
  * @param amountIn - the amount entering the first pool
  * @param steps - the pools in order of travel
+ * @param feeBasisPoints - the venue's swap fee in basis points; PulseX's 29 when omitted
  * @returns the amount leaving the last pool; 0 when any pool cannot pay out
  */
-export const amountOutAlongPath = (amountIn, steps) => steps.reduce((runningAmount, step) => constantProductAmountOut(runningAmount, step.reserveIn, step.reserveOut), amountIn);
+export const amountOutAlongPath = (amountIn, steps, feeBasisPoints = PULSEX_FEE_BASIS_POINTS) => steps.reduce((runningAmount, step) => constantProductAmountOut(runningAmount, step.reserveIn, step.reserveOut, feeBasisPoints), amountIn);
 /**
  * How far a trade's executed rate falls below the marginal (near-spot) rate,
  * in percent. The marginal rate is a tiny reference trade through the same
@@ -258,7 +285,7 @@ const poolKey = (tokenA, tokenB) => {
     return `${lower}|${higher}`;
 };
 /** The key one venue's pool is stored under: the same two tokens on V1 and on V2 are two different pools with two different reserves. */
-const venuePoolKey = (venue, tokenA, tokenB) => `${venue.factory.toLowerCase()}|${poolKey(tokenA, tokenB)}`;
+const venuePoolKey = (venue, tokenA, tokenB) => `${venue.chainId}|${venue.factory.toLowerCase()}|${poolKey(tokenA, tokenB)}`;
 /** Every consecutive (tokenIn, tokenOut) hop a PulseX swap path implies. */
 const hopsAlongPath = (path) => path.slice(0, -1).map((tokenIn, index) => [tokenIn, path[index + 1]]);
 /**
@@ -318,16 +345,36 @@ const stepsAlongPath = (options) => {
  */
 const preparePulseXReserves = async ({ nodes, venues, clientForChain, }) => {
     const reservesByPoolKey = new Map();
-    const client = clientForChain(pulsechainChainId);
-    if (client === null || venues.length === 0)
+    const chainIds = Object.keys(venues)
+        .map(Number)
+        .filter((chainId) => (venues[chainId] ?? []).length > 0);
+    for (const chainId of chainIds) {
+        const chainReserves = await preparePulseXReservesOnChain({ nodes, chainId, venues, clientForChain });
+        for (const [key, reserves] of chainReserves)
+            reservesByPoolKey.set(key, reserves);
+    }
+    return reservesByPoolKey;
+};
+/**
+ * One chain's share of {@link preparePulseXReserves}: two multicalls, the
+ * `getPair` reads and then the `getReserves` reads, over every venue of the
+ * chain. A chain with no client, or with no chain description to multicall
+ * against, reads nothing.
+ */
+const preparePulseXReservesOnChain = async ({ nodes, chainId, venues, clientForChain, }) => {
+    const reservesByPoolKey = new Map();
+    const client = clientForChain(chainId);
+    const knownChain = chainsMetadata[toChain(chainId)];
+    const chain = knownChain ?? client?.chain;
+    if (client === null || chain === undefined)
         return reservesByPoolKey;
-    const pulsechainNodes = nodes.filter((node) => node.ecosystem === 'evm' && node.chainId === pulsechainChainId);
+    const chainNodes = nodes.filter((node) => node.ecosystem === 'evm' && node.chainId === chainId);
     const poolTokenPairs = new Map();
-    for (const from of pulsechainNodes) {
-        for (const to of pulsechainNodes) {
+    for (const from of chainNodes) {
+        for (const to of chainNodes) {
             if (assetNodeKey(from) === assetNodeKey(to))
                 continue;
-            if (!pulseXCarries(from, to))
+            if (!pulseXCarries(venues, from, to))
                 continue;
             for (const path of pulseXCandidatePaths(from, to)) {
                 for (const [tokenIn, tokenOut] of hopsAlongPath(path)) {
@@ -338,14 +385,14 @@ const preparePulseXReserves = async ({ nodes, venues, clientForChain, }) => {
     }
     if (poolTokenPairs.size === 0)
         return reservesByPoolKey;
-    const poolQueries = venues.flatMap((venue) => Array.from(poolTokenPairs.values()).map(([tokenIn, tokenOut]) => ({
+    const poolQueries = (venues[chainId] ?? []).flatMap((venue) => Array.from(poolTokenPairs.values()).map(([tokenIn, tokenOut]) => ({
         key: venuePoolKey(venue, tokenIn, tokenOut),
         factory: venue.factory,
         tokenIn,
         tokenOut,
     })));
     const factoryResults = await multicallRead({
-        chain: chainsMetadata[toChain(pulsechainChainId)],
+        chain,
         client,
         abi: univ2FactoryAbi,
         calls: poolQueries.map((query) => ({
@@ -370,7 +417,7 @@ const preparePulseXReserves = async ({ nodes, venues, clientForChain, }) => {
         return reservesByPoolKey;
     const reservePoolKeys = Array.from(pairAddressByPoolKey.keys());
     const reserveResults = await multicallRead({
-        chain: chainsMetadata[toChain(pulsechainChainId)],
+        chain,
         client,
         abi: abis.pair,
         calls: reservePoolKeys.map((key) => ({
@@ -395,22 +442,24 @@ const preparePulseXReserves = async ({ nodes, venues, clientForChain, }) => {
     return reservesByPoolKey;
 };
 /**
- * The venues a carrier offers: every known venue, or only the routers the
- * host names. A named router that is not a known PulseX router is a
- * configuration error, thrown at construction rather than offered silently.
+ * The venues a carrier offers: every venue in `venues`, or only the routers
+ * the host names. A named router that is in no venue is a configuration
+ * error, thrown at construction rather than offered silently.
  *
+ * @param venues - the resolved venues
  * @param routers - the routers the host can sign on, or undefined for all
- * @returns the venues, in {@link pulseXVenues} order
+ * @returns the venues, in their original order
  */
-const selectPulseXVenues = (routers) => {
+const selectPulseXVenues = (venues, routers) => {
     if (routers === undefined)
-        return pulseXVenues;
+        return venues;
+    const named = (venue) => routers.some((router) => sameAddress(venue.router, router, 'evm'));
     for (const router of routers) {
-        if (!pulseXVenues.some((venue) => sameAddress(venue.router, router, 'evm'))) {
-            throw new Error(`createPulseXCarrier: ${router} is not a known PulseX router on PulseChain`);
-        }
+        const offered = Object.values(venues).some((list) => list.some((venue) => sameAddress(venue.router, router, 'evm')));
+        if (!offered)
+            throw new Error(`createPulseXCarrier: ${router} is not a known PulseX router in the offered swap venues`);
     }
-    return pulseXVenues.filter((venue) => routers.some((router) => sameAddress(venue.router, router, 'evm')));
+    return Object.freeze(Object.fromEntries(Object.entries(venues).map(([chainId, list]) => [chainId, list.filter(named)])));
 };
 /**
  * Builds the PulseX conversion swap as a plug-in carrier.
@@ -420,16 +469,16 @@ const selectPulseXVenues = (routers) => {
  */
 export const createPulseXCarrier = (options) => {
     const { readAmountOut, clientForChain } = options;
-    const venues = selectPulseXVenues(options.routers);
+    const venues = selectPulseXVenues(resolveSwapVenues(options.venues), options.routers);
     // ONE EDGE PER VENUE. Each names its router as its `venue`, so the search
     // quotes and ranks V1 and V2 as two separate hops and the better one wins
     // on its own figure — and the winner is signed on the router it names.
     const edgesFrom = (from, to) => {
         if (assetNodeKey(from) === assetNodeKey(to))
             return [];
-        if (!pulseXCarries(from, to))
+        if (!pulseXCarries(venues, from, to))
             return [];
-        return venues.map((venue) => ({
+        return (venues[from.chainId] ?? []).map((venue) => ({
             carrier: 'PulseX',
             from,
             to,
@@ -465,19 +514,19 @@ export const createPulseXCarrier = (options) => {
         reservesByPoolKey = await preparePulseXReserves({ nodes, venues, clientForChain });
     };
     const exact = (edge, amountIn) => {
-        if (!pulseXCarries(edge.from, edge.to))
+        if (!pulseXCarries(venues, edge.from, edge.to))
             return null;
         // Quoted on the edge's OWN venue — the router it will be signed on — and
         // only on a venue this carrier offers.
-        const venue = pulseXVenueForEdge(edge);
-        if (venue === null || !venues.includes(venue))
+        const venue = venueForEdge(venues, edge);
+        if (venue === null)
             return null;
         // EVERY CANDIDATE PATH IS PRICED, AND THE BEST ONE WINS. A path with a
         // pool `prepare` never found is left out — the same as a router call
         // that would revert — and a path that pays out nothing is never picked.
         const quotes = pulseXCandidatePaths(edge.from, edge.to).flatMap((path) => {
             const steps = stepsAlongPath({ venue, path, reservesByPoolKey });
-            return steps === null ? [] : [{ path, steps, deliveredAmount: amountOutAlongPath(amountIn, steps) }];
+            return steps === null ? [] : [{ path, steps, deliveredAmount: amountOutAlongPath(amountIn, steps, venue.feeBasisPoints) }];
         });
         // No path had every pool read — a structural non-answer, not a refusal
         // (`exact`'s own doc: `null` means "nothing to say"). NOTE THIS DOES NOT
@@ -497,7 +546,7 @@ export const createPulseXCarrier = (options) => {
             amountIn,
             amountOut: best.deliveredAmount,
             referenceAmountIn,
-            referenceAmountOut: amountOutAlongPath(referenceAmountIn, best.steps),
+            referenceAmountOut: amountOutAlongPath(referenceAmountIn, best.steps, venue.feeBasisPoints),
         });
         // The path rides on the answer, so the signer signs exactly what was
         // priced (`pulseXSwapPathForHop`). Impact is left off (not zero) when the

package/dist/routing/index.d.ts

@@ -8,12 +8,12 @@ export { netDeliveredAmount, restateInDecimals, valueEquivalentAmount } from './
 export { omnibridgeProviderForEntryChain, pulseXConversionSwapPath } from './providers.js';
 export { buildDirectCrossingCandidate } from './candidate.js';
 export type { RouteCandidate, DeferredCrossing, DirectCrossingCandidateInputs } from './candidate.js';
-export { buildRouteDataForCandidate, routeSignatureCount } from './candidate-route.js';
+export { buildRouteDataForCandidate, routeSignatureCount, routeSignatureCountForAccount, type RouteSignatureCount, } from './candidate-route.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,14 +24,18 @@ 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, pulseXRouterForEdge, pulseXSwapPathForHop, pulseXVenues, pulseXWrappedNativePath, } 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';

package/dist/routing/index.js

@@ -7,7 +7,7 @@
 export { netDeliveredAmount, restateInDecimals, valueEquivalentAmount } from './amounts.js';
 export { omnibridgeProviderForEntryChain, pulseXConversionSwapPath } from './providers.js';
 export { buildDirectCrossingCandidate } from './candidate.js';
-export { buildRouteDataForCandidate, routeSignatureCount } from './candidate-route.js';
+export { buildRouteDataForCandidate, routeSignatureCount, routeSignatureCountForAccount, } from './candidate-route.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';
@@ -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,8 +39,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, pulseXRouterForEdge, pulseXSwapPathForHop, pulseXVenues, pulseXWrappedNativePath, } 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.

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/plan-route-data.d.ts

@@ -3,7 +3,7 @@ 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';
 /**
@@ -141,6 +141,16 @@ export type PlanSectionPricing = {
      * 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. */
@@ -175,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. */