@gibs/bridge-sdk 1.17.0 → 1.18.0

package/dist/execution.js

@@ -1,8 +1,9 @@
 import { zeroAddress } from 'viem';
 import * as abis from './abis.js';
 import { Providers, toChain } from './config.js';
+import { resolveSwapVenues } from './swap-venues.js';
 import { aggregatorOriginCalls, } from './consolidated-quote.js';
-import { pulseXRouterForEdge, pulseXSwapPathForHop } from './routing/carriers/pulsex.js';
+import { pulseXSwapPathForHop, venueForEdge } from './routing/carriers/pulsex.js';
 import { buildPulseXSwapTransaction, buildWrapTransaction, swapMinimumOut } from './routing/swap-transactions.js';
 import { approvalAmounts, approveCall, bridgePathway, destinationDataParam, feeDirectorStructEncoded, feeTypeSettings, omnibridgeApproval, transactionInputs, } from './settings.js';
 /**
@@ -94,10 +95,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 = 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 = 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 = buildPulseXSwapTransaction({
@@ -109,8 +130,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() === zeroAddress;
     return {
@@ -154,11 +176,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);
@@ -183,10 +205,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
  */
-export const planExecution = async ({ account, legs, readAllowance, }) => {
-    const calls = legs.map((leg) => legCalls(leg, account));
+export const planExecution = async ({ account, legs, readAllowance, swapVenues, }) => {
+    const venues = 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') {
@@ -363,7 +388,7 @@ const sectionWindowProblem = ({ firstSectionIndex, plannedCount, sectionCount, }
  * @returns the ordered transactions with the deliveries they buy, or the first section that cannot be planned
  */
 export 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);
@@ -386,7 +411,7 @@ export 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 planExecution({ account, legs, readAllowance });
+    const planned = await planExecution({ account, legs, readAllowance, ...(swapVenues === undefined ? {} : { swapVenues }) });
     if (planned.kind === 'refused') {
         return { kind: 'refused', sectionIndex: firstSectionIndex + planned.legIndex, refusal: planned.refusal };
     }
@@ -406,13 +431,15 @@ export const planCandidateExecution = async (inputs) => {
  * @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 const readPulseXSectionQuote = async ({ hop, amountIn, client, }) => {
+export const readPulseXSectionQuote = async ({ hop, amountIn, client, swapVenues, }) => {
     const path = pulseXSwapPathForHop(hop);
-    const router = pulseXRouterForEdge(hop.edge);
-    if (path === null || router === null || amountIn <= 0n)
+    if (path === null || amountIn <= 0n)
         return null;
+    const router = requireSwapVenue(resolveSwapVenues(swapVenues), hop.edge).router;
     try {
         const amounts = await client.readContract({
             address: router,

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

@@ -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/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/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/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/pulsex.d.ts

@@ -1,34 +1,50 @@
 import { type Hex } from 'viem';
 import type { PublicClient } from 'viem';
+import { type SwapVenue, type SwapVenues } from '../../swap-venues.js';
 import { type AssetNode, type HopEdge, type PlannedHop } from '../search/graph.js';
 import type { CarrierAskAnswer, CarrierExactResult } from './ask-answer.js';
 /**
- * One PulseX deployment a swap can execute on: the router the reader signs
- * and the factory whose pools that router trades against. A Uniswap-V2-style
+ * One swap deployment a swap can execute on: the router the reader signs and
+ * the factory whose pools that router trades against. A Uniswap-V2-style
  * router resolves every pool through its OWN factory, so one router call can
  * only ever touch that one deployment's pools — a path can never mix them.
+ *
+ * Same type as {@link SwapVenue}; the old name stays for existing callers.
  */
-export type PulseXVenue = {
-    readonly router: Hex;
-    readonly factory: Hex;
-};
+export type PulseXVenue = SwapVenue;
 /**
- * Every PulseX deployment on PulseChain, V1 first: `uniV2Routers` paired with
- * `uniV2Factories` by index. Each factory is the router's own
- * `router.factory()` read on chain — see `uniV2Factories`'s own doc in
- * `config.ts`. A router with no recorded factory is left out, because its
- * pools cannot be read.
+ * Every PulseX deployment on PulseChain, V1 first: the PulseChain entry of
+ * {@link defaultSwapVenues}. Frozen. It lists the DEFAULTS only — a carrier
+ * built with its own `venues` offers those instead.
  */
 export declare const pulseXVenues: readonly PulseXVenue[];
 /**
- * The router a PulseX edge must be signed on — the one its figure was quoted
- * against. Reads the edge's own {@link HopEdge.venue}; an edge with none is a
- * V1 edge (see {@link defaultPulseXVenue}).
+ * The {@link SwapVenue} a swap edge runs on: the one its figure was quoted
+ * against. Reads the edge's own {@link HopEdge.venue}; an edge with none runs
+ * on the FIRST venue of its chain (V1 for PulseX) — every swap edge built
+ * before venues existed was quoted and signed there, and the same-chain swap
+ * sender's own hand-built edge still is.
+ *
+ * NEVER FALLS BACK TO ANOTHER CHAIN OR ANOTHER ROUTER. An edge that names a
+ * router `venues` does not list gets null, so the caller can refuse it.
+ *
+ * @param venues - the venues the caller allows
+ * @param edge - the edge to sign; `from` names the chain, and defaults to PulseChain when absent
+ * @returns the venue, or null when the edge is not a swap edge or names a router that is not in `venues`
+ */
+export declare const venueForEdge: (venues: SwapVenues, edge: Pick<HopEdge, "carrier" | "venue"> & {
+    readonly from?: Pick<AssetNode, "chainId">;
+}) => SwapVenue | null;
+/**
+ * The router a PulseX edge must be signed on, judged against the DEFAULT
+ * venues only. Prefer {@link venueForEdge} with the venues your host passes.
  *
  * @param edge - the edge to sign
- * @returns the router, or null when the edge is not a PulseX edge or names a venue that is not a known PulseX router
+ * @returns the router, or null when the edge is not a swap edge or names a router that is not a default
  */
-export declare const pulseXRouterForEdge: (edge: Pick<HopEdge, "carrier" | "venue">) => Hex | null;
+export declare const pulseXRouterForEdge: (edge: Pick<HopEdge, "carrier" | "venue"> & {
+    readonly from?: Pick<AssetNode, "chainId">;
+}) => Hex | null;
 /**
  * The fixed Wrapped-PLS path from `from` to `to` — `[from, WPLS, to]`, or
  * `[from, to]` when one side is WPLS — or null when both ends resolve to the
@@ -78,9 +94,10 @@ export type PulseXPathStep = {
  *
  * @param amountIn - the amount entering the first pool
  * @param steps - the pools in order of travel
+ * @param feeBasisPoints - the venue's swap fee in basis points; PulseX's 29 when omitted
  * @returns the amount leaving the last pool; 0 when any pool cannot pay out
  */
-export declare const amountOutAlongPath: (amountIn: bigint, steps: readonly PulseXPathStep[]) => bigint;
+export declare const amountOutAlongPath: (amountIn: bigint, steps: readonly PulseXPathStep[], feeBasisPoints?: number) => bigint;
 /**
  * How far a trade's executed rate falls below the marginal (near-spot) rate,
  * in percent. The marginal rate is a tiny reference trade through the same
@@ -110,12 +127,12 @@ export type CreatePulseXCarrierOptions = {
      * in the edge's `to` token's base units. Returns null when the path has no
      * liquidity.
      *
-     * MUST READ THE EDGE'S OWN ROUTER ({@link pulseXRouterForEdge}). A V2 edge
+     * MUST READ THE EDGE'S OWN ROUTER ({@link venueForEdge}). A V2 edge
      * answered from V1 would carry V1's figure into a V2 signature.
      */
     readonly readAmountOut: (edge: HopEdge, inputAmount: bigint) => Promise<bigint | null>;
     /**
-     * Returns a PulseChain client, for {@link Carrier.prepare}'s own batched
+     * Returns a client for a chain, for {@link Carrier.prepare}'s own batched
      * reserve reads — never called by `ask`, which keeps using
      * {@link readAmountOut} unchanged.
      *
@@ -123,17 +140,25 @@ export type CreatePulseXCarrierOptions = {
      * field for why: a host that has not wired this yet gets the carrier's
      * original behavior, `prepare` a no-op and `exact` always `null`.
      *
-     * @param chainId - always {@link pulsechainChainId} — PulseX runs nowhere else
+     * @param chainId - a chain that has swap venues
      * @returns a client, or null when this host has none
      */
     readonly clientForChain?: (chainId: number) => PublicClient | null;
     /**
-     * The PulseX routers this host can SIGN on. The carrier offers an edge on
-     * each, and only on these: an edge is always signed on the router it was
-     * quoted against ({@link pulseXRouterForEdge}), so a router the host cannot
-     * sign on must never be quoted either.
+     * The swap venues to offer. Merged over {@link defaultSwapVenues} by
+     * {@link resolveSwapVenues}: a chain named here REPLACES that chain's
+     * default list, a chain left out keeps its defaults, and an empty list
+     * switches swaps off on that chain. A venue on ANY chain builds swap edges
+     * there.
+     */
+    readonly venues?: SwapVenues;
+    /**
+     * Narrows the offered venues to these routers. An edge is always signed on
+     * the router it was quoted against ({@link venueForEdge}), so a router the
+     * host cannot sign on must never be quoted either. A router that is in no
+     * offered venue is a configuration error and throws at construction.
      *
-     * Defaults to every known venue ({@link pulseXVenues}: V1 and V2).
+     * Defaults to every offered venue.
      */
     readonly routers?: readonly Hex[];
 };