@gibs/bridge-sdk 1.13.1 → 1.17.0

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

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

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

@@ -0,0 +1,80 @@
+import { type Hex } from 'viem';
+/**
+ * Which swap path a PulseX hop takes. The hop no longer always goes through
+ * Wrapped PLS: the carrier prices every candidate path from the pool reserves
+ * it already read, and keeps the one that delivers the most. These are the
+ * pure parts of that choice — the hub list, the candidate paths, and the
+ * pick — kept apart from the carrier so each can be tested on its own.
+ */
+/** One token a PulseX swap may pass through on its way from the input token to the output token. */
+export type PulseXHubToken = {
+    /** The token's on-chain `symbol()`, for logs and tests only. Never used to match a token. */
+    readonly symbol: string;
+    /** The token's checksummed PulseChain address. Tokens are always matched by this. */
+    readonly address: Hex;
+};
+/**
+ * The tokens a PulseX swap may route through, Wrapped PLS first. Each address
+ * comes from a constant this package already holds; none is written here:
+ *
+ * - WPLS — `nativeAssetOut[Chains.PLS]` (`config.ts`).
+ * - PLSX, HEX, USDC, USDT — `pulsechainTokenAddresses` (`config.ts`).
+ * - DAI (from Ethereum) — `PULSECHAIN_USD_ANCHOR_ADDRESS` (`prices.ts`).
+ * - WETH (from Ethereum) — the Ethereum pathway's `bridgedNativeAssetOut` (`config.ts`).
+ *
+ * KEPT SMALL ON PURPOSE. Each hub adds pools to the one batched reserve read
+ * the carrier makes per search, and adds paths to every price it computes.
+ * Seven hubs give at most 20 candidate paths per hop (see
+ * {@link candidatePulseXPaths}).
+ */
+export declare const pulseXHubTokens: readonly PulseXHubToken[];
+/**
+ * Every swap path a PulseX hop from `from` to `to` may take:
+ *
+ * - direct: `[from, to]`;
+ * - one hub: `[from, hub, to]` for each hub, Wrapped PLS among them;
+ * - two hubs: `[from, wrappedNative, hub, to]` and `[from, hub, wrappedNative, to]`
+ *   for each other hub — Wrapped PLS holds the deepest pools on PulseX, so it
+ *   is the one middle token worth pairing with every other hub.
+ *
+ * A path that names a token twice is dropped. That removes every path whose
+ * hub IS `from` or `to`, and the same-token hop when `from` equals `to`.
+ *
+ * The fixed path this carrier used before — `[from, WPLS, to]`, or
+ * `[from, to]` when one side is WPLS — is always in the result, so the pick
+ * can only match or beat it.
+ *
+ * @param options.from - the pool token the swap spends
+ * @param options.to - the pool token the swap buys
+ * @param options.wrappedNative - Wrapped PLS
+ * @param options.hubs - the hub token addresses, Wrapped PLS included
+ * @returns the candidate paths, direct first, each at least two tokens long
+ */
+export declare const candidatePulseXPaths: (options: {
+    readonly from: Hex;
+    readonly to: Hex;
+    readonly wrappedNative: Hex;
+    readonly hubs: readonly Hex[];
+}) => readonly (readonly Hex[])[];
+/** One candidate path, priced. */
+export type PulseXPathQuote<Step> = {
+    /** The tokens the swap passes through, in order. */
+    readonly path: readonly Hex[];
+    /** What the path delivers for the trade, in the last token's base units. */
+    readonly deliveredAmount: bigint;
+    /** The pools the path crosses, in order — kept so the caller can measure price impact on the same pools. */
+    readonly steps: readonly Step[];
+};
+/**
+ * The priced path that delivers the most. A path that delivers nothing is
+ * never chosen. Among equal outputs the path with fewer pools wins, and among
+ * equal lengths the earlier candidate wins, so the pick is deterministic.
+ *
+ * Gas is not weighed beyond that tie-break: the search charges one flat gas
+ * figure per swap signature, whatever its path length (`route-search-gas.ts`
+ * in the interface), so there is no per-pool gas figure to subtract here.
+ *
+ * @param quotes - the priced candidates; paths with a missing pool are already left out
+ * @returns the best candidate, or null when none delivers anything
+ */
+export declare const bestPulseXPathQuote: <Step>(quotes: readonly PulseXPathQuote<Step>[]) => PulseXPathQuote<Step> | null;

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

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bestPulseXPathQuote = exports.candidatePulseXPaths = exports.pulseXHubTokens = void 0;
+const viem_1 = require("viem");
+const config_js_1 = require("../../config.js");
+const prices_js_1 = require("../../prices.js");
+/** Wrapped PLS: the first hub, and the middle token of every two-hub path. */
+const wrappedPulseAddress = (0, viem_1.getAddress)(config_js_1.nativeAssetOut[config_js_1.Chains.PLS]);
+/** The Ethereum-bridged WETH on PulseChain, read off the Ethereum pathway's own config. Undefined only if that pathway is removed. */
+const bridgedWrappedEtherAddress = config_js_1.pathways[config_js_1.Providers.PULSECHAIN][config_js_1.Chains.PLS]?.[config_js_1.Chains.ETH]?.bridgedNativeAssetOut;
+/**
+ * The tokens a PulseX swap may route through, Wrapped PLS first. Each address
+ * comes from a constant this package already holds; none is written here:
+ *
+ * - WPLS — `nativeAssetOut[Chains.PLS]` (`config.ts`).
+ * - PLSX, HEX, USDC, USDT — `pulsechainTokenAddresses` (`config.ts`).
+ * - DAI (from Ethereum) — `PULSECHAIN_USD_ANCHOR_ADDRESS` (`prices.ts`).
+ * - WETH (from Ethereum) — the Ethereum pathway's `bridgedNativeAssetOut` (`config.ts`).
+ *
+ * KEPT SMALL ON PURPOSE. Each hub adds pools to the one batched reserve read
+ * the carrier makes per search, and adds paths to every price it computes.
+ * Seven hubs give at most 20 candidate paths per hop (see
+ * {@link candidatePulseXPaths}).
+ */
+exports.pulseXHubTokens = Object.freeze([
+    { symbol: 'WPLS', address: wrappedPulseAddress },
+    { symbol: 'PLSX', address: config_js_1.pulsechainTokenAddresses.PLSX },
+    { symbol: 'HEX', address: config_js_1.pulsechainTokenAddresses.HEX },
+    { symbol: 'DAI', address: (0, viem_1.getAddress)(prices_js_1.PULSECHAIN_USD_ANCHOR_ADDRESS) },
+    { symbol: 'USDC', address: config_js_1.pulsechainTokenAddresses.USDC },
+    { symbol: 'USDT', address: config_js_1.pulsechainTokenAddresses.USDT },
+    ...(bridgedWrappedEtherAddress === undefined ? [] : [{ symbol: 'WETH', address: (0, viem_1.getAddress)(bridgedWrappedEtherAddress) }]),
+].map((hub) => Object.freeze(hub)));
+/** Whether a path names any token twice, compared without regard to letter case. */
+const repeatsAToken = (path) => new Set(path.map((address) => address.toLowerCase())).size !== path.length;
+/** Whether two addresses are the same token, compared without regard to letter case. */
+const sameToken = (left, right) => left.toLowerCase() === right.toLowerCase();
+/**
+ * Every swap path a PulseX hop from `from` to `to` may take:
+ *
+ * - direct: `[from, to]`;
+ * - one hub: `[from, hub, to]` for each hub, Wrapped PLS among them;
+ * - two hubs: `[from, wrappedNative, hub, to]` and `[from, hub, wrappedNative, to]`
+ *   for each other hub — Wrapped PLS holds the deepest pools on PulseX, so it
+ *   is the one middle token worth pairing with every other hub.
+ *
+ * A path that names a token twice is dropped. That removes every path whose
+ * hub IS `from` or `to`, and the same-token hop when `from` equals `to`.
+ *
+ * The fixed path this carrier used before — `[from, WPLS, to]`, or
+ * `[from, to]` when one side is WPLS — is always in the result, so the pick
+ * can only match or beat it.
+ *
+ * @param options.from - the pool token the swap spends
+ * @param options.to - the pool token the swap buys
+ * @param options.wrappedNative - Wrapped PLS
+ * @param options.hubs - the hub token addresses, Wrapped PLS included
+ * @returns the candidate paths, direct first, each at least two tokens long
+ */
+const candidatePulseXPaths = (options) => {
+    const { from, to, wrappedNative, hubs } = options;
+    const oneHubPaths = hubs.map((hub) => [from, hub, to]);
+    const twoHubPaths = hubs
+        .filter((hub) => !sameToken(hub, wrappedNative))
+        .flatMap((hub) => [
+        [from, wrappedNative, hub, to],
+        [from, hub, wrappedNative, to],
+    ]);
+    return [[from, to], ...oneHubPaths, ...twoHubPaths].filter((path) => !repeatsAToken(path));
+};
+exports.candidatePulseXPaths = candidatePulseXPaths;
+/**
+ * Whether `candidate` should replace `best`: it delivers more, or it delivers
+ * the same and crosses fewer pools. A tie goes to the shorter path because
+ * each extra pool costs gas, and nothing else separates the two.
+ */
+const beats = (candidate, best) => {
+    if (candidate.deliveredAmount !== best.deliveredAmount)
+        return candidate.deliveredAmount > best.deliveredAmount;
+    return candidate.path.length < best.path.length;
+};
+/**
+ * The priced path that delivers the most. A path that delivers nothing is
+ * never chosen. Among equal outputs the path with fewer pools wins, and among
+ * equal lengths the earlier candidate wins, so the pick is deterministic.
+ *
+ * Gas is not weighed beyond that tie-break: the search charges one flat gas
+ * figure per swap signature, whatever its path length (`route-search-gas.ts`
+ * in the interface), so there is no per-pool gas figure to subtract here.
+ *
+ * @param quotes - the priced candidates; paths with a missing pool are already left out
+ * @returns the best candidate, or null when none delivers anything
+ */
+const bestPulseXPathQuote = (quotes) => quotes
+    .filter((quote) => quote.deliveredAmount > 0n)
+    .reduce((best, quote) => (best === null || beats(quote, best) ? quote : best), null);
+exports.bestPulseXPathQuote = bestPulseXPathQuote;