@gibs/bridge-sdk 1.13.0 → 1.17.0

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,159 @@
+import { type Hex } from 'viem';
+import type { PublicClient } from 'viem';
+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
+ * 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.
+ */
+export type PulseXVenue = {
+    readonly router: Hex;
+    readonly factory: Hex;
+};
+/**
+ * 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.
+ */
+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}).
+ *
+ * @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
+ */
+export declare const pulseXRouterForEdge: (edge: Pick<HopEdge, "carrier" | "venue">) => 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
+ * @returns the amount leaving the last pool; 0 when any pool cannot pay out
+ */
+export declare const amountOutAlongPath: (amountIn: bigint, steps: readonly PulseXPathStep[]) => 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 pulseXRouterForEdge}). 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
+     * 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 - always {@link pulsechainChainId} — PulseX runs nowhere else
+     * @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.
+     *
+     * Defaults to every known venue ({@link pulseXVenues}: V1 and V2).
+     */
+    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;
+};