@gibs/bridge-sdk 1.13.1 → 1.18.0

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

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bestPulseXPathQuote = exports.candidatePulseXPaths = exports.pulseXHubTokens = void 0;
+const viem_1 = require("viem");
+const config_js_1 = require("../../config.js");
+const prices_js_1 = require("../../prices.js");
+/** Wrapped PLS: the first hub, and the middle token of every two-hub path. */
+const wrappedPulseAddress = (0, viem_1.getAddress)(config_js_1.nativeAssetOut[config_js_1.Chains.PLS]);
+/** The Ethereum-bridged WETH on PulseChain, read off the Ethereum pathway's own config. Undefined only if that pathway is removed. */
+const bridgedWrappedEtherAddress = config_js_1.pathways[config_js_1.Providers.PULSECHAIN][config_js_1.Chains.PLS]?.[config_js_1.Chains.ETH]?.bridgedNativeAssetOut;
+/**
+ * The tokens a PulseX swap may route through, Wrapped PLS first. Each address
+ * comes from a constant this package already holds; none is written here:
+ *
+ * - WPLS — `nativeAssetOut[Chains.PLS]` (`config.ts`).
+ * - PLSX, HEX, USDC, USDT — `pulsechainTokenAddresses` (`config.ts`).
+ * - DAI (from Ethereum) — `PULSECHAIN_USD_ANCHOR_ADDRESS` (`prices.ts`).
+ * - WETH (from Ethereum) — the Ethereum pathway's `bridgedNativeAssetOut` (`config.ts`).
+ *
+ * KEPT SMALL ON PURPOSE. Each hub adds pools to the one batched reserve read
+ * the carrier makes per search, and adds paths to every price it computes.
+ * Seven hubs give at most 20 candidate paths per hop (see
+ * {@link candidatePulseXPaths}).
+ */
+exports.pulseXHubTokens = Object.freeze([
+    { symbol: 'WPLS', address: wrappedPulseAddress },
+    { symbol: 'PLSX', address: config_js_1.pulsechainTokenAddresses.PLSX },
+    { symbol: 'HEX', address: config_js_1.pulsechainTokenAddresses.HEX },
+    { symbol: 'DAI', address: (0, viem_1.getAddress)(prices_js_1.PULSECHAIN_USD_ANCHOR_ADDRESS) },
+    { symbol: 'USDC', address: config_js_1.pulsechainTokenAddresses.USDC },
+    { symbol: 'USDT', address: config_js_1.pulsechainTokenAddresses.USDT },
+    ...(bridgedWrappedEtherAddress === undefined ? [] : [{ symbol: 'WETH', address: (0, viem_1.getAddress)(bridgedWrappedEtherAddress) }]),
+].map((hub) => Object.freeze(hub)));
+/** Whether a path names any token twice, compared without regard to letter case. */
+const repeatsAToken = (path) => new Set(path.map((address) => address.toLowerCase())).size !== path.length;
+/** Whether two addresses are the same token, compared without regard to letter case. */
+const sameToken = (left, right) => left.toLowerCase() === right.toLowerCase();
+/**
+ * Every swap path a PulseX hop from `from` to `to` may take:
+ *
+ * - direct: `[from, to]`;
+ * - one hub: `[from, hub, to]` for each hub, Wrapped PLS among them;
+ * - two hubs: `[from, wrappedNative, hub, to]` and `[from, hub, wrappedNative, to]`
+ *   for each other hub — Wrapped PLS holds the deepest pools on PulseX, so it
+ *   is the one middle token worth pairing with every other hub.
+ *
+ * A path that names a token twice is dropped. That removes every path whose
+ * hub IS `from` or `to`, and the same-token hop when `from` equals `to`.
+ *
+ * The fixed path this carrier used before — `[from, WPLS, to]`, or
+ * `[from, to]` when one side is WPLS — is always in the result, so the pick
+ * can only match or beat it.
+ *
+ * @param options.from - the pool token the swap spends
+ * @param options.to - the pool token the swap buys
+ * @param options.wrappedNative - Wrapped PLS
+ * @param options.hubs - the hub token addresses, Wrapped PLS included
+ * @returns the candidate paths, direct first, each at least two tokens long
+ */
+const candidatePulseXPaths = (options) => {
+    const { from, to, wrappedNative, hubs } = options;
+    const oneHubPaths = hubs.map((hub) => [from, hub, to]);
+    const twoHubPaths = hubs
+        .filter((hub) => !sameToken(hub, wrappedNative))
+        .flatMap((hub) => [
+        [from, wrappedNative, hub, to],
+        [from, hub, wrappedNative, to],
+    ]);
+    return [[from, to], ...oneHubPaths, ...twoHubPaths].filter((path) => !repeatsAToken(path));
+};
+exports.candidatePulseXPaths = candidatePulseXPaths;
+/**
+ * Whether `candidate` should replace `best`: it delivers more, or it delivers
+ * the same and crosses fewer pools. A tie goes to the shorter path because
+ * each extra pool costs gas, and nothing else separates the two.
+ */
+const beats = (candidate, best) => {
+    if (candidate.deliveredAmount !== best.deliveredAmount)
+        return candidate.deliveredAmount > best.deliveredAmount;
+    return candidate.path.length < best.path.length;
+};
+/**
+ * The priced path that delivers the most. A path that delivers nothing is
+ * never chosen. Among equal outputs the path with fewer pools wins, and among
+ * equal lengths the earlier candidate wins, so the pick is deterministic.
+ *
+ * Gas is not weighed beyond that tie-break: the search charges one flat gas
+ * figure per swap signature, whatever its path length (`route-search-gas.ts`
+ * in the interface), so there is no per-pool gas figure to subtract here.
+ *
+ * @param quotes - the priced candidates; paths with a missing pool are already left out
+ * @returns the best candidate, or null when none delivers anything
+ */
+const bestPulseXPathQuote = (quotes) => quotes
+    .filter((quote) => quote.deliveredAmount > 0n)
+    .reduce((best, quote) => (best === null || beats(quote, best) ? quote : best), null);
+exports.bestPulseXPathQuote = bestPulseXPathQuote;

package/dist/cjs/routing/carriers/pulsex-split.d.ts

@@ -0,0 +1,175 @@
+import type { Hex } from 'viem';
+/**
+ * PRICING ONLY. NOTHING SIGNS A SPLIT, SO NOTHING SERVES ONE.
+ *
+ * A split swap sends part of one trade along one PulseX path and the rest
+ * along others, often on both venues (V1 and V2). That lowers price impact on
+ * a large trade. But a split is several router calls, and on PulseChain no
+ * contract this application deploys or calls can run several router calls
+ * from the reader's tokens in one transaction:
+ *
+ * - The PulseX routers have no split call. Each call trades one path on one
+ *   factory.
+ * - The Gibs destination routers (`TokenOmnibridgeRouter`) only unwrap and pay
+ *   delivery fees in `onTokenBridged`. They make no arbitrary call.
+ * - Multicall3 forwards native value, but it cannot pull the reader's tokens
+ *   safely: an allowance to Multicall3 is open to anyone who calls it.
+ * - PulseChain has no EIP-7702, so an ordinary wallet cannot batch calls
+ *   atomically through `wallet_sendCalls`.
+ *
+ * So this module stays out of the package index and out of the carrier's
+ * `exact`. It exists so the figures can be measured and compared. Wiring it
+ * into the engine needs an execution path first: see the design note in the
+ * report that introduced this file.
+ */
+/** One pool a split leg crosses, read in the direction of travel, with the identity shared pools are matched by. */
+export type PulseXSplitStep = {
+    /** The pool's identity: its venue and token pair. Two legs that name the same `pool` trade against the same reserves. */
+    readonly pool: string;
+    /** The token flowing into the pool. */
+    readonly tokenIn: Hex;
+    /** The token flowing out of the pool. */
+    readonly tokenOut: Hex;
+    /** The pool's reserve of `tokenIn` before any leg of the split trades. */
+    readonly reserveIn: bigint;
+    /** The pool's reserve of `tokenOut` before any leg of the split trades. */
+    readonly reserveOut: bigint;
+};
+/** One path a split may send part of the trade along. */
+export type PulseXSplitCandidate = {
+    /** The router the leg would be signed on. */
+    readonly venue: Hex;
+    /** The tokens the leg passes through, in order. */
+    readonly path: readonly Hex[];
+    /** The pools the leg crosses, in order. */
+    readonly steps: readonly PulseXSplitStep[];
+};
+/** One leg of a priced split, in execution order. */
+export type PulseXSplitLeg = {
+    readonly venue: Hex;
+    readonly path: readonly Hex[];
+    /** The part of the trade this leg spends. The legs' inputs sum to the whole trade. */
+    readonly amountIn: bigint;
+    /** What this leg delivers, after every earlier leg has moved the pools it shares. */
+    readonly deliveredAmount: bigint;
+};
+/** A priced split: the legs, in the order they must execute, and the combined figures. */
+export type PulseXSplitQuote = {
+    readonly legs: readonly PulseXSplitLeg[];
+    /** What all legs deliver together. */
+    readonly deliveredAmount: bigint;
+    /** What the best single path delivers for the same trade, for comparison. */
+    readonly singlePathDeliveredAmount: bigint;
+    /**
+     * Price impact of the COMBINED trade, in percent, against the best marginal
+     * rate any candidate offers (see {@link splitPriceImpact}). Null when the
+     * reference trade rounds away.
+     */
+    readonly priceImpactPercent: number | null;
+};
+/**
+ * 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 declare 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 declare const PULSEX_SPLIT_MAX_LEGS = 3;
+/** How many candidate paths, best single-path output first, the search may spread the trade over. */
+export declare 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 declare const PULSEX_SPLIT_MINIMUM_GAIN_BASIS_POINTS = 25n;
+/**
+ * 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 declare const executePulseXSplitInOrder: (legs: readonly {
+    readonly candidate: PulseXSplitCandidate;
+    readonly amountIn: bigint;
+}[]) => readonly bigint[];
+/**
+ * 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 declare const rankPulseXSplitCandidates: (candidates: readonly PulseXSplitCandidate[], amountIn: bigint) => readonly {
+    readonly candidate: PulseXSplitCandidate;
+    readonly deliveredAmount: bigint;
+}[];
+/**
+ * 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 declare const allocatePulseXSplit: (candidates: readonly PulseXSplitCandidate[], amountIn: bigint) => readonly bigint[];
+/**
+ * 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 declare const splitPriceImpact: (options: {
+    readonly candidates: readonly PulseXSplitCandidate[];
+    readonly amountIn: bigint;
+    readonly deliveredAmount: bigint;
+}) => number | null;
+/**
+ * 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 declare const bestPulseXSplitQuote: (candidates: readonly PulseXSplitCandidate[], amountIn: bigint) => PulseXSplitQuote | null;

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

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bestPulseXSplitQuote = exports.splitPriceImpact = exports.allocatePulseXSplit = exports.rankPulseXSplitCandidates = exports.executePulseXSplitInOrder = exports.PULSEX_SPLIT_MINIMUM_GAIN_BASIS_POINTS = exports.PULSEX_SPLIT_CANDIDATE_LIMIT = exports.PULSEX_SPLIT_MAX_LEGS = exports.PULSEX_SPLIT_CHUNKS = void 0;
+const producers_js_1 = require("../producers.js");
+const pulsex_js_1 = require("./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.
+ */
+exports.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. */
+exports.PULSEX_SPLIT_MAX_LEGS = 3;
+/** How many candidate paths, best single-path output first, the search may spread the trade over. */
+exports.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.
+ */
+exports.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
+ */
+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 = (0, pulsex_js_1.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));
+};
+exports.executePulseXSplitInOrder = executePulseXSplitInOrder;
+/** What one candidate alone delivers for the whole trade. */
+const singlePathOutput = (candidate, amountIn) => (0, exports.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
+ */
+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, exports.PULSEX_SPLIT_CANDIDATE_LIMIT)
+    .map(({ candidate, deliveredAmount }) => ({ candidate, deliveredAmount }));
+exports.rankPulseXSplitCandidates = rankPulseXSplitCandidates;
+/** 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(exports.PULSEX_SPLIT_CHUNKS);
+    const chunk = amountIn / count;
+    return Array.from({ length: exports.PULSEX_SPLIT_CHUNKS }, (_, index) => index === exports.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) => (0, exports.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
+ */
+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 >= exports.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));
+exports.allocatePulseXSplit = allocatePulseXSplit;
+/**
+ * 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
+ */
+const splitPriceImpact = (options) => {
+    const { candidates, amountIn, deliveredAmount } = options;
+    const referenceAmountIn = amountIn / producers_js_1.PULSEX_MARGINAL_REFERENCE_DIVISOR;
+    const referenceAmountOut = candidates.reduce((best, candidate) => {
+        const output = singlePathOutput(candidate, referenceAmountIn);
+        return output > best ? output : best;
+    }, 0n);
+    return (0, pulsex_js_1.priceImpactAgainstMarginal)({ amountIn, amountOut: deliveredAmount, referenceAmountIn, referenceAmountOut });
+};
+exports.splitPriceImpact = splitPriceImpact;
+/**
+ * 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
+ */
+const bestPulseXSplitQuote = (candidates, amountIn) => {
+    if (amountIn <= 0n)
+        return null;
+    const ranked = (0, exports.rankPulseXSplitCandidates)(candidates, amountIn);
+    const singlePathDeliveredAmount = ranked[0]?.deliveredAmount;
+    if (singlePathDeliveredAmount === undefined)
+        return null;
+    const rankedCandidates = ranked.map(({ candidate }) => candidate);
+    const allocation = (0, exports.allocatePulseXSplit)(rankedCandidates, amountIn);
+    const legs = legsOf(rankedCandidates, allocation);
+    if (legs.length < 2)
+        return null;
+    const legOutputs = (0, exports.executePulseXSplitInOrder)(legs);
+    const deliveredAmount = legOutputs.reduce((total, amount) => total + amount, 0n);
+    const requiredAmount = singlePathDeliveredAmount + (singlePathDeliveredAmount * exports.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: (0, exports.splitPriceImpact)({ candidates: rankedCandidates, amountIn, deliveredAmount }),
+    };
+};
+exports.bestPulseXSplitQuote = bestPulseXSplitQuote;

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

@@ -0,0 +1,184 @@
+import { type Hex } from 'viem';
+import type { PublicClient } from 'viem';
+import { type SwapVenue, type SwapVenues } from '../../swap-venues.js';
+import { type AssetNode, type HopEdge, type PlannedHop } from '../search/graph.js';
+import type { CarrierAskAnswer, CarrierExactResult } from './ask-answer.js';
+/**
+ * One swap deployment a swap can execute on: the router the reader signs and
+ * the factory whose pools that router trades against. A Uniswap-V2-style
+ * router resolves every pool through its OWN factory, so one router call can
+ * only ever touch that one deployment's pools — a path can never mix them.
+ *
+ * Same type as {@link SwapVenue}; the old name stays for existing callers.
+ */
+export type PulseXVenue = SwapVenue;
+/**
+ * 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 declare const pulseXVenues: readonly PulseXVenue[];
+/**
+ * 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 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`
+ */
+export declare const venueForEdge: (venues: SwapVenues, edge: Pick<HopEdge, "carrier" | "venue"> & {
+    readonly from?: Pick<AssetNode, "chainId">;
+}) => SwapVenue | null;
+/**
+ * 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 declare const pulseXRouterForEdge: (edge: Pick<HopEdge, "carrier" | "venue"> & {
+    readonly from?: Pick<AssetNode, "chainId">;
+}) => Hex | null;
+/**
+ * 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).
+ *
+ * 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 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 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. */
+    readonly reserveIn: bigint;
+    /** The pool's reserve of the token flowing out. */
+    readonly reserveOut: bigint;
+};
+/**
+ * What `amountIn` delivers after crossing every pool of a path in order,
+ * chaining {@link constantProductAmountOut}.
+ *
+ * @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 declare const amountOutAlongPath: (amountIn: bigint, steps: readonly PulseXPathStep[], feeBasisPoints?: number) => bigint;
+/**
+ * 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
+ * pools (`amountIn / PULSEX_MARGINAL_REFERENCE_DIVISOR`). The swap fee rides
+ * in both rates, so it cancels and the gap is price impact alone. A path
+ * through several pools composes by itself: the reference trade crosses the
+ * same pools in the same order.
+ *
+ *   impact = (1 - (amountOut / amountIn) / (referenceAmountOut / referenceAmountIn)) * 100
+ *
+ * @param options.amountIn - the full trade's input
+ * @param options.amountOut - what the full trade delivers
+ * @param options.referenceAmountIn - the reference trade's input
+ * @param options.referenceAmountOut - what the reference trade delivers
+ * @returns the impact in percent, never below 0; null when a reference figure is zero (impact cannot be measured)
+ */
+export declare const priceImpactAgainstMarginal: (options: {
+    readonly amountIn: bigint;
+    readonly amountOut: bigint;
+    readonly referenceAmountIn: bigint;
+    readonly referenceAmountOut: bigint;
+}) => number | null;
+/** What {@link createPulseXCarrier} needs. */
+export type CreatePulseXCarrierOptions = {
+    /**
+     * Reads PulseX's `getAmountsOut` for one PulseX edge and an input amount,
+     * in the edge's `to` token's base units. Returns null when the path has no
+     * liquidity.
+     *
+     * MUST READ THE EDGE'S OWN ROUTER ({@link venueForEdge}). A V2 edge
+     * answered from V1 would carry V1's figure into a V2 signature.
+     */
+    readonly readAmountOut: (edge: HopEdge, inputAmount: bigint) => Promise<bigint | null>;
+    /**
+     * Returns a client for a chain, for {@link Carrier.prepare}'s own batched
+     * reserve reads — never called by `ask`, which keeps using
+     * {@link readAmountOut} unchanged.
+     *
+     * OPTIONAL, ON PURPOSE — see `omnibridge.ts`'s identical `clientForChain`
+     * field for why: a host that has not wired this yet gets the carrier's
+     * original behavior, `prepare` a no-op and `exact` always `null`.
+     *
+     * @param chainId - a chain that has swap venues
+     * @returns a client, or null when this host has none
+     */
+    readonly clientForChain?: (chainId: number) => PublicClient | null;
+    /**
+     * The swap venues to offer. Merged over {@link defaultSwapVenues} by
+     * {@link resolveSwapVenues}: a chain named here REPLACES that chain's
+     * default list, a chain left out keeps its defaults, and an empty list
+     * switches swaps off on that chain. A venue on ANY chain builds swap edges
+     * there.
+     */
+    readonly venues?: SwapVenues;
+    /**
+     * Narrows the offered venues to these routers. An edge is always signed on
+     * the router it was quoted against ({@link venueForEdge}), so a router the
+     * host cannot sign on must never be quoted either. A router that is in no
+     * offered venue is a configuration error and throws at construction.
+     *
+     * Defaults to every offered venue.
+     */
+    readonly routers?: readonly Hex[];
+};
+/**
+ * Builds the PulseX conversion swap as a plug-in carrier.
+ *
+ * @param options - see {@link CreatePulseXCarrierOptions}
+ * @returns the carrier — `id: 'PulseX'`
+ */
+export declare const createPulseXCarrier: (options: CreatePulseXCarrierOptions) => {
+    id: string;
+    edgesFrom: (from: AssetNode, to: AssetNode) => readonly HopEdge[];
+    ask: ({ edge, inputAmount }: {
+        edge: HopEdge;
+        inputAmount: bigint;
+    }) => Promise<CarrierAskAnswer>;
+    prepare: (nodes: readonly AssetNode[]) => Promise<void>;
+    exact: (edge: HopEdge, amountIn: bigint) => CarrierExactResult | null;
+    isRateLimited: boolean;
+    depositMode: "wallet-signed";
+    sender: "swap";
+    settlementSeconds: number;
+};