@gibs/bridge-sdk 1.12.0 → 1.13.0

package/dist/routing/carriers/pulsex.js

@@ -0,0 +1,404 @@
+import { multicallRead } from '@gibs/common/multicall';
+import { getAddress, parseAbi, zeroAddress } from 'viem';
+import * as abis from '../../abis.js';
+import { chainsMetadata } from '../../chains.js';
+import { Chains, nativeAssetOut, toChain, uniV2Factories, uniV2Routers } from '../../config.js';
+import { sameAddress } from '../../ecosystems.js';
+import { pulseXConversionSwapPath } from '../providers.js';
+import { pulsechainChainId } from '../producers.js';
+import { assetNodeKey } from '../search/graph.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 = nativeAssetOut[Chains.PLS];
+/**
+ * Every PulseX deployment on PulseChain, V1 first: `uniV2Routers` paired with
+ * `uniV2Factories` by index. Each factory is the router's own
+ * `router.factory()` read on chain — see `uniV2Factories`'s own doc in
+ * `config.ts`. A router with no recorded factory is left out, because its
+ * pools cannot be read.
+ */
+export const pulseXVenues = (uniV2Routers[Chains.PLS] ?? []).flatMap((router, index) => {
+    const factory = uniV2Factories[Chains.PLS]?.[index];
+    return factory === undefined ? [] : [{ router: getAddress(router), factory: 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 = 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
+ */
+export const pulseXRouterForEdge = (edge) => pulseXVenueForEdge(edge)?.router ?? null;
+/**
+ * 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 pulseXVenues.find((candidate) => 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 pulseXPoolPath}'s own doc.
+ *
+ * @param node - the node to resolve
+ * @returns the node's own address, or {@link wplsAddress} for native PLS
+ */
+const poolTokenAddress = (node) => (sameAddress(node.address, zeroAddress, 'evm') ? wplsAddress : node.address);
+/**
+ * The router swap path a PulseX hop from `from` to `to` prices and signs
+ * along, or null when there is no swap for PulseX to do — including when
+ * both ends resolve to the SAME pool token, which is true of PLS<->WPLS
+ * (native PLS resolves to {@link wplsAddress} via {@link poolTokenAddress},
+ * same as Wrapped PLS itself): that pair is the wrap carrier's job, never a
+ * PulseX hop, so this returns null rather than a zero-length or self-paired
+ * path.
+ *
+ * EVERY PULSEX QUOTE AND SIGNATURE IN THIS FILE MUST GO THROUGH THIS ONE
+ * FUNCTION — `pulseXCarries`, `prepare`'s pool discovery, and `exact`'s hop
+ * pricing all call it, so native PLS resolves the same way in every one of
+ * them. Before this existed, `pulseXCarries` and `prepare`/`exact` called
+ * `pulseXConversionSwapPath` directly on the raw node address: a native PLS
+ * node produced a path that LITERALLY STARTED WITH THE ZERO ADDRESS
+ * (`[zeroAddress, wplsAddress, ...]`), which `pulseXCarries` accepted (its
+ * length is still >= 2) but for which `prepare` could never find a pool —
+ * the factory has no pair for the zero address — so `exact` always answered
+ * `null` for a direct native-PLS PulseX hop, and `enumerate.ts` pruned it,
+ * leaving only the two-signature wrap-then-swap path.
+ *
+ * @param from - the hop's origin node
+ * @param to - the hop's destination node
+ * @returns the swap path, or null when there is nothing for PulseX to swap
+ */
+export const pulseXPoolPath = (from, to) => {
+    const fromAddress = poolTokenAddress(from);
+    const toAddress = poolTokenAddress(to);
+    if (sameAddress(fromAddress, toAddress, 'evm'))
+        return null;
+    return pulseXConversionSwapPath(fromAddress, toAddress, wplsAddress);
+};
+/**
+ * Whether PulseX can carry funds directly from `from` to `to`: both must be
+ * distinct Ethereum-Virtual-Machine tokens on PulseChain itself — PulseX runs
+ * only on PulseChain, never on an entry chain.
+ *
+ * NO TOKEN ALLOWLIST IS CONSULTED, on purpose: "any PulseChain token with a
+ * {@link pulseXPoolPath}" is every PulseChain token, because that function
+ * is total over any two addresses that do not resolve to the same pool
+ * token — it collapses to a direct hop only when one side is already WPLS,
+ * and otherwise always routes through WPLS. This calls it anyway and checks
+ * the result is at least two addresses long, so a future change that
+ * narrowed it to return an empty path for some input would fail this
+ * predicate rather than silently offer a hop with no path.
+ */
+const pulseXCarries = (from, to) => {
+    if (from.ecosystem !== 'evm' || to.ecosystem !== 'evm')
+        return false;
+    if (from.chainId !== pulsechainChainId || to.chainId !== pulsechainChainId)
+        return false;
+    const swapPath = pulseXPoolPath(from, to);
+    return swapPath !== null && swapPath.length >= 2;
+};
+/**
+ * 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 = 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;
+};
+/** 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]]);
+/**
+ * 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.
+ *
+ * @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(pulsechainChainId);
+    if (client === null || venues.length === 0)
+        return reservesByPoolKey;
+    const pulsechainNodes = nodes.filter((node) => node.ecosystem === 'evm' && node.chainId === pulsechainChainId);
+    const poolTokenPairs = new Map();
+    for (const from of pulsechainNodes) {
+        for (const to of pulsechainNodes) {
+            if (assetNodeKey(from) === assetNodeKey(to))
+                continue;
+            if (!pulseXCarries(from, to))
+                continue;
+            const path = pulseXPoolPath(from, to);
+            if (path === null)
+                continue;
+            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 multicallRead({
+        chain: chainsMetadata[toChain(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 !== zeroAddress) {
+            pairAddressByPoolKey.set(query.key, getAddress(pairAddress));
+        }
+    });
+    if (pairAddressByPoolKey.size === 0)
+        return reservesByPoolKey;
+    const reservePoolKeys = Array.from(pairAddressByPoolKey.keys());
+    const reserveResults = await multicallRead({
+        chain: chainsMetadata[toChain(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 pulseXVenues;
+    for (const router of routers) {
+        if (!pulseXVenues.some((venue) => sameAddress(venue.router, router, 'evm'))) {
+            throw new Error(`createPulseXCarrier: ${router} is not a known PulseX router on PulseChain`);
+        }
+    }
+    return pulseXVenues.filter((venue) => routers.some((router) => 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'`
+ */
+export 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 (assetNodeKey(from) === 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;
+        const path = pulseXPoolPath(edge.from, edge.to);
+        if (path === null)
+            return null;
+        const hops = hopsAlongPath(path);
+        if (hops.length === 0)
+            return null;
+        let runningAmount = amountIn;
+        for (const [tokenIn, tokenOut] of hops) {
+            const reserves = reservesByPoolKey.get(venuePoolKey(venue, tokenIn, tokenOut));
+            // `prepare` never read this pool — 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 (reserves === undefined)
+                return null;
+            const tokenInIsLower = tokenIn.toLowerCase() < tokenOut.toLowerCase();
+            const reserveIn = tokenInIsLower ? reserves.reserveOfLowerAddress : reserves.reserveOfHigherAddress;
+            const reserveOut = tokenInIsLower ? reserves.reserveOfHigherAddress : reserves.reserveOfLowerAddress;
+            const hopAmountOut = constantProductAmountOut(runningAmount, reserveIn, reserveOut);
+            if (hopAmountOut <= 0n) {
+                return { outcome: 'refused', refusal: { kind: 'no-quote', reason: 'no liquidity on this PulseX path', minimumAmount: null } };
+            }
+            runningAmount = hopAmountOut;
+        }
+        return { outcome: 'delivered', deliveredAmount: runningAmount };
+    };
+    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,
+    };
+};

package/dist/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;
+};

package/dist/routing/carriers/wrap.js

@@ -0,0 +1,115 @@
+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;
+    if (from.chainId !== to.chainId)
+        return false;
+    const wrappedNativeAddress = nativeAssetOut[toChain(from.chainId)];
+    if (wrappedNativeAddress === undefined)
+        return false;
+    const wrapped = getAddress(wrappedNativeAddress).toLowerCase();
+    const fromAddress = from.address.toLowerCase();
+    const toAddress = to.address.toLowerCase();
+    const fromIsNative = fromAddress === zeroAddress;
+    const toIsNative = toAddress === zeroAddress;
+    if (fromIsNative)
+        return toAddress === wrapped;
+    if (toIsNative)
+        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))
+            return [];
+        if (!wrapCarries(from, to))
+            return [];
+        return [{ carrier: 'wrap', from, to, fusesNext: false, origin: 'wallet', floors: [] }];
+    };
+    const ask = async ({ edge, inputAmount }) => {
+        const result = wrapExact(edge, inputAmount);
+        if (result === null || result.outcome === 'refused') {
+            return { ok: false, refusal: { kind: 'cannot-carry', reason: 'not a native/wrapped pair', minimumAmount: null } };
+        }
+        return {
+            ok: true,
+            deliveredAmount: result.deliveredAmount,
+            // 1:1, always — there is no slippage to guarantee against.
+            minimumDeliveredAmount: result.deliveredAmount,
+            claimedDurationSeconds: 0,
+        };
+    };
+    return {
+        id: 'wrap',
+        edgesFrom,
+        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.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 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 declare 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 declare const COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT = 5;
+/**
+ * The verdict on one composed route.
+ *
+ * THREE STATES RATHER THAN A BOOLEAN, because "we have not priced this yet"
+ * and "we priced it and it is bad" are different facts and a caller must be
+ * able to act differently on them. Collapsing them would either hide a route
+ * that is merely still loading or offer one nobody has checked.
+ */
+export type ComposedRouteVerdict = {
+    readonly state: 'acceptable';
+} | {
+    readonly state: 'unknown';
+    readonly missing: 'price-impact' | 'route-value';
+} | {
+    readonly state: 'rejected';
+    readonly reason: 'price-impact' | 'value-loss';
+    /** The measured figure, in percent, that failed its ceiling. */
+    readonly measuredPercent: number;
+    /** The ceiling it failed. */
+    readonly ceilingPercent: number;
+};
+/**
+ * Judges a composed route against both ceilings.
+ *
+ * Checks price impact first and value loss second, because impact names the
+ * specific leg at fault while value loss only says the journey as a whole went
+ * wrong — so reporting impact when both fail is the more useful answer.
+ *
+ * @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 declare const assessComposedRoute: ({ priceImpactPercent, paidUsdValue, deliveredUsdValue, }: {
+    priceImpactPercent: number | null | undefined;
+    paidUsdValue: number | null | undefined;
+    deliveredUsdValue: number | null | undefined;
+}) => ComposedRouteVerdict;
+/**
+ * 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 both ceilings
+ */
+export declare const composedRouteMayBeOffered: (verdict: ComposedRouteVerdict) => boolean;