@gibs/bridge-sdk 1.17.0 → 1.18.0

package/README.md

@@ -432,7 +432,8 @@ if (plan.kind === 'refused') throw new Error(plan.refusal.reason);
   non-zero allowance is reset to zero first, because some tokens refuse to change
   one non-zero allowance into another.
 - **Spenders come from fixed tables.** The plan approves only the omnibridge
-  mediator and the PulseX router from this package's configuration, LI.FI's
+  mediator and the swap routers in the swap venues (PulseX by default, see
+  "Overriding swap routers"), LI.FI's
   Diamond (`lifiDiamondAddressByChainId`, plus the LI.FI execution guard), and
   Relay's depository (`relayDepositoryByChainId`). A quote that names any other
   spender or deposit target is refused. NEAR Intents may name no spender at all.
@@ -440,6 +441,56 @@ if (plan.kind === 'refused') throw new Error(plan.refusal.reason);
   asked for your wallet, in `sections[i].aggregator`. The candidate's own quote
   priced the route on screen and is never signed.
 
+## Overriding swap routers
+
+The package swaps on PulseX V1 and V2 on PulseChain by default. You can swap on
+other routers, on any chain. Describe each router as a `SwapVenue` and pass the
+venues to the route search and to execution. Today the only `kind` is
+`'uniswap-v2'`: a router with `getAmountsOut` and the three
+`swapExact...` functions, a factory with `getPair`, and pairs with
+`getReserves`.
+
+```ts
+import {
+  type SwapVenues,
+  defaultSwapVenues,
+  planCandidateExecution,
+  resolveSwapVenues,
+} from '@gibs/bridge-sdk';
+
+const swapVenues: SwapVenues = {
+  // Swap on Ethereum, on Uniswap V2.
+  1: [{
+    kind: 'uniswap-v2',
+    chainId: 1,
+    router: '0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D',
+    factory: '0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f',
+    feeBasisPoints: 30, // 29 for PulseX, 30 for Uniswap V2 forks
+    label: 'Uniswap V2',
+  }],
+  // An empty list switches swaps off on PulseChain.
+  369: [],
+};
+
+// What the engine will use: your chains replace the defaults, other chains keep them.
+const venues = resolveSwapVenues(swapVenues);
+console.log(Object.keys(defaultSwapVenues)); // ['369']
+```
+
+- **A chain you name replaces that chain's default list.** A chain you leave out
+  keeps its defaults. An empty list disables swaps on that chain.
+- **A venue on any chain builds swap steps there.** The rule that aggregators
+  never receive PulseChain is separate and does not change.
+- **Each swap step records the venue it was priced on.** Signing uses that
+  venue's router, also as the approval spender. Pass the same `swapVenues` to
+  `planExecution`, `planCandidateExecution` and `readPulseXSectionQuote` that
+  you gave the search. A router that is not in the venues throws an error. The
+  package never falls back to PulseX.
+- **The LI.FI execution guard does not change.** It checks the LI.FI Diamond
+  address and has no override.
+- `uniV2Routers` and `uniV2Factories` stay exported. They are frozen and derive
+  from `defaultSwapVenues`.
+
 ## Manual claims
 
 A crossing from PulseChain to Ethereum or BNB Smart Chain ends with a release on

package/dist/cjs/config.d.ts

@@ -1,4 +1,5 @@
 import { type Hex } from 'viem';
+import type { SwapVenues } from './swap-venues.js';
 import type { BridgeKey, Token, TokenOut } from './types.js';
 /**
  * Add here your chain id as hex, be sure to add your chain in the chainsMetadata object too
@@ -59,8 +60,22 @@ export declare const pulsechainTokenAddresses: Readonly<{
 }>;
 /** A map of chains to deprecated native asset out addresses */
 export declare const deprecatedNativeAssetOut: Partial<Record<Chains, Set<Hex>>>;
-/** A map of chains to uni v2 router addresses */
-export declare const uniV2Routers: Record<Chains, Hex[]>;
+/**
+ * The swap venues the package ships with: PulseX V1 then V2 on PulseChain.
+ * Frozen. A caller who wants other routers passes its own
+ * {@link SwapVenues} (see `resolveSwapVenues`); this table is never mutated.
+ *
+ * Each factory is the router's own `router.factory()` read on chain — see
+ * {@link uniV2Factories}'s doc. The fee is 29 basis points for both
+ * deployments (measured, same doc).
+ */
+export declare const defaultSwapVenues: SwapVenues;
+/**
+ * A map of chains to uni v2 router addresses. Frozen. PulseChain's entries
+ * derive from {@link defaultSwapVenues}, so the two cannot drift. Kept for
+ * compatibility; to swap on other routers pass `swapVenues` instead.
+ */
+export declare const uniV2Routers: Readonly<Record<Chains, readonly Hex[]>>;
 /**
  * Each {@link uniV2Routers} entry's OWN factory address, same index, same
  * chain — `router.factory()` read live from `one.valve.city` on 2026-09-24.
@@ -85,7 +100,7 @@ export declare const uniV2Routers: Record<Chains, Hex[]>;
  * salt collision) and worth this note so a future reader does not assume a
  * transcription error and "fix" it back to something wrong.
  */
-export declare const uniV2Factories: Record<Chains, Hex[]>;
+export declare const uniV2Factories: Readonly<Record<Chains, readonly Hex[]>>;
 /** A map of chains to native token symbols */
 export declare const nativeTokenSymbol: Record<Chains, string>;
 /** A map of chains to native token names */

package/dist/cjs/config.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FOREIGN_TO_HOME_FEE = exports.HOME_TO_FOREIGN_FEE = exports.bridgeConfigs = exports.startBlocks = exports.chainIds = exports.chains = exports.canChangeUnwrap = exports.isUnwrappable = exports.isNative = exports.defaultAssetIn = exports.pathway = exports.pathwayGroup = exports.inferBridgeKey = exports.isTestnetChain = exports.validBridgeKeys = exports.testnetPathways = exports.pathways = exports.nativeTokenName = exports.nativeTokenSymbol = exports.uniV2Factories = exports.uniV2Routers = exports.deprecatedNativeAssetOut = exports.pulsechainTokenAddresses = exports.nativeAssetOut = exports.Providers = exports.toChainKey = exports.toChain = exports.chainIdToKey = exports.Chains = void 0;
+exports.FOREIGN_TO_HOME_FEE = exports.HOME_TO_FOREIGN_FEE = exports.bridgeConfigs = exports.startBlocks = exports.chainIds = exports.chains = exports.canChangeUnwrap = exports.isUnwrappable = exports.isNative = exports.defaultAssetIn = exports.pathway = exports.pathwayGroup = exports.inferBridgeKey = exports.isTestnetChain = exports.validBridgeKeys = exports.testnetPathways = exports.pathways = exports.nativeTokenName = exports.nativeTokenSymbol = exports.uniV2Factories = exports.uniV2Routers = exports.defaultSwapVenues = exports.deprecatedNativeAssetOut = exports.pulsechainTokenAddresses = exports.nativeAssetOut = exports.Providers = exports.toChainKey = exports.toChain = exports.chainIdToKey = exports.Chains = void 0;
 const viem_1 = require("viem");
 (function (Chains) {
     Chains["PLS"] = "0x171";
@@ -72,12 +72,13 @@ exports.pulsechainTokenAddresses = Object.freeze({
 exports.deprecatedNativeAssetOut = {
     [exports.Chains.PLS]: new Set(['0x97Ac4a2439A47c07ad535bb1188c989dae755341']),
 };
-/** A map of chains to uni v2 router addresses */
-exports.uniV2Routers = {
-    [exports.Chains.PLS]: [
-        '0x98bf93ebf5c380C0e6Ae8e192A7e2AE08edAcc02',
-        '0x165C3410fC91EF562C50559f7d2289fEbed552d9',
-    ],
+/**
+ * Routers on chains where this package knows the router but has not verified
+ * a factory, so no {@link SwapVenue} can be built for them. They stay in
+ * {@link uniV2Routers} for the native-price reads (`chain-info.ts`,
+ * `readAmountOut`) that need only a router.
+ */
+const routersWithoutVenue = {
     [exports.Chains.ETH]: ['0x7a250d5630b4cf539739df2c5dacb4c659f2488d'],
     [exports.Chains.BNB]: ['0x05fF2B0DB69458A0750badebc4f9e13aDd608C7F'],
     [exports.Chains.SEP]: ['0xeE567Fe1712Faf6149d80dA1E6934E354124CfE3'],
@@ -86,6 +87,43 @@ exports.uniV2Routers = {
         '0x636f6407B90661b73b1C0F7e24F4C79f624d0738',
     ],
 };
+/**
+ * The swap venues the package ships with: PulseX V1 then V2 on PulseChain.
+ * Frozen. A caller who wants other routers passes its own
+ * {@link SwapVenues} (see `resolveSwapVenues`); this table is never mutated.
+ *
+ * Each factory is the router's own `router.factory()` read on chain — see
+ * {@link uniV2Factories}'s doc. The fee is 29 basis points for both
+ * deployments (measured, same doc).
+ */
+exports.defaultSwapVenues = Object.freeze({
+    [Number(exports.Chains.PLS)]: Object.freeze([
+        Object.freeze({
+            kind: 'uniswap-v2',
+            chainId: Number(exports.Chains.PLS),
+            router: '0x98bf93ebf5c380C0e6Ae8e192A7e2AE08edAcc02',
+            factory: '0x1715a3E4A142d8b698131108995174F37aEBA10D',
+            feeBasisPoints: 29,
+            label: 'PulseX V1',
+        }),
+        Object.freeze({
+            kind: 'uniswap-v2',
+            chainId: Number(exports.Chains.PLS),
+            router: '0x165C3410fC91EF562C50559f7d2289fEbed552d9',
+            factory: '0x29eA7545DEf87022BAdc76323F373EA1e707C523',
+            feeBasisPoints: 29,
+            label: 'PulseX V2',
+        }),
+    ]),
+});
+/** One chain's routers: its default venues' routers, else the router-only entries. */
+const defaultRoutersFor = (chain) => exports.defaultSwapVenues[Number(chain)]?.map((venue) => venue.router) ?? routersWithoutVenue[chain] ?? [];
+/**
+ * A map of chains to uni v2 router addresses. Frozen. PulseChain's entries
+ * derive from {@link defaultSwapVenues}, so the two cannot drift. Kept for
+ * compatibility; to swap on other routers pass `swapVenues` instead.
+ */
+exports.uniV2Routers = Object.freeze(Object.fromEntries(Object.values(exports.Chains).map((chain) => [chain, Object.freeze([...defaultRoutersFor(chain)])])));
 /**
  * Each {@link uniV2Routers} entry's OWN factory address, same index, same
  * chain — `router.factory()` read live from `one.valve.city` on 2026-09-24.
@@ -110,16 +148,10 @@ exports.uniV2Routers = {
  * salt collision) and worth this note so a future reader does not assume a
  * transcription error and "fix" it back to something wrong.
  */
-exports.uniV2Factories = {
-    [exports.Chains.PLS]: [
-        '0x1715a3E4A142d8b698131108995174F37aEBA10D',
-        '0x29eA7545DEf87022BAdc76323F373EA1e707C523',
-    ],
-    [exports.Chains.ETH]: [],
-    [exports.Chains.BNB]: [],
-    [exports.Chains.SEP]: [],
-    [exports.Chains.V4PLS]: [],
-};
+exports.uniV2Factories = Object.freeze(Object.fromEntries(Object.values(exports.Chains).map((chain) => [
+    chain,
+    Object.freeze((exports.defaultSwapVenues[Number(chain)] ?? []).map((venue) => venue.factory)),
+])));
 /** A map of chains to native token symbols */
 exports.nativeTokenSymbol = {
     [exports.Chains.PLS]: 'PLS',

package/dist/cjs/execution.d.ts

@@ -1,5 +1,6 @@
 import { type Hex, type PublicClient } from 'viem';
 import type { TokenBridgeInfo } from './chain-info.js';
+import { type SwapVenues } from './swap-venues.js';
 import { type AggregatorOriginRefusal, type ConsolidatedQuote, type ConsolidatedQuoteRequest } from './consolidated-quote.js';
 import type { FeeType } from './fee-type.js';
 import type { RouteCandidate } from './routing/candidate.js';
@@ -20,7 +21,7 @@ import type { BridgeKey, Token } from './types.js';
  * EVERY SPENDER IS ONE THIS CODE ALREADY KNOWS. Approvals are for the exact
  * amount spent, never unlimited, and go only to:
  * - the omnibridge pathway's `from` mediator, read from `config.ts`;
- * - the PulseX router the edge was quoted on, read from `config.ts`;
+ * - the swap router the edge was quoted on, found in the swap venues (the defaults in `config.ts` unless the caller passes its own);
  * - an aggregator spender that `aggregatorOriginCalls` checked against a
  *   fixed table for its provider and chain (LI.FI's Diamond, Relay's
  *   depository). A quote cannot name its own spender.
@@ -212,12 +213,15 @@ export type ExecutionPlan = {
  * @param options.account - the account that signs every transaction
  * @param options.legs - the legs, in the order the wallet signs them
  * @param options.readAllowance - reads an allowance on chain; see {@link AllowanceReader}
+ * @param options.swapVenues - the routers swaps may sign on, merged over the defaults; a swap whose router is in none of them throws
  * @returns the ordered transactions, or the first leg that cannot be planned
+ * @throws when a swap leg's router is not in the swap venues
  */
-export declare const planExecution: ({ account, legs, readAllowance, }: {
+export declare const planExecution: ({ account, legs, readAllowance, swapVenues, }: {
     readonly account: Hex;
     readonly legs: readonly ExecutionLeg[];
     readonly readAllowance: AllowanceReader;
+    readonly swapVenues?: SwapVenues;
 }) => Promise<ExecutionPlan>;
 /**
  * What the caller supplies for one signature section of a candidate. Each
@@ -270,6 +274,12 @@ export type CandidateExecutionInputs = {
     readonly readAllowance: AllowanceReader;
     /** The resolver the candidate was built with; turns a plan's graph node into its token. */
     readonly resolveToken: ResolveNodeToken;
+    /**
+     * The routers swaps may sign on, merged over the defaults: a chain named
+     * here replaces that chain's default list. Pass the SAME venues the route
+     * search used. A swap whose router is in none of them throws.
+     */
+    readonly swapVenues?: SwapVenues;
     /**
      * The index of the section that `sections[0]` plans. It defaults to 0.
      * Pass it to plan a later section after the earlier ones landed, with the
@@ -337,10 +347,13 @@ export declare const planCandidateExecution: (inputs: CandidateExecutionInputs)
  * @param options.hop - the swap hop; its recorded path and edge name what to read
  * @param options.amountIn - the amount the swap spends, in base units
  * @param options.client - a client that can call `readContract`
- * @returns the amount the last token of the path delivers, or null when the hop records no path, names no known router, the amount is not positive, or the read fails or returns nothing
+ * @param options.swapVenues - the routers swaps may sign on, merged over the defaults
+ * @returns the amount the last token of the path delivers, or null when the hop records no path, the amount is not positive, or the read fails or returns nothing
+ * @throws when the hop records a path but its router is not in the swap venues
  */
-export declare const readPulseXSectionQuote: ({ hop, amountIn, client, }: {
+export declare const readPulseXSectionQuote: ({ hop, amountIn, client, swapVenues, }: {
     readonly hop: Pick<PlannedHop, "edge" | "outcome">;
     readonly amountIn: bigint;
     readonly client: Pick<PublicClient, "readContract">;
+    readonly swapVenues?: SwapVenues;
 }) => Promise<bigint | null>;

package/dist/cjs/execution.js

@@ -37,6 +37,7 @@ exports.readPulseXSectionQuote = exports.planCandidateExecution = exports.planEx
 const viem_1 = require("viem");
 const abis = __importStar(require("./abis.js"));
 const config_js_1 = require("./config.js");
+const swap_venues_js_1 = require("./swap-venues.js");
 const consolidated_quote_js_1 = require("./consolidated-quote.js");
 const pulsex_js_1 = require("./routing/carriers/pulsex.js");
 const swap_transactions_js_1 = require("./routing/swap-transactions.js");
@@ -131,10 +132,30 @@ const omnibridgeCalls = (leg, account) => {
         delivery: deliveryTermsOf(leg.delivery),
     };
 };
-const pulseXSwapCalls = (leg) => {
+/**
+ * The venue a swap edge was priced on, from the venues execution was given.
+ * A router that is not in those venues THROWS: signing on another router, on
+ * PulseX most of all, would trade against pools the reader was never shown.
+ *
+ * @param venues - the venues passed to execution
+ * @param edge - the swap edge
+ * @returns the venue
+ * @throws when the edge's router is not in `venues`, or its chain has no venue
+ */
+const requireSwapVenue = (venues, edge) => {
+    const venue = (0, pulsex_js_1.venueForEdge)(venues, edge);
+    if (venue !== null)
+        return venue;
+    const router = edge.venue ?? 'the default router';
+    throw new Error(`The swap was priced on ${router} on chain ${edge.from.chainId}, but that router is not in the swap venues passed to execution. ` +
+        'Pass the same swapVenues the route search used.');
+};
+const pulseXSwapCalls = (leg, venues) => {
     const { edge } = leg.hop;
     const chainId = edge.from.chainId;
-    const routerAddress = (0, pulsex_js_1.pulseXRouterForEdge)(edge);
+    if (edge.carrier !== 'PulseX')
+        return refusal({ reason: 'swap-refused' });
+    const routerAddress = requireSwapVenue(venues, edge).router;
     // The builder refuses a hop that records no priced path, a router other
     // than the edge's own, and a leg on screen that disagrees.
     const call = (0, swap_transactions_js_1.buildPulseXSwapTransaction)({
@@ -146,8 +167,9 @@ const pulseXSwapCalls = (leg) => {
         signedLeg: { kind: 'swap', chainId },
         chainId,
         routerAddress,
+        venues,
     });
-    if (call === null || routerAddress === null)
+    if (call === null)
         return refusal({ reason: 'swap-refused' });
     const spendsNative = edge.from.address.toLowerCase() === viem_1.zeroAddress;
     return {
@@ -191,11 +213,11 @@ const aggregatorCalls = (leg) => {
         delivery: null,
     };
 };
-const legCalls = (leg, account) => {
+const legCalls = (leg, account, venues) => {
     if (leg.kind === 'omnibridge')
         return omnibridgeCalls(leg, account);
     if (leg.kind === 'pulsex-swap')
-        return pulseXSwapCalls(leg);
+        return pulseXSwapCalls(leg, venues);
     if (leg.kind === 'wrap')
         return wrapCalls(leg);
     return aggregatorCalls(leg);
@@ -220,10 +242,13 @@ const approvalTransactions = async ({ approval, account, readAllowance, }) => {
  * @param options.account - the account that signs every transaction
  * @param options.legs - the legs, in the order the wallet signs them
  * @param options.readAllowance - reads an allowance on chain; see {@link AllowanceReader}
+ * @param options.swapVenues - the routers swaps may sign on, merged over the defaults; a swap whose router is in none of them throws
  * @returns the ordered transactions, or the first leg that cannot be planned
+ * @throws when a swap leg's router is not in the swap venues
  */
-const planExecution = async ({ account, legs, readAllowance, }) => {
-    const calls = legs.map((leg) => legCalls(leg, account));
+const planExecution = async ({ account, legs, readAllowance, swapVenues, }) => {
+    const venues = (0, swap_venues_js_1.resolveSwapVenues)(swapVenues);
+    const calls = legs.map((leg) => legCalls(leg, account, venues));
     const refusedIndex = calls.findIndex((entry) => entry.kind === 'refused');
     const refused = calls[refusedIndex];
     if (refused !== undefined && refused.kind === 'refused') {
@@ -401,7 +426,7 @@ const sectionWindowProblem = ({ firstSectionIndex, plannedCount, sectionCount, }
  * @returns the ordered transactions with the deliveries they buy, or the first section that cannot be planned
  */
 const planCandidateExecution = async (inputs) => {
-    const { candidate, account, readAllowance, resolveToken, sections } = inputs;
+    const { candidate, account, readAllowance, resolveToken, sections, swapVenues } = inputs;
     const firstSectionIndex = inputs.firstSectionIndex ?? 0;
     const plan = candidate.plan;
     const allSections = plan === undefined ? null : planSections(plan);
@@ -424,7 +449,7 @@ const planCandidateExecution = async (inputs) => {
         return { kind: 'refused', sectionIndex: firstSectionIndex + refusedIndex, refusal: refused.refusal };
     }
     const legs = sectionLegs.flatMap((entry) => (entry.kind === 'leg' ? [entry.leg] : []));
-    const planned = await (0, exports.planExecution)({ account, legs, readAllowance });
+    const planned = await (0, exports.planExecution)({ account, legs, readAllowance, ...(swapVenues === undefined ? {} : { swapVenues }) });
     if (planned.kind === 'refused') {
         return { kind: 'refused', sectionIndex: firstSectionIndex + planned.legIndex, refusal: planned.refusal };
     }
@@ -445,13 +470,15 @@ exports.planCandidateExecution = planCandidateExecution;
  * @param options.hop - the swap hop; its recorded path and edge name what to read
  * @param options.amountIn - the amount the swap spends, in base units
  * @param options.client - a client that can call `readContract`
- * @returns the amount the last token of the path delivers, or null when the hop records no path, names no known router, the amount is not positive, or the read fails or returns nothing
+ * @param options.swapVenues - the routers swaps may sign on, merged over the defaults
+ * @returns the amount the last token of the path delivers, or null when the hop records no path, the amount is not positive, or the read fails or returns nothing
+ * @throws when the hop records a path but its router is not in the swap venues
  */
-const readPulseXSectionQuote = async ({ hop, amountIn, client, }) => {
+const readPulseXSectionQuote = async ({ hop, amountIn, client, swapVenues, }) => {
     const path = (0, pulsex_js_1.pulseXSwapPathForHop)(hop);
-    const router = (0, pulsex_js_1.pulseXRouterForEdge)(hop.edge);
-    if (path === null || router === null || amountIn <= 0n)
+    if (path === null || amountIn <= 0n)
         return null;
+    const router = requireSwapVenue((0, swap_venues_js_1.resolveSwapVenues)(swapVenues), hop.edge).router;
     try {
         const amounts = await client.readContract({
             address: router,

package/dist/cjs/index.d.ts

@@ -17,6 +17,7 @@ export * from './referral.js';
 export * from './route-steps.js';
 export * from './routing/index.js';
 export * from './settings.js';
+export * from './swap-venues.js';
 export * from './types.js';
 export * from './claims.js';
 export * from './execution.js';

package/dist/cjs/index.js

@@ -33,6 +33,7 @@ __exportStar(require("./referral.js"), exports);
 __exportStar(require("./route-steps.js"), exports);
 __exportStar(require("./routing/index.js"), exports);
 __exportStar(require("./settings.js"), exports);
+__exportStar(require("./swap-venues.js"), exports);
 __exportStar(require("./types.js"), exports);
 __exportStar(require("./claims.js"), exports);
 __exportStar(require("./execution.js"), exports);

package/dist/cjs/prices.d.ts

@@ -105,3 +105,13 @@ export declare const resolveTokenPriceUsd: (token: Token, { pulsexPrices, lifiPr
     pulsexPrices: Map<string, number>;
     lifiPrices: Map<string, number>;
 }) => number | null;
+/**
+ * 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 declare const sameChainWrappedNative: (token: Token) => Hex | null;

package/dist/cjs/prices.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveTokenPriceUsd = exports.computeUsdPriceFromAmountsOut = exports.pulsexPricePaths = exports.pulsechainOriginAddress = exports.isPulsechain = exports.lifiPriceKey = exports.lowercaseAddress = exports.WPLS_ADDRESS = exports.PULSECHAIN_USD_ANCHOR_DECIMALS = exports.PULSECHAIN_USD_ANCHOR_ADDRESS = exports.PULSECHAIN_TESTNET_CHAIN_ID = exports.PULSECHAIN_CHAIN_ID = void 0;
+exports.sameChainWrappedNative = exports.resolveTokenPriceUsd = exports.computeUsdPriceFromAmountsOut = exports.pulsexPricePaths = exports.pulsechainOriginAddress = exports.isPulsechain = exports.lifiPriceKey = exports.lowercaseAddress = exports.WPLS_ADDRESS = exports.PULSECHAIN_USD_ANCHOR_DECIMALS = exports.PULSECHAIN_USD_ANCHOR_ADDRESS = exports.PULSECHAIN_TESTNET_CHAIN_ID = exports.PULSECHAIN_CHAIN_ID = void 0;
 const viem_1 = require("viem");
 const config_js_1 = require("./config.js");
 /**
@@ -147,6 +147,59 @@ exports.computeUsdPriceFromAmountsOut = computeUsdPriceFromAmountsOut;
  * @returns the USD price as a number, or null when no source can price it
  */
 const resolveTokenPriceUsd = (token, { pulsexPrices, lifiPrices, }) => {
+    const wrappedNative = (0, exports.sameChainWrappedNative)(token);
+    if (wrappedNative !== null) {
+        return resolveNativeFamilyPriceUsd(token, wrappedNative, { pulsexPrices, lifiPrices });
+    }
+    return resolveOwnPriceUsd(token, { pulsexPrices, lifiPrices });
+};
+exports.resolveTokenPriceUsd = resolveTokenPriceUsd;
+/**
+ * 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
+ */
+const sameChainWrappedNative = (token) => {
+    const wrapped = config_js_1.nativeAssetOut[(0, config_js_1.toChain)(token.chainId)];
+    if (wrapped === undefined) {
+        return null;
+    }
+    const isNativeCoin = sameAddress(token.address, NATIVE_TOKEN_ADDRESS);
+    return isNativeCoin || sameAddress(token.address, wrapped) ? wrapped : null;
+};
+exports.sameChainWrappedNative = sameChainWrappedNative;
+/**
+ * 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 ((0, exports.isPulsechain)(token.chainId)) {
+        return (resolveOwnPriceUsd(wrapped, maps) ??
+            resolveOwnPriceUsd({ ...token, address: NATIVE_TOKEN_ADDRESS }, maps));
+    }
+    return (maps.lifiPrices.get((0, exports.lifiPriceKey)(token.chainId, NATIVE_TOKEN_ADDRESS)) ??
+        maps.lifiPrices.get((0, exports.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 ((0, exports.isPulsechain)(token.chainId)) {
         if (sameAddress(token.address, exports.PULSECHAIN_USD_ANCHOR_ADDRESS)) {
             return 1;
@@ -169,4 +222,3 @@ const resolveTokenPriceUsd = (token, { pulsexPrices, lifiPrices, }) => {
     }
     return lifiPrices.get((0, exports.lifiPriceKey)(token.chainId, token.address)) ?? null;
 };
-exports.resolveTokenPriceUsd = resolveTokenPriceUsd;

package/dist/cjs/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/cjs/routing/carrier-provider-key.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.carrierStepKind = exports.carrierProviderKey = exports.WRAP_CARRIER_ID = void 0;
+const config_js_1 = require("../config.js");
+const providers_js_1 = require("../providers.js");
+/**
+ * The carrier id of the native-coin wrap and unwrap step
+ * (`routing/carriers/wrap.ts`).
+ */
+exports.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(config_js_1.Providers).map((provider) => [provider, provider]),
+    ...providers_js_1.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
+ */
+const carrierProviderKey = (carrierId) => providerKeyByCarrierId.get(carrierId) ?? null;
+exports.carrierProviderKey = carrierProviderKey;
+/**
+ * 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
+ */
+const carrierStepKind = (carrierId) => carrierId === exports.WRAP_CARRIER_ID ? 'wrap' : null;
+exports.carrierStepKind = carrierStepKind;