@gibs/bridge-sdk 1.13.1 → 1.18.0

package/dist/prices.js

@@ -1,5 +1,5 @@
 import { formatUnits } from 'viem';
-import { Chains, nativeAssetOut } from './config.js';
+import { Chains, nativeAssetOut, toChain } from './config.js';
 /**
  * PulseChain mainnet numeric chain id (`Chains.PLS` = `0x171`). Tokens on this
  * chain (and its testnet sibling below) are priced on-chain via PulseX rather
@@ -138,6 +138,57 @@ export const computeUsdPriceFromAmountsOut = ({ results, stableDecimals = PULSEC
  * @returns the USD price as a number, or null when no source can price it
  */
 export const resolveTokenPriceUsd = (token, { pulsexPrices, lifiPrices, }) => {
+    const wrappedNative = sameChainWrappedNative(token);
+    if (wrappedNative !== null) {
+        return resolveNativeFamilyPriceUsd(token, wrappedNative, { pulsexPrices, lifiPrices });
+    }
+    return resolveOwnPriceUsd(token, { pulsexPrices, lifiPrices });
+};
+/**
+ * The chain's canonical wrapped native address when `token` is the native
+ * coin (zero address) or that wrapper itself, and null for every other token.
+ * Only the SAME chain's pair is returned: a bridged copy of a wrapper on
+ * another chain is a different token and keeps its own price.
+ *
+ * @param token - the token to test
+ * @returns the wrapped native address on the token's own chain, or null
+ */
+export const sameChainWrappedNative = (token) => {
+    const wrapped = nativeAssetOut[toChain(token.chainId)];
+    if (wrapped === undefined) {
+        return null;
+    }
+    const isNativeCoin = sameAddress(token.address, NATIVE_TOKEN_ADDRESS);
+    return isNativeCoin || sameAddress(token.address, wrapped) ? wrapped : null;
+};
+/**
+ * One price for a native coin and its canonical wrapper. The contract wraps
+ * and unwraps 1:1, so two prices would show a value loss on a wrap step that
+ * loses nothing.
+ *
+ * Off PulseChain the native coin's market feed (LI.FI) wins. The wrapper's
+ * own price there is the PulseX price of its bridged copy (it carries a
+ * PulseChain origin link), which is a derivative market with its own
+ * premium or discount. The coin's feed prices the underlying asset. When the
+ * feed has no native price, the wrapper's feed price, then its own resolved
+ * price, stand in.
+ *
+ * On PulseChain both are priced by PulseX through the WPLS path, so the
+ * wrapper's entry is used and the coin's entry stands in when the wrapper was
+ * not in the priced set.
+ */
+const resolveNativeFamilyPriceUsd = (token, wrappedNative, maps) => {
+    const wrapped = { ...token, address: wrappedNative };
+    if (isPulsechain(token.chainId)) {
+        return (resolveOwnPriceUsd(wrapped, maps) ??
+            resolveOwnPriceUsd({ ...token, address: NATIVE_TOKEN_ADDRESS }, maps));
+    }
+    return (maps.lifiPrices.get(lifiPriceKey(token.chainId, NATIVE_TOKEN_ADDRESS)) ??
+        maps.lifiPrices.get(lifiPriceKey(token.chainId, wrappedNative)) ??
+        resolveOwnPriceUsd(wrapped, maps));
+};
+/** The token's price by its own address, with no native-wrapper pairing. */
+const resolveOwnPriceUsd = (token, { pulsexPrices, lifiPrices, }) => {
     if (isPulsechain(token.chainId)) {
         if (sameAddress(token.address, PULSECHAIN_USD_ANCHOR_ADDRESS)) {
             return 1;

package/dist/providers.d.ts

@@ -132,6 +132,23 @@ export type ProviderDescriptor = {
      * `providers.test.ts`).
      */
     destinationCallCarriesNativeValue: boolean;
+    /**
+     * How this provider takes an Ethereum token from the reader's wallet.
+     *
+     * - `'allowance'` — the provider's contract pulls the token, so the wallet
+     *   must first approve that contract as a spender. The execution quote names
+     *   the spender (`ConsolidatedQuote.approvalAddress`), and the executor
+     *   raises the allowance before it sends.
+     * - `'transfer'` — the reader sends the token to an address the provider
+     *   gives. A plain transfer needs no approval, and the parser leaves
+     *   `approvalAddress` null.
+     *
+     * A DISPLAY FACT, NEVER A SIGNING ONE. The press reads the live quote's own
+     * `approvalAddress` and the live allowance. This field lets a route say, BEFORE
+     * any live quote exists, that its wallet may ask for an approval first.
+     * The native coin never needs one, whatever this says.
+     */
+    originTokenSpend: 'allowance' | 'transfer';
     /**
      * Phase one: the plain forward-solving origin-to-anchor swap pre-quote.
      *

package/dist/providers.js

@@ -11,6 +11,8 @@ const lifiDescriptor = {
     executesDestinationCalls: true,
     destinationCallOriginChainIds: [Number(Chains.ETH)],
     destinationCallCarriesNativeValue: false,
+    // Its quote names the Diamond as `estimate.approvalAddress`.
+    originTokenSpend: 'allowance',
     preQuote: {
         method: 'GET',
         build: buildLifiPreQuoteRequest,
@@ -33,6 +35,8 @@ const relayDescriptor = {
     executesDestinationCalls: true,
     destinationCallOriginChainIds: 'any',
     destinationCallCarriesNativeValue: true,
+    // Its quote carries an approve step; the parser lifts its spender.
+    originTokenSpend: 'allowance',
     preQuote: {
         method: 'POST',
         build: buildRelayPreQuoteRequest,
@@ -61,6 +65,8 @@ const nearIntentsDescriptor = {
     executesDestinationCalls: false,
     destinationCallOriginChainIds: [],
     destinationCallCarriesNativeValue: false,
+    // The reader sends the token to a deposit address.
+    originTokenSpend: 'transfer',
     preQuote: {
         method: 'POST',
         build: buildNearIntentsPreQuoteRequest,

package/dist/referral.d.ts

@@ -34,7 +34,11 @@ export declare const referralIntegrator = "gibs.finance";
  */
 export declare const resolveAttribution: (override: string | null | undefined, packageDefault: string | undefined) => string | undefined;
 /**
- * Payout address for Relay application fees.
+ * Gibs Finance's payout address for Relay application fees.
+ *
+ * NO BUILDER APPLIES IT. A Relay request carries an `appFees` entry only when
+ * the caller passes `relayAppFee`. The Gibs interface passes this address
+ * explicitly; any other caller passes its own, or nothing.
  *
  * Set to the owner's receiving wallet. Setting it back to `null` is a working
  * state rather than a broken one, and is the way to stop collecting: Relay
@@ -53,9 +57,13 @@ export declare const resolveAttribution: (override: string | null | undefined, p
  */
 export declare const relayReferralRecipient: Hex | null;
 /**
- * Default application fee in basis points. Ten basis points is one tenth of one
- * percent. The interface can override it per provider in stored settings; this
- * is the value a reader who has never touched the setting gets.
+ * The application fee the Gibs interface charges, in basis points. Ten basis
+ * points is one tenth of one percent. The interface can override it per
+ * provider in stored settings; this is the value a reader who has never touched
+ * the setting gets.
+ *
+ * NO BUILDER APPLIES IT. It reaches a request only when a caller passes it as
+ * `relayAppFee.basisPoints` (Relay) or converts it to `lifiFee` (LI.FI).
  */
 export declare const defaultReferralFeeBasisPoints = 10n;
 /**

package/dist/referral.js

@@ -33,7 +33,11 @@ export const referralIntegrator = 'gibs.finance';
  */
 export const resolveAttribution = (override, packageDefault) => (override === null ? undefined : (override ?? packageDefault));
 /**
- * Payout address for Relay application fees.
+ * Gibs Finance's payout address for Relay application fees.
+ *
+ * NO BUILDER APPLIES IT. A Relay request carries an `appFees` entry only when
+ * the caller passes `relayAppFee`. The Gibs interface passes this address
+ * explicitly; any other caller passes its own, or nothing.
  *
  * Set to the owner's receiving wallet. Setting it back to `null` is a working
  * state rather than a broken one, and is the way to stop collecting: Relay
@@ -52,9 +56,13 @@ export const resolveAttribution = (override, packageDefault) => (override === nu
  */
 export const relayReferralRecipient = '0xAF2ce0189f46f5663715b0b9ED2a10eA924AB9B0';
 /**
- * Default application fee in basis points. Ten basis points is one tenth of one
- * percent. The interface can override it per provider in stored settings; this
- * is the value a reader who has never touched the setting gets.
+ * The application fee the Gibs interface charges, in basis points. Ten basis
+ * points is one tenth of one percent. The interface can override it per
+ * provider in stored settings; this is the value a reader who has never touched
+ * the setting gets.
+ *
+ * NO BUILDER APPLIES IT. It reaches a request only when a caller passes it as
+ * `relayAppFee.basisPoints` (Relay) or converts it to `lifiFee` (LI.FI).
  */
 export const defaultReferralFeeBasisPoints = 10n;
 /**

package/dist/relay-depository.d.ts

@@ -0,0 +1,2 @@
+import { type Hex } from 'viem';
+export declare const relayDepositoryByChainId: ReadonlyMap<number, Hex>;

package/dist/relay-depository.js

@@ -0,0 +1,82 @@
+import { getAddress } from 'viem';
+/**
+ * Relay's deposit contract (its "depository") on each Ethereum-style chain:
+ * the ONLY address a Relay origin deposit may be sent to, and the only
+ * address it may ask the reader to approve.
+ *
+ * WHY A FIXED TABLE. A quote that names its own spender cannot be trusted to
+ * name an honest one: a compromised quote host could name any contract. This
+ * table ships with the code and changes only through a release.
+ *
+ * SOURCE. Relay's Chains API, `GET https://api.relay.link/chains`, field
+ * `chains[].protocol.v2.depository`, read 2026-10-07 for every chain whose
+ * `vmType` is `evm`. Relay's documentation says its depository addresses are
+ * published only through that API
+ * (https://docs.relay.link/references/protocol/addresses). A live quote the
+ * same day (Ethereum USDC to Base, `POST /quote/v2`) approved and deposited to
+ * exactly the Ethereum entry below.
+ *
+ * NOT THE `contracts` BLOCK. The same API also lists `relayReceiver`,
+ * `approvalProxy` and `erc20Router` under `chains[].contracts`. The live
+ * quote used none of them, so they are left out: an address the quote does
+ * not use is not one this table should accept.
+ *
+ * A CHAIN NOT LISTED IS REFUSED. If Relay adds a chain or moves a depository,
+ * deposits there are refused until this table is updated.
+ */
+const common = getAddress('0x4cd00e387622c35bddb9b4c962c136462338bc31');
+const alternate = getAddress('0x59916da825d2d2ec1bf878d71c88826f6633ecca');
+export const relayDepositoryByChainId = new Map([
+    [1, common], // ethereum
+    [10, common], // optimism
+    [25, alternate], // cronos
+    [56, common], // bsc
+    [100, common], // gnosis
+    [130, common], // unichain
+    [137, common], // polygon
+    [143, common], // monad
+    [146, common], // sonic
+    [169, common], // manta-pacific
+    [196, common], // xlayer
+    [288, common], // boba
+    [324, common], // zksync
+    [360, common], // shape
+    [480, common], // world-chain
+    [747, common], // flow-evm
+    [988, common], // stable
+    [999, common], // hyperevm
+    [1088, alternate], // metis
+    [1135, common], // lisk
+    [1868, common], // soneium
+    [2020, common], // ronin
+    [2741, common], // abstract
+    [2818, common], // morph
+    [4217, common], // tempo
+    [4326, common], // megaeth
+    [4663, common], // robinhood
+    [5000, alternate], // mantle
+    [5031, common], // somnia
+    [5042, common], // arc
+    [5330, common], // superseed
+    [8453, common], // base
+    [9745, common], // plasma
+    [33139, common], // apechain
+    [34443, common], // mode
+    [42018, common], // mythos
+    [42161, common], // arbitrum
+    [42220, common], // celo
+    [43114, common], // avalanche
+    [48900, common], // zircuit
+    [57073, common], // ink
+    [59144, alternate], // linea
+    [60808, common], // bob
+    [80094, common], // berachain
+    [81457, common], // blast
+    [97477, common], // doma
+    [98866, common], // plume
+    [534352, common], // scroll
+    [685689, common], // gensyn
+    [747474, common], // katana
+    [5064014, common], // ethereal
+    [7777777, common], // zora
+]);

package/dist/relay-quote.js

@@ -1,3 +1,4 @@
+import { buildUrl } from '@gibs/common/url';
 import { decodeFunctionData, encodeFunctionData, erc20Abi, maxUint256, zeroAddress, } from 'viem';
 import { Chains } from './config.js';
 import { isNonEthereumVirtualMachineOrigin, } from './consolidated-quote.js';
@@ -861,9 +862,7 @@ export const parseRelayQuote = (payload) => {
  * than trust it — see `checkConsolidatedRecord`.
  */
 export const relayStatusUrl = ({ quoteId }) => {
-    const url = new URL(relayRequestsUrl);
-    url.searchParams.set('id', quoteId);
-    return url.toString();
+    return buildUrl(relayRequestsUrl, { id: quoteId });
 };
 /**
  * Relay's request lifecycle states. Terminal states are `success` (the

package/dist/routing/candidate.d.ts

@@ -208,9 +208,9 @@ export type DirectCrossingCandidateInputs = {
  * to quote — the user bridges directly from that chain to PulseChain. The
  * same-chain skip in {@link useAggregatorRouteCandidate} is correct (nothing to
  * quote), but it left the conversion path empty. This helper fills that gap by
- * synthesizing a zero-step candidate that `usePulseXConversionRoutes` (the user
- * interface's plural composer) can consume unchanged, producing the correct
- * same-chain conversion route so the ranker can pick the cheapest option.
+ * synthesizing a zero-step candidate. The user interface no longer calls this:
+ * the route engine serves a conversion now. The export stays as published
+ * interface until a separate decision removes it.
  *
  * The synthetic quote carries zero steps (no aggregator hops), a zero execution
  * duration (the direct crossing needs no quote wait), and a null transaction

package/dist/routing/candidate.js

@@ -8,9 +8,9 @@ import { omnibridgeProviderForEntryChain } from './providers.js';
  * to quote — the user bridges directly from that chain to PulseChain. The
  * same-chain skip in {@link useAggregatorRouteCandidate} is correct (nothing to
  * quote), but it left the conversion path empty. This helper fills that gap by
- * synthesizing a zero-step candidate that `usePulseXConversionRoutes` (the user
- * interface's plural composer) can consume unchanged, producing the correct
- * same-chain conversion route so the ranker can pick the cheapest option.
+ * synthesizing a zero-step candidate. The user interface no longer calls this:
+ * the route engine serves a conversion now. The export stays as published
+ * interface until a separate decision removes it.
  *
  * The synthetic quote carries zero steps (no aggregator hops), a zero execution
  * duration (the direct crossing needs no quote wait), and a null transaction

package/dist/routing/carrier-provider-key.d.ts

@@ -0,0 +1,31 @@
+import { type ProviderKey } from '../providers.js';
+/**
+ * The carrier id of the native-coin wrap and unwrap step
+ * (`routing/carriers/wrap.ts`).
+ */
+export declare const WRAP_CARRIER_ID = "wrap";
+/**
+ * The steps a route can take that no third-party provider performs. A step of
+ * this kind is drawn from its own mark, never from a provider's.
+ */
+export type CarrierStepKind = 'wrap';
+/**
+ * The one place an engine carrier id becomes a {@link ProviderKey}.
+ *
+ * AN ENGINE CARRIER ID IS NOT A PROVIDER KEY. The engine is a plug-in host: a
+ * carrier id is any string, and one of them, `'wrap'`, names a step that no
+ * provider performs. Handing a raw id to the logo, glyph, or name tables drew a
+ * blank mark and logged an error. Route data resolves the key here, once, and
+ * every display site reads the resolved key.
+ *
+ * @param carrierId - the `carrier` of a planned hop's edge
+ * @returns the provider key, or null when no registered provider carries that id
+ */
+export declare const carrierProviderKey: (carrierId: string) => ProviderKey | null;
+/**
+ * The kind of provider-less step a carrier id performs.
+ *
+ * @param carrierId - the `carrier` of a planned hop's edge
+ * @returns the step kind, or null when the carrier is a provider or unknown
+ */
+export declare const carrierStepKind: (carrierId: string) => CarrierStepKind | null;

package/dist/routing/carrier-provider-key.js

@@ -0,0 +1,37 @@
+import { Providers } from '../config.js';
+import { providerRegistry } from '../providers.js';
+/**
+ * The carrier id of the native-coin wrap and unwrap step
+ * (`routing/carriers/wrap.ts`).
+ */
+export const WRAP_CARRIER_ID = 'wrap';
+/**
+ * Every engine carrier id that IS a provider, mapped to its {@link ProviderKey}.
+ * The omnibridge crossings carry the provider value itself; the aggregators
+ * carry their registry id; the PulseChain exchange carries its own literal.
+ */
+const providerKeyByCarrierId = new Map([
+    ...Object.values(Providers).map((provider) => [provider, provider]),
+    ...providerRegistry.map((descriptor) => [descriptor.id, descriptor.id]),
+    ['PulseX', 'PulseX'],
+]);
+/**
+ * The one place an engine carrier id becomes a {@link ProviderKey}.
+ *
+ * AN ENGINE CARRIER ID IS NOT A PROVIDER KEY. The engine is a plug-in host: a
+ * carrier id is any string, and one of them, `'wrap'`, names a step that no
+ * provider performs. Handing a raw id to the logo, glyph, or name tables drew a
+ * blank mark and logged an error. Route data resolves the key here, once, and
+ * every display site reads the resolved key.
+ *
+ * @param carrierId - the `carrier` of a planned hop's edge
+ * @returns the provider key, or null when no registered provider carries that id
+ */
+export const carrierProviderKey = (carrierId) => providerKeyByCarrierId.get(carrierId) ?? null;
+/**
+ * The kind of provider-less step a carrier id performs.
+ *
+ * @param carrierId - the `carrier` of a planned hop's edge
+ * @returns the step kind, or null when the carrier is a provider or unknown
+ */
+export const carrierStepKind = (carrierId) => carrierId === WRAP_CARRIER_ID ? 'wrap' : null;

package/dist/routing/carriers/ask-answer.d.ts

@@ -29,6 +29,11 @@ export type CarrierAskAnswer = {
         readonly reason: string | null;
         /** A minimum amount this refusal names, in `edge.from`'s base units, or null. */
         readonly minimumAmount: bigint | null;
+        /**
+         * What the carrier can still take today, in `edge.from`'s base units,
+         * when the refusal is `'above-available'`. Absent otherwise.
+         */
+        readonly availableAmount?: bigint;
     };
 };
 /**
@@ -48,6 +53,13 @@ export type CarrierExactResult = {
     readonly deliveredAmount: bigint;
     /** How far this edge's executed rate falls below its marginal rate, in percent; absent when the carrier cannot measure it. */
     readonly priceImpactPercent?: number;
+    /**
+     * The token addresses the carrier's own execution passes through, in
+     * order, when it chose among several (a PulseX swap path). The figure
+     * above was priced along exactly this path, so it is the path that must
+     * be signed. Absent when the carrier makes no such choice.
+     */
+    readonly swapPath?: readonly string[];
 } | {
     readonly outcome: 'refused';
     readonly refusal: {
@@ -56,5 +68,10 @@ export type CarrierExactResult = {
         readonly reason: string | null;
         /** A minimum amount this refusal names, in `edge.from`'s base units, or null. */
         readonly minimumAmount: bigint | null;
+        /**
+         * What the carrier can still take today, in `edge.from`'s base units,
+         * when the refusal is `'above-available'`. Absent otherwise.
+         */
+        readonly availableAmount?: bigint;
     };
 };

package/dist/routing/carriers/omnibridge.js

@@ -277,9 +277,27 @@ const prepareOmnibridgeReads = async ({ nodes, edgesFrom, isProductionNetwork, c
     }
     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)`;
+/**
+ * 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.
  *
@@ -316,15 +334,7 @@ export const createOmnibridgeCarrier = (options) => {
             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: 'refused', refusal: entryAmountRefusal(verdict) };
         }
         return { outcome: 'delivered', deliveredAmount: netDeliveredAmount(amountIn, prepared.feePerEther) };
     };
@@ -332,15 +342,7 @@ export const createOmnibridgeCarrier = (options) => {
         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,
-                },
-            };
+            return { ok: false, refusal: entryAmountRefusal(verdict) };
         }
         const feePerEther = await readFeePerEther(edge);
         const deliveredAmount = netDeliveredAmount(inputAmount, feePerEther);

package/dist/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/routing/carriers/pulsex-paths.js

@@ -0,0 +1,92 @@
+import { getAddress } from 'viem';
+import { Chains, Providers, nativeAssetOut, pathways, pulsechainTokenAddresses } from '../../config.js';
+import { PULSECHAIN_USD_ANCHOR_ADDRESS } from '../../prices.js';
+/** Wrapped PLS: the first hub, and the middle token of every two-hub path. */
+const wrappedPulseAddress = getAddress(nativeAssetOut[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 = pathways[Providers.PULSECHAIN][Chains.PLS]?.[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}).
+ */
+export const pulseXHubTokens = Object.freeze([
+    { symbol: 'WPLS', address: wrappedPulseAddress },
+    { symbol: 'PLSX', address: pulsechainTokenAddresses.PLSX },
+    { symbol: 'HEX', address: pulsechainTokenAddresses.HEX },
+    { symbol: 'DAI', address: getAddress(PULSECHAIN_USD_ANCHOR_ADDRESS) },
+    { symbol: 'USDC', address: pulsechainTokenAddresses.USDC },
+    { symbol: 'USDT', address: pulsechainTokenAddresses.USDT },
+    ...(bridgedWrappedEtherAddress === undefined ? [] : [{ symbol: 'WETH', address: 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
+ */
+export 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));
+};
+/**
+ * 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
+ */
+export const bestPulseXPathQuote = (quotes) => quotes
+    .filter((quote) => quote.deliveredAmount > 0n)
+    .reduce((best, quote) => (best === null || beats(quote, best) ? quote : best), null);