@gibs/bridge-sdk 1.19.0 → 1.20.0

package/dist/cjs/routing/carriers/omnibridge.js

@@ -46,25 +46,13 @@ const amounts_js_1 = require("../amounts.js");
 const entry_chain_anchor_js_1 = require("../entry-chain-anchor.js");
 const producers_js_1 = require("../producers.js");
 const graph_js_1 = require("../search/graph.js");
-/** Builds an {@link AssetNode} for an Ethereum-Virtual-Machine token. */
 const evmNode = (token) => ({
     chainId: token.chainId,
     address: token.address,
     decimals: token.decimals,
     ecosystem: 'evm',
 });
-/**
- * A directed pair of node keys, joined for use as a `Map` key. Never leaves
- * this module — see `capabilities.ts`'s former `directedPairKey` doc for why
- * a plain `|` join is enough here.
- */
 const directedPairKey = (from, to) => `${(0, graph_js_1.assetNodeKey)(from)}|${(0, graph_js_1.assetNodeKey)(to)}`;
-/**
- * Finds which omnibridge provider, if any, has a live pathway carrying funds
- * from `fromChainId` to `toChainId`. Checks BOTH omnibridge providers rather
- * than assuming one: `Providers.PULSECHAIN` carries the Ethereum pathway,
- * `Providers.TOKENSEX` the Binance Smart Chain one.
- */
 const omnibridgeCarrierBetween = (fromChainId, toChainId, isProductionNetwork) => {
     const fromChain = (0, config_js_1.toChain)(fromChainId);
     const toChainKey = (0, config_js_1.toChain)(toChainId);
@@ -77,12 +65,6 @@ const omnibridgeCarrierBetween = (fromChainId, toChainId, isProductionNetwork) =
     }
     return null;
 };
-/**
- * Builds the omnibridge's directed edge map from the bridgeable pairs and the
- * live pathway config, in both directions. INBOUND goes through
- * {@link entryChainAnchorsForPair} so a native coin and its wrapped form both
- * anchor the same PulseChain mint; OUTBOUND needs no aliasing.
- */
 const buildOmnibridgeEdgeMap = (bridgeablePairs, isProductionNetwork) => {
     const edges = new Map();
     for (const pair of bridgeablePairs) {
@@ -104,13 +86,6 @@ const buildOmnibridgeEdgeMap = (bridgeablePairs, isProductionNetwork) => {
     }
     return edges;
 };
-/**
- * Resolves one edge's crossing details from the live pathway config, or null
- * when no pathway matches — the same "no live pathway" case `edgesFrom`
- * already prunes, kept here as a guard rather than assumed away, because
- * `prepare` walks every node pair itself rather than trusting the caller to
- * hand it only edges this carrier already offered.
- */
 const resolveCrossing = (edge, isProductionNetwork) => {
     const bridgeKey = [edge.carrier, (0, config_js_1.toChain)(edge.from.chainId), (0, config_js_1.toChain)(edge.to.chainId)];
     const wrappedNativeAddress = config_js_1.nativeAssetOut[(0, config_js_1.toChain)(edge.from.chainId)];
@@ -131,7 +106,6 @@ const resolveCrossing = (edge, isProductionNetwork) => {
         feeTypeKey: path.toHome ? config_js_1.FOREIGN_TO_HOME_FEE : config_js_1.HOME_TO_FOREIGN_FEE,
     };
 };
-/** Groups values by a computed chain id, preserving the deduped-by-`keyOf` invariant callers rely on. */
 const groupByChainId = (values, chainIdOf) => {
     const groups = new Map();
     for (const value of values) {
@@ -146,7 +120,6 @@ const groupByChainId = (values, chainIdOf) => {
     }
     return groups;
 };
-/** Stage-one read: `minPerTx`, `maxAvailablePerTx` (an entry mediator's own bounds) and `feeManager()` (the fee contract's address) — every one a fixed-arity view call, so one multicall per chain covers all three kinds at once. */
 const readStageOneBatch = async ({ resolvedCrossings, clientForChain, }) => {
     const limitsByKey = new Map();
     const feeManagerAddressByKey = new Map();
@@ -202,11 +175,6 @@ const readStageOneBatch = async ({ resolvedCrossings, clientForChain, }) => {
             }
             const feeManagerAddress = results[cursor];
             cursor += 1;
-            // A DECODED address is exactly 42 characters ("0x" + 40 hex digits).
-            // `multicallRead` returns the UNDECODED revert bytes on a failed
-            // `allowFailure` call — also a `string`, usually a different length
-            // (`'0x'` for a bare revert) — so `typeof` alone cannot tell success
-            // from failure here the way it does for the `bigint` reads above.
             if (typeof feeManagerAddress === 'string' && feeManagerAddress.length === 42) {
                 feeManagerAddressByKey.set(request.key, (0, viem_1.getAddress)(feeManagerAddress));
             }
@@ -214,7 +182,6 @@ const readStageOneBatch = async ({ resolvedCrossings, clientForChain, }) => {
     }));
     return { limitsByKey, feeManagerAddressByKey };
 };
-/** Stage-two read: `getFee(feeTypeKey, address(0))` on every fee manager contract stage one resolved — needs the address stage one just learned, so it cannot join that multicall. */
 const readStageTwoBatch = async ({ resolvedCrossings, feeManagerAddressByKey, clientForChain, }) => {
     const feeRateByKey = new Map();
     const feeRateRequests = new Map();
@@ -257,35 +224,6 @@ const limitsKey = (crossing) => `${crossing.limitsChainId}|${crossing.entryMedia
 const feeManagerHostKey = (crossing) => `${crossing.feeManagerHostChainId}|${crossing.feeManagerHostAddress}`;
 const feeRateKey = (crossing, feeManagerAddress) => `${crossing.feeManagerHostChainId}|${feeManagerAddress}|${crossing.feeTypeKey}`;
 const preparedEdgeKey = (edge) => `${edge.carrier}|${(0, graph_js_1.assetNodeKey)(edge.from)}|${(0, graph_js_1.assetNodeKey)(edge.to)}`;
-/**
- * Batch-reads every entry-mediator bound and fee rate `nodes` implies, once,
- * so {@link createOmnibridgeCarrier}'s `exact` can answer every crossing
- * SYNCHRONOUSLY afterward — the owner's own model, "each individual step and
- * its associated fees can be known ahead of time."
- *
- * TWO MULTICALLS PER CHAIN, NOT ONE: `getFee` needs the fee manager's
- * address, which stage one is what LEARNS — the same two-stage shape
- * `chain-info.ts`'s `loadBridgeFees` already uses for one pathway at a time,
- * generalized here to batch across every crossing the search's node universe
- * touches. `HOME_TO_FOREIGN_FEE`/`FOREIGN_TO_HOME_FEE` are not re-read from
- * the chain — they are fixed `keccak256` constants (`config.ts`), so reading
- * them per pathway (as `loadBridgeFees` still does, defensively) would only
- * spend a third multicall confirming a value that cannot change.
- *
- * WATCH PAYLOAD SIZE (request-payload-size-traps.md). `nodes` is the search
- * graph's own hub-token-restricted universe, not a full token list — this
- * function reads one `minPerTx`/`maxAvailablePerTx` pair per DISTINCT
- * (mediator, token) crossing in that universe, never per token a chain
- * lists. `multicallRead` (`@gibs/common`) chunks by measured encoded size on
- * top of that, so a universe large enough to matter still cannot repeat the
- * 8.5 MB trap that memory records.
- *
- * @param nodes - every node the search might branch through
- * @param edgesFrom - this carrier's own edge enumerator, reused to find every candidate crossing among `nodes`
- * @param isProductionNetwork - see `CreateOmnibridgeCarrierOptions`'s own field
- * @param clientForChain - see `CreateOmnibridgeCarrierOptions`'s own field
- * @returns every resolved crossing's edge key, mapped to what `exact` needs — never thrown; a chain this host has no client for is simply left unanswered
- */
 const prepareOmnibridgeReads = async ({ nodes, edgesFrom, isProductionNetwork, clientForChain, }) => {
     const edges = [];
     for (const from of nodes) {
@@ -313,15 +251,6 @@ const prepareOmnibridgeReads = async ({ nodes, edgesFrom, isProductionNetwork, c
     }
     return preparedByEdgeKey;
 };
-/**
- * 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',
@@ -334,14 +263,6 @@ const entryAmountRefusal = (verdict) => verdict.reason === 'below-minimum'
         minimumAmount: null,
         availableAmount: verdict.availablePerTransaction,
     };
-/**
- * Builds the omnibridge crossing as a plug-in carrier.
- *
- * @param options - see {@link CreateOmnibridgeCarrierOptions}
- * @returns the carrier — `id: 'omnibridge'`; every EDGE it offers carries the
- *   real `'pulsechain'`/`'tokensex'` provider id, since one registration can
- *   speak for either entry chain depending on the pair
- */
 const createOmnibridgeCarrier = (options) => {
     const { bridgeablePairs, isProductionNetwork, readEntryLimits, readFeePerEther, clientForChain } = options;
     const edgeMap = buildOmnibridgeEdgeMap(bridgeablePairs, isProductionNetwork);
@@ -353,11 +274,6 @@ const createOmnibridgeCarrier = (options) => {
             return [];
         return [{ carrier, from, to, fusesNext: false, origin: 'wallet', floors: [] }];
     };
-    // Populated by `prepare`, read by `exact` — see that method's own doc for
-    // why a mutable closure here is safe: this carrier is a client-side,
-    // one-search-at-a-time object (quote-service.md: the omnibridge crossing
-    // is "never built into" the shared, multi-tenant display-quote service),
-    // so nothing else can be mutating this map while a search reads it.
     let preparedByEdgeKey = new Map();
     const prepare = async (nodes) => {
         if (clientForChain === undefined)
@@ -385,7 +301,6 @@ const createOmnibridgeCarrier = (options) => {
         return {
             ok: true,
             deliveredAmount,
-            // An exact local computation: the guaranteed figure IS the expected one.
             minimumDeliveredAmount: deliveredAmount,
             claimedDurationSeconds: producers_js_1.BRIDGE_SETTLEMENT_ETA_MINUTES * 60,
         };
@@ -397,47 +312,12 @@ const createOmnibridgeCarrier = (options) => {
         prepare,
         exact,
         isRateLimited: false,
-        // Crossing requires the reader's own wallet signature on the entry
-        // chain — never a by-hand deposit.
         depositMode: 'wallet-signed',
         sender: 'omnibridge',
         settlementSeconds: producers_js_1.BRIDGE_SETTLEMENT_ETA_MINUTES * 60,
     };
 };
 exports.createOmnibridgeCarrier = createOmnibridgeCarrier;
-/**
- * Wraps ANY carrier-shaped object (built-in or a host's own) with the
- * omnibridge's OWN fuse rule: whether THIS carrier's execution, landing on
- * arrival, also performs the omnibridge's entry call — so the two hops
- * together cost the reader one signature instead of two.
- *
- * EVERY CONDITION IS A FACT THE PROVIDER'S OWN DESCRIPTOR STATES
- * (`../../providers.ts`), never a name compared here:
- *
- * - it executes destination calls at all (`executesDestinationCalls` — true
- *   for LI.FI and Relay, false for NEAR Intents, which delivers to the
- *   reader's own wallet and stops);
- * - it can do so FROM this hop's origin chain (`destinationCallOriginChainIds`
- *   — LI.FI's contract-calls endpoint is Ethereum only, so from Base or
- *   Arbitrum a LI.FI hop is an unfused delivery followed by a crossing the
- *   reader signs);
- * - when the entry is the omnibridge's NATIVE one (the provider lands a
- *   native coin, and `wrapAndRelayTokens` is payable), it can attach value to
- *   the call (`destinationCallCarriesNativeValue`);
- * - and the next hop really IS the omnibridge entry, landing on PulseChain
- *   (`relayTokens`/`wrapAndRelayTokens` both MINT there; any other
- *   destination is the omnibridge's OUTBOUND leg, which no arrival can make).
- *
- * THIS IS THE ONE PLACE `'pulsechain'`/`'tokensex'`/PulseChain'S CHAIN ID
- * APPEAR IN A `fusesWithNext` CALLBACK — gibs's own registration
- * (`packages/ui/src/lib/state/useRouteSearch.ts`) wraps `createLifiCarrier`/
- * `createRelayCarrier` with this before registering them, so the generic
- * search engine (`@gibs/quotes`'s `capabilities.ts`) never has to know what
- * "the bridge" means.
- *
- * @param carrier - the carrier to wrap; its own shape is preserved, only `fusesWithNext` is added/replaced
- * @returns the same carrier, with a `fusesWithNext` that recognizes the omnibridge entry call
- */
 const withOmnibridgeEntryFusing = (carrier) => {
     const descriptor = (0, providers_js_1.findProviderById)(carrier.id);
     return {

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

@@ -4,24 +4,8 @@ exports.bestPulseXPathQuote = exports.candidatePulseXPaths = exports.pulseXHubTo
 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 },
@@ -31,32 +15,8 @@ exports.pulseXHubTokens = Object.freeze([
     { 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]);
@@ -69,28 +29,11 @@ const candidatePulseXPaths = (options) => {
     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);

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

@@ -3,42 +3,12 @@ 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;
@@ -52,18 +22,7 @@ const executePulseXSplitInOrder = (legs) => {
     }, 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)
@@ -77,42 +36,16 @@ const rankPulseXSplitCandidates = (candidates, amountIn) => candidates
     .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) => {
@@ -126,20 +59,6 @@ const allocatePulseXSplit = (candidates, amountIn) => chunksOf(amountIn).reduce(
     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;
@@ -150,17 +69,6 @@ const splitPriceImpact = (options) => {
     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;