@gibs/bridge-sdk 1.13.0 → 1.17.0

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

@@ -0,0 +1,565 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPulseXCarrier = exports.priceImpactAgainstMarginal = exports.amountOutAlongPath = exports.pulseXSwapPathForHop = exports.pulseXWrappedNativePath = exports.pulseXRouterForEdge = exports.pulseXVenues = void 0;
+const multicall_1 = require("@gibs/common/multicall");
+const viem_1 = require("viem");
+const abis = __importStar(require("../../abis.js"));
+const chains_js_1 = require("../../chains.js");
+const config_js_1 = require("../../config.js");
+const ecosystems_js_1 = require("../../ecosystems.js");
+const providers_js_1 = require("../providers.js");
+const producers_js_1 = require("../producers.js");
+const graph_js_1 = require("../search/graph.js");
+const pulsex_paths_js_1 = require("./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.
+ */
+/** WPLS, the wrapped-native intermediary {@link pulseXConversionSwapPath} routes conversions through. */
+const wplsAddress = config_js_1.nativeAssetOut[config_js_1.Chains.PLS];
+/** The hub addresses every candidate path is built from — see {@link pulseXHubTokens}. */
+const hubAddresses = pulsex_paths_js_1.pulseXHubTokens.map((hub) => hub.address);
+/**
+ * Every PulseX deployment on PulseChain, V1 first: `uniV2Routers` paired with
+ * `uniV2Factories` by index. Each factory is the router's own
+ * `router.factory()` read on chain — see `uniV2Factories`'s own doc in
+ * `config.ts`. A router with no recorded factory is left out, because its
+ * pools cannot be read.
+ */
+exports.pulseXVenues = (config_js_1.uniV2Routers[config_js_1.Chains.PLS] ?? []).flatMap((router, index) => {
+    const factory = config_js_1.uniV2Factories[config_js_1.Chains.PLS]?.[index];
+    return factory === undefined ? [] : [{ router: (0, viem_1.getAddress)(router), factory: (0, viem_1.getAddress)(factory) }];
+});
+/**
+ * The venue an edge with no {@link HopEdge.venue} runs on: V1, index 0. Every
+ * PulseX edge built before venues existed was quoted and signed on V1 — the
+ * same-chain swap sender's own hand-built edge still is — so this keeps that
+ * meaning rather than guessing a new one.
+ */
+const defaultPulseXVenue = exports.pulseXVenues[0];
+/**
+ * The router a PulseX edge must be signed on — the one its figure was quoted
+ * against. Reads the edge's own {@link HopEdge.venue}; an edge with none is a
+ * V1 edge (see {@link defaultPulseXVenue}).
+ *
+ * @param edge - the edge to sign
+ * @returns the router, or null when the edge is not a PulseX edge or names a venue that is not a known PulseX router
+ */
+const pulseXRouterForEdge = (edge) => pulseXVenueForEdge(edge)?.router ?? null;
+exports.pulseXRouterForEdge = pulseXRouterForEdge;
+/**
+ * The {@link PulseXVenue} a PulseX edge runs on — see {@link pulseXRouterForEdge}.
+ *
+ * @param edge - the edge
+ * @returns the venue, or null when there is none
+ */
+const pulseXVenueForEdge = (edge) => {
+    if (edge.carrier !== 'PulseX')
+        return null;
+    if (edge.venue === undefined)
+        return defaultPulseXVenue ?? null;
+    const venue = edge.venue;
+    return exports.pulseXVenues.find((candidate) => (0, ecosystems_js_1.sameAddress)(candidate.router, venue, 'evm')) ?? null;
+};
+/**
+ * A node's own address for a PulseX pool lookup: native PLS (the zero
+ * address) is not a token the router or its factory ever holds a pool for —
+ * only Wrapped PLS is — so a native node resolves to {@link wplsAddress}
+ * before it ever reaches {@link pulseXConversionSwapPath}. Every other node
+ * is unchanged.
+ *
+ * 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 {@link wplsAddress} for native PLS
+ */
+const poolTokenAddress = (node) => ((0, ecosystems_js_1.sameAddress)(node.address, viem_1.zeroAddress, 'evm') ? wplsAddress : 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
+ */
+const pulseXWrappedNativePath = (from, to) => {
+    const fromAddress = poolTokenAddress(from);
+    const toAddress = poolTokenAddress(to);
+    if ((0, ecosystems_js_1.sameAddress)(fromAddress, toAddress, 'evm'))
+        return null;
+    return (0, providers_js_1.pulseXConversionSwapPath)(fromAddress, toAddress, wplsAddress);
+};
+exports.pulseXWrappedNativePath = pulseXWrappedNativePath;
+/**
+ * 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 ((0, ecosystems_js_1.sameAddress)(fromAddress, toAddress, 'evm'))
+        return [];
+    return (0, pulsex_paths_js_1.candidatePulseXPaths)({ from: fromAddress, to: toAddress, wrappedNative: wplsAddress, hubs: hubAddresses });
+};
+/**
+ * Whether PulseX can carry funds directly from `from` to `to`: both must be
+ * Ethereum-Virtual-Machine tokens on PulseChain itself — PulseX runs only on
+ * PulseChain, never on an entry chain — that resolve to two 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 = (from, to) => {
+    if (from.ecosystem !== 'evm' || to.ecosystem !== 'evm')
+        return false;
+    if (from.chainId !== producers_js_1.pulsechainChainId || to.chainId !== producers_js_1.pulsechainChainId)
+        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
+ */
+const pulseXSwapPathForHop = (hop) => {
+    if (hop.edge.carrier !== 'PulseX')
+        return null;
+    const swapPath = hop.outcome.swapPath;
+    if (swapPath === undefined || swapPath.length < 2)
+        return null;
+    if (!swapPath.every((address) => (0, viem_1.isAddress)(address, { strict: false })))
+        return null;
+    const path = swapPath.map((address) => (0, viem_1.getAddress)(address));
+    if (new Set(path).size !== path.length)
+        return null;
+    if (!(0, ecosystems_js_1.sameAddress)(path[0], poolTokenAddress(hop.edge.from), 'evm'))
+        return null;
+    if (!(0, ecosystems_js_1.sameAddress)(path[path.length - 1], poolTokenAddress(hop.edge.to), 'evm'))
+        return null;
+    return path;
+};
+exports.pulseXSwapPathForHop = pulseXSwapPathForHop;
+/**
+ * PulseX's own constant-product swap fee, as a numerator over
+ * {@link PULSEX_FEE_DENOMINATOR} — 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_NUMERATOR = 9971n;
+/** The denominator {@link PULSEX_FEE_NUMERATOR} is a fraction of. */
+const PULSEX_FEE_DENOMINATOR = 10000n;
+/** The minimal read-only factory ABI `prepare` needs — just enough to resolve a pool's address from its two tokens. */
+const univ2FactoryAbi = (0, viem_1.parseAbi)([
+    'function getPair(address tokenA, address tokenB) external view returns (address pair)',
+]);
+/**
+ * The Uniswap-V2-style constant-product `getAmountOut`, applied with
+ * {@link PULSEX_FEE_NUMERATOR}. 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
+ * @returns the output amount, in `reserveOut`'s token's base units; 0 when either reserve is 0
+ */
+const constantProductAmountOut = (amountIn, reserveIn, reserveOut) => {
+    if (reserveIn <= 0n || reserveOut <= 0n || amountIn <= 0n)
+        return 0n;
+    const amountInWithFee = amountIn * PULSEX_FEE_NUMERATOR;
+    const numerator = amountInWithFee * reserveOut;
+    const denominator = reserveIn * PULSEX_FEE_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
+ * @returns the amount leaving the last pool; 0 when any pool cannot pay out
+ */
+const amountOutAlongPath = (amountIn, steps) => steps.reduce((runningAmount, step) => constantProductAmountOut(runningAmount, step.reserveIn, step.reserveOut), amountIn);
+exports.amountOutAlongPath = amountOutAlongPath;
+/**
+ * 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)
+ */
+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;
+    if (amountOut >= idealAmountOut)
+        return 0;
+    const MILLIONTHS = 1000000n;
+    return Number(((idealAmountOut - amountOut) * MILLIONTHS * 100n) / idealAmountOut) / Number(MILLIONTHS);
+};
+exports.priceImpactAgainstMarginal = priceImpactAgainstMarginal;
+/** 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.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 = [];
+    for (const [tokenIn, tokenOut] of hopsAlongPath(path)) {
+        const reserves = reservesByPoolKey.get(venuePoolKey(venue, tokenIn, tokenOut));
+        if (reserves === undefined)
+            return null;
+        const tokenInIsLower = tokenIn.toLowerCase() < tokenOut.toLowerCase();
+        steps.push({
+            reserveIn: tokenInIsLower ? reserves.reserveOfLowerAddress : reserves.reserveOfHigherAddress,
+            reserveOut: tokenInIsLower ? reserves.reserveOfHigherAddress : reserves.reserveOfLowerAddress,
+        });
+    }
+    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 client = clientForChain(producers_js_1.pulsechainChainId);
+    if (client === null || venues.length === 0)
+        return reservesByPoolKey;
+    const pulsechainNodes = nodes.filter((node) => node.ecosystem === 'evm' && node.chainId === producers_js_1.pulsechainChainId);
+    const poolTokenPairs = new Map();
+    for (const from of pulsechainNodes) {
+        for (const to of pulsechainNodes) {
+            if ((0, graph_js_1.assetNodeKey)(from) === (0, graph_js_1.assetNodeKey)(to))
+                continue;
+            if (!pulseXCarries(from, to))
+                continue;
+            for (const path of pulseXCandidatePaths(from, to)) {
+                for (const [tokenIn, tokenOut] of hopsAlongPath(path)) {
+                    poolTokenPairs.set(poolKey(tokenIn, tokenOut), [tokenIn, tokenOut]);
+                }
+            }
+        }
+    }
+    if (poolTokenPairs.size === 0)
+        return reservesByPoolKey;
+    const poolQueries = venues.flatMap((venue) => Array.from(poolTokenPairs.values()).map(([tokenIn, tokenOut]) => ({
+        key: venuePoolKey(venue, tokenIn, tokenOut),
+        factory: venue.factory,
+        tokenIn,
+        tokenOut,
+    })));
+    const factoryResults = await (0, multicall_1.multicallRead)({
+        chain: chains_js_1.chainsMetadata[(0, config_js_1.toChain)(producers_js_1.pulsechainChainId)],
+        client,
+        abi: univ2FactoryAbi,
+        calls: poolQueries.map((query) => ({
+            functionName: 'getPair',
+            target: query.factory,
+            args: [query.tokenIn, query.tokenOut],
+            allowFailure: true,
+        })),
+    });
+    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 !== viem_1.zeroAddress) {
+            pairAddressByPoolKey.set(query.key, (0, viem_1.getAddress)(pairAddress));
+        }
+    });
+    if (pairAddressByPoolKey.size === 0)
+        return reservesByPoolKey;
+    const reservePoolKeys = Array.from(pairAddressByPoolKey.keys());
+    const reserveResults = await (0, multicall_1.multicallRead)({
+        chain: chains_js_1.chainsMetadata[(0, config_js_1.toChain)(producers_js_1.pulsechainChainId)],
+        client,
+        abi: abis.pair,
+        calls: reservePoolKeys.map((key) => ({
+            functionName: 'getReserves',
+            target: pairAddressByPoolKey.get(key),
+            allowFailure: true,
+        })),
+    });
+    reservePoolKeys.forEach((key, index) => {
+        const result = reserveResults[index];
+        if (!Array.isArray(result))
+            return;
+        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 known venue, or only the routers the
+ * host names. A named router that is not a known PulseX router is a
+ * configuration error, thrown at construction rather than offered silently.
+ *
+ * @param routers - the routers the host can sign on, or undefined for all
+ * @returns the venues, in {@link pulseXVenues} order
+ */
+const selectPulseXVenues = (routers) => {
+    if (routers === undefined)
+        return exports.pulseXVenues;
+    for (const router of routers) {
+        if (!exports.pulseXVenues.some((venue) => (0, ecosystems_js_1.sameAddress)(venue.router, router, 'evm'))) {
+            throw new Error(`createPulseXCarrier: ${router} is not a known PulseX router on PulseChain`);
+        }
+    }
+    return exports.pulseXVenues.filter((venue) => routers.some((router) => (0, ecosystems_js_1.sameAddress)(venue.router, router, 'evm')));
+};
+/**
+ * Builds the PulseX conversion swap as a plug-in carrier.
+ *
+ * @param options - see {@link CreatePulseXCarrierOptions}
+ * @returns the carrier — `id: 'PulseX'`
+ */
+const createPulseXCarrier = (options) => {
+    const { readAmountOut, clientForChain } = options;
+    const venues = selectPulseXVenues(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 ((0, graph_js_1.assetNodeKey)(from) === (0, graph_js_1.assetNodeKey)(to))
+            return [];
+        if (!pulseXCarries(from, to))
+            return [];
+        return venues.map((venue) => ({
+            carrier: 'PulseX',
+            from,
+            to,
+            fusesNext: false,
+            origin: 'wallet',
+            floors: [],
+            venue: venue.router,
+        }));
+    };
+    const ask = async ({ edge, inputAmount }) => {
+        const amountOut = await readAmountOut(edge, inputAmount);
+        if (amountOut === null || amountOut <= 0n) {
+            return { ok: false, refusal: { kind: 'no-quote', reason: 'no liquidity on this PulseX path', minimumAmount: null } };
+        }
+        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)
+            return;
+        reservesByPoolKey = await preparePulseXReserves({ nodes, venues, clientForChain });
+    };
+    const exact = (edge, amountIn) => {
+        if (!pulseXCarries(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 = pulseXVenueForEdge(edge);
+        if (venue === null || !venues.includes(venue))
+            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: (0, exports.amountOutAlongPath)(amountIn, steps) }];
+        });
+        // 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 = (0, pulsex_paths_js_1.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 / producers_js_1.PULSEX_MARGINAL_REFERENCE_DIVISOR;
+        const priceImpactPercent = (0, exports.priceImpactAgainstMarginal)({
+            amountIn,
+            amountOut: best.deliveredAmount,
+            referenceAmountIn,
+            referenceAmountOut: (0, exports.amountOutAlongPath)(referenceAmountIn, best.steps),
+        });
+        // 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 };
+    };
+    return {
+        id: 'PulseX',
+        edgesFrom,
+        ask,
+        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,
+    };
+};
+exports.createPulseXCarrier = createPulseXCarrier;

package/dist/cjs/routing/carriers/wrap.d.ts

@@ -0,0 +1,25 @@
+import { type AssetNode, type HopEdge } from '../search/graph.js';
+import type { CarrierAskAnswer, CarrierExactResult } from './ask-answer.js';
+/**
+ * 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 declare const createWrapCarrier: () => {
+    id: string;
+    edgesFrom: (from: AssetNode, to: AssetNode) => readonly HopEdge[];
+    ask: ({ edge, inputAmount }: {
+        edge: HopEdge;
+        inputAmount: bigint;
+    }) => Promise<CarrierAskAnswer>;
+    exact: (edge: HopEdge, amountIn: bigint) => CarrierExactResult | null;
+    isRateLimited: boolean;
+    depositMode: "wallet-signed";
+    sender: "swap";
+    settlementSeconds: number;
+};