@gibs/bridge-sdk 1.13.1 → 1.17.0

package/dist/routing/carriers/pulsex-split.js

@@ -0,0 +1,185 @@
+import { PULSEX_MARGINAL_REFERENCE_DIVISOR } from '../producers.js';
+import { amountOutAlongPath, priceImpactAgainstMarginal } from './pulsex.js';
+/**
+ * How many equal chunks the search divides the trade into: 20, so legs move
+ * in 5% steps. Finer steps buy a little output for proportionally more work.
+ */
+export const PULSEX_SPLIT_CHUNKS = 20;
+/** The most legs one split may have. Each leg is one more router call to sign or batch, and one more swap's gas. */
+export const PULSEX_SPLIT_MAX_LEGS = 3;
+/** How many candidate paths, best single-path output first, the search may spread the trade over. */
+export const PULSEX_SPLIT_CANDIDATE_LIMIT = 4;
+/**
+ * The gain a split must show over the best single path before it is chosen,
+ * in basis points of the single path's output: 25, or 0.25%.
+ *
+ * GAS IS REAL. Each extra leg costs roughly one more swap's gas, and a
+ * batching contract adds its own overhead. A split that wins by a rounding
+ * margin buys the reader nothing but a larger fee. The figure is a judgement,
+ * not a measurement; revisit it once an execution path has a real gas cost.
+ */
+export const PULSEX_SPLIT_MINIMUM_GAIN_BASIS_POINTS = 25n;
+const BASIS_POINTS = 10000n;
+/** The key one token's reserve in one pool is held under while a split executes. */
+const reserveKey = (pool, token) => `${pool}|${token.toLowerCase()}`;
+/**
+ * Executes legs one after another against shared pool state, exactly as
+ * sequential router calls would. A leg that crosses a pool an earlier leg
+ * already traded sees that pool's moved reserves, in whichever direction the
+ * earlier leg traded it.
+ *
+ * Each trade adds its full input to the pool and removes its output, the
+ * Uniswap-V2 accounting. See the open risk in the report: if PulseX moves
+ * part of its fee out of the pool during a swap, a shared pool is a few
+ * hundredths of a percent shallower here than on chain.
+ *
+ * @param legs - each candidate with the amount it spends, in execution order
+ * @returns what each leg delivers, in the same order
+ */
+export const executePulseXSplitInOrder = (legs) => {
+    const reserves = new Map();
+    const reserveOf = (pool, token, initial) => reserves.get(reserveKey(pool, token)) ?? initial;
+    return legs.map(({ candidate, amountIn }) => candidate.steps.reduce((runningAmount, step) => {
+        const reserveIn = reserveOf(step.pool, step.tokenIn, step.reserveIn);
+        const reserveOut = reserveOf(step.pool, step.tokenOut, step.reserveOut);
+        const amountOut = amountOutAlongPath(runningAmount, [{ reserveIn, reserveOut }]);
+        reserves.set(reserveKey(step.pool, step.tokenIn), reserveIn + runningAmount);
+        reserves.set(reserveKey(step.pool, step.tokenOut), reserveOut - amountOut);
+        return amountOut;
+    }, amountIn));
+};
+/** What one candidate alone delivers for the whole trade. */
+const singlePathOutput = (candidate, amountIn) => executePulseXSplitInOrder([{ candidate, amountIn }])[0] ?? 0n;
+/**
+ * The candidates a split may use: the {@link PULSEX_SPLIT_CANDIDATE_LIMIT}
+ * best by single-path output for the whole trade. A candidate that delivers
+ * nothing is dropped. Ties go to the shorter path, then the earlier
+ * candidate, so the ranking is deterministic.
+ *
+ * @param candidates - every priced path, on every venue
+ * @param amountIn - the whole trade
+ * @returns the ranked candidates, best first, each with its single-path output
+ */
+export const rankPulseXSplitCandidates = (candidates, amountIn) => candidates
+    .map((candidate, index) => ({ candidate, index, deliveredAmount: singlePathOutput(candidate, amountIn) }))
+    .filter((ranked) => ranked.deliveredAmount > 0n)
+    .sort((left, right) => {
+    if (left.deliveredAmount !== right.deliveredAmount)
+        return left.deliveredAmount > right.deliveredAmount ? -1 : 1;
+    if (left.candidate.path.length !== right.candidate.path.length)
+        return left.candidate.path.length - right.candidate.path.length;
+    return left.index - right.index;
+})
+    .slice(0, PULSEX_SPLIT_CANDIDATE_LIMIT)
+    .map(({ candidate, deliveredAmount }) => ({ candidate, deliveredAmount }));
+/** The trade divided into {@link PULSEX_SPLIT_CHUNKS} chunks; the last one takes the remainder, so the chunks sum to the trade exactly. */
+const chunksOf = (amountIn) => {
+    const count = BigInt(PULSEX_SPLIT_CHUNKS);
+    const chunk = amountIn / count;
+    return Array.from({ length: PULSEX_SPLIT_CHUNKS }, (_, index) => index === PULSEX_SPLIT_CHUNKS - 1 ? amountIn - chunk * (count - 1n) : chunk);
+};
+/** Each candidate with a positive allocation, in candidate order — the order the legs execute in. */
+const legsOf = (candidates, allocation) => candidates.flatMap((candidate, index) => {
+    const amountIn = allocation[index] ?? 0n;
+    return amountIn > 0n ? [{ candidate, amountIn }] : [];
+});
+/** What an allocation delivers in total, executed in candidate order. */
+const allocationOutput = (candidates, allocation) => executePulseXSplitInOrder(legsOf(candidates, allocation)).reduce((total, amount) => total + amount, 0n);
+/**
+ * Spreads a trade over ranked candidates, one chunk at a time. Each chunk goes
+ * to the candidate whose share, once raised by that chunk, makes the WHOLE
+ * split deliver the most — the split is re-executed in full each time
+ * ({@link executePulseXSplitInOrder}), so a shared pool is always priced with
+ * the reserves every leg leaves behind. A candidate not yet used is skipped
+ * once {@link PULSEX_SPLIT_MAX_LEGS} legs exist. Ties go to the earlier
+ * candidate.
+ *
+ * BOUNDED AND DETERMINISTIC. Work per quote is at most
+ * `PULSEX_SPLIT_CHUNKS × PULSEX_SPLIT_CANDIDATE_LIMIT` full executions (80),
+ * each of at most `PULSEX_SPLIT_MAX_LEGS` legs of at most three pools: under
+ * 750 constant-product evaluations, no network call.
+ *
+ * On pools that share nothing, each candidate's output is concave in its
+ * share, so this greedy fill reaches the best allocation on the chunk grid.
+ * Shared pools break that guarantee; {@link bestPulseXSplitQuote} still never
+ * returns a split worse than the best single path.
+ *
+ * @param candidates - ranked candidates, best first
+ * @param amountIn - the whole trade
+ * @returns the share of the trade each candidate spends, in candidate order
+ */
+export const allocatePulseXSplit = (candidates, amountIn) => chunksOf(amountIn).reduce((allocation, chunk) => {
+    const usedLegs = allocation.filter((amount) => amount > 0n).length;
+    const trials = candidates.flatMap((_, index) => {
+        const unused = (allocation[index] ?? 0n) === 0n;
+        if (unused && usedLegs >= PULSEX_SPLIT_MAX_LEGS)
+            return [];
+        const trial = allocation.map((amount, trialIndex) => (trialIndex === index ? amount + chunk : amount));
+        return [{ trial, output: allocationOutput(candidates, trial) }];
+    });
+    const best = trials.reduce((leader, entry) => (leader === null || entry.output > leader.output ? entry : leader), null);
+    return best === null ? allocation : best.trial;
+}, candidates.map(() => 0n));
+/**
+ * Price impact of a combined trade, in percent, measured with the same
+ * reference size the single-path figure uses
+ * (`amountIn / PULSEX_MARGINAL_REFERENCE_DIVISOR`).
+ *
+ * THE REFERENCE IS THE BEST MARGINAL RATE OF ANY CANDIDATE, not a blend of
+ * the legs' own rates. A split that leans on a path with a worse spot price
+ * pays for that, and the figure shows it. A blend would hide it.
+ *
+ * @param options.candidates - every ranked candidate
+ * @param options.amountIn - the whole trade
+ * @param options.deliveredAmount - what the combined trade delivers
+ * @returns the impact in percent, or null when the reference trade rounds away
+ */
+export const splitPriceImpact = (options) => {
+    const { candidates, amountIn, deliveredAmount } = options;
+    const referenceAmountIn = amountIn / PULSEX_MARGINAL_REFERENCE_DIVISOR;
+    const referenceAmountOut = candidates.reduce((best, candidate) => {
+        const output = singlePathOutput(candidate, referenceAmountIn);
+        return output > best ? output : best;
+    }, 0n);
+    return priceImpactAgainstMarginal({ amountIn, amountOut: deliveredAmount, referenceAmountIn, referenceAmountOut });
+};
+/**
+ * The best split of a PulseX trade, or null when no split beats the best
+ * single path by {@link PULSEX_SPLIT_MINIMUM_GAIN_BASIS_POINTS}.
+ *
+ * NEVER WORSE THAN ONE PATH. A null answer means "take the best single path";
+ * this never returns a split that delivers less than that path.
+ *
+ * @param candidates - every priced path, on every venue
+ * @param amountIn - the whole trade
+ * @returns the split with its legs in execution order, or null
+ */
+export const bestPulseXSplitQuote = (candidates, amountIn) => {
+    if (amountIn <= 0n)
+        return null;
+    const ranked = rankPulseXSplitCandidates(candidates, amountIn);
+    const singlePathDeliveredAmount = ranked[0]?.deliveredAmount;
+    if (singlePathDeliveredAmount === undefined)
+        return null;
+    const rankedCandidates = ranked.map(({ candidate }) => candidate);
+    const allocation = allocatePulseXSplit(rankedCandidates, amountIn);
+    const legs = legsOf(rankedCandidates, allocation);
+    if (legs.length < 2)
+        return null;
+    const legOutputs = executePulseXSplitInOrder(legs);
+    const deliveredAmount = legOutputs.reduce((total, amount) => total + amount, 0n);
+    const requiredAmount = singlePathDeliveredAmount + (singlePathDeliveredAmount * PULSEX_SPLIT_MINIMUM_GAIN_BASIS_POINTS) / BASIS_POINTS;
+    if (deliveredAmount < requiredAmount)
+        return null;
+    return {
+        legs: legs.map(({ candidate, amountIn: legAmountIn }, index) => ({
+            venue: candidate.venue,
+            path: candidate.path,
+            amountIn: legAmountIn,
+            deliveredAmount: legOutputs[index] ?? 0n,
+        })),
+        deliveredAmount,
+        singlePathDeliveredAmount,
+        priceImpactPercent: splitPriceImpact({ candidates: rankedCandidates, amountIn, deliveredAmount }),
+    };
+};

package/dist/routing/carriers/pulsex.d.ts

@@ -1,6 +1,6 @@
 import { type Hex } from 'viem';
 import type { PublicClient } from 'viem';
-import { type AssetNode, type HopEdge } from '../search/graph.js';
+import { type AssetNode, type HopEdge, type PlannedHop } from '../search/graph.js';
 import type { CarrierAskAnswer, CarrierExactResult } from './ask-answer.js';
 /**
  * One PulseX deployment a swap can execute on: the router the reader signs
@@ -30,31 +30,41 @@ export declare const pulseXVenues: readonly PulseXVenue[];
  */
 export declare const pulseXRouterForEdge: (edge: Pick<HopEdge, "carrier" | "venue">) => Hex | null;
 /**
- * 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 declare const pulseXWrappedNativePath: (from: AssetNode, to: AssetNode) => readonly Hex[] | null;
+/**
+ * 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 declare const pulseXPoolPath: (from: AssetNode, to: AssetNode) => readonly Hex[] | null;
+export declare const pulseXSwapPathForHop: (hop: Pick<PlannedHop, "edge" | "outcome">) => readonly Hex[] | null;
 /** One pool a swap path crosses, read in the direction of travel. */
 export type PulseXPathStep = {
     /** The pool's reserve of the token flowing in. */

package/dist/routing/carriers/pulsex.js

@@ -1,5 +1,5 @@
 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';
@@ -7,6 +7,7 @@ import { sameAddress } from '../../ecosystems.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
@@ -19,6 +20,8 @@ import { assetNodeKey } from '../search/graph.js';
  */
 /** 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}. */
+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
@@ -70,65 +73,104 @@ const pulseXVenueForEdge = (edge) => {
  * 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
  */
 const poolTokenAddress = (node) => (sameAddress(node.address, zeroAddress, 'evm') ? wplsAddress : 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);
 };
+/**
+ * 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 [];
+    return candidatePulseXPaths({ from: fromAddress, to: toAddress, wrappedNative: wplsAddress, hubs: hubAddresses });
+};
 /**
  * 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.
+ * 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.
  *
- * 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) => {
     if (from.ecosystem !== 'evm' || to.ecosystem !== 'evm')
         return false;
     if (from.chainId !== pulsechainChainId || to.chainId !== pulsechainChainId)
         return false;
-    const swapPath = pulseXPoolPath(from, to);
-    return swapPath !== null && swapPath.length >= 2;
+    return pulseXCandidatePaths(from, to).length > 0;
+};
+/**
+ * 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, as a numerator over
@@ -219,6 +261,32 @@ const poolKey = (tokenA, tokenB) => {
 const venuePoolKey = (venue, tokenA, tokenB) => `${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 +303,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
@@ -253,11 +329,10 @@ const preparePulseXReserves = async ({ nodes, venues, clientForChain, }) => {
                 continue;
             if (!pulseXCarries(from, to))
                 continue;
-            const path = pulseXPoolPath(from, to);
-            if (path === null)
-                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]);
+                }
             }
         }
     }
@@ -397,44 +472,39 @@ export const createPulseXCarrier = (options) => {
         const venue = pulseXVenueForEdge(edge);
         if (venue === null || !venues.includes(venue))
             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) }];
+        });
+        // 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),
         });
-        // 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',

package/dist/routing/composed-route-quality.d.ts

@@ -47,6 +47,26 @@ export declare const COMPOSED_ROUTE_MAX_PRICE_IMPACT_PERCENT = 3;
  * of the reader's money.
  */
 export declare const COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT = 5;
+/**
+ * The end-to-end value GAIN above which a composed route is withdrawn, in
+ * percent of what the reader pays.
+ *
+ * A ROUTE CANNOT MAKE MONEY. Every leg charges a fee, so a route that
+ * delivers more value than it takes says one of its figures is wrong. Only a
+ * disagreement between the two price feeds can make a gain look real, and the
+ * value-loss ceiling already trusts those feeds to within the same five
+ * percent. So the bound is symmetric with
+ * {@link COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT}.
+ *
+ * THE DEFECT THIS STOPS. On 2026-10-03 the engine served 0.0002 BNB to HEX at
+ * 495,256 HEX, about seven thousand times the rate of the next tier. The
+ * value-loss test read that as a loss of minus seven hundred thousand percent
+ * and passed it. A PulseX hop rescaled from an upstream live answer keeps the
+ * price impact measured at its original, smaller input
+ * (`recomposePath` in `@gibs/quotes`'s `search/waves.ts`), so the impact test
+ * cannot see an inflated amount either. Only the two ends of the journey can.
+ */
+export declare const COMPOSED_ROUTE_MAX_VALUE_GAIN_PERCENT = 5;
 /**
  * The verdict on one composed route.
  *
@@ -62,18 +82,20 @@ export type ComposedRouteVerdict = {
     readonly missing: 'price-impact' | 'route-value';
 } | {
     readonly state: 'rejected';
-    readonly reason: 'price-impact' | 'value-loss';
+    readonly reason: 'price-impact' | 'value-loss' | 'value-gain';
     /** The measured figure, in percent, that failed its ceiling. */
     readonly measuredPercent: number;
     /** The ceiling it failed. */
     readonly ceilingPercent: number;
 };
 /**
- * Judges a composed route against both ceilings.
+ * Judges a composed route against its three ceilings.
  *
- * Checks price impact first and value loss second, because impact names the
- * specific leg at fault while value loss only says the journey as a whole went
- * wrong — so reporting impact when both fail is the more useful answer.
+ * Checks price impact first, then value loss, then value gain. Impact names
+ * the specific leg at fault, while the two value tests only say the journey as
+ * a whole went wrong, so impact is the more useful answer when several fail.
+ * In the measured percent of a `'value-gain'` rejection, the gain is a
+ * positive number.
  *
  * @param options.priceImpactPercent - the swap leg's price impact, from the
  *   estimate's marginal reference quote; null when not yet quoted
@@ -98,6 +120,6 @@ export declare const assessComposedRoute: ({ priceImpactPercent, paidUsdValue, d
  * pricing" rather than "no route", which a boolean alone could not.
  *
  * @param verdict - the verdict from {@link assessComposedRoute}
- * @returns true only when the route passed both ceilings
+ * @returns true only when the route passed every ceiling
  */
 export declare const composedRouteMayBeOffered: (verdict: ComposedRouteVerdict) => boolean;