@gibs/bridge-sdk 1.13.1 → 1.18.0

package/dist/routing/carriers/pulsex.js

@@ -1,12 +1,14 @@
 import { multicallRead } from '@gibs/common/multicall';
-import { getAddress, parseAbi, zeroAddress } from 'viem';
+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';
+import { bestPulseXPathQuote, candidatePulseXPaths, pulseXHubTokens } from './pulsex-paths.js';
 /**
  * PulseX (the PulseChain-native decentralized exchange, used here for a
  * conversion swap leg) as a plug-in `Carrier` for `@gibs/quotes`'s
@@ -17,122 +19,187 @@ import { assetNodeKey } from '../search/graph.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 = nativeAssetOut[Chains.PLS];
+/** 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.
+ *
+ * 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) => {
+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
  * SAME rule, restated here because `prepare`/`exact` never go through the
- * UI's `readAmountOut` at all; see {@link pulseXPoolPath}'s own doc.
+ * 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 router swap path a PulseX hop from `from` to `to` prices and signs
- * along, or null when there is no swap for PulseX to do — including when
- * both ends resolve to the SAME pool token, which is true of PLS<->WPLS
- * (native PLS resolves to {@link wplsAddress} via {@link poolTokenAddress},
- * same as Wrapped PLS itself): that pair is the wrap carrier's job, never a
- * PulseX hop, so this returns null rather than a zero-length or self-paired
- * path.
+ * 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
+ * same pool token (PLS<->WPLS is the wrap carrier's job).
  *
- * EVERY PULSEX QUOTE AND SIGNATURE IN THIS FILE MUST GO THROUGH THIS ONE
- * FUNCTION — `pulseXCarries`, `prepare`'s pool discovery, and `exact`'s hop
- * pricing all call it, so native PLS resolves the same way in every one of
- * them. Before this existed, `pulseXCarries` and `prepare`/`exact` called
- * `pulseXConversionSwapPath` directly on the raw node address: a native PLS
- * node produced a path that LITERALLY STARTED WITH THE ZERO ADDRESS
- * (`[zeroAddress, wplsAddress, ...]`), which `pulseXCarries` accepted (its
- * length is still >= 2) but for which `prepare` could never find a pool —
- * the factory has no pair for the zero address — so `exact` always answered
- * `null` for a direct native-PLS PulseX hop, and `enumerate.ts` pruned it,
- * leaving only the two-signature wrap-then-swap path.
+ * NOT THE PATH A HOP IS SIGNED ALONG. The carrier's own `exact` picks the
+ * best of many paths ({@link candidatePulseXPaths}) and records the winner on
+ * the hop's outcome; the signer reads it back with {@link pulseXSwapPathForHop}.
+ * This fixed path serves only the carrier's asynchronous `ask` — the
+ * interface's `getAmountsOut` read, which the route search never calls for a
+ * PulseX hop, because the search only asks aggregators live.
+ *
+ * Native PLS resolves to WPLS first ({@link poolTokenAddress}), so a path
+ * never starts or ends on the zero address, which has no pool.
  *
  * @param from - the hop's origin node
  * @param to - the hop's destination node
- * @returns the swap path, or null when there is nothing for PulseX to swap
+ * @returns the fixed path, or null when there is nothing for PulseX to swap
  */
-export const pulseXPoolPath = (from, to) => {
+export const pulseXWrappedNativePath = (from, to) => {
     const fromAddress = poolTokenAddress(from);
     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
+ * when both ends resolve to the same pool token. EVERY PULSEX PRICE AND
+ * POOL READ IN THIS FILE GOES THROUGH THIS ONE FUNCTION, so `prepare` reads
+ * exactly the pools `exact` will look up, and native PLS resolves to WPLS
+ * the same way in both ({@link poolTokenAddress} — a path that started on
+ * the zero address once left every native-PLS hop unpriced).
+ *
+ * @param from - the hop's origin node
+ * @param to - the hop's destination node
+ * @returns the candidate paths, direct first; empty when there is nothing to swap
+ */
+const pulseXCandidatePaths = (from, to) => {
+    const fromAddress = poolTokenAddress(from);
+    const toAddress = poolTokenAddress(to);
+    if (sameAddress(fromAddress, toAddress, 'evm'))
+        return [];
+    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
- * distinct Ethereum-Virtual-Machine tokens on PulseChain itself — PulseX runs
- * only on PulseChain, never on an entry chain.
+ * 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: "any PulseChain token with a
- * {@link pulseXPoolPath}" is every PulseChain token, because that function
- * is total over any two addresses that do not resolve to the same pool
- * token — it collapses to a direct hop only when one side is already WPLS,
- * and otherwise always routes through WPLS. This calls it anyway and checks
- * the result is at least two addresses long, so a future change that
- * narrowed it to return an empty path for some input would fail this
- * predicate rather than silently offer a hop with no path.
+ * 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;
-    const swapPath = pulseXPoolPath(from, to);
-    return swapPath !== null && swapPath.length >= 2;
+    if ((venues[from.chainId] ?? []).length === 0)
+        return false;
+    return pulseXCandidatePaths(from, to).length > 0;
 };
 /**
- * PulseX's own constant-product swap fee, as a numerator over
- * {@link PULSEX_FEE_DENOMINATOR} — the SAME `getAmountOut` formula every
+ * The swap path a planned PulseX hop must be signed along: the path its
+ * outcome records ({@link HopOutcome.swapPath}), which is the path the
+ * carrier's `exact` priced the figure on. NEVER REBUILT HERE — rebuilding a
+ * path at signing time is how a quote on one path becomes a signature on
+ * another.
+ *
+ * The recorded path is checked against the hop's own edge before it is
+ * returned: it must start at the edge's input pool token, end at its output
+ * pool token, hold only addresses, and name no token twice. A path that fails
+ * any check is refused (null) rather than signed.
+ *
+ * @param hop - the planned hop to sign
+ * @returns the path to sign, or null when the hop is not a PulseX hop, records no path, or records one that does not fit its edge
+ */
+export const pulseXSwapPathForHop = (hop) => {
+    if (hop.edge.carrier !== 'PulseX')
+        return null;
+    const swapPath = hop.outcome.swapPath;
+    if (swapPath === undefined || swapPath.length < 2)
+        return null;
+    if (!swapPath.every((address) => isAddress(address, { strict: false })))
+        return null;
+    const path = swapPath.map((address) => getAddress(address));
+    if (new Set(path).size !== path.length)
+        return null;
+    if (!sameAddress(path[0], poolTokenAddress(hop.edge.from), 'evm'))
+        return null;
+    if (!sameAddress(path[path.length - 1], poolTokenAddress(hop.edge.to), 'evm'))
+        return null;
+    return path;
+};
+/**
+ * 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))`.
  *
@@ -145,16 +212,16 @@ const pulseXCarries = (from, to) => {
  * 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.
@@ -162,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;
 };
 /**
@@ -178,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
@@ -216,9 +285,35 @@ 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]]);
+/**
+ * The pools a path crosses on one venue, each read in the direction of
+ * travel, or null when any of them was never read — `getPair` found no pool,
+ * or the read failed. A path with a missing pool cannot be priced, exactly as
+ * the router's own `getAmountsOut` would revert on it.
+ *
+ * @param options.venue - the deployment whose pools the path trades against
+ * @param options.path - the tokens, in order
+ * @param options.reservesByPoolKey - every pool `prepare` read, keyed by {@link venuePoolKey}
+ * @returns the steps in order, or null when a pool is missing
+ */
+const stepsAlongPath = (options) => {
+    const { venue, path, reservesByPoolKey } = options;
+    const steps = [];
+    for (const [tokenIn, tokenOut] of hopsAlongPath(path)) {
+        const reserves = reservesByPoolKey.get(venuePoolKey(venue, tokenIn, tokenOut));
+        if (reserves === undefined)
+            return null;
+        const tokenInIsLower = tokenIn.toLowerCase() < tokenOut.toLowerCase();
+        steps.push({
+            reserveIn: tokenInIsLower ? reserves.reserveOfLowerAddress : reserves.reserveOfHigherAddress,
+            reserveOut: tokenInIsLower ? reserves.reserveOfHigherAddress : reserves.reserveOfLowerAddress,
+        });
+    }
+    return steps;
+};
 /**
  * Batch-reads reserves for every pool `nodes`' candidate PulseX paths touch,
  * on EVERY venue in `venues`, once, so {@link createPulseXCarrier}'s `exact`
@@ -235,6 +330,14 @@ const hopsAlongPath = (path) => path.slice(0, -1).map((tokenIn, index) => [token
  * the second read cannot join the first — but every venue's `getPair` rides
  * the first multicall and every pool's `getReserves` rides the second.
  *
+ * THE HUB SEARCH WIDENS EACH READ, NOT THEIR NUMBER. Every pool any candidate
+ * path crosses is read here ({@link pulseXCandidatePaths}), so `exact` can
+ * price every path with no further call. Measured 2026-10-06: an 8-token
+ * PulseChain universe asked 84 entries across the two reads (the fixed
+ * Wrapped-PLS path asked about 16). The shared multicall helper splits a read
+ * past its request-size budget into sequential posts; `getPair` crosses that
+ * line at about 11 pool tokens (198 entries over two venues).
+ *
  * @param nodes - every node the search might branch through
  * @param venues - the venues this carrier offers
  * @param clientForChain - see {@link CreatePulseXCarrierOptions}'s own field
@@ -242,35 +345,54 @@ const hopsAlongPath = (path) => path.slice(0, -1).map((tokenIn, index) => [token
  */
 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))
-                continue;
-            const path = pulseXPoolPath(from, to);
-            if (path === null)
+            if (!pulseXCarries(venues, from, to))
                 continue;
-            for (const [tokenIn, tokenOut] of hopsAlongPath(path)) {
-                poolTokenPairs.set(poolKey(tokenIn, tokenOut), [tokenIn, tokenOut]);
+            for (const path of pulseXCandidatePaths(from, to)) {
+                for (const [tokenIn, tokenOut] of hopsAlongPath(path)) {
+                    poolTokenPairs.set(poolKey(tokenIn, tokenOut), [tokenIn, tokenOut]);
+                }
             }
         }
     }
     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) => ({
@@ -295,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) => ({
@@ -320,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.
@@ -345,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,
@@ -390,51 +514,46 @@ 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;
-        const path = pulseXPoolPath(edge.from, edge.to);
-        if (path === null)
-            return null;
-        const hops = hopsAlongPath(path);
-        if (hops.length === 0)
+        // 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, 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
+        // FALL BACK TO AN ESTIMATE: a carrier with `exact` defined never yields
+        // an `'estimate'` outcome (see `enumerate.ts`'s `resolveHopOutcome`,
+        // branch 1) — `null` here PRUNES the hop entirely, the same as a refusal.
+        if (quotes.length === 0)
             return null;
-        const steps = [];
-        for (const [tokenIn, tokenOut] of hops) {
-            const reserves = reservesByPoolKey.get(venuePoolKey(venue, tokenIn, tokenOut));
-            // `prepare` never read this pool — a structural non-answer, not a
-            // refusal (`exact`'s own doc: `null` means "nothing to say"). NOTE
-            // THIS DOES NOT FALL BACK TO AN ESTIMATE: a carrier with `exact`
-            // defined never yields an `'estimate'` outcome (see
-            // `enumerate.ts`'s `resolveHopOutcome`, branch 1) — `null` here
-            // PRUNES the hop entirely, the same as a refusal.
-            if (reserves === undefined)
-                return null;
-            const tokenInIsLower = tokenIn.toLowerCase() < tokenOut.toLowerCase();
-            steps.push({
-                reserveIn: tokenInIsLower ? reserves.reserveOfLowerAddress : reserves.reserveOfHigherAddress,
-                reserveOut: tokenInIsLower ? reserves.reserveOfHigherAddress : reserves.reserveOfLowerAddress,
-            });
-        }
-        const deliveredAmount = amountOutAlongPath(amountIn, steps);
-        if (deliveredAmount <= 0n) {
+        const best = bestPulseXPathQuote(quotes);
+        if (best === null) {
             return { outcome: 'refused', refusal: { kind: 'no-quote', reason: 'no liquidity on this PulseX path', minimumAmount: null } };
         }
+        // Price impact is measured on the CHOSEN path's own pools, with the same
+        // reference trade as before.
+        const referenceAmountIn = amountIn / PULSEX_MARGINAL_REFERENCE_DIVISOR;
         const priceImpactPercent = priceImpactAgainstMarginal({
             amountIn,
-            amountOut: deliveredAmount,
-            referenceAmountIn: amountIn / PULSEX_MARGINAL_REFERENCE_DIVISOR,
-            referenceAmountOut: amountOutAlongPath(amountIn / PULSEX_MARGINAL_REFERENCE_DIVISOR, steps),
+            amountOut: best.deliveredAmount,
+            referenceAmountIn,
+            referenceAmountOut: amountOutAlongPath(referenceAmountIn, best.steps, venue.feeBasisPoints),
         });
-        // Left off (not zero) when the reference trade rounds away: an unknown
-        // impact must stay unknown so the quality gate withholds the plan.
-        return priceImpactPercent === null
-            ? { outcome: 'delivered', deliveredAmount }
-            : { outcome: 'delivered', deliveredAmount, priceImpactPercent };
+        // The path rides on the answer, so the signer signs exactly what was
+        // priced (`pulseXSwapPathForHop`). Impact is left off (not zero) when the
+        // reference trade rounds away: an unknown impact must stay unknown so the
+        // quality gate withholds the plan.
+        const delivered = { outcome: 'delivered', deliveredAmount: best.deliveredAmount, swapPath: best.path };
+        return priceImpactPercent === null ? delivered : { ...delivered, priceImpactPercent };
     };
     return {
         id: 'PulseX',