@gibs/bridge-sdk 1.13.1 → 1.17.0

package/dist/cjs/abis.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// All ABIs have moved to the standalone @gibs/abis package.
+// This module re-exports everything for backwards compatibility.
+__exportStar(require("@gibs/abis"), exports);

package/dist/cjs/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/cjs/bridge-limits.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkEntryAmount = exports.bridgeEntryLimits = exports.entryLimitsAbi = void 0;
+const viem_1 = require("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.
+ */
+exports.entryLimitsAbi = (0, viem_1.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
+ */
+const bridgeEntryLimits = async ({ destinationCall, entryChainClient, }) => {
+    if (!destinationCall) {
+        return null;
+    }
+    const { entryMediator, entryTokenAddress } = destinationCall;
+    const [minimumPerTransaction, availablePerTransaction] = await Promise.all([
+        entryChainClient.readContract({
+            abi: exports.entryLimitsAbi,
+            functionName: 'minPerTx',
+            args: [entryTokenAddress],
+            address: entryMediator,
+        }),
+        entryChainClient.readContract({
+            abi: exports.entryLimitsAbi,
+            functionName: 'maxAvailablePerTx',
+            args: [entryTokenAddress],
+            address: entryMediator,
+        }),
+    ]);
+    return { minimumPerTransaction, availablePerTransaction };
+};
+exports.bridgeEntryLimits = bridgeEntryLimits;
+/**
+ * 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
+ */
+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 };
+};
+exports.checkEntryAmount = checkEntryAmount;

package/dist/cjs/chain-info.d.ts

@@ -0,0 +1,169 @@
+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;
+    assetOutAddress: Hex | null;
+    toForeign?: {
+        home: Hex;
+        foreign: Hex | null;
+    };
+    toHome?: {
+        home: Hex | null;
+        foreign: Hex;
+    };
+};
+/** The inputs of one {@link links} read. */
+type LinksInputs = {
+    chainId: number;
+    target: Hex;
+    address: Hex;
+    client: PublicClient;
+};
+/**
+ * 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
+ * @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 declare const tokenBridgeInfo: ({ bridgeKey, assetIn, isProd, fromChainClient, toChainClient, }: {
+    bridgeKey: BridgeKey;
+    assetIn: Token | null;
+    isProd: boolean;
+    fromChainClient: PublicClient;
+    toChainClient: PublicClient;
+}) => Promise<null | TokenBridgeInfo>;
+/** The result of reading the amount out from a router */
+export type FetchResult = bigint[] | Hex;
+/**
+ * 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 declare const fetchPriceCorrective: ({ bridgeKeyPartner, assetOut, measurementToken, fromChainClient, toChainClient, assetLink, amountIn, isProd, }: {
+    bridgeKey: BridgeKey;
+    bridgeKeyPartner: BridgeKey;
+    measurementToken: Hex;
+    assetOut: Token;
+    fromChainClient: PublicClient;
+    toChainClient: PublicClient;
+    assetLink: TokenBridgeInfo;
+    amountIn: bigint;
+    isProd: boolean;
+}) => {
+    getPaymentToken: () => Promise<TokenBridgeInfo | null>;
+    getSwapResults: ({ paymentTokenResult, chain, uniV2Router, client, }: {
+        paymentTokenResult: TokenBridgeInfo;
+        chain: Chains;
+        client: PublicClient;
+        uniV2Router?: Hex;
+    }) => Promise<[FetchResult[], FetchResult[]]>;
+    reduceResults: ({ results, oneToken, }: {
+        results: [FetchResult[], ...[FetchResult[]]];
+        oneToken: bigint;
+    }) => bigint;
+};
+/**
+ * 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, }: {
+    assetIn: Token;
+    pathway: Pathway;
+    fromPublicClient: PublicClient;
+}) => Promise<bigint>;
+/** get the symbol of the native asset, unwrap it if it needs to be */
+export declare const nativeSymbol: (asset: {
+    address: string;
+    symbol: string;
+    chainId: number;
+} | null, unwrap?: boolean) => string;
+/** The input for loading the bridge fees */
+export type InputLoadFeeFor = {
+    pathway: Pathway;
+    fromChainClient: PublicClient;
+    toChainClient: PublicClient;
+};
+/** The fee configuration for a given pathway */
+export type PathwayExtendableConfig = {
+    feeManager: Hex;
+    feeH2F: bigint;
+    feeF2H: bigint;
+};
+/** A typed Multicall3 contract instance for one chain. */
+export type ChainMulticall = GetContractReturnType<typeof multicall3Abi, PublicClient, Address>;
+/**
+ * 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) => ChainMulticall;
+/**
+ * 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 declare const loadBridgeFees: ({ pathway, fromChainClient, toChainClient, }: InputLoadFeeFor) => Promise<PathwayExtendableConfig>;
+export {};