@gibs/bridge-sdk 1.13.1 → 1.18.0

package/dist/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/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,60 +1,86 @@
 import { type Hex } from 'viem';
 import type { PublicClient } from 'viem';
-import { type AssetNode, type HopEdge } from '../search/graph.js';
+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 PulseX deployment a swap can execute on: the router the reader signs
- * and the factory whose pools that router trades against. A Uniswap-V2-style
+ * 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 = {
-    readonly router: Hex;
-    readonly factory: Hex;
-};
+export type PulseXVenue = SwapVenue;
 /**
- * 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.
+ * 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 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}).
+ * 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 PulseX edge or names a venue that is not a known PulseX router
+ * @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">) => Hex | null;
+export declare const pulseXRouterForEdge: (edge: Pick<HopEdge, "carrier" | "venue"> & {
+    readonly from?: Pick<AssetNode, "chainId">;
+}) => 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).
+ *
+ * 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.
  *
- * 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.
+ * 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 pulseXPoolPath: (from: AssetNode, to: AssetNode) => readonly Hex[] | null;
+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. */
@@ -68,9 +94,10 @@ export type PulseXPathStep = {
  *
  * @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[]) => bigint;
+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
@@ -100,12 +127,12 @@ export type CreatePulseXCarrierOptions = {
      * 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 pulseXRouterForEdge}). A V2 edge
+     * 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 PulseChain client, for {@link Carrier.prepare}'s own batched
+     * 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.
      *
@@ -113,17 +140,25 @@ export type CreatePulseXCarrierOptions = {
      * 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 - always {@link pulsechainChainId} — PulseX runs nowhere else
+     * @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 PulseX routers this host can SIGN on. The carrier offers an edge on
-     * each, and only on these: an edge is always signed on the router it was
-     * quoted against ({@link pulseXRouterForEdge}), so a router the host cannot
-     * sign on must never be quoted either.
+     * 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 known venue ({@link pulseXVenues}: V1 and V2).
+     * Defaults to every offered venue.
      */
     readonly routers?: readonly Hex[];
 };