@gibs/bridge-sdk 1.10.1 → 1.13.0

package/dist/abis.d.ts

@@ -0,0 +1 @@
+export * from '@gibs/abis';

package/dist/abis.js

@@ -0,0 +1,3 @@
+// 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.d.ts

@@ -0,0 +1,103 @@
+import type { PublicClient } from 'viem';
+import type { DestinationCall } from './destination-calldata.js';
+/**
+ * The two bounds the entry mediator puts on a single transfer, read from the
+ * contract the transaction actually calls.
+ *
+ * BOTH ARE READ FROM THE ENTRY SIDE, NOT THE FAR SIDE. The mediator validates
+ * the amount before it emits anything, so the bound that decides whether a
+ * transfer happens at all belongs to the chain the funds leave. The far side
+ * keeps its own limits under the same names, and nothing makes the two agree —
+ * they are separately governed contracts. Measured 2026-08-31: raising
+ * `minPerTx` on the Ethereum mediator alone, with PulseChain untouched, makes
+ * the entry call revert. `bridge-limits.fork.test.ts` keeps that honest.
+ */
+export type EntryLimits = {
+    /** Smallest transfer the mediator will accept, in the token's base units. */
+    minimumPerTransaction: bigint;
+    /**
+     * Largest transfer the mediator will accept RIGHT NOW, in base units.
+     *
+     * This is not a constant ceiling. The mediator returns the lower of its
+     * per-transfer cap and what is left of today's allowance, so it falls as the
+     * day is used up and resets on its own schedule. Do not cache it.
+     */
+    availablePerTransaction: bigint;
+};
+/** Why an amount cannot enter the bridge, or that it can. */
+export type EntryAmountVerdict = {
+    fits: true;
+} | {
+    fits: false;
+    reason: 'below-minimum';
+    minimumPerTransaction: bigint;
+} | {
+    fits: false;
+    reason: 'above-available';
+    availablePerTransaction: bigint;
+};
+/**
+ * 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 declare const entryLimitsAbi: readonly [{
+    readonly name: "minPerTx";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "token";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "maxAvailablePerTx";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "token";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "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 declare const bridgeEntryLimits: ({ destinationCall, entryChainClient, }: {
+    destinationCall: Pick<DestinationCall, "entryMediator" | "entryTokenAddress"> | null;
+    entryChainClient: PublicClient;
+}) => Promise<EntryLimits | null>;
+/**
+ * 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 declare const checkEntryAmount: ({ amount, limits, }: {
+    amount: bigint;
+    limits: EntryLimits | null;
+}) => EntryAmountVerdict;

package/dist/bridge-limits.js

@@ -0,0 +1,84 @@
+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;
+    }
+    const { entryMediator, entryTokenAddress } = destinationCall;
+    const [minimumPerTransaction, availablePerTransaction] = await Promise.all([
+        entryChainClient.readContract({
+            abi: entryLimitsAbi,
+            functionName: 'minPerTx',
+            args: [entryTokenAddress],
+            address: entryMediator,
+        }),
+        entryChainClient.readContract({
+            abi: entryLimitsAbi,
+            functionName: 'maxAvailablePerTx',
+            args: [entryTokenAddress],
+            address: entryMediator,
+        }),
+    ]);
+    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 };
+    }
+    if (amount < limits.minimumPerTransaction) {
+        return {
+            fits: false,
+            reason: 'below-minimum',
+            minimumPerTransaction: limits.minimumPerTransaction,
+        };
+    }
+    if (amount > limits.availablePerTransaction) {
+        return {
+            fits: false,
+            reason: 'above-available',
+            availablePerTransaction: limits.availablePerTransaction,
+        };
+    }
+    return { fits: true };
+};

package/dist/{src/chain-info.d.ts → chain-info.d.ts}

@@ -1,7 +1,6 @@
-import { type Hex, type PublicClient } from "viem";
-import { Chains, type Pathway } from "./config.js";
-import type { BridgeKey, Token } from "./types.js";
-import _ from "lodash";
+import { type Address, type GetContractReturnType, type Hex, multicall3Abi, type PublicClient } from 'viem';
+import { type Chains, type Pathway } from './config.js';
+import type { BridgeKey, Token } from './types.js';
 export type TokenBridgeInfo = {
     originationChainId: Chains;
     assetInAddress: Hex;
@@ -15,20 +14,42 @@ export type TokenBridgeInfo = {
         foreign: Hex;
     };
 };
-/**
- * Returns the bridged token address and native token address
- * @param chainId - the chain id being targeted
- * @param target - the target
- * @param address - the address
- * @param client - the client
- * @returns the bridged token address and native token address
- */
-export declare const links: (({ chainId, target, address, client }: {
+/** The inputs of one {@link links} read. */
+type LinksInputs = {
     chainId: number;
     target: Hex;
     address: Hex;
     client: PublicClient;
-}) => Promise<[`0x${string}`, `0x${string}`]>) & _.MemoizedFunction;
+};
+/**
+ * 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
+ */
+export declare const links: ((inputs: LinksInputs) => Promise<[Hex, Hex]>) & {
+    cache: {
+        delete: (key: string) => boolean;
+        clear?: () => void;
+    };
+};
+/**
+ * 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 declare const clearChainInfoCaches: () => void;
 /**
  * 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
@@ -83,18 +104,32 @@ export declare const fetchPriceCorrective: ({ bridgeKeyPartner, assetOut, measur
     }) => bigint;
 };
 /**
- * Fetch the minimum bridge amount in for the given asset in, pathway, from public client, and to public client
- * @param assetIn - the asset in
- * @param pathway - the pathway
- * @param fromPublicClient - the from public client
- * @param toPublicClient - the to public client
- * @returns the minimum bridge amount in
+ * 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 declare const minBridgeAmountIn: ({ assetIn, pathway, fromPublicClient, toPublicClient, }: {
+export declare const minBridgeAmountIn: ({ assetIn, pathway, fromPublicClient, }: {
     assetIn: Token;
     pathway: Pathway;
     fromPublicClient: PublicClient;
-    toPublicClient: PublicClient;
 }) => Promise<bigint>;
 /** get the symbol of the native asset, unwrap it if it needs to be */
 export declare const nativeSymbol: (asset: {
@@ -114,12 +149,15 @@ export type PathwayExtendableConfig = {
     feeH2F: bigint;
     feeF2H: bigint;
 };
+/** A typed Multicall3 contract instance for one chain. */
+export type ChainMulticall = GetContractReturnType<typeof multicall3Abi, PublicClient, Address>;
 /**
- * Returns the chain multicall for the given client
- * @param client - the client
- * @returns the chain multicall
+ * 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 declare const chainMulticall: (client: PublicClient) => any;
+export declare const chainMulticall: (client: PublicClient) => ChainMulticall;
 /**
  * Load the bridge fees for the given pathway, from chain client, and to chain client
  * @param pathway - the pathway
@@ -127,4 +165,5 @@ export declare const chainMulticall: (client: PublicClient) => any;
  * @param toChainClient - the to chain client
  * @returns the bridge fees
  */
-export declare const loadBridgeFees: ({ pathway, fromChainClient, toChainClient }: InputLoadFeeFor) => Promise<PathwayExtendableConfig>;
+export declare const loadBridgeFees: ({ pathway, fromChainClient, toChainClient, }: InputLoadFeeFor) => Promise<PathwayExtendableConfig>;
+export {};

package/dist/{src/chain-info.js → chain-info.js}

@@ -1,19 +1,44 @@
-import { encodeFunctionData, getContract, multicall3Abi, zeroAddress } from "viem";
-import { nativeAssetOut, pathway, toChain, uniV2Routers } from "./config.js";
-import _ from "lodash";
-import { chainsMetadata } from "./chains.js";
-import * as abis from "./abis.js";
-import { multicallRead } from "@gibs/common/multicall";
+import { multicallRead } from '@gibs/common/multicall';
+import * as _ from 'lodash-es';
+import { encodeFunctionData, getContract, multicall3Abi, zeroAddress, } from 'viem';
+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();
 /**
- * Returns the bridged token address and native token address
- * @param chainId - the chain id being targeted
- * @param target - the target
- * @param address - the address
- * @param client - the client
+ * 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
  */
-export const links = _.memoize(async ({ chainId, target, address, client }) => {
-    return multicallRead({
+// The annotation is required, not stylistic: `@types/lodash-es` re-exports its
+// `MemoizedFunction` type from a nested `@types/lodash` that a generated
+// declaration file cannot name (TS2742). 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 = _.memoize(async (inputs) => {
+    const { chainId, target, address, client } = inputs;
+    const evict = () => links.cache.delete(linksCacheKey(inputs));
+    const pair = await multicallRead({
         client,
         chain: chainsMetadata[toChain(chainId)],
         abi: abis.inputBridge,
@@ -22,8 +47,27 @@ export const links = _.memoize(async ({ chainId, target, address, client }) => {
             { functionName: 'bridgedTokenAddress', args: [address] },
             { functionName: 'nativeTokenAddress', args: [address] },
         ],
+    }).catch((error) => {
+        // a transient read failure must not poison the cache for the session
+        evict();
+        throw error;
     });
-}, ({ chainId, target, address }) => `${chainId}-${target}-${address}`.toLowerCase());
+    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 = () => {
+    // lodash types mark `clear` optional; the default MapCache always has it
+    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
@@ -36,7 +80,6 @@ export const links = _.memoize(async ({ chainId, target, address, client }) => {
 export const tokenBridgeInfo = async ({ bridgeKey, assetIn, isProd, fromChainClient, toChainClient, }) => {
     const bridgePathway = pathway(bridgeKey, isProd, assetIn?.address);
     if (!assetIn || !bridgePathway) {
-        console.log('missing asset in or bridge pathway');
         return null;
     }
     const [, fromChain, toChain] = bridgeKey;
@@ -228,43 +271,62 @@ export const fetchPriceCorrective = ({ bridgeKeyPartner, assetOut, measurementTo
                     : outputToken
                 : inputToken;
             return result;
-        }
+        },
     };
 };
 /**
- * Fetch the minimum bridge amount in for the given asset in, pathway, from public client, and to public client
- * @param assetIn - the asset in
- * @param pathway - the pathway
- * @param fromPublicClient - the from public client
- * @param toPublicClient - the to public client
- * @returns the minimum bridge amount in
+ * 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, toPublicClient, }) => {
-    const publicClient = pathway?.feeManager === 'from' ? fromPublicClient : toPublicClient;
-    return publicClient.readContract({
-        abi: abis.inputBridge,
-        functionName: 'minPerTx',
-        args: [assetIn.address],
-        address: pathway[pathway.feeManager],
-    });
-};
+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)] ? asset.symbol.slice(1) : asset.symbol) : '';
+    return asset
+        ? unwrap && asset.address === nativeAssetOut[toChain(asset.chainId)]
+            ? asset.symbol.slice(1)
+            : asset.symbol
+        : '';
 };
 /**
- * Returns the chain multicall for the given client
- * @param client - the client
- * @returns the chain multicall
+ * 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;
-    const metadata = chainsMetadata[toChain(chainId)];
-    return getContract({
-        abi: multicall3Abi,
-        client: client,
-        address: metadata.contracts.multicall3.address,
-    });
+    const chainId = client.chain?.id;
+    if (chainId === undefined) {
+        throw new Error('chainMulticall: the client has no chain configured');
+    }
+    const address = chainsMetadata[toChain(chainId)]?.contracts?.multicall3?.address;
+    if (!address) {
+        throw new Error(`chainMulticall: no Multicall3 address known for chain ${chainId}`);
+    }
+    return getContract({ abi: multicall3Abi, client, address });
 };
 /**
  * Load the bridge fees for the given pathway, from chain client, and to chain client
@@ -273,10 +335,8 @@ export const chainMulticall = (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);
+export const loadBridgeFees = async ({ pathway, fromChainClient, toChainClient, }) => {
+    const multicall = pathway.feeManager === 'from' ? chainMulticall(fromChainClient) : chainMulticall(toChainClient);
     const [feeManagerResponse] = await multicall.read.aggregate3([
         [
             {