@gibs/bridge-sdk 1.18.0 → 1.20.0

package/README.md

@@ -441,6 +441,39 @@ 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.
 
+### Counting signatures, approvals included
+
+`routeSignatureCount(route)` counts sections only, so a USDC route reads 1 and
+then asks for two prompts. It leaves out approvals. Use
+`routeSignatureCountForAccount` for the number the wallet will really ask for:
+
+```ts
+import {
+  type AllowanceReader,
+  type ResolveNodeToken,
+  type RouteCandidate,
+  type SectionExecutionInputs,
+  routeSignatureCountForAccount,
+} from '@gibs/bridge-sdk';
+import type { Hex } from 'viem';
+
+declare const candidate: RouteCandidate;
+declare const account: Hex;
+declare const readAllowance: AllowanceReader;
+declare const resolveToken: ResolveNodeToken;
+declare const sections: SectionExecutionInputs[];
+
+const { signatures, approvals, total } = await routeSignatureCountForAccount({
+  candidate, account, readAllowance, resolveToken, sections,
+});
+```
+
+It takes the inputs `planCandidateExecution` takes and counts the plan, so it
+uses the same allowance rule and the same spender (mediator, swap router, or
+aggregator address). A native input and a covered allowance add no approval. A
+short, non-zero allowance counts two approvals (reset, then approve). It throws
+when a section cannot be planned.
+
 ## Overriding swap routers
 
 The package swaps on PulseX V1 and V2 on PulseChain by default. You can swap on

package/dist/abis.js

@@ -1,3 +1 @@
-// All ABIs have moved to the standalone @gibs/abis package.
-// This module re-exports everything for backwards compatibility.
 export * from '@gibs/abis';

package/dist/bridge-limits.js

@@ -1,25 +1,8 @@
 import { parseAbi } from 'viem';
-/**
- * Exported so a batched reader (`routing/carriers/omnibridge.ts`'s `prepare`)
- * can multicall the same two functions across many tokens in one call rather
- * than duplicating this ABI.
- */
 export const entryLimitsAbi = parseAbi([
     'function minPerTx(address token) external view returns(uint256)',
     'function maxAvailablePerTx(address token) external view returns(uint256)',
 ]);
-/**
- * Reads the bounds the entry mediator will enforce on this exact call.
- *
- * IT TAKES THE CALL, NOT A MEDIATOR AND A TOKEN. The two travel together on the
- * destination call precisely so a caller cannot pair one route's mediator with
- * another route's token and get a plausible number back — the reads would
- * succeed and the answer would be about a transfer nobody is making.
- *
- * @param destinationCall - the entry call, or null when none could be built
- * @param entryChainClient - a client on the chain the funds leave
- * @returns the two bounds, or null when there is no call to measure
- */
 export const bridgeEntryLimits = async ({ destinationCall, entryChainClient, }) => {
     if (!destinationCall) {
         return null;
@@ -41,28 +24,7 @@ export const bridgeEntryLimits = async ({ destinationCall, entryChainClient, })
     ]);
     return { minimumPerTransaction, availablePerTransaction };
 };
-/**
- * Decides whether an amount can enter the bridge.
- *
- * WHY THIS IS WORTH CHECKING BEFORE A ROUTE IS OFFERED: on a consolidated
- * route the entry call is made by an aggregator's executor, not by the user.
- * When the mediator rejects the amount the executor's call reverts, the
- * aggregator has already delivered the funds, and they stop at the fallback
- * address on the entry chain. The user is left holding an entry-chain token
- * and a second transfer to make. Refusing the quote costs them nothing.
- *
- * The bounds are inclusive: the mediator accepts an amount equal to either.
- *
- * @param amount - the transfer, in the token's base units
- * @param limits - the bounds from {@link bridgeEntryLimits}, or null when they
- *   could not be read
- * @returns a verdict naming the bound that was missed
- */
 export const checkEntryAmount = ({ amount, limits, }) => {
-    // An unread limit is not a failed one. A network hiccup must not block a
-    // route that the mediator would accept — the transaction still gets the
-    // mediator's own answer, and this guard exists to save the user a wasted
-    // crossing, not to be the only thing standing between them and a revert.
     if (!limits) {
         return { fits: true };
     }

package/dist/chain-info.js

@@ -4,34 +4,8 @@ import { encodeFunctionData, getContract, multicall3Abi, zeroAddress, } from 'vi
 import * as abis from './abis.js';
 import { chainsMetadata } from './chains.js';
 import { nativeAssetOut, pathway, toChain, uniV2Routers, } from './config.js';
-/** Cache key for the links memoize: one entry per (chain, bridge, token) triple. */
 const linksCacheKey = ({ chainId, target, address, }) => `${chainId}-${target}-${address}`.toLowerCase();
-/**
- * Whether a {@link links} answer says the token has no mapping on this bridge
- * yet. That answer is temporary: the first transfer of the token creates the
- * mapping, so it must not be cached.
- * @param pair - the bridged and native addresses the mediator returned
- * @returns true when both are the zero address
- */
 const isUnmappedAnswer = ([bridged, native]) => bridged === zeroAddress && native === zeroAddress;
-/**
- * Returns the bridged token address and native token address that a mediator
- * holds for one token.
- *
- * A non-zero answer is cached for the life of the process: a mediator never
- * changes a mapping once the first transfer creates it. A failed read, and a
- * `[zero, zero]` answer (the token is not bridged yet), are not cached, so the
- * next call reads the chain again. Call {@link clearChainInfoCaches} to drop
- * every cached answer.
- *
- * @param inputs.chainId - the chain id being targeted
- * @param inputs.target - the mediator to ask
- * @param inputs.address - the token address
- * @param inputs.client - a client for that chain
- * @returns the bridged token address and native token address
- */
-// The body reaches for `links.cache` to evict an answer, so the cache surface
-// is spelled out to the extent this file uses it.
 export const links = memoizeByKey(async (inputs) => {
     const { chainId, target, address, client } = inputs;
     const evict = () => links.cache.delete(linksCacheKey(inputs));
@@ -45,34 +19,17 @@ export const links = memoizeByKey(async (inputs) => {
             { functionName: 'nativeTokenAddress', args: [address] },
         ],
     }).catch((error) => {
-        // a transient read failure must not poison the cache for the session
         evict();
         throw error;
     });
     if (isUnmappedAnswer(pair)) {
-        // the token may be bridged a minute from now; ask again next time
         evict();
     }
     return pair;
 }, linksCacheKey);
-/**
- * Drops every answer this module has cached, so the next read goes to the chain.
- *
- * Use it after a token's first transfer, in a long-running process that wants
- * a fresh view, or between tests.
- */
 export const clearChainInfoCaches = () => {
     links.cache.clear();
 };
-/**
- * Returns the token bridge info for the given bridge key, asset in, is prod, from chain client, and to chain client
- * @param bridgeKey - the bridge key
- * @param assetIn - the asset in
- * @param isProd - whether to use the production pathway
- * @param fromChainClient - the from chain client
- * @param toChainClient - the to chain client
- * @returns the token bridge info
- */
 export const tokenBridgeInfo = async ({ bridgeKey, assetIn, isProd, fromChainClient, toChainClient, }) => {
     const bridgePathway = pathway(bridgeKey, isProd, assetIn?.address);
     if (!assetIn || !bridgePathway) {
@@ -140,7 +97,6 @@ export const tokenBridgeInfo = async ({ bridgeKey, assetIn, isProd, fromChainCli
             },
         };
     }
-    // the token has not been bridged yet
     return {
         originationChainId: toChain,
         assetInAddress: assetInAddress,
@@ -160,23 +116,11 @@ export const tokenBridgeInfo = async ({ bridgeKey, assetIn, isProd, fromChainCli
             }),
     };
 };
-/**
- * Check the prices that each router offers for the given paths
- * @param assetInAddress the address of the asset going into the bridge
- * @param oneTokenInt the number of tokens to push into the bridge (before fees)
- * @param chain the chain of the asset going into the bridge
- * @param bridgeKey the bridge key
- * @param blockNumber the block number to use for the price
- * @param paths the paths to check
- * @returns the prices as bigint for each path, hex whenever the price is not available
- */
 const readAmountOut = ({ amountIn, chain, paths, client, uniV2Router, }) => {
     return multicallRead({
         chain: chainsMetadata[chain],
         client,
         abi: abis.univ2Router,
-        // pulsex router
-        // a chain with no router reads nothing, as lodash's flatMap over undefined did
         calls: (uniV2Router ? [uniV2Router] : (uniV2Routers[chain] ?? [])).flatMap((target) => paths.map((path) => ({
             functionName: 'getAmountsOut',
             allowFailure: true,
@@ -185,22 +129,9 @@ const readAmountOut = ({ amountIn, chain, paths, client, uniV2Router, }) => {
         }))),
     });
 };
-/**
- * Fetch the price corrective for the given bridge key, asset out, measurement token, from chain client, to chain client, asset link, amount in, and is prod
- * @param bridgeKeyPartner - the bridge key partner
- * @param assetOut - the asset out
- * @param measurementToken - the measurement token
- * @param fromChainClient - the from chain client
- * @param toChainClient - the to chain client
- * @param assetLink - the asset link
- * @param amountIn - the amount in
- * @param isProd - whether to use the production pathway
- * @returns the price corrective
- */
 export const fetchPriceCorrective = ({ bridgeKeyPartner, assetOut, measurementToken, fromChainClient, toChainClient, assetLink, amountIn, isProd, }) => {
     return {
         getPaymentToken: async () => {
-            // fetch the token bridge info for the token that is about to be spent by the delivery service
             return await tokenBridgeInfo({
                 bridgeKey: bridgeKeyPartner,
                 assetIn: {
@@ -208,8 +139,6 @@ export const fetchPriceCorrective = ({ bridgeKeyPartner, assetOut, measurementTo
                     address: measurementToken,
                 },
                 isProd,
-                // clients are reversed here because we are actually fetching the
-                // tokens going the opposite direction to the provided bridge key
                 fromChainClient: toChainClient,
                 toChainClient: fromChainClient,
             });
@@ -222,9 +151,7 @@ export const fetchPriceCorrective = ({ bridgeKeyPartner, assetOut, measurementTo
                     uniV2Router,
                     client,
                     paths: [
-                        // check the direct route
                         [assetLink.assetInAddress, paymentTokenResult.assetOutAddress],
-                        // might have heavier liquidity going through the native asset on the home side
                         [assetLink.assetInAddress, nativeAssetOut[chain], paymentTokenResult.assetOutAddress],
                     ],
                 }),
@@ -234,22 +161,17 @@ export const fetchPriceCorrective = ({ bridgeKeyPartner, assetOut, measurementTo
                     uniV2Router,
                     client,
                     paths: [[assetOut.address, measurementToken]],
-                    // only the direct route is available.
-                    // might be able to create a whitelist for this at some point
                 }),
             ]);
         },
         reduceResults: ({ results, oneToken, }) => {
             const outputFromRouter = (result) => {
                 if (typeof result === 'string') {
-                    // the router failed to return a result
                     return 0n;
                 }
                 if (!result.length) {
-                    // the router returned an empty result
                     return 0n;
                 }
-                // the last element is the amount of the output token
                 const last = result[result.length - 1];
                 return (last * oneToken) / amountIn;
             };
@@ -258,7 +180,6 @@ export const fetchPriceCorrective = ({ bridgeKeyPartner, assetOut, measurementTo
                     .filter((amount) => amount !== undefined)
                     .reduce((max, current) => (max < current ? current : max), 0n);
             };
-            // could do with a refactor to unify the results
             const [outputs, inputs] = results;
             const outputAmounts = outputs.map(outputFromRouter);
             const inputAmounts = inputs.map(outputFromRouter);
@@ -273,36 +194,12 @@ export const fetchPriceCorrective = ({ bridgeKeyPartner, assetOut, measurementTo
         },
     };
 };
-/**
- * Read the smallest amount the bridge will accept for this asset on this pathway.
- *
- * THE ENTRY MEDIATOR DECIDES, so this always reads `pathway.from` on the chain
- * the funds leave. `feeManager` says which side prices the transfer; it has
- * never said which side validates the amount, and using it for both is what
- * produced the defect this replaces.
- *
- * Both mediators keep a `minPerTx` under the same name, and for a token that
- * originates on the entry chain the two sides usually hold the same number. That
- * agreement is a coincidence of configuration - each side is separately
- * governed, and both happen to apply one blanket default. It breaks outright for
- * a token that originates on the far side, because the two mediators key their
- * limits by different addresses. Wrapped Pulse entering from Ethereum is the
- * live case: the entry mediator enforces 50,000, and the destination mediator
- * answers 0 for that same address because it files that token under its
- * PulseChain address instead. Reading the destination got both the chain and the
- * token key wrong, and reported no floor where a real one stood.
- * @param assetIn - the asset the sender holds, on the chain it leaves from
- * @param pathway - the pathway, with any per-asset overrides already applied
- * @param fromPublicClient - a client for the chain the funds leave
- * @returns the smallest amount the entry mediator will accept
- */
 export const minBridgeAmountIn = async ({ assetIn, pathway, fromPublicClient, }) => fromPublicClient.readContract({
     abi: abis.inputBridge,
     functionName: 'minPerTx',
     args: [assetIn.address],
     address: pathway.from,
 });
-/** get the symbol of the native asset, unwrap it if it needs to be */
 export const nativeSymbol = (asset, unwrap = false) => {
     return asset
         ? unwrap && asset.address === nativeAssetOut[toChain(asset.chainId)]
@@ -310,12 +207,6 @@ export const nativeSymbol = (asset, unwrap = false) => {
             : asset.symbol
         : '';
 };
-/**
- * Returns the Multicall3 contract for the client's chain.
- * @param client - a client whose `chain` is one of {@link chainsMetadata}'s chains
- * @returns the Multicall3 contract instance
- * @throws when the client carries no chain, or the chain has no Multicall3 address
- */
 export const chainMulticall = (client) => {
     const chainId = client.chain?.id;
     if (chainId === undefined) {
@@ -327,13 +218,6 @@ export const chainMulticall = (client) => {
     }
     return getContract({ abi: multicall3Abi, client, address });
 };
-/**
- * Load the bridge fees for the given pathway, from chain client, and to chain client
- * @param pathway - the pathway
- * @param fromChainClient - the from chain client
- * @param toChainClient - the to chain client
- * @returns the bridge fees
- */
 export const loadBridgeFees = async ({ pathway, fromChainClient, toChainClient, }) => {
     const multicall = pathway.feeManager === 'from' ? chainMulticall(fromChainClient) : chainMulticall(toChainClient);
     const [feeManagerResponse] = await multicall.read.aggregate3([

package/dist/chain-names.js

@@ -1,117 +1,22 @@
-/**
- * Chain identifiers and their human-readable display names, in one place.
- *
- * This module exists to break an import cycle. `relay-quote.ts` imports the
- * step normalizers from `route-steps.ts`, and `route-steps.ts` needs to name
- * Relay's non-Ethereum chains when it labels a leg. Holding the shared lookup
- * here lets both import it without either importing the other.
- *
- * Names are spelled out in full — these strings are shown to someone choosing
- * where their funds leave from, so "The Open Network", never "TON".
- */
-/**
- * Relay's numeric chain identifiers for the non-Ethereum-Virtual-Machine origin
- * chains this bridge supports. These are Relay's OWN identifiers, distinct from
- * any native chain id, and are required verbatim as the request's
- * `originChainId`.
- *
- * Source: https://api.relay.link/chains, where each entry's `vmType` names the
- * ecosystem and each is reported `depositEnabled`.
- */
 export const relayChainIds = {
-    /** Relay's chain id for Solana mainnet (virtual-machine type `svm`). */
     solana: 792703809,
-    /**
-     * Relay's chain id for Eclipse (virtual-machine type `svm`) — a SECOND chain
-     * in the Solana ecosystem, sharing Solana's address encoding, deposit shape
-     * and native-asset sentinel while being a different network with a different
-     * native asset (Ether, not Sol).
-     *
-     * Quotable, but see the guard in the interface's Solana signer: sharing an
-     * ecosystem means sharing a wallet adapter, and that adapter is bound to ONE
-     * Solana network at a time. A deposit for this chain must never be signed
-     * against a connection pointed at Solana.
-     */
     eclipse: 9286185,
-    /** Relay's chain id for Bitcoin mainnet (virtual-machine type `bvm`). */
     bitcoin: 8253038,
-    /** Relay's chain id for Tron mainnet (virtual-machine type `tvm`). */
     tron: 728126428,
-    /** Relay's chain id for The Open Network (virtual-machine type `tonvm`). */
     ton: 224235520,
-    /**
-     * Relay's chain id for Hyperliquid (virtual-machine type `hypevm`).
-     *
-     * BEWARE: 1337 is also the default chain id of a local Ganache development
-     * node, so this is the one Relay identifier that can collide with a real
-     * Ethereum Virtual Machine chain a developer might be running. Treating a
-     * local test chain as Hyperliquid would route it down the HyperCore deposit
-     * path, so never feed a local development chain id through
-     * `ecosystemByChainId`.
-     */
     hyperliquid: 1337,
 };
-/**
- * Chain identifiers for origin chains a reader PAYS BY HAND.
- *
- * WHAT MAKES THESE DIFFERENT FROM EVERY OTHER CHAIN HERE. Every identifier
- * above names a chain this interface can connect a wallet to and sign on.
- * These name chains it cannot. There is no connector, no signer and no
- * transaction: the provider issues an address, the reader sends an ordinary
- * transfer to it from any wallet or any exchange, and the provider's own
- * watcher reports the arrival. The chain identifier exists so the route layer
- * can NAME the chain, price it and draw it — nothing more.
- *
- * THE NUMBERS ARE DERIVED, NOT INVENTED, and the derivation is written down
- * because a chain identifier typed from memory is a hypothesis every later
- * reader will trust. Each is the chain's registered SLIP-0044 coin type with
- * the hardened bit set, exactly as a BIP-44 derivation path writes it:
- * `0x80000000 + coinType`. That puts them above every chain identifier in
- * public use, so one can never collide with a real Ethereum chain and be
- * mistaken for one — which is the failure that matters, because an Ethereum
- * chain has a wallet and would be handed a payload to sign.
- *
- * They are LOCAL identifiers and never travel on a wire. NEAR Intents names
- * Zcash `zec`; `chainIdByNearIntentsChain` is where the two are reconciled.
- */
 export const depositAddressChainIds = {
-    /** Zcash mainnet. SLIP-0044 coin type 133, hardened: 0x80000000 + 133. */
     zcash: 2_147_483_781,
 };
-/**
- * Display names for the chains a reader pays by hand, one entry per member of
- * {@link DepositAddressChain}. Typed on the union rather than on `number` so a
- * chain added to {@link depositAddressChainIds} without a name here is a
- * compile error, not a blank badge.
- */
 const depositAddressChainNamesByChain = {
     zcash: 'Zcash',
 };
-/** {@link depositAddressChainNamesByChain}, keyed by chain id for lookup. */
 const depositAddressChainNames = new Map(Object.keys(depositAddressChainIds).map((chain) => [
     depositAddressChainIds[chain],
     depositAddressChainNamesByChain[chain],
 ]));
-/**
- * Whether a chain identifier names a chain this interface CANNOT SIGN ON.
- *
- * The one predicate every surface asks before offering a wallet. A chain that
- * answers true has no connector, so anything that would connect, switch
- * networks, estimate gas or compose a transaction for it is wrong — the reader
- * is shown an address to pay instead.
- *
- * @param chainId - a chain identifier
- * @returns whether the reader pays this chain by hand
- */
 export const isDepositAddressChain = (chainId) => depositAddressChainNames.has(chainId);
-/**
- * Display names for Relay's non-Ethereum origin chains.
- *
- * An ecosystem label is NOT a chain name, and using one as a name is actively
- * wrong: `svm` holds both Solana and Eclipse, so labelling by ecosystem renders
- * Eclipse as "Solana" — a different network, shown to someone choosing where
- * their funds leave from. Keyed by chain id for exactly that reason.
- */
 export const relayChainNames = new Map([
     [relayChainIds.solana, 'Solana'],
     [relayChainIds.eclipse, 'Eclipse'],
@@ -120,11 +25,6 @@ export const relayChainNames = new Map([
     [relayChainIds.ton, 'The Open Network'],
     [relayChainIds.hyperliquid, 'Hyperliquid'],
 ]);
-/**
- * Display names for the Ethereum-Virtual-Machine chains a route can traverse.
- * Only the chains this bridge actually routes through need an entry; anything
- * else falls back to its numeric identifier rather than being dropped.
- */
 const virtualMachineChainNames = new Map([
     [1, 'Ethereum'],
     [56, 'Binance Smart Chain'],
@@ -133,28 +33,7 @@ const virtualMachineChainNames = new Map([
     [42161, 'Arbitrum One'],
     [11155111, 'Sepolia'],
 ]);
-/**
- * Names registered at startup from the wider chain registry.
- *
- * This package cannot import that registry — it sits below the client that
- * holds it — but it must still be the ONE place a chain name is decided. The
- * alternative was what this replaced: three resolvers, each with different
- * coverage, so the same chain read as "Base" beside one element, "chain 8453"
- * beside another, and vanished entirely from a third. A reader hovering two
- * parts of the same row saw two different answers.
- */
 const registeredChainNames = new Map();
-/**
- * Registers display names for chains this module does not know about.
- *
- * Call once during startup, before anything renders. Entries are merged, and a
- * name declared in `virtualMachineChainNames` above WINS over a registered one:
- * the local table is deliberate ("Binance Smart Chain", not the registry's
- * "BNB Smart Chain"), and a registry that happens to disagree must not quietly
- * rename a chain the product has already named.
- *
- * @param entries - chain id and display name pairs
- */
 export const registerChainNames = (entries) => {
     for (const [chainId, name] of entries) {
         if (!name)
@@ -162,37 +41,7 @@ export const registerChainNames = (entries) => {
         registeredChainNames.set(chainId, name);
     }
 };
-/**
- * Returns a human-readable chain name for the given chain id, covering both
- * Ethereum-Virtual-Machine chains and Relay's non-Ethereum pseudo identifiers.
- *
- * Falls back to the numeric id stringified when the chain is not known — better
- * to show "chain 999" than to silently drop the leg that traverses it.
- *
- * @param chainId - a decimal chain id, Relay's identifier included
- * @returns the display name, or `chain <id>` when unknown
- */
 export const chainDisplayName = (chainId) => knownChainName(chainId) ?? `chain ${chainId}`;
-/**
- * The name this module KNOWS for a chain, or null when it knows none.
- *
- * Same lookup as {@link chainDisplayName} without the placeholder, so a caller
- * with a better fallback of its own can reach one. {@link chainDisplayName} is
- * defined in terms of this, which is the point: the two can never disagree
- * about which chains are known.
- *
- * WHY A CALLER WOULD WANT THIS. The network chips in the token picker have a
- * second name to fall back on — the aggregator's own chain list, which reaches
- * chains this registry has never been told about and says "Unknown network"
- * rather than printing a bare number. Choosing between the two used to be done
- * by comparing `chainDisplayName`'s answer against the literal string
- * `chain <id>`, which is a caller reaching into another function's fallback
- * format: rename the placeholder here and that comparison quietly stops
- * matching, leaving every unknown chain labelled with its number.
- *
- * @param chainId - a decimal chain id, Relay's identifiers included
- * @returns the display name, or null when the chain is not known here
- */
 export const knownChainName = (chainId) => virtualMachineChainNames.get(chainId) ??
     relayChainNames.get(chainId) ??
     depositAddressChainNames.get(chainId) ??