@gibs/bridge-sdk 1.17.0 → 1.18.0

package/dist/cjs/routing/route-data.d.ts

@@ -1,6 +1,7 @@
 import type { Hex } from 'viem';
 import type { QuoteFee } from '../quote-fees.js';
 import type { ProviderKey } from '../providers.js';
+import type { CarrierStepKind } from './carrier-provider-key.js';
 /**
  * The executing engine family a route runs through.
  *
@@ -91,7 +92,12 @@ export type RouteHopData = {
     /** Display name for the hop's provider, e.g. "LI.FI", "PulseChain Bridge". */
     providerName: string;
     /** Raw provider key for logo resolution when no `providerLogoUri` is supplied. */
-    providerKey?: string | null;
+    providerKey?: ProviderKey | null;
+    /**
+     * What the hop does when no provider performs it (a native wrap). Such a hop
+     * has a null `providerKey`; the adapter draws its mark from this kind.
+     */
+    stepKind?: CarrierStepKind | null;
     /** Quote-supplied provider logo url (aggregator legs); preferred when present. */
     providerLogoUri?: string | null;
     /** Human-readable hop title, e.g. "Bridge to PulseChain". */
@@ -110,11 +116,27 @@ export type RouteHopData = {
      * completes. Null/undefined when the provider named no output token.
      */
     toToken?: RouteTokenRef | null;
-    /** Per-hop fee in United States dollars as a NUMBER, or null when unknown. */
+    /** Per-hop fee in United States dollars as a NUMBER, or null when unknown. A search route's figure INCLUDES the signature's network gas (carried on the section's first hop). */
     feeUsdValue?: number | null;
+    /** The part of {@link feeUsdValue} that is not network gas: what the hop costs in value. Absent when the producer states no gas split. */
+    feeExcludingGasUsdValue?: number | null;
+    /** The network gas of the signature this hop opens, in dollars; null or absent on every hop that opens none, and when gas is unknown. */
+    gasUsdValue?: number | null;
     /** True when this hop runs automatically inside the section's single signature. */
     automatic?: boolean;
 };
+/**
+ * The network gas a route needs on one signing chain, summed across the
+ * signatures it signs there.
+ */
+export type RouteGasByChain = {
+    /** The chain the signatures broadcast on. */
+    chainId: number;
+    /** The native coin they burn, in base units (wei), or null when the chain's gas price is unknown. */
+    amountWei: bigint | null;
+    /** The same gas in dollars, or null when the amount or the native price is unknown. */
+    usdValue: number | null;
+};
 /**
  * What a signature section's funds LAND IN when that step completes — the stop
  * the money actually comes to rest at, named in tokens rather than only drawn as
@@ -181,7 +203,9 @@ export type RouteSectionData = {
     /** Short label naming what this signature does, e.g. "Bridge to PulseChain". */
     label: string;
     /** Raw provider key for the service executing this signature, or null. */
-    providerKey?: string | null;
+    providerKey?: ProviderKey | null;
+    /** What the signature does when no provider performs it (a native wrap); see {@link RouteHopData.stepKind}. */
+    stepKind?: CarrierStepKind | null;
     /**
      * The token-icon flow this signature walks, in raw references: the source, then
      * every INTERMEDIATE stop the funds pass through, then the destination. A
@@ -202,8 +226,12 @@ export type RouteSectionData = {
      * a cost.
      */
     unspent?: RouteUnspentData | null;
-    /** Section total fee in United States dollars as a NUMBER, or null. */
+    /** Section total fee in United States dollars as a NUMBER, or null. A search route's figure INCLUDES this signature's network gas. */
     feeUsdValue?: number | null;
+    /** The part of {@link feeUsdValue} that is not network gas. Absent when the producer states no gas split. */
+    feeExcludingGasUsdValue?: number | null;
+    /** This signature's network gas in dollars, or null/absent when unknown. */
+    gasUsdValue?: number | null;
     /** Numeric inputs for an optional fee breakdown line (conversion mode). */
     feePercent?: number | null;
     /** Price-impact percentage for an optional fee breakdown line (conversion mode). */
@@ -316,8 +344,22 @@ export type RouteData = {
     sections: RouteSectionData[];
     /** What the route delivers — used for ranking and the output row. */
     output: RouteOutputData;
-    /** Aggregate all-in cost in United States dollars as a NUMBER, or null. */
+    /**
+     * Aggregate ALL-IN cost in United States dollars as a NUMBER, or null:
+     * value lost plus network gas. The ranking reads this figure. For the
+     * figure without gas, read {@link costExcludingGasUsdValue}.
+     */
     totalCostUsdValue?: number | null;
+    /** {@link totalCostUsdValue} without network gas: the value the reader gives up. Absent when the producer states no gas split. */
+    costExcludingGasUsdValue?: number | null;
+    /**
+     * The network gas the reader pays across every signature, in dollars, or
+     * null/absent when no signing chain has a gas reading. Never zero for
+     * "unknown".
+     */
+    gasCostUsdValue?: number | null;
+    /** The gas by signing chain, in signing order: what to hold, and in which coin. */
+    gasByChain?: RouteGasByChain[];
     /** The user's net United States dollar outcome; the figure routes are ranked on. */
     netValueUsd?: number | null;
     /** Estimated end-to-end duration in minutes, or null when unknown. */

package/dist/cjs/routing/search/plan-route-data.d.ts

@@ -3,7 +3,7 @@ import type { Provider } from '../../config.js';
 import type { QuoteFee } from '../../quote-fees.js';
 import type { Token } from '../../types.js';
 import type { DeferredCrossing, RouteCandidate } from '../candidate.js';
-import type { RouteData, RouteKind } from '../route-data.js';
+import type { RouteData, RouteGasByChain, RouteKind } from '../route-data.js';
 import type { RouteScoreInputs } from './score.js';
 import { type AssetNode, type RoutePlan } from './graph.js';
 /**
@@ -141,6 +141,16 @@ export type PlanSectionPricing = {
      * caller passes shares that add up to `feeUsdValue`, or nothing.
      */
     hopFeeUsdValues?: readonly (number | null)[];
+    /**
+     * The gas split of `feeUsdValue`, from a producer that prices network gas
+     * apart: `feeExcludingGasUsdValue` is the cost without gas, `gasUsdValue` the
+     * signature's gas (null when unknown). `hopFeeExcludingGasUsdValues` splits
+     * the first the way `hopFeeUsdValues` splits the all-in figure. The gas sits
+     * on the section's first hop.
+     */
+    feeExcludingGasUsdValue?: number | null;
+    gasUsdValue?: number | null;
+    hopFeeExcludingGasUsdValues?: readonly (number | null)[];
     /** The itemized charges behind `feeUsdValue`, passed straight through to `RouteSectionData.fees`. */
     fees?: readonly QuoteFee[];
     /** Estimated duration for this signature in minutes, or null/undefined to omit. */
@@ -175,6 +185,12 @@ export type PlanRouteDataInputs = {
     sections: readonly PlanSectionPricing[];
     /** The route's aggregate all-in cost in United States dollars, or null/undefined. */
     totalCostUsdValue?: number | null;
+    /** The all-in cost without network gas, or null/undefined. */
+    costExcludingGasUsdValue?: number | null;
+    /** The route's network gas in dollars, or null/undefined when unknown. */
+    gasCostUsdValue?: number | null;
+    /** The gas by signing chain, in signing order. */
+    gasByChain?: readonly RouteGasByChain[];
     /** The route's net United States dollar outcome — the figure routes are ranked on. */
     netValueUsd?: number | null;
     /** Estimated end-to-end duration in minutes, or null/undefined. */

package/dist/cjs/routing/search/plan-route-data.js

@@ -37,6 +37,7 @@ exports.buildRouteScoreInputsFromPlan = exports.buildRouteCandidateFromPlan = ex
 const imageLinks = __importStar(require("../../image-links.js"));
 const chain_names_js_1 = require("../../chain-names.js");
 const providers_js_1 = require("../../providers.js");
+const carrier_provider_key_js_1 = require("../carrier-provider-key.js");
 const near_intents_route_js_1 = require("../../near-intents-route.js");
 const producers_js_1 = require("../producers.js");
 const graph_js_1 = require("./graph.js");
@@ -265,6 +266,8 @@ const hopProviderName = (carrier) => {
         return (0, producers_js_1.providerDisplayName)(carrier);
     if (carrier === 'PulseX')
         return 'PulseX';
+    if ((0, carrier_provider_key_js_1.carrierStepKind)(carrier) === 'wrap')
+        return 'Wrap';
     // TOTAL OVER EVERY CARRIER. The engine plans hops for carriers the provider
     // registry does not hold (a local wrap, a host's own plug-in). Casting such
     // an id to a provider id and asking the throwing lookup crashed the whole
@@ -386,11 +389,13 @@ const hopIsAutomatic = (hopIndex, plan) => {
  * @param plan - the plan the hop belongs to
  * @param resolveToken - resolves a graph node to its full display token
  * @param feeUsdValue - the hop's own share of its section's cost, or null
+ * @param gas - the hop's gas split, or null when the producer states none
  * @returns the raw hop data
  */
-const toRouteHopData = (hop, hopIndex, plan, resolveToken, feeUsdValue) => ({
+const toRouteHopData = (hop, hopIndex, plan, resolveToken, feeUsdValue, gas) => ({
     providerName: hopProviderName(hop.edge.carrier),
-    providerKey: hop.edge.carrier,
+    providerKey: (0, carrier_provider_key_js_1.carrierProviderKey)(hop.edge.carrier),
+    stepKind: (0, carrier_provider_key_js_1.carrierStepKind)(hop.edge.carrier),
     title: hopTitle(hop, hopIndex, plan, resolveToken),
     conversion: hopConversion(hop, hopIndex, plan, resolveToken),
     fromToken: toRouteTokenRef(hop.edge.from, resolveToken),
@@ -398,6 +403,7 @@ const toRouteHopData = (hop, hopIndex, plan, resolveToken, feeUsdValue) => ({
     // The per-hop dollar figure is a caller-supplied input (see this module's
     // head doc); the caller passes it in, never derived here.
     feeUsdValue,
+    ...(gas === null ? {} : gas),
     automatic: hopIsAutomatic(hopIndex, plan),
 });
 /**
@@ -542,8 +548,6 @@ exports.derivePlanKind = derivePlanKind;
  * @param carrier - the plan's headline carrier
  * @returns the same value, typed as `ProviderKey`
  */
-/** The carrier id of the native-coin wrap step (`routing/carriers/wrap.ts`). */
-const WRAP_CARRIER = 'wrap';
 const toHeadlineProviderKey = (carrier) => {
     if (isBridgeCarrier(carrier))
         return carrier;
@@ -576,7 +580,7 @@ exports.deriveHeadlineProviderKeyFromPlan = deriveHeadlineProviderKeyFromPlan;
  * @param plan - the plan to read
  * @returns the carrier to headline
  */
-const firstHeadlineCarrier = (plan) => plan.hops.find((hop) => hop.edge.carrier !== WRAP_CARRIER)?.edge.carrier ?? 'PulseX';
+const firstHeadlineCarrier = (plan) => plan.hops.find((hop) => hop.edge.carrier !== carrier_provider_key_js_1.WRAP_CARRIER_ID)?.edge.carrier ?? 'PulseX';
 /**
  * The anchor a two-signature plan leaves the reader holding between its
  * first and second groups — `RouteCandidate.plan`'s own TSDoc: "the anchor
@@ -696,10 +700,13 @@ const buildRouteDataFromPlan = (inputs) => {
         const landing = resolveNodeWithAssertedDecimals(lastHop.edge.to, resolveToken);
         const landingIsUnpriced = hopOutcomeIsUnpriced(lastHop);
         const hopFeeUsdValues = groupHopFeeUsdValues(pricing, group, groupIndex);
+        const statesGasSplit = pricing.feeExcludingGasUsdValue !== undefined;
+        const hopFeeExcludingGasUsdValues = pricing.hopFeeExcludingGasUsdValues;
         return {
             id: `${routeId}-signature-${groupIndex + 1}`,
             label: sectionLabel(group, groupIndex, plan),
-            providerKey: hops[0].edge.carrier,
+            providerKey: (0, carrier_provider_key_js_1.carrierProviderKey)(hops[0].edge.carrier),
+            stepKind: (0, carrier_provider_key_js_1.carrierStepKind)(hops[0].edge.carrier),
             tokenFlow: buildGroupTokenFlow(hops, resolveToken),
             landing: {
                 amount: sectionLandingAmount(pricing, lastHop),
@@ -709,10 +716,19 @@ const buildRouteDataFromPlan = (inputs) => {
                 estimateBasis: hopEstimateBasis(lastHop),
             },
             feeUsdValue: pricing.feeUsdValue,
+            ...(statesGasSplit
+                ? { feeExcludingGasUsdValue: pricing.feeExcludingGasUsdValue, gasUsdValue: pricing.gasUsdValue ?? null }
+                : {}),
             fees: pricing.fees ? [...pricing.fees] : undefined,
             etaMinutes: pricing.etaMinutes,
             etaSeconds: pricing.etaSeconds,
-            hops: group.map((hopIndex, positionInGroup) => toRouteHopData(plan.hops[hopIndex], hopIndex, plan, resolveToken, hopFeeUsdValues[positionInGroup] ?? null)),
+            hops: group.map((hopIndex, positionInGroup) => toRouteHopData(plan.hops[hopIndex], hopIndex, plan, resolveToken, hopFeeUsdValues[positionInGroup] ?? null, statesGasSplit
+                ? {
+                    feeExcludingGasUsdValue: hopFeeExcludingGasUsdValues?.[positionInGroup] ??
+                        (group.length === 1 ? (pricing.feeExcludingGasUsdValue ?? null) : null),
+                    gasUsdValue: positionInGroup === 0 ? (pricing.gasUsdValue ?? null) : null,
+                }
+                : null)),
             deferred: groupIndex > 0 ? true : undefined,
             deferredNote: pricing.deferredNote,
         };
@@ -731,6 +747,13 @@ const buildRouteDataFromPlan = (inputs) => {
             estimateBasis: lastSection.landing?.estimateBasis ?? null,
         },
         totalCostUsdValue,
+        ...(inputs.costExcludingGasUsdValue === undefined
+            ? {}
+            : {
+                costExcludingGasUsdValue: inputs.costExcludingGasUsdValue,
+                gasCostUsdValue: inputs.gasCostUsdValue ?? null,
+                gasByChain: [...(inputs.gasByChain ?? [])],
+            }),
         netValueUsd,
         etaMinutes,
         // The single legacy `viaChainId` a not-yet-migrated consumer may still

package/dist/cjs/routing/swap-transactions.d.ts

@@ -1,5 +1,6 @@
 import { type Hex } from 'viem';
 import { type SignedLeg } from '../settings.js';
+import type { SwapVenues } from '../swap-venues.js';
 import type { HopEdge, PlannedHop } from './search/graph.js';
 /**
  * The same-chain, one-signature transaction shape every sender in this file
@@ -27,7 +28,7 @@ export type SwapCallInputs = {
  * looking at) and the native-in/native-out/token-token branching.
  *
  * SIGNS ON THE EDGE'S OWN ROUTER. A PulseX edge names the deployment it was
- * quoted on (`pulseXRouterForEdge`: V1 or V2, each with its own pools). The
+ * quoted on (`venueForEdge`: V1 or V2, each with its own pools). The
  * caller's `routerAddress` must be that same router — it is also the router
  * the caller approved to spend the input token — or nothing is built. A V2
  * quote signed on V1 would trade against a different pool than the one the
@@ -35,8 +36,9 @@ export type SwapCallInputs = {
  *
  * @param options - the hop to swap, the amount and slippage-adjusted
  *   minimum, who receives the output, the signing deadline, what the caller
- *   believes this signature does (`signedLeg`), the chain it executes on, and
- *   the resolved router address
+ *   believes this signature does (`signedLeg`), the chain it executes on, the
+ *   resolved router address, and the swap venues the router must belong to
+ *   (the defaults when omitted)
  * @returns the swap transaction inputs, or null when the hop records no
  *   PulseX swap path, names no known router, `routerAddress` is not the
  *   edge's own router, the leg on screen disagrees, or any of
@@ -51,6 +53,8 @@ export declare const buildPulseXSwapTransaction: (options: {
     readonly signedLeg: SignedLeg | null;
     readonly chainId: number | null;
     readonly routerAddress: Hex | null;
+    /** The venues the edge's router must belong to. Omitted means the defaults. */
+    readonly venues?: SwapVenues;
 }) => SwapCallInputs | null;
 /**
  * Builds a native-coin wrap/unwrap transaction for one route-search graph

package/dist/cjs/routing/swap-transactions.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.swapMinimumOut = exports.buildWrapTransaction = exports.buildPulseXSwapTransaction = void 0;
 const viem_1 = require("viem");
 const settings_js_1 = require("../settings.js");
+const config_js_1 = require("../config.js");
 const pulsex_js_1 = require("./carriers/pulsex.js");
 /**
  * The minimal WETH9-style wrap/unwrap interface: `deposit()` mints the
@@ -32,7 +33,7 @@ const wrapAbi = (0, viem_1.parseAbi)(['function deposit() payable', 'function wi
  * looking at) and the native-in/native-out/token-token branching.
  *
  * SIGNS ON THE EDGE'S OWN ROUTER. A PulseX edge names the deployment it was
- * quoted on (`pulseXRouterForEdge`: V1 or V2, each with its own pools). The
+ * quoted on (`venueForEdge`: V1 or V2, each with its own pools). The
  * caller's `routerAddress` must be that same router — it is also the router
  * the caller approved to spend the input token — or nothing is built. A V2
  * quote signed on V1 would trade against a different pool than the one the
@@ -40,8 +41,9 @@ const wrapAbi = (0, viem_1.parseAbi)(['function deposit() payable', 'function wi
  *
  * @param options - the hop to swap, the amount and slippage-adjusted
  *   minimum, who receives the output, the signing deadline, what the caller
- *   believes this signature does (`signedLeg`), the chain it executes on, and
- *   the resolved router address
+ *   believes this signature does (`signedLeg`), the chain it executes on, the
+ *   resolved router address, and the swap venues the router must belong to
+ *   (the defaults when omitted)
  * @returns the swap transaction inputs, or null when the hop records no
  *   PulseX swap path, names no known router, `routerAddress` is not the
  *   edge's own router, the leg on screen disagrees, or any of
@@ -54,7 +56,7 @@ const buildPulseXSwapTransaction = (options) => {
     if (swapPath === null) {
         return null;
     }
-    const quotedRouter = (0, pulsex_js_1.pulseXRouterForEdge)(edge);
+    const quotedRouter = (0, pulsex_js_1.venueForEdge)(options.venues ?? config_js_1.defaultSwapVenues, edge)?.router ?? null;
     if (quotedRouter === null || routerAddress === null || !(0, viem_1.isAddressEqual)(quotedRouter, routerAddress)) {
         return null;
     }

package/dist/cjs/swap-venues.d.ts

@@ -0,0 +1,43 @@
+import type { Hex } from 'viem';
+/**
+ * A place a same-chain token swap can execute. Today only Uniswap-V2-shaped
+ * routers exist: `getAmountsOut`, `swapExactTokensForTokens`,
+ * `swapExactETHForTokens`, `swapExactTokensForETH`, a factory with
+ * `getPair`, and pairs with `getReserves`. The `kind` field leaves room for
+ * other shapes (for example `'uniswap-v3'`) without breaking callers.
+ */
+export type SwapVenue = {
+    /** The router shape. Only `'uniswap-v2'` is supported. */
+    readonly kind: 'uniswap-v2';
+    /** The numeric chain id the router lives on. */
+    readonly chainId: number;
+    /** The router a swap is signed on. It is also the token approval spender. */
+    readonly router: Hex;
+    /** The factory whose pools the router trades against. */
+    readonly factory: Hex;
+    /** The swap fee in basis points: 29 for PulseX, 30 for Uniswap V2 forks. */
+    readonly feeBasisPoints: number;
+    /** A name for logs and displays. */
+    readonly label?: string;
+};
+/** The venues on each chain, keyed by numeric chain id. The first venue of a chain is its default. */
+export type SwapVenues = Readonly<Record<number, readonly SwapVenue[]>>;
+/**
+ * Merges caller venues over {@link defaultSwapVenues}. A chain present in
+ * `overrides` replaces the default list for that chain. A chain absent from
+ * `overrides` keeps its default list. An empty list switches swaps off on
+ * that chain. Neither input is changed; the result is frozen.
+ *
+ * @param overrides - the caller's venues, or undefined for the defaults
+ * @returns the venues to use
+ */
+export declare const resolveSwapVenues: (overrides?: SwapVenues) => SwapVenues;
+/**
+ * Finds the venue on a chain that has the given router.
+ *
+ * @param venues - the venues to search
+ * @param chainId - the numeric chain id
+ * @param router - the router address, in any letter case
+ * @returns the venue, or null when the chain has no venue with that router
+ */
+export declare const findSwapVenue: (venues: SwapVenues, chainId: number, router: Hex) => SwapVenue | null;

package/dist/cjs/swap-venues.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findSwapVenue = exports.resolveSwapVenues = void 0;
+const config_js_1 = require("./config.js");
+/**
+ * Merges caller venues over {@link defaultSwapVenues}. A chain present in
+ * `overrides` replaces the default list for that chain. A chain absent from
+ * `overrides` keeps its default list. An empty list switches swaps off on
+ * that chain. Neither input is changed; the result is frozen.
+ *
+ * @param overrides - the caller's venues, or undefined for the defaults
+ * @returns the venues to use
+ */
+const resolveSwapVenues = (overrides) => {
+    if (overrides === undefined)
+        return config_js_1.defaultSwapVenues;
+    return Object.freeze({ ...config_js_1.defaultSwapVenues, ...overrides });
+};
+exports.resolveSwapVenues = resolveSwapVenues;
+/**
+ * Finds the venue on a chain that has the given router.
+ *
+ * @param venues - the venues to search
+ * @param chainId - the numeric chain id
+ * @param router - the router address, in any letter case
+ * @returns the venue, or null when the chain has no venue with that router
+ */
+const findSwapVenue = (venues, chainId, router) => venues[chainId]?.find((venue) => venue.router.toLowerCase() === router.toLowerCase()) ?? null;
+exports.findSwapVenue = findSwapVenue;

package/dist/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/config.js

@@ -71,12 +71,13 @@ export const pulsechainTokenAddresses = Object.freeze({
 export const deprecatedNativeAssetOut = {
     [Chains.PLS]: new Set(['0x97Ac4a2439A47c07ad535bb1188c989dae755341']),
 };
-/** A map of chains to uni v2 router addresses */
-export const uniV2Routers = {
-    [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 = {
     [Chains.ETH]: ['0x7a250d5630b4cf539739df2c5dacb4c659f2488d'],
     [Chains.BNB]: ['0x05fF2B0DB69458A0750badebc4f9e13aDd608C7F'],
     [Chains.SEP]: ['0xeE567Fe1712Faf6149d80dA1E6934E354124CfE3'],
@@ -85,6 +86,43 @@ export const 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).
+ */
+export const defaultSwapVenues = Object.freeze({
+    [Number(Chains.PLS)]: Object.freeze([
+        Object.freeze({
+            kind: 'uniswap-v2',
+            chainId: Number(Chains.PLS),
+            router: '0x98bf93ebf5c380C0e6Ae8e192A7e2AE08edAcc02',
+            factory: '0x1715a3E4A142d8b698131108995174F37aEBA10D',
+            feeBasisPoints: 29,
+            label: 'PulseX V1',
+        }),
+        Object.freeze({
+            kind: 'uniswap-v2',
+            chainId: Number(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) => 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.
+ */
+export const uniV2Routers = Object.freeze(Object.fromEntries(Object.values(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.
@@ -109,16 +147,10 @@ export const uniV2Routers = {
  * salt collision) and worth this note so a future reader does not assume a
  * transcription error and "fix" it back to something wrong.
  */
-export const uniV2Factories = {
-    [Chains.PLS]: [
-        '0x1715a3E4A142d8b698131108995174F37aEBA10D',
-        '0x29eA7545DEf87022BAdc76323F373EA1e707C523',
-    ],
-    [Chains.ETH]: [],
-    [Chains.BNB]: [],
-    [Chains.SEP]: [],
-    [Chains.V4PLS]: [],
-};
+export const uniV2Factories = Object.freeze(Object.fromEntries(Object.values(Chains).map((chain) => [
+    chain,
+    Object.freeze((defaultSwapVenues[Number(chain)] ?? []).map((venue) => venue.factory)),
+])));
 /** A map of chains to native token symbols */
 export const nativeTokenSymbol = {
     [Chains.PLS]: 'PLS',

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