@gibs/bridge-sdk 1.17.0 → 1.19.0

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

@@ -1,3 +1,4 @@
+import { type CandidateExecutionInputs } from '../execution.js';
 import type { RouteCandidate } from './candidate.js';
 import type { RouteData } from './route-data.js';
 /**
@@ -37,7 +38,51 @@ export declare const buildRouteDataForCandidate: (candidate: RouteCandidate) =>
  * site, so a surface that warns about a long journey and a surface that ranks
  * routes cannot come to different counts.
  *
+ * THIS COUNT LEAVES OUT APPROVALS. A token that is not the chain's native coin
+ * needs an `approve` transaction before its first section when the allowance
+ * is too small, and that approval is a signature too. Raw route data does not
+ * say who the spender is or what the account has approved already, so this
+ * function cannot count it. Use {@link routeSignatureCountForAccount} for the
+ * number the wallet will really ask for.
+ *
  * @param route - the raw route data
- * @returns the number of signatures, one per section
+ * @returns the number of signatures, one per section, with no approvals
  */
 export declare const routeSignatureCount: (route: RouteData) => number;
+/** What {@link routeSignatureCountForAccount} reports. */
+export type RouteSignatureCount = {
+    /** Signatures for the sections themselves: one per planned section. */
+    readonly signatures: number;
+    /** Approval transactions the account must sign first, given what it has approved already. */
+    readonly approvals: number;
+    /** `signatures + approvals`: every wallet prompt the planned sections cause. */
+    readonly total: number;
+};
+/**
+ * How many wallet signatures a route asks one account for, approvals included.
+ *
+ * {@link routeSignatureCount} counts sections only, so a USDC route reads "1"
+ * and then asks for two prompts: approve, then send. This function plans the
+ * sections with {@link planCandidateExecution} and counts what that plan
+ * contains, so it uses the same allowance rule and the same spender the
+ * execution planner uses. A native input needs no approval. An allowance that
+ * already covers the amount needs none. A smaller, non-zero allowance counts
+ * the reset and the new approval, the two transactions the planner emits. The
+ * spender is whatever the planner picks: the omnibridge mediator, a swap
+ * venue's router (including routers passed in `swapVenues`), or the
+ * aggregator's approval address.
+ *
+ * Pass every section of the route to count the whole route. Pass fewer to
+ * count only the window you plan now; each section is counted against the
+ * allowance on chain today, so a later section that spends a token an earlier
+ * section delivers is counted as if the approval is still needed.
+ *
+ * An aggregator section needs its `aggregator` inputs, a quote and the request
+ * it answered, exactly as {@link planCandidateExecution} does. Without them
+ * this function throws, because the approval spender comes from that quote.
+ *
+ * @param inputs - the same inputs {@link planCandidateExecution} takes
+ * @returns the signatures, approvals, and their total
+ * @throws when a section cannot be planned; the message names the section and the reason
+ */
+export declare const routeSignatureCountForAccount: (inputs: CandidateExecutionInputs) => Promise<RouteSignatureCount>;

package/dist/cjs/routing/candidate-route.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.routeSignatureCount = exports.buildRouteDataForCandidate = void 0;
+exports.routeSignatureCountForAccount = exports.routeSignatureCount = exports.buildRouteDataForCandidate = void 0;
 const near_intents_route_js_1 = require("../near-intents-route.js");
+const execution_js_1 = require("../execution.js");
 const producers_js_1 = require("./producers.js");
 /**
  * One door in front of the two base route builders.
@@ -43,8 +44,52 @@ exports.buildRouteDataForCandidate = buildRouteDataForCandidate;
  * site, so a surface that warns about a long journey and a surface that ranks
  * routes cannot come to different counts.
  *
+ * THIS COUNT LEAVES OUT APPROVALS. A token that is not the chain's native coin
+ * needs an `approve` transaction before its first section when the allowance
+ * is too small, and that approval is a signature too. Raw route data does not
+ * say who the spender is or what the account has approved already, so this
+ * function cannot count it. Use {@link routeSignatureCountForAccount} for the
+ * number the wallet will really ask for.
+ *
  * @param route - the raw route data
- * @returns the number of signatures, one per section
+ * @returns the number of signatures, one per section, with no approvals
  */
 const routeSignatureCount = (route) => route.sections.length;
 exports.routeSignatureCount = routeSignatureCount;
+/**
+ * How many wallet signatures a route asks one account for, approvals included.
+ *
+ * {@link routeSignatureCount} counts sections only, so a USDC route reads "1"
+ * and then asks for two prompts: approve, then send. This function plans the
+ * sections with {@link planCandidateExecution} and counts what that plan
+ * contains, so it uses the same allowance rule and the same spender the
+ * execution planner uses. A native input needs no approval. An allowance that
+ * already covers the amount needs none. A smaller, non-zero allowance counts
+ * the reset and the new approval, the two transactions the planner emits. The
+ * spender is whatever the planner picks: the omnibridge mediator, a swap
+ * venue's router (including routers passed in `swapVenues`), or the
+ * aggregator's approval address.
+ *
+ * Pass every section of the route to count the whole route. Pass fewer to
+ * count only the window you plan now; each section is counted against the
+ * allowance on chain today, so a later section that spends a token an earlier
+ * section delivers is counted as if the approval is still needed.
+ *
+ * An aggregator section needs its `aggregator` inputs, a quote and the request
+ * it answered, exactly as {@link planCandidateExecution} does. Without them
+ * this function throws, because the approval spender comes from that quote.
+ *
+ * @param inputs - the same inputs {@link planCandidateExecution} takes
+ * @returns the signatures, approvals, and their total
+ * @throws when a section cannot be planned; the message names the section and the reason
+ */
+const routeSignatureCountForAccount = async (inputs) => {
+    const plan = await (0, execution_js_1.planCandidateExecution)(inputs);
+    if (plan.kind === 'refused') {
+        throw new Error(`Cannot count signatures: section ${plan.sectionIndex} cannot be planned (${JSON.stringify(plan.refusal)}).`);
+    }
+    const approvals = plan.transactions.filter((transaction) => transaction.kind === 'approve').length;
+    const signatures = plan.transactions.length - approvals;
+    return { signatures, approvals, total: plan.transactions.length };
+};
+exports.routeSignatureCountForAccount = routeSignatureCountForAccount;

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;

package/dist/cjs/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[];
 };