@gibs/bridge-sdk 1.12.0 → 1.13.0

package/dist/routing/carriers/omnibridge.js

@@ -0,0 +1,419 @@
+import { multicallRead } from '@gibs/common/multicall';
+import { getAddress, zeroAddress } from 'viem';
+import * as abis from '../../abis.js';
+import { checkEntryAmount, entryLimitsAbi } from '../../bridge-limits.js';
+import { chainsMetadata } from '../../chains.js';
+import { FOREIGN_TO_HOME_FEE, HOME_TO_FOREIGN_FEE, nativeAssetOut, pathway, Providers, pathwayGroup, toChain, } from '../../config.js';
+import { isNativeAsset } from '../../ecosystems.js';
+import { findProviderById } from '../../providers.js';
+import { netDeliveredAmount } from '../amounts.js';
+import { entryChainAnchorsForPair } from '../entry-chain-anchor.js';
+import { BRIDGE_SETTLEMENT_ETA_MINUTES, pulsechainChainId } from '../producers.js';
+import { assetNodeKey } from '../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) => `${assetNodeKey(from)}|${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 = toChain(fromChainId);
+    const toChainKey = toChain(toChainId);
+    const omnibridgeProviders = [Providers.PULSECHAIN, Providers.TOKENSEX];
+    for (const provider of omnibridgeProviders) {
+        const group = 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 = 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, toChain(edge.from.chainId), toChain(edge.to.chainId)];
+    const wrappedNativeAddress = nativeAssetOut[toChain(edge.from.chainId)];
+    const isNativeEntry = edge.from.address.toLowerCase() === zeroAddress;
+    const entryTokenAddress = isNativeEntry && wrappedNativeAddress !== undefined ? getAddress(wrappedNativeAddress) : getAddress(edge.from.address);
+    const path = 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 ? FOREIGN_TO_HOME_FEE : 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 multicallRead({
+            chain: chainsMetadata[toChain(chainId)],
+            client,
+            abi: 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, 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 multicallRead({
+            chain: chainsMetadata[toChain(chainId)],
+            client,
+            abi: abis.feeManager,
+            calls: entries.map(([, request]) => ({
+                functionName: 'getFee',
+                args: [request.feeTypeKey, 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}|${assetNodeKey(edge.from)}|${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 (assetNodeKey(from) === 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;
+};
+const entryAmountVerdictReason = (verdict) => verdict.reason === 'below-minimum'
+    ? `below the entry mediator's minimum of ${verdict.minimumPerTransaction} base units`
+    : `above what the entry mediator has left today (${verdict.availablePerTransaction} base units)`;
+/**
+ * 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
+ */
+export const createOmnibridgeCarrier = (options) => {
+    const { bridgeablePairs, isProductionNetwork, readEntryLimits, readFeePerEther, clientForChain } = options;
+    const edgeMap = buildOmnibridgeEdgeMap(bridgeablePairs, isProductionNetwork);
+    const edgesFrom = (from, to) => {
+        if (assetNodeKey(from) === 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 = checkEntryAmount({ amount: amountIn, limits: prepared.limits });
+        if (!verdict.fits) {
+            const minimumAmount = verdict.reason === 'below-minimum' ? verdict.minimumPerTransaction : null;
+            return {
+                outcome: 'refused',
+                refusal: {
+                    kind: verdict.reason === 'below-minimum' ? 'below-minimum' : 'above-available',
+                    reason: entryAmountVerdictReason(verdict),
+                    minimumAmount,
+                },
+            };
+        }
+        return { outcome: 'delivered', deliveredAmount: netDeliveredAmount(amountIn, prepared.feePerEther) };
+    };
+    const ask = async ({ edge, inputAmount }) => {
+        const limits = await readEntryLimits(edge);
+        const verdict = checkEntryAmount({ amount: inputAmount, limits });
+        if (!verdict.fits) {
+            const minimumAmount = verdict.reason === 'below-minimum' ? verdict.minimumPerTransaction : null;
+            return {
+                ok: false,
+                refusal: {
+                    kind: verdict.reason === 'below-minimum' ? 'below-minimum' : 'above-available',
+                    reason: entryAmountVerdictReason(verdict),
+                    minimumAmount,
+                },
+            };
+        }
+        const feePerEther = await readFeePerEther(edge);
+        const deliveredAmount = netDeliveredAmount(inputAmount, feePerEther);
+        return {
+            ok: true,
+            deliveredAmount,
+            // An exact local computation: the guaranteed figure IS the expected one.
+            minimumDeliveredAmount: deliveredAmount,
+            claimedDurationSeconds: 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: BRIDGE_SETTLEMENT_ETA_MINUTES * 60,
+    };
+};
+/**
+ * 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
+ */
+export const withOmnibridgeEntryFusing = (carrier) => {
+    const descriptor = findProviderById(carrier.id);
+    return {
+        ...carrier,
+        fusesWithNext: (nextHop) => {
+            if (descriptor === null || !descriptor.executesDestinationCalls)
+                return false;
+            const nextHopIsOmnibridgeCrossing = nextHop.nextHopCarrier === Providers.PULSECHAIN || nextHop.nextHopCarrier === Providers.TOKENSEX;
+            if (!nextHopIsOmnibridgeCrossing || nextHop.nextHopDestinationChainId !== pulsechainChainId)
+                return false;
+            const origins = descriptor.destinationCallOriginChainIds;
+            if (origins !== 'any' && !origins.includes(nextHop.hopFrom.chainId))
+                return false;
+            const entersNative = isNativeAsset(nextHop.nextHopFrom.address, nextHop.nextHopFrom.ecosystem);
+            return !entersNative || descriptor.destinationCallCarriesNativeValue;
+        },
+    };
+};

package/dist/routing/carriers/pulsex.d.ts

@@ -0,0 +1,111 @@
+import { type Hex } from 'viem';
+import type { PublicClient } from 'viem';
+import { type AssetNode, type HopEdge } from '../search/graph.js';
+import type { CarrierAskAnswer, CarrierExactResult } from './ask-answer.js';
+/**
+ * One PulseX deployment a swap can execute on: the router the reader signs
+ * and the factory whose pools that router trades against. A Uniswap-V2-style
+ * router resolves every pool through its OWN factory, so one router call can
+ * only ever touch that one deployment's pools — a path can never mix them.
+ */
+export type PulseXVenue = {
+    readonly router: Hex;
+    readonly factory: Hex;
+};
+/**
+ * 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 declare const pulseXVenues: readonly PulseXVenue[];
+/**
+ * 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 declare const pulseXRouterForEdge: (edge: Pick<HopEdge, "carrier" | "venue">) => Hex | null;
+/**
+ * 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 declare const pulseXPoolPath: (from: AssetNode, to: AssetNode) => readonly Hex[] | null;
+/** What {@link createPulseXCarrier} needs. */
+export type CreatePulseXCarrierOptions = {
+    /**
+     * Reads PulseX's `getAmountsOut` for one PulseX edge and an input amount,
+     * in the edge's `to` token's base units. Returns null when the path has no
+     * liquidity.
+     *
+     * MUST READ THE EDGE'S OWN ROUTER ({@link pulseXRouterForEdge}). A V2 edge
+     * answered from V1 would carry V1's figure into a V2 signature.
+     */
+    readonly readAmountOut: (edge: HopEdge, inputAmount: bigint) => Promise<bigint | null>;
+    /**
+     * Returns a PulseChain client, for {@link Carrier.prepare}'s own batched
+     * reserve reads — never called by `ask`, which keeps using
+     * {@link readAmountOut} unchanged.
+     *
+     * OPTIONAL, ON PURPOSE — see `omnibridge.ts`'s identical `clientForChain`
+     * field for why: a host that has not wired this yet gets the carrier's
+     * original behavior, `prepare` a no-op and `exact` always `null`.
+     *
+     * @param chainId - always {@link pulsechainChainId} — PulseX runs nowhere else
+     * @returns a client, or null when this host has none
+     */
+    readonly clientForChain?: (chainId: number) => PublicClient | null;
+    /**
+     * The PulseX routers this host can SIGN on. The carrier offers an edge on
+     * each, and only on these: an edge is always signed on the router it was
+     * quoted against ({@link pulseXRouterForEdge}), so a router the host cannot
+     * sign on must never be quoted either.
+     *
+     * Defaults to every known venue ({@link pulseXVenues}: V1 and V2).
+     */
+    readonly routers?: readonly Hex[];
+};
+/**
+ * Builds the PulseX conversion swap as a plug-in carrier.
+ *
+ * @param options - see {@link CreatePulseXCarrierOptions}
+ * @returns the carrier — `id: 'PulseX'`
+ */
+export declare const createPulseXCarrier: (options: CreatePulseXCarrierOptions) => {
+    id: string;
+    edgesFrom: (from: AssetNode, to: AssetNode) => readonly HopEdge[];
+    ask: ({ edge, inputAmount }: {
+        edge: HopEdge;
+        inputAmount: bigint;
+    }) => Promise<CarrierAskAnswer>;
+    prepare: (nodes: readonly AssetNode[]) => Promise<void>;
+    exact: (edge: HopEdge, amountIn: bigint) => CarrierExactResult | null;
+    isRateLimited: boolean;
+    depositMode: "wallet-signed";
+    sender: "swap";
+    settlementSeconds: number;
+};