@gibs/bridge-sdk 1.13.1 → 1.18.0

package/dist/chains.js

@@ -3,7 +3,7 @@
 // same module would be loaded twice, once as source and once as build output,
 // and `Chains.PLS` from one would not be the same object as from the other.
 import { chainDisplayName } from './chain-names.js';
-import { Chains } from './config.js';
+import { Chains, toChain } from './config.js';
 import * as imageLinks from './image-links.js';
 // Chain definitions come from viem, not from a wallet-connection library. These
 // five objects are identical in `@reown/appkit/networks`, which is where they used
@@ -14,6 +14,12 @@ import { bsc, mainnet, pulsechain, pulsechainV4, sepolia } from 'viem/chains';
 /**
  * Builds an endpoint on valve.city, which proxies four of this dapp's chains.
  *
+ * DEMO ONLY. These endpoints live in {@link demoRpcUrls}, never in
+ * {@link chainsMetadata}. A third party that hands `chainsMetadata` to viem with
+ * a bare `http()` gets the public endpoints below, not this shared key. The Gibs
+ * interface asks for the demo list by name (`@gibs/bridge-client`'s
+ * `clientFromChain`). Any other caller should pass its own clients.
+ *
  * The key in this URL is `vk_demo`, and it is MEANT to be here. It is the
  * proxy's published demo key — it is already listed on chainlist.org, so it is
  * public knowledge and shipping it in a browser bundle discloses nothing. The
@@ -99,7 +105,7 @@ export const chainsMetadata = {
         alt: 'a pink blue and purple hexagon with an ekg line running horizontally',
         rpcUrls: {
             default: {
-                http: [valveCity(pulsechain.id), 'https://rpc.pulsechain.com'],
+                http: ['https://rpc.pulsechain.com'],
             },
         },
         contracts: {
@@ -123,13 +129,13 @@ export const chainsMetadata = {
         alt: 'two pyramids joined on one side',
         rpcUrls: {
             default: {
-                // THREE, because the middle one is the only real fallback. On
-                // 2026-08-25 g4mm4 answered nothing at all for hours, and this list
-                // was g4mm4 then valve.city — so every read fell through a dead host
-                // onto a key that rejects four requests in five. publicnode measured
-                // 40 of 40 on 2026-08-27 and costs nothing to carry.
+                // TWO PUBLIC ENDPOINTS, and {@link demoRpcUrls} puts valve.city in
+                // front of them. Both are needed behind it. On 2026-08-25 g4mm4
+                // answered nothing at all for hours, and the list was g4mm4 then
+                // valve.city — so every read fell through a dead host onto a key that
+                // rejects four requests in five. publicnode measured 40 of 40 on
+                // 2026-08-27 and costs nothing to carry.
                 http: [
-                    valveCity(mainnet.id),
                     'https://rpc-ethereum.g4mm4.io',
                     'https://ethereum-rpc.publicnode.com',
                 ],
@@ -180,20 +186,18 @@ export const chainsMetadata = {
                 // Ordered deliberately, by the operational rule that the most reliable
                 // endpoint goes FIRST.
                 //
-                // valve.city led this list on the belief that it "is ours and is not
-                // rate limited against us". The first half is true and the second is
-                // not: the SHARED DEMO KEY is what ships here, and it answered 429 for
-                // 32 of 40 burst requests against Sepolia on 2026-08-27. Being ours
-                // does not buy a budget, so it goes last with the rest.
+                // valve.city is not here. It sits in front of these three only in
+                // {@link demoRpcUrls}. Being ours does not buy it a budget: the SHARED
+                // DEMO KEY answered 429 for 32 of 40 burst requests against Sepolia on
+                // 2026-08-27, which is why nothing may depend on it alone.
                 //
-                // The other three keep the order an earlier browser measurement earned
+                // These three keep the order an earlier browser measurement earned
                 // them. publicnode stays last of the public three because it is the one
                 // observed returning 403 under a browser's load — five times on one
                 // page render — which a `curl` burst does not reproduce and therefore
                 // cannot overturn. It answers fine when the others are busy, so it is
                 // demoted rather than dropped.
                 http: [
-                    valveCity(sepolia.id),
                     'https://sepolia.gateway.tenderly.co',
                     'https://1rpc.io/sepolia',
                     'https://ethereum-sepolia-rpc.publicnode.com',
@@ -211,12 +215,11 @@ export const chainsMetadata = {
         alt: 'a pink blue and purple hexagon with an ekg line running horizontally',
         rpcUrls: {
             default: {
-                // Three for the reason Ethereum is three: g4mm4 is a single host
-                // that has gone away before, and valve.city alone behind it is not a
-                // fallback. The official testnet node measured 40 of 40 on
-                // 2026-08-27.
+                // Two, for the reason Ethereum has two: g4mm4 is a single host that
+                // has gone away before, and valve.city ({@link demoRpcUrls}) alone in
+                // front of it is not a fallback. The official testnet node measured 40
+                // of 40 on 2026-08-27.
                 http: [
-                    valveCity(pulsechainV4.id),
                     'https://rpc-testnet-pulsechain.g4mm4.io',
                     'https://rpc.v4.testnet.pulsechain.com',
                 ],
@@ -233,6 +236,38 @@ export const chainsMetadata = {
         },
     },
 };
+/**
+ * The RPC endpoints the Gibs interface uses, FOR DEMOS ONLY.
+ *
+ * Each proxied chain's list starts with valve.city's shared `vk_demo` key and
+ * falls through to that chain's public endpoints in {@link chainsMetadata}.
+ * Binance Smart Chain has no valve.city entry, so its list is the public one.
+ *
+ * WHY IT IS A SEPARATE, NAMED LIST. The key is public, so shipping it discloses
+ * nothing. But its rate budget is shared by everybody who uses it, and the proxy
+ * belongs to the Gibs Finance operator. A wallet that inherits it without
+ * choosing it puts its users' reads on somebody else's budget and uptime. So no
+ * reader in this package uses it, and `chainsMetadata` does not carry it. A
+ * caller who wants it asks for it by this name.
+ *
+ * Production callers: pass your own viem clients to every reader.
+ */
+export const demoRpcUrls = Object.freeze({
+    [Chains.PLS]: [valveCity(pulsechain.id), ...chainsMetadata[Chains.PLS].rpcUrls.default.http],
+    [Chains.ETH]: [valveCity(mainnet.id), ...chainsMetadata[Chains.ETH].rpcUrls.default.http],
+    [Chains.BNB]: [...chainsMetadata[Chains.BNB].rpcUrls.default.http],
+    [Chains.SEP]: [valveCity(sepolia.id), ...chainsMetadata[Chains.SEP].rpcUrls.default.http],
+    [Chains.V4PLS]: [valveCity(pulsechainV4.id), ...chainsMetadata[Chains.V4PLS].rpcUrls.default.http],
+});
+/**
+ * The demo endpoints for one chain, FOR DEMOS ONLY. See {@link demoRpcUrls}.
+ *
+ * @param chainId - a decimal chain id
+ * @returns a copy of the chain's demo endpoints, or an empty list for a chain the bridge does not cross
+ */
+export const demoRpcUrlsFor = (chainId) => [
+    ...(demoRpcUrls[toChain(chainId)] ?? []),
+];
 /**
  * Every chain this bridge itself carries funds across, in the order the
  * metadata declares them.

package/dist/cjs/abis.d.ts

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

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 {};