@gibs/bridge-sdk 1.13.0 → 1.17.0

package/dist/referral.js

@@ -33,7 +33,11 @@ export const referralIntegrator = 'gibs.finance';
  */
 export const resolveAttribution = (override, packageDefault) => (override === null ? undefined : (override ?? packageDefault));
 /**
- * Payout address for Relay application fees.
+ * Gibs Finance's payout address for Relay application fees.
+ *
+ * NO BUILDER APPLIES IT. A Relay request carries an `appFees` entry only when
+ * the caller passes `relayAppFee`. The Gibs interface passes this address
+ * explicitly; any other caller passes its own, or nothing.
  *
  * Set to the owner's receiving wallet. Setting it back to `null` is a working
  * state rather than a broken one, and is the way to stop collecting: Relay
@@ -52,9 +56,13 @@ export const resolveAttribution = (override, packageDefault) => (override === nu
  */
 export const relayReferralRecipient = '0xAF2ce0189f46f5663715b0b9ED2a10eA924AB9B0';
 /**
- * Default application fee in basis points. Ten basis points is one tenth of one
- * percent. The interface can override it per provider in stored settings; this
- * is the value a reader who has never touched the setting gets.
+ * The application fee the Gibs interface charges, in basis points. Ten basis
+ * points is one tenth of one percent. The interface can override it per
+ * provider in stored settings; this is the value a reader who has never touched
+ * the setting gets.
+ *
+ * NO BUILDER APPLIES IT. It reaches a request only when a caller passes it as
+ * `relayAppFee.basisPoints` (Relay) or converts it to `lifiFee` (LI.FI).
  */
 export const defaultReferralFeeBasisPoints = 10n;
 /**

package/dist/relay-depository.d.ts

@@ -0,0 +1,2 @@
+import { type Hex } from 'viem';
+export declare const relayDepositoryByChainId: ReadonlyMap<number, Hex>;

package/dist/relay-depository.js

@@ -0,0 +1,82 @@
+import { getAddress } from 'viem';
+/**
+ * Relay's deposit contract (its "depository") on each Ethereum-style chain:
+ * the ONLY address a Relay origin deposit may be sent to, and the only
+ * address it may ask the reader to approve.
+ *
+ * WHY A FIXED TABLE. A quote that names its own spender cannot be trusted to
+ * name an honest one: a compromised quote host could name any contract. This
+ * table ships with the code and changes only through a release.
+ *
+ * SOURCE. Relay's Chains API, `GET https://api.relay.link/chains`, field
+ * `chains[].protocol.v2.depository`, read 2026-10-07 for every chain whose
+ * `vmType` is `evm`. Relay's documentation says its depository addresses are
+ * published only through that API
+ * (https://docs.relay.link/references/protocol/addresses). A live quote the
+ * same day (Ethereum USDC to Base, `POST /quote/v2`) approved and deposited to
+ * exactly the Ethereum entry below.
+ *
+ * NOT THE `contracts` BLOCK. The same API also lists `relayReceiver`,
+ * `approvalProxy` and `erc20Router` under `chains[].contracts`. The live
+ * quote used none of them, so they are left out: an address the quote does
+ * not use is not one this table should accept.
+ *
+ * A CHAIN NOT LISTED IS REFUSED. If Relay adds a chain or moves a depository,
+ * deposits there are refused until this table is updated.
+ */
+const common = getAddress('0x4cd00e387622c35bddb9b4c962c136462338bc31');
+const alternate = getAddress('0x59916da825d2d2ec1bf878d71c88826f6633ecca');
+export const relayDepositoryByChainId = new Map([
+    [1, common], // ethereum
+    [10, common], // optimism
+    [25, alternate], // cronos
+    [56, common], // bsc
+    [100, common], // gnosis
+    [130, common], // unichain
+    [137, common], // polygon
+    [143, common], // monad
+    [146, common], // sonic
+    [169, common], // manta-pacific
+    [196, common], // xlayer
+    [288, common], // boba
+    [324, common], // zksync
+    [360, common], // shape
+    [480, common], // world-chain
+    [747, common], // flow-evm
+    [988, common], // stable
+    [999, common], // hyperevm
+    [1088, alternate], // metis
+    [1135, common], // lisk
+    [1868, common], // soneium
+    [2020, common], // ronin
+    [2741, common], // abstract
+    [2818, common], // morph
+    [4217, common], // tempo
+    [4326, common], // megaeth
+    [4663, common], // robinhood
+    [5000, alternate], // mantle
+    [5031, common], // somnia
+    [5042, common], // arc
+    [5330, common], // superseed
+    [8453, common], // base
+    [9745, common], // plasma
+    [33139, common], // apechain
+    [34443, common], // mode
+    [42018, common], // mythos
+    [42161, common], // arbitrum
+    [42220, common], // celo
+    [43114, common], // avalanche
+    [48900, common], // zircuit
+    [57073, common], // ink
+    [59144, alternate], // linea
+    [60808, common], // bob
+    [80094, common], // berachain
+    [81457, common], // blast
+    [97477, common], // doma
+    [98866, common], // plume
+    [534352, common], // scroll
+    [685689, common], // gensyn
+    [747474, common], // katana
+    [5064014, common], // ethereal
+    [7777777, common], // zora
+]);

package/dist/relay-quote.js

@@ -1,3 +1,4 @@
+import { buildUrl } from '@gibs/common/url';
 import { decodeFunctionData, encodeFunctionData, erc20Abi, maxUint256, zeroAddress, } from 'viem';
 import { Chains } from './config.js';
 import { isNonEthereumVirtualMachineOrigin, } from './consolidated-quote.js';
@@ -861,9 +862,7 @@ export const parseRelayQuote = (payload) => {
  * than trust it — see `checkConsolidatedRecord`.
  */
 export const relayStatusUrl = ({ quoteId }) => {
-    const url = new URL(relayRequestsUrl);
-    url.searchParams.set('id', quoteId);
-    return url.toString();
+    return buildUrl(relayRequestsUrl, { id: quoteId });
 };
 /**
  * Relay's request lifecycle states. Terminal states are `success` (the

package/dist/routing/candidate.d.ts

@@ -208,9 +208,9 @@ export type DirectCrossingCandidateInputs = {
  * to quote — the user bridges directly from that chain to PulseChain. The
  * same-chain skip in {@link useAggregatorRouteCandidate} is correct (nothing to
  * quote), but it left the conversion path empty. This helper fills that gap by
- * synthesizing a zero-step candidate that `usePulseXConversionRoutes` (the user
- * interface's plural composer) can consume unchanged, producing the correct
- * same-chain conversion route so the ranker can pick the cheapest option.
+ * synthesizing a zero-step candidate. The user interface no longer calls this:
+ * the route engine serves a conversion now. The export stays as published
+ * interface until a separate decision removes it.
  *
  * The synthetic quote carries zero steps (no aggregator hops), a zero execution
  * duration (the direct crossing needs no quote wait), and a null transaction

package/dist/routing/candidate.js

@@ -8,9 +8,9 @@ import { omnibridgeProviderForEntryChain } from './providers.js';
  * to quote — the user bridges directly from that chain to PulseChain. The
  * same-chain skip in {@link useAggregatorRouteCandidate} is correct (nothing to
  * quote), but it left the conversion path empty. This helper fills that gap by
- * synthesizing a zero-step candidate that `usePulseXConversionRoutes` (the user
- * interface's plural composer) can consume unchanged, producing the correct
- * same-chain conversion route so the ranker can pick the cheapest option.
+ * synthesizing a zero-step candidate. The user interface no longer calls this:
+ * the route engine serves a conversion now. The export stays as published
+ * interface until a separate decision removes it.
  *
  * The synthetic quote carries zero steps (no aggregator hops), a zero execution
  * duration (the direct crossing needs no quote wait), and a null transaction

package/dist/routing/carriers/ask-answer.d.ts

@@ -29,6 +29,11 @@ export type CarrierAskAnswer = {
         readonly reason: string | null;
         /** A minimum amount this refusal names, in `edge.from`'s base units, or null. */
         readonly minimumAmount: bigint | null;
+        /**
+         * What the carrier can still take today, in `edge.from`'s base units,
+         * when the refusal is `'above-available'`. Absent otherwise.
+         */
+        readonly availableAmount?: bigint;
     };
 };
 /**
@@ -46,6 +51,15 @@ export type CarrierExactResult = {
     readonly outcome: 'delivered';
     /** What this edge delivers for exactly the requested input amount, in `edge.to`'s base units. */
     readonly deliveredAmount: bigint;
+    /** How far this edge's executed rate falls below its marginal rate, in percent; absent when the carrier cannot measure it. */
+    readonly priceImpactPercent?: number;
+    /**
+     * The token addresses the carrier's own execution passes through, in
+     * order, when it chose among several (a PulseX swap path). The figure
+     * above was priced along exactly this path, so it is the path that must
+     * be signed. Absent when the carrier makes no such choice.
+     */
+    readonly swapPath?: readonly string[];
 } | {
     readonly outcome: 'refused';
     readonly refusal: {
@@ -54,5 +68,10 @@ export type CarrierExactResult = {
         readonly reason: string | null;
         /** A minimum amount this refusal names, in `edge.from`'s base units, or null. */
         readonly minimumAmount: bigint | null;
+        /**
+         * What the carrier can still take today, in `edge.from`'s base units,
+         * when the refusal is `'above-available'`. Absent otherwise.
+         */
+        readonly availableAmount?: bigint;
     };
 };

package/dist/routing/carriers/omnibridge.js

@@ -277,9 +277,27 @@ const prepareOmnibridgeReads = async ({ nodes, edgesFrom, isProductionNetwork, c
     }
     return preparedByEdgeKey;
 };
-const entryAmountVerdictReason = (verdict) => verdict.reason === 'below-minimum'
-    ? `below the entry mediator's minimum of ${verdict.minimumPerTransaction} base units`
-    : `above what the entry mediator has left today (${verdict.availablePerTransaction} base units)`;
+/**
+ * The refusal an entry mediator's own bound produces, carrying the bound
+ * itself as a figure: `minimumAmount` below the floor, `availableAmount`
+ * above what is left today. A reader is told the number to type, so the
+ * number must survive here rather than live only inside the reason string.
+ *
+ * @param verdict - the crossed bound, in the entry token's base units
+ * @returns the refusal, in `edge.from`'s base units
+ */
+const entryAmountRefusal = (verdict) => verdict.reason === 'below-minimum'
+    ? {
+        kind: 'below-minimum',
+        reason: `below the entry mediator's minimum of ${verdict.minimumPerTransaction} base units`,
+        minimumAmount: verdict.minimumPerTransaction,
+    }
+    : {
+        kind: 'above-available',
+        reason: `above what the entry mediator has left today (${verdict.availablePerTransaction} base units)`,
+        minimumAmount: null,
+        availableAmount: verdict.availablePerTransaction,
+    };
 /**
  * Builds the omnibridge crossing as a plug-in carrier.
  *
@@ -316,15 +334,7 @@ export const createOmnibridgeCarrier = (options) => {
             return null;
         const verdict = checkEntryAmount({ amount: amountIn, limits: prepared.limits });
         if (!verdict.fits) {
-            const minimumAmount = verdict.reason === 'below-minimum' ? verdict.minimumPerTransaction : null;
-            return {
-                outcome: 'refused',
-                refusal: {
-                    kind: verdict.reason === 'below-minimum' ? 'below-minimum' : 'above-available',
-                    reason: entryAmountVerdictReason(verdict),
-                    minimumAmount,
-                },
-            };
+            return { outcome: 'refused', refusal: entryAmountRefusal(verdict) };
         }
         return { outcome: 'delivered', deliveredAmount: netDeliveredAmount(amountIn, prepared.feePerEther) };
     };
@@ -332,15 +342,7 @@ export const createOmnibridgeCarrier = (options) => {
         const limits = await readEntryLimits(edge);
         const verdict = checkEntryAmount({ amount: inputAmount, limits });
         if (!verdict.fits) {
-            const minimumAmount = verdict.reason === 'below-minimum' ? verdict.minimumPerTransaction : null;
-            return {
-                ok: false,
-                refusal: {
-                    kind: verdict.reason === 'below-minimum' ? 'below-minimum' : 'above-available',
-                    reason: entryAmountVerdictReason(verdict),
-                    minimumAmount,
-                },
-            };
+            return { ok: false, refusal: entryAmountRefusal(verdict) };
         }
         const feePerEther = await readFeePerEther(edge);
         const deliveredAmount = netDeliveredAmount(inputAmount, feePerEther);

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

@@ -0,0 +1,80 @@
+import { type Hex } from 'viem';
+/**
+ * Which swap path a PulseX hop takes. The hop no longer always goes through
+ * Wrapped PLS: the carrier prices every candidate path from the pool reserves
+ * it already read, and keeps the one that delivers the most. These are the
+ * pure parts of that choice — the hub list, the candidate paths, and the
+ * pick — kept apart from the carrier so each can be tested on its own.
+ */
+/** One token a PulseX swap may pass through on its way from the input token to the output token. */
+export type PulseXHubToken = {
+    /** The token's on-chain `symbol()`, for logs and tests only. Never used to match a token. */
+    readonly symbol: string;
+    /** The token's checksummed PulseChain address. Tokens are always matched by this. */
+    readonly address: Hex;
+};
+/**
+ * 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}).
+ */
+export declare const pulseXHubTokens: readonly PulseXHubToken[];
+/**
+ * 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
+ */
+export declare const candidatePulseXPaths: (options: {
+    readonly from: Hex;
+    readonly to: Hex;
+    readonly wrappedNative: Hex;
+    readonly hubs: readonly Hex[];
+}) => readonly (readonly Hex[])[];
+/** One candidate path, priced. */
+export type PulseXPathQuote<Step> = {
+    /** The tokens the swap passes through, in order. */
+    readonly path: readonly Hex[];
+    /** What the path delivers for the trade, in the last token's base units. */
+    readonly deliveredAmount: bigint;
+    /** The pools the path crosses, in order — kept so the caller can measure price impact on the same pools. */
+    readonly steps: readonly Step[];
+};
+/**
+ * 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
+ */
+export declare const bestPulseXPathQuote: <Step>(quotes: readonly PulseXPathQuote<Step>[]) => PulseXPathQuote<Step> | null;

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

@@ -0,0 +1,92 @@
+import { getAddress } from 'viem';
+import { Chains, Providers, nativeAssetOut, pathways, pulsechainTokenAddresses } from '../../config.js';
+import { PULSECHAIN_USD_ANCHOR_ADDRESS } from '../../prices.js';
+/** Wrapped PLS: the first hub, and the middle token of every two-hub path. */
+const wrappedPulseAddress = getAddress(nativeAssetOut[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 = pathways[Providers.PULSECHAIN][Chains.PLS]?.[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}).
+ */
+export const pulseXHubTokens = Object.freeze([
+    { symbol: 'WPLS', address: wrappedPulseAddress },
+    { symbol: 'PLSX', address: pulsechainTokenAddresses.PLSX },
+    { symbol: 'HEX', address: pulsechainTokenAddresses.HEX },
+    { symbol: 'DAI', address: getAddress(PULSECHAIN_USD_ANCHOR_ADDRESS) },
+    { symbol: 'USDC', address: pulsechainTokenAddresses.USDC },
+    { symbol: 'USDT', address: pulsechainTokenAddresses.USDT },
+    ...(bridgedWrappedEtherAddress === undefined ? [] : [{ symbol: 'WETH', address: 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
+ */
+export 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));
+};
+/**
+ * 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
+ */
+export const bestPulseXPathQuote = (quotes) => quotes
+    .filter((quote) => quote.deliveredAmount > 0n)
+    .reduce((best, quote) => (best === null || beats(quote, best) ? quote : best), null);

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;