@gibs/bridge-sdk 1.17.0 → 1.19.0

package/dist/cjs/routing/carriers/pulsex.js

@@ -33,13 +33,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createPulseXCarrier = exports.priceImpactAgainstMarginal = exports.amountOutAlongPath = exports.pulseXSwapPathForHop = exports.pulseXWrappedNativePath = exports.pulseXRouterForEdge = exports.pulseXVenues = void 0;
+exports.createPulseXCarrier = exports.priceImpactAgainstMarginal = exports.amountOutAlongPath = exports.pulseXSwapPathForHop = exports.pulseXWrappedNativePath = exports.pulseXRouterForEdge = exports.venueForEdge = exports.pulseXVenues = void 0;
 const multicall_1 = require("@gibs/common/multicall");
 const viem_1 = require("viem");
 const abis = __importStar(require("../../abis.js"));
 const chains_js_1 = require("../../chains.js");
 const config_js_1 = require("../../config.js");
 const ecosystems_js_1 = require("../../ecosystems.js");
+const swap_venues_js_1 = require("../../swap-venues.js");
 const providers_js_1 = require("../providers.js");
 const producers_js_1 = require("../producers.js");
 const graph_js_1 = require("../search/graph.js");
@@ -54,58 +55,75 @@ const pulsex_paths_js_1 = require("./pulsex-paths.js");
  * 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 = config_js_1.nativeAssetOut[config_js_1.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 = pulsex_paths_js_1.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
  */
-exports.pulseXVenues = (config_js_1.uniV2Routers[config_js_1.Chains.PLS] ?? []).flatMap((router, index) => {
-    const factory = config_js_1.uniV2Factories[config_js_1.Chains.PLS]?.[index];
-    return factory === undefined ? [] : [{ router: (0, viem_1.getAddress)(router), factory: (0, viem_1.getAddress)(factory) }];
-});
+const wrappedNativeFor = (chainId) => {
+    const wrapped = config_js_1.nativeAssetOut[(0, config_js_1.toChain)(chainId)];
+    return wrapped === undefined ? undefined : (0, viem_1.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 = exports.pulseXVenues[0];
+const hubsFor = (chainId) => {
+    if (chainId === producers_js_1.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.
  */
-const pulseXRouterForEdge = (edge) => pulseXVenueForEdge(edge)?.router ?? null;
-exports.pulseXRouterForEdge = pulseXRouterForEdge;
+exports.pulseXVenues = config_js_1.defaultSwapVenues[producers_js_1.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.
+ *
+ * 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 edge - the edge
- * @returns the venue, or null when there is none
+ * @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) => {
+const venueForEdge = (venues, edge) => {
     if (edge.carrier !== 'PulseX')
         return null;
+    const chainId = edge.from?.chainId ?? producers_js_1.pulsechainChainId;
     if (edge.venue === undefined)
-        return defaultPulseXVenue ?? null;
-    const venue = edge.venue;
-    return exports.pulseXVenues.find((candidate) => (0, ecosystems_js_1.sameAddress)(candidate.router, venue, 'evm')) ?? null;
+        return venues[chainId]?.[0] ?? null;
+    return (0, swap_venues_js_1.findSwapVenue)(venues, chainId, edge.venue);
 };
+exports.venueForEdge = venueForEdge;
 /**
- * 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
+ */
+const pulseXRouterForEdge = (edge) => (0, exports.venueForEdge)(config_js_1.defaultSwapVenues, edge)?.router ?? null;
+exports.pulseXRouterForEdge = pulseXRouterForEdge;
+/**
+ * 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
@@ -113,9 +131,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) => ((0, ecosystems_js_1.sameAddress)(node.address, viem_1.zeroAddress, 'evm') ? wplsAddress : node.address);
+const poolTokenAddress = (node) => (0, ecosystems_js_1.sameAddress)(node.address, viem_1.zeroAddress, 'evm') ? (wrappedNativeFor(node.chainId) ?? viem_1.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
@@ -140,7 +158,8 @@ const pulseXWrappedNativePath = (from, to) => {
     const toAddress = poolTokenAddress(to);
     if ((0, ecosystems_js_1.sameAddress)(fromAddress, toAddress, 'evm'))
         return null;
-    return (0, providers_js_1.pulseXConversionSwapPath)(fromAddress, toAddress, wplsAddress);
+    const wrappedNative = wrappedNativeFor(from.chainId);
+    return wrappedNative === undefined ? [fromAddress, toAddress] : (0, providers_js_1.pulseXConversionSwapPath)(fromAddress, toAddress, wrappedNative);
 };
 exports.pulseXWrappedNativePath = pulseXWrappedNativePath;
 /**
@@ -160,21 +179,27 @@ const pulseXCandidatePaths = (from, to) => {
     const toAddress = poolTokenAddress(to);
     if ((0, ecosystems_js_1.sameAddress)(fromAddress, toAddress, 'evm'))
         return [];
-    return (0, pulsex_paths_js_1.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 (0, pulsex_paths_js_1.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 !== producers_js_1.pulsechainChainId || to.chainId !== producers_js_1.pulsechainChainId)
+    if (from.chainId !== to.chainId)
+        return false;
+    if ((venues[from.chainId] ?? []).length === 0)
         return false;
     return pulseXCandidatePaths(from, to).length > 0;
 };
@@ -212,8 +237,9 @@ const pulseXSwapPathForHop = (hop) => {
 };
 exports.pulseXSwapPathForHop = pulseXSwapPathForHop;
 /**
- * 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))`.
  *
@@ -226,16 +252,16 @@ exports.pulseXSwapPathForHop = pulseXSwapPathForHop;
  * 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 = (0, viem_1.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.
@@ -243,14 +269,15 @@ const univ2FactoryAbi = (0, viem_1.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;
 };
 /**
@@ -259,9 +286,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
  */
-const amountOutAlongPath = (amountIn, steps) => steps.reduce((runningAmount, step) => constantProductAmountOut(runningAmount, step.reserveIn, step.reserveOut), amountIn);
+const amountOutAlongPath = (amountIn, steps, feeBasisPoints = PULSEX_FEE_BASIS_POINTS) => steps.reduce((runningAmount, step) => constantProductAmountOut(runningAmount, step.reserveIn, step.reserveOut, feeBasisPoints), amountIn);
 exports.amountOutAlongPath = amountOutAlongPath;
 /**
  * How far a trade's executed rate falls below the marginal (near-spot) rate,
@@ -299,7 +327,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]]);
 /**
@@ -359,16 +387,36 @@ const stepsAlongPath = (options) => {
  */
 const preparePulseXReserves = async ({ nodes, venues, clientForChain, }) => {
     const reservesByPoolKey = new Map();
-    const client = clientForChain(producers_js_1.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 = chains_js_1.chainsMetadata[(0, config_js_1.toChain)(chainId)];
+    const chain = knownChain ?? client?.chain;
+    if (client === null || chain === undefined)
         return reservesByPoolKey;
-    const pulsechainNodes = nodes.filter((node) => node.ecosystem === 'evm' && node.chainId === producers_js_1.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 ((0, graph_js_1.assetNodeKey)(from) === (0, graph_js_1.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)) {
@@ -379,14 +427,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 (0, multicall_1.multicallRead)({
-        chain: chains_js_1.chainsMetadata[(0, config_js_1.toChain)(producers_js_1.pulsechainChainId)],
+        chain,
         client,
         abi: univ2FactoryAbi,
         calls: poolQueries.map((query) => ({
@@ -411,7 +459,7 @@ const preparePulseXReserves = async ({ nodes, venues, clientForChain, }) => {
         return reservesByPoolKey;
     const reservePoolKeys = Array.from(pairAddressByPoolKey.keys());
     const reserveResults = await (0, multicall_1.multicallRead)({
-        chain: chains_js_1.chainsMetadata[(0, config_js_1.toChain)(producers_js_1.pulsechainChainId)],
+        chain,
         client,
         abi: abis.pair,
         calls: reservePoolKeys.map((key) => ({
@@ -436,22 +484,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 exports.pulseXVenues;
+        return venues;
+    const named = (venue) => routers.some((router) => (0, ecosystems_js_1.sameAddress)(venue.router, router, 'evm'));
     for (const router of routers) {
-        if (!exports.pulseXVenues.some((venue) => (0, ecosystems_js_1.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) => (0, ecosystems_js_1.sameAddress)(venue.router, router, 'evm')));
+        if (!offered)
+            throw new Error(`createPulseXCarrier: ${router} is not a known PulseX router in the offered swap venues`);
     }
-    return exports.pulseXVenues.filter((venue) => routers.some((router) => (0, ecosystems_js_1.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.
@@ -461,16 +511,16 @@ const selectPulseXVenues = (routers) => {
  */
 const createPulseXCarrier = (options) => {
     const { readAmountOut, clientForChain } = options;
-    const venues = selectPulseXVenues(options.routers);
+    const venues = selectPulseXVenues((0, swap_venues_js_1.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 ((0, graph_js_1.assetNodeKey)(from) === (0, graph_js_1.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,
@@ -506,19 +556,19 @@ 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 = (0, exports.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: (0, exports.amountOutAlongPath)(amountIn, steps) }];
+            return steps === null ? [] : [{ path, steps, deliveredAmount: (0, exports.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
@@ -538,7 +588,7 @@ const createPulseXCarrier = (options) => {
             amountIn,
             amountOut: best.deliveredAmount,
             referenceAmountIn,
-            referenceAmountOut: (0, exports.amountOutAlongPath)(referenceAmountIn, best.steps),
+            referenceAmountOut: (0, exports.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/cjs/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/cjs/routing/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.composeRouteDelivery = exports.composableHopBasis = exports.routePlanPathKey = exports.planIsRankable = exports.planIsConfirmed = exports.planComposedBasis = exports.isRateLimitedCarrier = exports.isRankableBasis = exports.isConfirmedBasis = exports.hopEdgeKey = exports.hopComposedBasis = exports.groupHopsBySignature = exports.compareRoutePlansByDeliveredAmount = exports.combineComposedPathBasis = exports.assetNodeKey = exports.RANKABLE_ESTIMATE_BASES = exports.candidatePaidUsd = exports.candidateOutsideFeesUsd = exports.candidateNetValueUsd = exports.candidateDeliveredUsd = exports.buildSameChainSwapRouteData = exports.buildOutboundRouteData = exports.buildPulseXSwapSectionData = exports.buildPulseXSwapEstimateData = exports.buildDirectRouteData = exports.buildConversionRouteData = exports.buildCandidateRouteData = exports.resolveEntryChainName = exports.providerDisplayName = exports.addUsdValues = exports.pulsechainChainId = exports.PULSEX_MARGINAL_REFERENCE_DIVISOR = exports.BRIDGE_SETTLEMENT_ETA_MINUTES = exports.formatUsdNullable = exports.formatUsd = exports.usdValueOfAmount = exports.entryChainAnchorsForPair = exports.composedRouteMayBeOffered = exports.assessComposedRoute = exports.COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT = exports.COMPOSED_ROUTE_MAX_VALUE_GAIN_PERCENT = exports.COMPOSED_ROUTE_MAX_PRICE_IMPACT_PERCENT = exports.routeSignatureCount = exports.buildRouteDataForCandidate = exports.buildDirectCrossingCandidate = exports.pulseXConversionSwapPath = exports.omnibridgeProviderForEntryChain = exports.valueEquivalentAmount = exports.restateInDecimals = exports.netDeliveredAmount = void 0;
-exports.swapMinimumOut = exports.buildWrapTransaction = exports.buildPulseXSwapTransaction = exports.createWrapCarrier = exports.pulseXHubTokens = exports.candidatePulseXPaths = exports.bestPulseXPathQuote = exports.pulseXWrappedNativePath = exports.pulseXVenues = exports.pulseXSwapPathForHop = exports.pulseXRouterForEdge = exports.createPulseXCarrier = exports.withOmnibridgeEntryFusing = exports.createOmnibridgeCarrier = exports.derivePlanKind = exports.deriveViaChainIdsFromPlan = exports.deriveOmnibridgeProviderFromPlan = exports.deriveEntryChainIdFromPlan = exports.deriveDeferredCrossingFromPlan = exports.buildRouteScoreInputsFromPlan = exports.buildRouteDataFromPlan = exports.buildRouteCandidateFromPlan = exports.zeroGasCostFor = exports.waitPenaltyPpm = exports.sectionIsFundedByLanding = exports.scoreRoutePlan = exports.gasAdjustedDeliveredAmount = exports.compareRoutePlansByScoreAdjustedDeliveredAmount = exports.compareRoutePlansByGasAdjustedDeliveredAmount = exports.SIGNATURE_PENALTY_PPM = exports.SIGNATURE_PENALTY_FLOOR_USD = exports.GAS_TOPUP_PENALTY_PPM = exports.GAS_TOPUP_PENALTY_FLOOR_USD = exports.hopOutputAmount = void 0;
+exports.composableHopBasis = exports.routePlanPathKey = exports.planIsRankable = exports.planIsConfirmed = exports.planComposedBasis = exports.isRateLimitedCarrier = exports.isRankableBasis = exports.isConfirmedBasis = exports.hopEdgeKey = exports.hopComposedBasis = exports.groupHopsBySignature = exports.compareRoutePlansByDeliveredAmount = exports.combineComposedPathBasis = exports.assetNodeKey = exports.RANKABLE_ESTIMATE_BASES = exports.candidatePaidUsd = exports.candidateOutsideFeesUsd = exports.candidateNetValueUsd = exports.candidateDeliveredUsd = exports.buildSameChainSwapRouteData = exports.buildOutboundRouteData = exports.buildPulseXSwapSectionData = exports.buildPulseXSwapEstimateData = exports.buildDirectRouteData = exports.buildConversionRouteData = exports.buildCandidateRouteData = exports.resolveEntryChainName = exports.providerDisplayName = exports.addUsdValues = exports.pulsechainChainId = exports.PULSEX_MARGINAL_REFERENCE_DIVISOR = exports.BRIDGE_SETTLEMENT_ETA_MINUTES = exports.formatUsdNullable = exports.formatUsd = exports.usdValueOfAmount = exports.entryChainAnchorsForPair = exports.composedRouteMayBeOffered = exports.assessComposedRoute = exports.COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT = exports.COMPOSED_ROUTE_MAX_VALUE_GAIN_PERCENT = exports.COMPOSED_ROUTE_MAX_PRICE_IMPACT_PERCENT = exports.routeSignatureCountForAccount = exports.routeSignatureCount = exports.buildRouteDataForCandidate = exports.buildDirectCrossingCandidate = exports.pulseXConversionSwapPath = exports.omnibridgeProviderForEntryChain = exports.valueEquivalentAmount = exports.restateInDecimals = exports.netDeliveredAmount = void 0;
+exports.swapMinimumOut = exports.buildWrapTransaction = exports.buildPulseXSwapTransaction = exports.createWrapCarrier = exports.resolveSwapVenues = exports.findSwapVenue = exports.pulseXHubTokens = exports.candidatePulseXPaths = exports.bestPulseXPathQuote = exports.pulseXWrappedNativePath = exports.pulseXVenues = exports.pulseXSwapPathForHop = exports.venueForEdge = exports.pulseXRouterForEdge = exports.createPulseXCarrier = exports.withOmnibridgeEntryFusing = exports.createOmnibridgeCarrier = exports.derivePlanKind = exports.deriveViaChainIdsFromPlan = exports.deriveOmnibridgeProviderFromPlan = exports.deriveEntryChainIdFromPlan = exports.deriveDeferredCrossingFromPlan = exports.buildRouteScoreInputsFromPlan = exports.buildRouteDataFromPlan = exports.buildRouteCandidateFromPlan = exports.carrierStepKind = exports.carrierProviderKey = exports.WRAP_CARRIER_ID = exports.zeroGasCostFor = exports.waitPenaltyPpm = exports.sectionIsFundedByLanding = exports.scoreRoutePlan = exports.gasAdjustedDeliveredAmount = exports.compareRoutePlansByScoreAdjustedDeliveredAmount = exports.compareRoutePlansByGasAdjustedDeliveredAmount = exports.SIGNATURE_PENALTY_PPM = exports.SIGNATURE_PENALTY_FLOOR_USD = exports.GAS_TOPUP_PENALTY_PPM = exports.GAS_TOPUP_PENALTY_FLOOR_USD = exports.hopOutputAmount = exports.composeRouteDelivery = void 0;
 /**
  * Framework-agnostic routing core for the Gibs bridge. Holds the raw numeric
  * primitives, the candidate shape, and candidate construction — none of which
@@ -20,6 +20,7 @@ Object.defineProperty(exports, "buildDirectCrossingCandidate", { enumerable: tru
 var candidate_route_js_1 = require("./candidate-route.js");
 Object.defineProperty(exports, "buildRouteDataForCandidate", { enumerable: true, get: function () { return candidate_route_js_1.buildRouteDataForCandidate; } });
 Object.defineProperty(exports, "routeSignatureCount", { enumerable: true, get: function () { return candidate_route_js_1.routeSignatureCount; } });
+Object.defineProperty(exports, "routeSignatureCountForAccount", { enumerable: true, get: function () { return candidate_route_js_1.routeSignatureCountForAccount; } });
 var composed_route_quality_js_1 = require("./composed-route-quality.js");
 Object.defineProperty(exports, "COMPOSED_ROUTE_MAX_PRICE_IMPACT_PERCENT", { enumerable: true, get: function () { return composed_route_quality_js_1.COMPOSED_ROUTE_MAX_PRICE_IMPACT_PERCENT; } });
 Object.defineProperty(exports, "COMPOSED_ROUTE_MAX_VALUE_GAIN_PERCENT", { enumerable: true, get: function () { return composed_route_quality_js_1.COMPOSED_ROUTE_MAX_VALUE_GAIN_PERCENT; } });
@@ -92,6 +93,10 @@ Object.defineProperty(exports, "scoreRoutePlan", { enumerable: true, get: functi
 Object.defineProperty(exports, "sectionIsFundedByLanding", { enumerable: true, get: function () { return score_js_1.sectionIsFundedByLanding; } });
 Object.defineProperty(exports, "waitPenaltyPpm", { enumerable: true, get: function () { return score_js_1.waitPenaltyPpm; } });
 Object.defineProperty(exports, "zeroGasCostFor", { enumerable: true, get: function () { return score_js_1.zeroGasCostFor; } });
+var carrier_provider_key_js_1 = require("./carrier-provider-key.js");
+Object.defineProperty(exports, "WRAP_CARRIER_ID", { enumerable: true, get: function () { return carrier_provider_key_js_1.WRAP_CARRIER_ID; } });
+Object.defineProperty(exports, "carrierProviderKey", { enumerable: true, get: function () { return carrier_provider_key_js_1.carrierProviderKey; } });
+Object.defineProperty(exports, "carrierStepKind", { enumerable: true, get: function () { return carrier_provider_key_js_1.carrierStepKind; } });
 // 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.
@@ -117,6 +122,7 @@ Object.defineProperty(exports, "withOmnibridgeEntryFusing", { enumerable: true,
 var pulsex_js_1 = require("./carriers/pulsex.js");
 Object.defineProperty(exports, "createPulseXCarrier", { enumerable: true, get: function () { return pulsex_js_1.createPulseXCarrier; } });
 Object.defineProperty(exports, "pulseXRouterForEdge", { enumerable: true, get: function () { return pulsex_js_1.pulseXRouterForEdge; } });
+Object.defineProperty(exports, "venueForEdge", { enumerable: true, get: function () { return pulsex_js_1.venueForEdge; } });
 Object.defineProperty(exports, "pulseXSwapPathForHop", { enumerable: true, get: function () { return pulsex_js_1.pulseXSwapPathForHop; } });
 Object.defineProperty(exports, "pulseXVenues", { enumerable: true, get: function () { return pulsex_js_1.pulseXVenues; } });
 Object.defineProperty(exports, "pulseXWrappedNativePath", { enumerable: true, get: function () { return pulsex_js_1.pulseXWrappedNativePath; } });
@@ -124,6 +130,9 @@ var pulsex_paths_js_1 = require("./carriers/pulsex-paths.js");
 Object.defineProperty(exports, "bestPulseXPathQuote", { enumerable: true, get: function () { return pulsex_paths_js_1.bestPulseXPathQuote; } });
 Object.defineProperty(exports, "candidatePulseXPaths", { enumerable: true, get: function () { return pulsex_paths_js_1.candidatePulseXPaths; } });
 Object.defineProperty(exports, "pulseXHubTokens", { enumerable: true, get: function () { return pulsex_paths_js_1.pulseXHubTokens; } });
+var swap_venues_js_1 = require("../swap-venues.js");
+Object.defineProperty(exports, "findSwapVenue", { enumerable: true, get: function () { return swap_venues_js_1.findSwapVenue; } });
+Object.defineProperty(exports, "resolveSwapVenues", { enumerable: true, get: function () { return swap_venues_js_1.resolveSwapVenues; } });
 var wrap_js_1 = require("./carriers/wrap.js");
 Object.defineProperty(exports, "createWrapCarrier", { enumerable: true, get: function () { return wrap_js_1.createWrapCarrier; } });
 // The same-chain swap and wrap builders. The interface's section signing and

package/dist/cjs/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. */