@gibs/bridge-sdk 1.18.0 → 1.20.0

package/dist/routing/carriers/pulsex.js

@@ -9,60 +9,18 @@ import { pulseXConversionSwapPath } from '../providers.js';
 import { PULSEX_MARGINAL_REFERENCE_DIVISOR, pulsechainChainId } from '../producers.js';
 import { assetNodeKey } from '../search/graph.js';
 import { bestPulseXPathQuote, candidatePulseXPaths, pulseXHubTokens } from './pulsex-paths.js';
-/**
- * PulseX (the PulseChain-native decentralized exchange, used here for a
- * conversion swap leg) as a plug-in `Carrier` for `@gibs/quotes`'s
- * route-search engine. GIBS-SPECIFIC — see `docs/quote-service.md`'s
- * "Carriers" section: "never built in ... PulseX." Registered from
- * `packages/ui/src/lib/state/useRouteSearch.ts` / `route-search-quotes.ts`.
- *
- * See `omnibridge.ts`'s head doc for why this returns a plain object shaped
- * like `Carrier` rather than importing that type.
- */
-/** The hub addresses every candidate path on PulseChain is built from — see {@link pulseXHubTokens}. */
 const hubAddresses = pulseXHubTokens.map((hub) => hub.address);
-/**
- * The wrapped-native token a chain's swaps route through, or undefined when
- * this package does not know one for the chain. Without it a path on that
- * chain can only be direct.
- *
- * @param chainId - the numeric chain id
- */
 const wrappedNativeFor = (chainId) => {
     const wrapped = nativeAssetOut[toChain(chainId)];
     return wrapped === undefined ? undefined : getAddress(wrapped);
 };
-/**
- * The hub tokens a path on `chainId` may pass through. PulseChain has the
- * full list; any other chain has only its wrapped-native token, because this
- * package knows no other hubs.
- */
 const hubsFor = (chainId) => {
     if (chainId === pulsechainChainId)
         return hubAddresses;
     const wrapped = wrappedNativeFor(chainId);
     return wrapped === undefined ? [] : [wrapped];
 };
-/**
- * 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 const pulseXVenues = defaultSwapVenues[pulsechainChainId] ?? [];
-/**
- * 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 const venueForEdge = (venues, edge) => {
     if (edge.carrier !== 'PulseX')
         return null;
@@ -71,50 +29,8 @@ export const venueForEdge = (venues, edge) => {
         return venues[chainId]?.[0] ?? null;
     return findSwapVenue(venues, chainId, edge.venue);
 };
-/**
- * The router a PulseX edge must be signed on, judged against the DEFAULT
- * venues only. Prefer {@link venueForEdge} with the venues your host passes.
- *
- * @param edge - the edge to sign
- * @returns the router, or null when the edge is not a swap edge or names a router that is not a default
- */
 export const pulseXRouterForEdge = (edge) => venueForEdge(defaultSwapVenues, edge)?.router ?? null;
-/**
- * A node's own address for a pool lookup: native (the zero address) is not a
- * token the router or its factory ever holds a pool for — only the chain's
- * wrapped-native token is — so a native node resolves to that wrapped token
- * before it ever reaches {@link pulseXConversionSwapPath}. Every other node
- * is unchanged. A chain with no known wrapped-native token leaves a native
- * node as it is; it has no pool, so no path prices.
- *
- * MIRRORS `useRouteSearch.ts`'s `quotePathAddress` (the UI's async `ask`
- * already resolves native this way through that function) — this is the
- * SAME rule, restated here because `prepare`/`exact` never go through the
- * UI's `readAmountOut` at all; see {@link pulseXCandidatePaths}'s own doc.
- *
- * @param node - the node to resolve
- * @returns the node's own address, or its chain's wrapped-native address for a native node
- */
 const poolTokenAddress = (node) => sameAddress(node.address, zeroAddress, 'evm') ? (wrappedNativeFor(node.chainId) ?? zeroAddress) : node.address;
-/**
- * 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 const pulseXWrappedNativePath = (from, to) => {
     const fromAddress = poolTokenAddress(from);
     const toAddress = poolTokenAddress(to);
@@ -123,38 +39,16 @@ export const pulseXWrappedNativePath = (from, to) => {
     const wrappedNative = wrappedNativeFor(from.chainId);
     return wrappedNative === undefined ? [fromAddress, toAddress] : pulseXConversionSwapPath(fromAddress, toAddress, wrappedNative);
 };
-/**
- * Every path a PulseX hop from `from` to `to` may be priced along, or none
- * when both ends resolve to the same pool token. EVERY PULSEX PRICE AND
- * POOL READ IN THIS FILE GOES THROUGH THIS ONE FUNCTION, so `prepare` reads
- * exactly the pools `exact` will look up, and native PLS resolves to WPLS
- * the same way in both ({@link poolTokenAddress} — a path that started on
- * the zero address once left every native-PLS hop unpriced).
- *
- * @param from - the hop's origin node
- * @param to - the hop's destination node
- * @returns the candidate paths, direct first; empty when there is nothing to swap
- */
 const pulseXCandidatePaths = (from, to) => {
     const fromAddress = poolTokenAddress(from);
     const toAddress = poolTokenAddress(to);
     if (sameAddress(fromAddress, toAddress, 'evm'))
         return [];
     const wrappedNative = wrappedNativeFor(from.chainId);
-    // No known wrapped-native token: the direct pool is the only path.
     if (wrappedNative === undefined)
         return [[fromAddress, toAddress]];
     return candidatePulseXPaths({ from: fromAddress, to: toAddress, wrappedNative, hubs: hubsFor(from.chainId) });
 };
-/**
- * Whether a swap venue in `venues` can carry funds directly from `from` to
- * `to`: both must be Ethereum-Virtual-Machine tokens on the SAME chain, that
- * chain must have at least one venue, and the two must resolve to different
- * pool tokens, so there is at least one path to price.
- *
- * NO TOKEN ALLOWLIST IS CONSULTED, on purpose: whether a pool exists is the
- * reserve read's question, answered in `prepare`, not this one's.
- */
 const pulseXCarries = (venues, from, to) => {
     if (from.ecosystem !== 'evm' || to.ecosystem !== 'evm')
         return false;
@@ -164,21 +58,6 @@ const pulseXCarries = (venues, from, to) => {
         return false;
     return pulseXCandidatePaths(from, to).length > 0;
 };
-/**
- * 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 const pulseXSwapPathForHop = (hop) => {
     if (hop.edge.carrier !== 'PulseX')
         return null;
@@ -196,42 +75,11 @@ export const pulseXSwapPathForHop = (hop) => {
         return null;
     return path;
 };
-/**
- * PulseX's own constant-product swap fee in basis points (29 of 10000, a
- * numerator of 9971) — the default for {@link amountOutAlongPath}; a
- * venue carries its own `feeBasisPoints`. The SAME `getAmountOut` formula every
- * Uniswap-V2-style router uses: `amountOut = floor(amountIn * feeNumerator *
- * reserveOut / (reserveIn * feeDenominator + amountIn * feeNumerator))`.
- *
- * MEASURED, NOT ASSUMED — see `uniV2Factories`'s own doc in `config.ts` for
- * the full account. Reading live reserves from both PulseX router
- * deployments (V1 `0x98bf93…`, V2 `0x165C34…`) and back-solving this ratio
- * against each router's own `getAmountsOut`, on a one-hop and a two-hop
- * path, gave the IDENTICAL ratio — `9971/10000` — for both, to the base
- * unit. One constant serves both, and `pulsex-carrier.fork.test.ts` pins
- * this claim against live chain data rather than trusting the arithmetic
- * alone.
- */
 const PULSEX_FEE_BASIS_POINTS = 29;
-/** Basis points in a whole: the denominator of every venue's fee. */
 const BASIS_POINTS_DENOMINATOR = 10000n;
-/** The minimal read-only factory ABI `prepare` needs — just enough to resolve a pool's address from its two tokens. */
 const univ2FactoryAbi = parseAbi([
     'function getPair(address tokenA, address tokenB) external view returns (address pair)',
 ]);
-/**
- * The Uniswap-V2-style constant-product `getAmountOut`, applied with
- * the venue's fee. Reproduces the router's own on-chain formula
- * exactly — see `pulsex-carrier.fork.test.ts` — so PRICE IMPACT IS ALREADY
- * IN HERE: this is the same nonlinear function the router evaluates, not a
- * flat-fee approximation with an impact correction bolted on afterward.
- *
- * @param amountIn - the input amount, in `reserveIn`'s token's base units
- * @param reserveIn - the pool's reserve of the input token
- * @param reserveOut - the pool's reserve of the output token
- * @param feeBasisPoints - the venue's swap fee, in basis points
- * @returns the output amount, in `reserveOut`'s token's base units; 0 when either reserve is 0
- */
 const constantProductAmountOut = (amountIn, reserveIn, reserveOut, feeBasisPoints) => {
     if (reserveIn <= 0n || reserveOut <= 0n || amountIn <= 0n)
         return 0n;
@@ -240,37 +88,11 @@ const constantProductAmountOut = (amountIn, reserveIn, reserveOut, feeBasisPoint
     const denominator = reserveIn * BASIS_POINTS_DENOMINATOR + amountInWithFee;
     return numerator / denominator;
 };
-/**
- * What `amountIn` delivers after crossing every pool of a path in order,
- * chaining {@link constantProductAmountOut}.
- *
- * @param amountIn - the amount entering the first pool
- * @param steps - the pools in order of travel
- * @param feeBasisPoints - the venue's swap fee in basis points; PulseX's 29 when omitted
- * @returns the amount leaving the last pool; 0 when any pool cannot pay out
- */
 export const amountOutAlongPath = (amountIn, steps, feeBasisPoints = PULSEX_FEE_BASIS_POINTS) => steps.reduce((runningAmount, step) => constantProductAmountOut(runningAmount, step.reserveIn, step.reserveOut, feeBasisPoints), amountIn);
-/**
- * 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 const priceImpactAgainstMarginal = (options) => {
     const { amountIn, amountOut, referenceAmountIn, referenceAmountOut } = options;
     if (amountIn <= 0n || referenceAmountIn <= 0n || referenceAmountOut <= 0n)
         return null;
-    // The output the trade would deliver at the marginal rate with no impact.
     const idealAmountOut = (referenceAmountOut * amountIn) / referenceAmountIn;
     if (idealAmountOut <= 0n)
         return null;
@@ -279,26 +101,12 @@ export const priceImpactAgainstMarginal = (options) => {
     const MILLIONTHS = 1000000n;
     return Number(((idealAmountOut - amountOut) * MILLIONTHS * 100n) / idealAmountOut) / Number(MILLIONTHS);
 };
-/** The stable key one pool is stored and looked up under — the two token addresses, lower-cased and sorted, so either query order finds the same entry. */
 const poolKey = (tokenA, tokenB) => {
     const [lower, higher] = [tokenA.toLowerCase(), tokenB.toLowerCase()].sort();
     return `${lower}|${higher}`;
 };
-/** The key one venue's pool is stored under: the same two tokens on V1 and on V2 are two different pools with two different reserves. */
 const venuePoolKey = (venue, tokenA, tokenB) => `${venue.chainId}|${venue.factory.toLowerCase()}|${poolKey(tokenA, tokenB)}`;
-/** Every consecutive (tokenIn, tokenOut) hop a PulseX swap path implies. */
 const hopsAlongPath = (path) => path.slice(0, -1).map((tokenIn, index) => [tokenIn, path[index + 1]]);
-/**
- * The pools a path crosses on one venue, each read in the direction of
- * travel, or null when any of them was never read — `getPair` found no pool,
- * or the read failed. A path with a missing pool cannot be priced, exactly as
- * the router's own `getAmountsOut` would revert on it.
- *
- * @param options.venue - the deployment whose pools the path trades against
- * @param options.path - the tokens, in order
- * @param options.reservesByPoolKey - every pool `prepare` read, keyed by {@link venuePoolKey}
- * @returns the steps in order, or null when a pool is missing
- */
 const stepsAlongPath = (options) => {
     const { venue, path, reservesByPoolKey } = options;
     const steps = [];
@@ -314,35 +122,6 @@ const stepsAlongPath = (options) => {
     }
     return steps;
 };
-/**
- * Batch-reads reserves for every pool `nodes`' candidate PulseX paths touch,
- * on EVERY venue in `venues`, once, so {@link createPulseXCarrier}'s `exact`
- * can answer every hop SYNCHRONOUSLY afterward.
- *
- * EACH VENUE IS READ THROUGH ITS OWN FACTORY. The same two tokens usually
- * have a pool on V1 and another on V2, with different reserves; the two are
- * stored apart ({@link venuePoolKey}) and never blended. `PULSEX_FEE_NUMERATOR`
- * is proven identical for both deployments (see its own doc), so the formula
- * is shared and only the reserves differ.
- *
- * TWO MULTICALLS ON PULSECHAIN, WHATEVER THE VENUE COUNT: `getPair` must
- * resolve each pool's address before `getReserves` can be read from it, so
- * the second read cannot join the first — but every venue's `getPair` rides
- * the first multicall and every pool's `getReserves` rides the second.
- *
- * THE HUB SEARCH WIDENS EACH READ, NOT THEIR NUMBER. Every pool any candidate
- * path crosses is read here ({@link pulseXCandidatePaths}), so `exact` can
- * price every path with no further call. Measured 2026-10-06: an 8-token
- * PulseChain universe asked 84 entries across the two reads (the fixed
- * Wrapped-PLS path asked about 16). The shared multicall helper splits a read
- * past its request-size budget into sequential posts; `getPair` crosses that
- * line at about 11 pool tokens (198 entries over two venues).
- *
- * @param nodes - every node the search might branch through
- * @param venues - the venues this carrier offers
- * @param clientForChain - see {@link CreatePulseXCarrierOptions}'s own field
- * @returns every pool this universe touches, keyed by {@link venuePoolKey} — pools with no `getPair` result are simply absent, not an error
- */
 const preparePulseXReserves = async ({ nodes, venues, clientForChain, }) => {
     const reservesByPoolKey = new Map();
     const chainIds = Object.keys(venues)
@@ -355,12 +134,6 @@ const preparePulseXReserves = async ({ nodes, venues, clientForChain, }) => {
     }
     return reservesByPoolKey;
 };
-/**
- * One chain's share of {@link preparePulseXReserves}: two multicalls, the
- * `getPair` reads and then the `getReserves` reads, over every venue of the
- * chain. A chain with no client, or with no chain description to multicall
- * against, reads nothing.
- */
 const preparePulseXReservesOnChain = async ({ nodes, chainId, venues, clientForChain, }) => {
     const reservesByPoolKey = new Map();
     const client = clientForChain(chainId);
@@ -405,10 +178,6 @@ const preparePulseXReservesOnChain = async ({ nodes, chainId, venues, clientForC
     const pairAddressByPoolKey = new Map();
     poolQueries.forEach((query, index) => {
         const pairAddress = factoryResults[index];
-        // A decoded address is exactly 42 characters; a failed `allowFailure`
-        // call's undecoded revert bytes are almost never that length — see
-        // `omnibridge.ts`'s identical guard for why `typeof` alone cannot tell
-        // success from failure for an address-returning call.
         if (typeof pairAddress === 'string' && pairAddress.length === 42 && pairAddress !== zeroAddress) {
             pairAddressByPoolKey.set(query.key, getAddress(pairAddress));
         }
@@ -433,23 +202,10 @@ const preparePulseXReservesOnChain = async ({ nodes, chainId, venues, clientForC
         const [reserve0, reserve1] = result;
         if (typeof reserve0 !== 'bigint' || typeof reserve1 !== 'bigint')
             return;
-        // Standard Uniswap-V2-style factories sort a pair's tokens before
-        // creating it, so `token0` is always the LEXICOGRAPHICALLY LOWER
-        // address — confirmed against live PulseX pools 2026-09-24 (both V1 and
-        // V2), never re-derived with an extra `token0()` read.
         reservesByPoolKey.set(key, { reserveOfLowerAddress: reserve0, reserveOfHigherAddress: reserve1 });
     });
     return reservesByPoolKey;
 };
-/**
- * The venues a carrier offers: every venue in `venues`, or only the routers
- * the host names. A named router that is in no venue is a configuration
- * error, thrown at construction rather than offered silently.
- *
- * @param venues - the resolved venues
- * @param routers - the routers the host can sign on, or undefined for all
- * @returns the venues, in their original order
- */
 const selectPulseXVenues = (venues, routers) => {
     if (routers === undefined)
         return venues;
@@ -461,18 +217,9 @@ const selectPulseXVenues = (venues, routers) => {
     }
     return Object.freeze(Object.fromEntries(Object.entries(venues).map(([chainId, list]) => [chainId, list.filter(named)])));
 };
-/**
- * Builds the PulseX conversion swap as a plug-in carrier.
- *
- * @param options - see {@link CreatePulseXCarrierOptions}
- * @returns the carrier — `id: 'PulseX'`
- */
 export const createPulseXCarrier = (options) => {
     const { readAmountOut, clientForChain } = options;
     const venues = selectPulseXVenues(resolveSwapVenues(options.venues), options.routers);
-    // ONE EDGE PER VENUE. Each names its router as its `venue`, so the search
-    // quotes and ranks V1 and V2 as two separate hops and the better one wins
-    // on its own figure — and the winner is signed on the router it names.
     const edgesFrom = (from, to) => {
         if (assetNodeKey(from) === assetNodeKey(to))
             return [];
@@ -496,17 +243,10 @@ export const createPulseXCarrier = (options) => {
         return {
             ok: true,
             deliveredAmount: amountOut,
-            // getAmountsOut is exact for the CURRENT block; no slippage tolerance is
-            // modelled here, so the guaranteed figure is left equal to the expected
-            // one, matching the omnibridge carrier's own convention.
             minimumDeliveredAmount: amountOut,
             claimedDurationSeconds: 0,
         };
     };
-    // Populated by `prepare`, read by `exact` — see `omnibridge.ts`'s identical
-    // field for why a mutable closure here is safe (client-side,
-    // one-search-at-a-time; PulseX is likewise "never built into" the shared
-    // display-quote service).
     let reservesByPoolKey = new Map();
     const prepare = async (nodes) => {
         if (clientForChain === undefined)
@@ -516,31 +256,19 @@ export const createPulseXCarrier = (options) => {
     const exact = (edge, amountIn) => {
         if (!pulseXCarries(venues, edge.from, edge.to))
             return null;
-        // Quoted on the edge's OWN venue — the router it will be signed on — and
-        // only on a venue this carrier offers.
         const venue = venueForEdge(venues, edge);
         if (venue === null)
             return null;
-        // EVERY CANDIDATE PATH IS PRICED, AND THE BEST ONE WINS. A path with a
-        // pool `prepare` never found is left out — the same as a router call
-        // that would revert — and a path that pays out nothing is never picked.
         const quotes = pulseXCandidatePaths(edge.from, edge.to).flatMap((path) => {
             const steps = stepsAlongPath({ venue, path, reservesByPoolKey });
             return steps === null ? [] : [{ path, steps, deliveredAmount: amountOutAlongPath(amountIn, steps, venue.feeBasisPoints) }];
         });
-        // No path had every pool read — a structural non-answer, not a refusal
-        // (`exact`'s own doc: `null` means "nothing to say"). NOTE THIS DOES NOT
-        // FALL BACK TO AN ESTIMATE: a carrier with `exact` defined never yields
-        // an `'estimate'` outcome (see `enumerate.ts`'s `resolveHopOutcome`,
-        // branch 1) — `null` here PRUNES the hop entirely, the same as a refusal.
         if (quotes.length === 0)
             return null;
         const best = bestPulseXPathQuote(quotes);
         if (best === null) {
             return { outcome: 'refused', refusal: { kind: 'no-quote', reason: 'no liquidity on this PulseX path', minimumAmount: null } };
         }
-        // Price impact is measured on the CHOSEN path's own pools, with the same
-        // reference trade as before.
         const referenceAmountIn = amountIn / PULSEX_MARGINAL_REFERENCE_DIVISOR;
         const priceImpactPercent = priceImpactAgainstMarginal({
             amountIn,
@@ -548,10 +276,6 @@ export const createPulseXCarrier = (options) => {
             referenceAmountIn,
             referenceAmountOut: amountOutAlongPath(referenceAmountIn, best.steps, venue.feeBasisPoints),
         });
-        // The path rides on the answer, so the signer signs exactly what was
-        // priced (`pulseXSwapPathForHop`). Impact is left off (not zero) when the
-        // reference trade rounds away: an unknown impact must stay unknown so the
-        // quality gate withholds the plan.
         const delivered = { outcome: 'delivered', deliveredAmount: best.deliveredAmount, swapPath: best.path };
         return priceImpactPercent === null ? delivered : { ...delivered, priceImpactPercent };
     };
@@ -562,11 +286,8 @@ export const createPulseXCarrier = (options) => {
         prepare,
         exact,
         isRateLimited: false,
-        // A same-chain swap requires the reader's own wallet signature — never
-        // a by-hand deposit.
         depositMode: 'wallet-signed',
         sender: 'swap',
-        // A same-chain swap settles with the transaction itself.
         settlementSeconds: 0,
     };
 };

package/dist/routing/carriers/wrap.js

@@ -1,48 +1,6 @@
 import { getAddress, zeroAddress } from 'viem';
 import { nativeAssetOut, toChain } from '../../config.js';
 import { assetNodeKey } from '../search/graph.js';
-/**
- * Native-coin wrap/unwrap (PLS <-> WPLS on PulseChain, and the same pair on
- * every other Ethereum-Virtual-Machine chain the search graph touches — ETH
- * <-> WETH, BNB <-> WBNB) as a plug-in `Carrier` for `@gibs/quotes`'s
- * route-search engine. GIBS-SPECIFIC in the sense `omnibridge.ts`/`pulsex.ts`
- * are (see `omnibridge.ts`'s head doc for why this returns a plain object
- * shaped like `Carrier` rather than importing that type) — though the
- * carrier itself names no chain: it derives every wrap pair from
- * `config.ts`'s own `nativeAssetOut` map, so a chain added there gains a
- * wrap edge with no change here.
- *
- * WHY THIS IS A SEPARATE CARRIER FROM PulseX. `pulsex.ts`'s own
- * `readPulseXAmountOut` (via `pulseXSwapPathForEdge` in
- * `packages/ui/src/lib/state/useRouteSearch.ts`) quotes native Pulse AS
- * Wrapped Pulse — both map to the same `quotePathAddress` — so a PLS<->WPLS
- * pair collapses to "no swap to quote" and PulseX has never carried it.
- * There is no PulseX POOL for native-versus-wrapped; it is a 1:1 contract
- * call (`deposit()`/`withdraw(uint256)`), not a trade, so it needed its own
- * carrier rather than a PulseX special case.
- *
- * SENDER: `'swap'`, THE SAME NAME `pulsex.ts` USES — the reader's own
- * connected wallet signs a `deposit()`/`withdraw(uint256)` call on the
- * wrapped token's own contract (WETH9-style; confirmed present on WPLS by
- * bytecode selector 2026-09-24), exactly the wallet a same-chain PulseX swap
- * already uses. WHETHER `settings.ts`'s EXISTING swap-transaction builder
- * (`pulseXSwapTransactionInputs`) CAN BUILD THIS CALL: NO, not without a
- * change there — that builder only ever targets a PulseX ROUTER address and
- * encodes `swapExact*` calldata; a wrap needs `to` = the wrapped token
- * itself and `data` = plain `deposit()`/`withdraw(amount)` calldata, which
- * is a different (and simpler) shape. Sharing the `'swap'` sender name says
- * "the same wallet, the same signing step in the flow" — it does not claim
- * the existing builder already emits this calldata. Building that call is
- * `settings.ts`'s job, out of this carrier's scope; this module answers only
- * the route-search question ("what does this edge deliver, exactly").
- */
-/**
- * Whether this carrier can wrap/unwrap directly between `from` and `to`:
- * same Ethereum-Virtual-Machine chain, and the two addresses are EXACTLY the
- * zero-address/wrapped-native pair `config.ts`'s `nativeAssetOut` names for
- * that chain — nothing else, so a plain token pair that merely happens to
- * share a chain is never mistaken for a wrap.
- */
 const wrapCarries = (from, to) => {
     if (from.ecosystem !== 'evm' || to.ecosystem !== 'evm')
         return false;
@@ -62,22 +20,11 @@ const wrapCarries = (from, to) => {
         return fromAddress === wrapped;
     return false;
 };
-/** Every wrap/unwrap edge is worth exactly `amountIn`, in `edge.to`'s base units — native and wrapped share the same decimals on every chain this carrier has ever seen (18, both sides, everywhere `nativeAssetOut` names). */
 const wrapExact = (edge, amountIn) => {
     if (!wrapCarries(edge.from, edge.to))
         return null;
     return { outcome: 'delivered', deliveredAmount: amountIn };
 };
-/**
- * Builds the native wrap/unwrap carrier as a plug-in.
- *
- * NO OPTIONS, NO `prepare`. There is no local read to batch — a wrap has no
- * minimum, no maximum, no fee rate and no reserve to be wrong about; it is a
- * pure 1:1 identity over every chain `config.ts` names a wrapped-native
- * token for. `exact` alone is total over every edge this carrier offers.
- *
- * @returns the carrier — `id: 'wrap'`
- */
 export const createWrapCarrier = () => {
     const edgesFrom = (from, to) => {
         if (assetNodeKey(from) === assetNodeKey(to))
@@ -94,7 +41,6 @@ export const createWrapCarrier = () => {
         return {
             ok: true,
             deliveredAmount: result.deliveredAmount,
-            // 1:1, always — there is no slippage to guarantee against.
             minimumDeliveredAmount: result.deliveredAmount,
             claimedDurationSeconds: 0,
         };
@@ -105,11 +51,8 @@ export const createWrapCarrier = () => {
         ask,
         exact: wrapExact,
         isRateLimited: false,
-        // A `deposit()`/`withdraw()` call requires the reader's own wallet
-        // signature — never a by-hand deposit.
         depositMode: 'wallet-signed',
         sender: 'swap',
-        // A same-chain call settles with the transaction itself.
         settlementSeconds: 0,
     };
 };

package/dist/routing/composed-route-quality.js

@@ -1,89 +1,6 @@
-/**
- * Whether a composed multi-signature route is good enough to offer at all.
- *
- * WHY A ROUTE NEEDS A GATE THAT A SINGLE CROSSING DOES NOT. A one-signature
- * route that turns out badly costs the reader one transaction and they still
- * hold something they chose. A composed route — an aggregator leg, then an
- * omnibridge crossing, then a swap — strands them between signatures: after
- * the first they hold an anchor token on a chain they did not ask for, and the
- * only way out is to pay again. So a cheap first leg followed by a bad swap is
- * worse than the route it replaced, and the difference has to be found BEFORE
- * the route is listed rather than after the reader has signed.
- *
- * NOTHING HERE COSTS A REQUEST. Both figures the verdict reads are already in
- * hand when a composer runs: the swap's price impact comes from the on-chain
- * `getAmountsOut` pair the estimate already fetched, and the two dollar values
- * come from the route's own basis. The gate is free, which is why it can run
- * on every route rather than only on suspicious ones.
- */
-/**
- * The price impact above which a composed route is withdrawn, in percent.
- *
- * MEASURED RATHER THAN CHOSEN. Across the anchor and size combinations swept
- * on 2026-09-21 — bridged wrapped ether, USD Coin, DAI and USDT into wrapped
- * PulseChain coin, at roughly forty and one hundred and forty United States
- * dollars — the impact ran from 0.008 percent to 0.037 percent, with bridged
- * USDT the one outlier at 0.34 to 0.37 percent. Three percent is two orders of
- * magnitude above the normal case and an order above the worst observed, so it
- * cannot fire on an ordinary route; and it is still far below the point where
- * a reader is quietly losing real money on a leg they cannot undo.
- *
- * See `docs/near-intents-conversion-composition.md` for the full sweep.
- */
 export const COMPOSED_ROUTE_MAX_PRICE_IMPACT_PERCENT = 3;
-/**
- * The end-to-end value loss above which a composed route is withdrawn, in
- * percent of what the reader pays.
- *
- * A SECOND TEST BECAUSE THE FIRST CAN READ FINE ON A BROKEN POOL. Price impact
- * is measured against a marginal reference quote taken from the same pool, so
- * a pool that is uniformly mispriced — a stale pair, a pair holding almost
- * nothing — reports a small impact while paying out far less than the tokens
- * going in are worth. Only comparing the two ends of the journey catches that.
- *
- * Measured whole-journey loss on the same sweep ran from 0.81 to 1.36 percent,
- * of which the swap fee alone is 0.29. Five percent leaves every observed
- * route untouched and still stops a route that is quietly eating a twentieth
- * of the reader's money.
- */
 export const COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT = 5;
-/**
- * The end-to-end value GAIN above which a composed route is withdrawn, in
- * percent of what the reader pays.
- *
- * A ROUTE CANNOT MAKE MONEY. Every leg charges a fee, so a route that
- * delivers more value than it takes says one of its figures is wrong. Only a
- * disagreement between the two price feeds can make a gain look real, and the
- * value-loss ceiling already trusts those feeds to within the same five
- * percent. So the bound is symmetric with
- * {@link COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT}.
- *
- * THE DEFECT THIS STOPS. On 2026-10-03 the engine served 0.0002 BNB to HEX at
- * 495,256 HEX, about seven thousand times the rate of the next tier. The
- * value-loss test read that as a loss of minus seven hundred thousand percent
- * and passed it. A PulseX hop rescaled from an upstream live answer keeps the
- * price impact measured at its original, smaller input
- * (`recomposePath` in `@gibs/quotes`'s `search/waves.ts`), so the impact test
- * cannot see an inflated amount either. Only the two ends of the journey can.
- */
 export const COMPOSED_ROUTE_MAX_VALUE_GAIN_PERCENT = 5;
-/**
- * Judges a composed route against its three ceilings.
- *
- * Checks price impact first, then value loss, then value gain. Impact names
- * the specific leg at fault, while the two value tests only say the journey as
- * a whole went wrong, so impact is the more useful answer when several fail.
- * In the measured percent of a `'value-gain'` rejection, the gain is a
- * positive number.
- *
- * @param options.priceImpactPercent - the swap leg's price impact, from the
- *   estimate's marginal reference quote; null when not yet quoted
- * @param options.paidUsdValue - what the reader spends at the origin, in
- *   United States dollars; null when unpriced
- * @param options.deliveredUsdValue - what the route delivers, valued on the
- *   SAME basis as `paidUsdValue`; null when unpriced
- * @returns the verdict
- */
 export const assessComposedRoute = ({ priceImpactPercent, paidUsdValue, deliveredUsdValue, }) => {
     if (typeof priceImpactPercent !== 'number' || !Number.isFinite(priceImpactPercent)) {
         return { state: 'unknown', missing: 'price-impact' };
@@ -124,16 +41,4 @@ export const assessComposedRoute = ({ priceImpactPercent, paidUsdValue, delivere
     }
     return { state: 'acceptable' };
 };
-/**
- * Whether a composed route may be listed on the strip.
- *
- * ONLY AN EXPLICIT PASS LISTS THE ROUTE. An unknown verdict withholds it, the
- * same as a rejection, because a three-signature route nobody has checked is
- * the case this gate exists for. The two remain distinct in
- * {@link ComposedRouteVerdict} so a surface can tell the reader "still
- * pricing" rather than "no route", which a boolean alone could not.
- *
- * @param verdict - the verdict from {@link assessComposedRoute}
- * @returns true only when the route passed every ceiling
- */
 export const composedRouteMayBeOffered = (verdict) => verdict.state === 'acceptable';