@gibs/bridge-sdk 1.10.1 → 1.13.0

package/dist/chains.js

@@ -0,0 +1,284 @@
+// Relative, not through this package's own name. A self-reference resolves
+// through the `exports` map, which now points at the compiled `dist` — so the
+// 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 * 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
+// to be imported from — but that made a package with no user interface depend on a
+// wallet modal, and it was never declared in `dependencies`, so the root entry
+// point of this package could not be loaded by anyone outside this repository.
+import { bsc, mainnet, pulsechain, pulsechainV4, sepolia } from 'viem/chains';
+/**
+ * Builds an endpoint on valve.city, which proxies four of this dapp's chains.
+ *
+ * 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
+ * proxy reflects any `Origin` back, which is what makes it usable at all from
+ * an IPFS build: the same bundle is served from gib.show, from ipfs.io, from
+ * dweb.link, and from a local node, so an origin-locked key would break every
+ * gateway but one.
+ *
+ * NEVER replace this with the unlimited key from 1Password. That one is a
+ * bearer credential, this file compiles into the public bundle, and the two
+ * facts together would hand an unmetered proxy to every visitor.
+ *
+ * Only chains 1, 369, 943 and 11155111 are proxied; the service lists them at
+ * its root. Binance Smart Chain is not, which is why it keeps a public endpoint
+ * alone. Every chain below keeps its previous endpoints after this one, so a
+ * valve.city outage falls through to where it used to go rather than breaking.
+ *
+ * IT LEADS EVERY LIST IT APPEARS IN, and the measurement that says it may is
+ * not a burst — it is the shape this interface actually produces.
+ *
+ * MEASURED 2026-08-29, against the real cadence rather than a synthetic flood:
+ *
+ *   steady, 1 request per 4 seconds for 3 minutes   45 of 45 answered 200
+ *   bursts, 8 concurrent, four rounds                30 of 32 answered 200
+ *   20 requests at concurrency 1, 2, 4, 6 and 8      20 of 20 every time
+ *   20 requests at concurrency 12                    19 of 20
+ *
+ * Four seconds is not arbitrary: `watchBlocks` runs on viem's default poll, one
+ * per watched chain, and `clientFromChain` coalesces up to 32 JSON-RPC calls
+ * made within 10ms into ONE HTTP POST. So the interface's request rate is about
+ * a quarter of a request per second per chain, and the key handles four times
+ * that without a single refusal.
+ *
+ * AN EARLIER READING SAID THE OPPOSITE AND WAS MEASURING SOMETHING ELSE. On
+ * 2026-08-27 this key answered 429 for four requests in five — from 40 requests
+ * at 12 concurrent, fired four times back to back across four chains, roughly
+ * 160 requests with no pause. That exhausts a windowed budget. No browser does
+ * it. The reading before THAT one was 40 CONSECUTIVE requests, which cannot see
+ * a rate limit at all because it paces itself. Both were honest measurements of
+ * the wrong thing.
+ *
+ * THE PROBE STORM WAS THE REAL CULPRIT. `fallback` used to run `rank: true`,
+ * which pings every url on every chain every few seconds forever — on an idle
+ * page, every outbound request was one of those. That is what spent the key's
+ * budget. It is off now (see `packages/common/src/client.ts`), and the
+ * demotion that shipped alongside turning it off was treating the symptom.
+ *
+ * THE SPARE BEHIND IT IS STILL LOAD-BEARING. `vk_demo` is shared — published on
+ * chainlist.org — so the budget is not ours alone and the headroom moves with
+ * other people's use. About one burst request in sixteen still meets a 429, and
+ * a 429 is an HTTP error, so `fallback` moves to the next entry at once. The
+ * cost is one wasted round trip on a small fraction of burst requests, not a
+ * failed read. Never leave a proxied chain with valve.city alone.
+ *
+ * @param chainId - the numeric chain id to proxy
+ * @returns the fully qualified JSON-RPC endpoint
+ */
+const valveCity = (chainId) => `https://one.valve.city/rpc/vk_demo/evm/${chainId}`;
+/**
+ * all of the chains that are enabled in this dapp
+ * and their corresponding useful metadata
+ *
+ * Every entry below sets `name` explicitly to `chainDisplayName(...)` rather
+ * than trusting the spread-in viem chain object or typing a string here. Two
+ * hand-typed copies of the same name is exactly how chain 943 once read as
+ * "PulseChain Testnet V4" in the resolver and "Pulsechain V4" here — one
+ * string, two spellings, and only one of them got fixed. Routing every name
+ * through `chainDisplayName` leaves nothing to drift a second time.
+ *
+ * Each `logoURI` is a getter, not a string fixed at import time, so a later
+ * `setImageRoot` call (from `image-links.ts`) changes every chain logo. Spread
+ * an entry (`{ ...chainsMetadata[chain] }`) and the copy holds the URL as it
+ * was at that moment.
+ */
+export const chainsMetadata = {
+    [Chains.PLS]: {
+        ...pulsechain,
+        name: chainDisplayName(pulsechain.id),
+        chainId: Chains.PLS,
+        get logoURI() {
+            return imageLinks.network(pulsechain.id);
+        },
+        alt: 'a pink blue and purple hexagon with an ekg line running horizontally',
+        rpcUrls: {
+            default: {
+                http: [valveCity(pulsechain.id), 'https://rpc.pulsechain.com'],
+            },
+        },
+        contracts: {
+            ...pulsechain.contracts,
+            ensRegistry: {
+                address: '0xbd5133993FCDED5945c5539D9f032261F0d13170',
+            },
+            ensUniversalResolver: {
+                address: '0x2FDBb906b4FE68e31D928C1ED0b6a3bD1f204374',
+                blockCreated: 19_400_610,
+            },
+        },
+    },
+    [Chains.ETH]: {
+        ...mainnet,
+        name: chainDisplayName(mainnet.id),
+        chainId: Chains.ETH,
+        get logoURI() {
+            return imageLinks.network(mainnet.id);
+        },
+        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.
+                http: [
+                    valveCity(mainnet.id),
+                    'https://rpc-ethereum.g4mm4.io',
+                    'https://ethereum-rpc.publicnode.com',
+                ],
+            },
+        },
+    },
+    [Chains.BNB]: {
+        ...bsc,
+        // viem's own default is "BNB Smart Chain" — deferring to the resolver
+        // keeps this the product's chosen "Binance Smart Chain" without a second
+        // hand-typed copy of that decision living here.
+        name: chainDisplayName(bsc.id),
+        chainId: Chains.BNB,
+        get logoURI() {
+            return imageLinks.network(bsc.id);
+        },
+        alt: 'a gold cube with slits in the middle of each side',
+        rpcUrls: {
+            default: {
+                // valve.city does not proxy chain 56 — it answers "Unsupported
+                // chain" — so this is the one chain with no entry of ours, which
+                // makes a second PUBLIC endpoint the only fallback available. A
+                // one-entry list is what took Sepolia down outright (see below).
+                // Both measured 40 of 40 on 2026-08-27.
+                http: ['https://bsc-rpc.publicnode.com', 'https://bsc-dataseed.binance.org'],
+            },
+        },
+    },
+    [Chains.SEP]: {
+        ...sepolia,
+        name: chainDisplayName(sepolia.id),
+        chainId: Chains.SEP,
+        get logoURI() {
+            return imageLinks.network(sepolia.id);
+        },
+        alt: 'two pyramids joined on one side',
+        // FOUR endpoints, not one, and the reason is specific: a public endpoint
+        // answers a single curl perfectly well and returns 403 under a browser's
+        // load — five times on one page render. A rate limit, not a dead host.
+        //
+        // The transport wraps this list in viem's `fallback()`, which moves on for
+        // an HTTP error, and 403 is one. With a single entry there was nowhere to
+        // move to, so the whole testnet side simply failed. All three were checked
+        // for a correct chain id AND for an allow-origin header, because answering
+        // curl is not the same as being reachable from a page.
+        rpcUrls: {
+            default: {
+                // 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.
+                //
+                // The other 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',
+                ],
+            },
+        },
+    },
+    [Chains.V4PLS]: {
+        ...pulsechainV4,
+        name: chainDisplayName(pulsechainV4.id),
+        chainId: Chains.V4PLS,
+        get logoURI() {
+            return imageLinks.network(pulsechainV4.id);
+        },
+        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.
+                http: [
+                    valveCity(pulsechainV4.id),
+                    'https://rpc-testnet-pulsechain.g4mm4.io',
+                    'https://rpc.v4.testnet.pulsechain.com',
+                ],
+            },
+        },
+        contracts: {
+            ...pulsechainV4.contracts,
+            ensRegistry: {
+                address: '0xaDB38309aF7F85034FDC35bd6E6B45d1216CfB56',
+            },
+            ensUniversalResolver: {
+                address: '0xDDFde3fA938dE0cdff82645579d03Ed750DE2e69',
+            },
+        },
+    },
+};
+/**
+ * Every chain this bridge itself carries funds across, in the order the
+ * metadata declares them.
+ *
+ * Read from {@link chainsMetadata} rather than typed out, for the reason the
+ * whole table above gives: a second hand-written list is how one chain ends up
+ * present in one place and missing from another. A control that offers the
+ * reader a network to add or remove reads this, so a chain added to the
+ * metadata appears in that control without anybody remembering to add it.
+ *
+ * This is NOT every chain a route can traverse. An aggregator reaches dozens
+ * more, and `chain-names.ts` can name them. These five are the ones the
+ * transfers archive holds records for.
+ */
+export const bridgeNetworkChainIds = Object.values(chainsMetadata).map((metadata) => Number(metadata.id));
+/**
+ * The chain identifiers this product treats as TEST networks.
+ *
+ * THE FLAG IS VIEM'S AND IT IS CHECKED FOR `true`, NOT FOR TRUTHINESS. Each
+ * entry above spreads a viem chain definition, and viem sets `testnet: true` on
+ * Sepolia and on PulseChain Testnet V4, `testnet: false` on PulseChain, and
+ * omits the key entirely on Ethereum and on Binance Smart Chain. So the value
+ * has three states, and only one of them is a claim. Testing for `=== true`
+ * means a chain whose definition says nothing is treated as a real network —
+ * which is the safe direction, because the cost of failing to hide a test
+ * network is an extra row and the cost of hiding a real one is a reader who
+ * cannot find their money.
+ *
+ * WHY NOT DERIVE IT FROM THE BRIDGE KEYS. `validBridgeKeys(isProd)` in
+ * `config.ts` splits the same five chains into a mainnet set and a testnet set,
+ * and subtracting one from the other would give the same two identifiers today.
+ * It would also give the wrong answer the moment a real chain gains a pathway
+ * that is still behind the testnet switch — the key list records what is
+ * ENABLED, and this records what a chain IS. Two different questions.
+ *
+ * `buildFullChainIdSet` in the interface already gates the pickers on the same
+ * flag, and `tokenLists.ts` gates the synthesized native assets on it. This is
+ * that decision written down once so a third reader does not restate it.
+ */
+export const testNetworkChainIds = new Set(Object.values(chainsMetadata)
+    .filter((metadata) => metadata.testnet === true)
+    .map((metadata) => Number(metadata.id)));
+/**
+ * Whether one chain is a test network.
+ *
+ * @param chainId - a decimal chain id
+ * @returns true only when the chain's own definition claims it is a test network
+ */
+export const isTestNetwork = (chainId) => testNetworkChainIds.has(chainId);

package/dist/config.d.ts

@@ -0,0 +1,216 @@
+import { type Hex } from 'viem';
+import type { BridgeKey, Token, TokenOut } from './types.js';
+/**
+ * Add here your chain id as hex, be sure to add your chain in the chainsMetadata object too
+ */
+export declare enum Chains {
+    PLS = "0x171",
+    ETH = "0x1",
+    BNB = "0x38",
+    SEP = "0xaa36a7",
+    V4PLS = "0x3af"
+}
+/** The key of a chain - human readable for query params */
+export type ChainKey = keyof typeof Chains;
+/** A map of chain ids to chain keys */
+export declare const chainIdToKey: Map<Chains, "PLS" | "ETH" | "BNB" | "SEP" | "V4PLS">;
+/**
+ * Converts a chain id to a chain key
+ * @param chainId - the chain id
+ * @returns the chain key
+ */
+export declare const toChain: (chainId: number | string) => Chains;
+/**
+ * Converts a chain id to a chain key
+ * @param chainId - the chain id
+ * @returns the chain key
+ */
+export declare const toChainKey: (chainId: number | string) => "PLS" | "ETH" | "BNB" | "SEP" | "V4PLS" | undefined;
+export declare const Providers: {
+    readonly PULSECHAIN: "pulsechain";
+    readonly TOKENSEX: "tokensex";
+};
+export type Provider = (typeof Providers)[keyof typeof Providers];
+/** A map of chains to native asset out addresses */
+export declare const nativeAssetOut: Record<Chains, Hex>;
+/** A map of chains to deprecated native asset out addresses */
+export declare const deprecatedNativeAssetOut: Partial<Record<Chains, Set<Hex>>>;
+/** A map of chains to uni v2 router addresses */
+export declare const uniV2Routers: Record<Chains, Hex[]>;
+/**
+ * Each {@link uniV2Routers} entry's OWN factory address, same index, same
+ * chain — `router.factory()` read live from `one.valve.city` on 2026-09-24.
+ * Only PulseChain mainnet is filled: PulseX carries funds nowhere else
+ * (`routing/carriers/pulsex.ts`'s own `pulseXCarries`), so no other chain's
+ * factory has ever been needed or verified.
+ *
+ * MEASURED, NOT ASSUMED (owner Rule 13). Reading each factory's `getPair`
+ * and the resulting pool's `getReserves`, then recomputing `getAmountsOut`
+ * from the standard constant-product formula, showed the SAME fee ratio for
+ * both — `9971/10000` (0.29%) — to the base unit, on both a one-hop and a
+ * two-hop path. "V1 and V2 differ" was the assumption going in; measurement
+ * said otherwise, so `routing/carriers/pulsex.ts`'s `exact` uses one shared
+ * fee constant rather than two.
+ *
+ * `0x1715a3E4A142d8b698131108995174F37aEBA10D` (the V1 factory, index 0) is
+ * NOT a copy-paste of the omnibridge's Ethereum mediator address from
+ * `pathways` above — it is the same string on a DIFFERENT chain (PulseChain,
+ * not Ethereum), confirmed by reading it fresh from `one.valve.city/…/evm/369`.
+ * Two unrelated contracts landing on the same address on two different
+ * chains is possible (a shared deployer at a matching nonce, or a CREATE2
+ * salt collision) and worth this note so a future reader does not assume a
+ * transcription error and "fix" it back to something wrong.
+ */
+export declare const uniV2Factories: Record<Chains, Hex[]>;
+/** A map of chains to native token symbols */
+export declare const nativeTokenSymbol: Record<Chains, string>;
+/** A map of chains to native token names */
+export declare const nativeTokenName: Record<Chains, string>;
+/** The pathway of a bridge */
+export type Pathway = {
+    from: Hex;
+    to: Hex;
+    destinationRouter: Hex | null;
+    nativeRouter: Hex;
+    validator: Hex;
+    usesExtraParam: boolean;
+    feeManager: 'from' | 'to';
+    toHome: boolean;
+    requiresDelivery: boolean;
+    bridgedNativeAssetOut: Hex;
+    settingOverrides?: Record<Hex, Partial<Pathway>>;
+};
+/** A map of providers to pathways */
+export type DeepPathwayConfig = Record<Provider, Partial<Record<Chains, Partial<Record<Chains, Pathway>>>>>;
+export declare const pathways: DeepPathwayConfig;
+export declare const testnetPathways: DeepPathwayConfig;
+/** Returns the valid bridge keys for the given is prod */
+export declare const validBridgeKeys: (isProd: boolean) => BridgeKey[];
+/**
+ * Whether a chain belongs to the testnet pathway map rather than the mainnet one.
+ * @param chain - the chain to classify
+ * @returns true for Sepolia and PulseChain testnet V4
+ */
+export declare const isTestnetChain: (chain: Chains) => boolean;
+/**
+ * Infers the bridge key from the current key, provider, from chain, and to chain.
+ *
+ * A chain the provider does not serve falls back to the provider's first chain,
+ * so a provider switch lands on a real pathway. That fallback never crosses
+ * between the testnet and mainnet maps: when testnets are off and a requested
+ * chain is a testnet chain, this returns null rather than a mainnet key for a
+ * testnet pair.
+ *
+ * @param options.currentKey - the current bridge key
+ * @param options.provider - the provider
+ * @param options.fromChain - the from chain (defaults to the current key's)
+ * @param options.toChain - the to chain (defaults to the current key's)
+ * @param options.isProd - true leaves testnet pathways out (default false: both maps)
+ * @returns the inferred bridge key, or null when no pathway can honour the request
+ */
+export declare const inferBridgeKey: ({ currentKey, provider, fromChain, toChain, isProd, }: {
+    currentKey: BridgeKey;
+    provider: Provider;
+    fromChain?: Chains;
+    toChain?: Chains;
+    isProd?: boolean;
+}) => BridgeKey | null;
+/**
+ * Returns the pathway for the given bridge key, is prod, and asset in address
+ * @param bridgeKey - the bridge key
+ * @param isProd - whether to use the production pathway
+ * @param assetInAddress - the asset in address
+ * @returns the pathway
+ */
+/**
+ * The pathway group for one provider on one chain, honouring the testnet map.
+ *
+ * Exists because {@link pathway} already knew that testnet pathways live in a
+ * SECOND map and are only in play off production, while other callers reached
+ * straight into `pathways` and therefore could not see a testnet route at all.
+ * That is the sort of knowledge that has to live in one place: duplicated, one
+ * copy silently lags the other, and the symptom is a thrown "no pathway found"
+ * on a route the rest of the application considers perfectly valid.
+ *
+ * @param provider - the bridge provider
+ * @param chain - the chain being bridged FROM
+ * @param isProd - whether this is a production build; testnets are off when true
+ * @returns the group keyed by destination chain, or undefined when unknown
+ */
+export declare const pathwayGroup: (provider: Provider, chain: Chains, isProd: boolean) => Partial<Record<Chains, Pathway>> | undefined;
+export declare const pathway: (bridgeKey: BridgeKey | null, isProd: boolean, assetInAddress?: string | Hex | null | undefined) => Pathway | undefined;
+/**
+ * Returns the default asset in for the given bridge key and is prod
+ * @param bridgeKey - the bridge key
+ * @param isProd - whether to use the production pathway
+ * @returns the default asset in
+ */
+export declare const defaultAssetIn: ($bridgeKey: BridgeKey | null, isProd: boolean) => `0x${string}` | null | undefined;
+/** Which pathway maps a lookup reads. */
+export type PathwayLookupOptions = {
+    /**
+     * true reads the mainnet map alone; false (the default) also reads the
+     * testnet map, which is what every caller did before this option existed.
+     */
+    isProd?: boolean;
+};
+/**
+ * Returns whether the given asset is the native asset for the given bridge key.
+ *
+ * Never throws. A token whose address is not known yet (a {@link TokenOut} for a
+ * not-yet-bridged token), an address that is not a valid address, and a bridge
+ * key with no pathway each answer false.
+ *
+ * @param asset - the asset
+ * @param bridgeKey - the bridge key
+ * @param options - which pathway maps to read; see {@link PathwayLookupOptions}
+ * @returns whether the given asset is the native asset for the given bridge key
+ */
+export declare const isNative: (asset: Token | TokenOut | null, bridgeKey: BridgeKey | null, options?: PathwayLookupOptions) => boolean;
+/**
+ * Returns whether the given asset is unwrappable for the given bridge key.
+ *
+ * Never throws: a missing or malformed address and a bridge key with no
+ * pathway each answer false.
+ *
+ * @param bridgeKey - the bridge key
+ * @param assetIn - the asset in
+ * @param options - which pathway maps to read; see {@link PathwayLookupOptions}
+ * @returns whether the given asset is unwrappable for the given bridge key
+ */
+export declare const isUnwrappable: (bridgeKey: BridgeKey | null, assetIn: {
+    address: string | null;
+} | null, options?: PathwayLookupOptions) => boolean;
+/**
+ * Returns whether the given asset can be unwrapped for the given bridge key
+ * @param bridgeKey - the bridge key
+ * @param assetIn - the asset in
+ * @param options - which pathway maps to read; see {@link PathwayLookupOptions}
+ * @returns boolean
+ */
+export declare const canChangeUnwrap: (bridgeKey: BridgeKey, assetIn: Token | null, options?: PathwayLookupOptions) => boolean;
+export declare const chains: {
+    readonly ethereum: 1;
+    readonly bsc: 56;
+    readonly pulsechain: 369;
+    readonly pulsechainV4: 943;
+    readonly sepolia: 11155111;
+};
+export declare const chainIds: (1 | 56 | 369 | 943 | 11155111)[];
+/** Start blocks aligned with when bridge validators began operating — canonical reference for all ponder indexers in this monorepo. */
+export declare const startBlocks: Record<keyof typeof chains, number>;
+export type ChainId = (typeof chainIds)[number];
+export type Side = 'home' | 'foreign';
+export type MinimalKey = `${ChainId}-${Hex}`;
+export type PathwayInfo = {
+    pair: string;
+    key: string;
+    home: Hex;
+    foreign: Hex;
+};
+export type ProviderHomeChainEntry = Partial<Record<ChainId, PathwayInfo[]>>;
+export type ProviderEntries = Partial<Record<ChainId, ProviderHomeChainEntry>>;
+export type BridgeConfig = Record<Provider, ProviderEntries>;
+export declare const bridgeConfigs: BridgeConfig;
+export declare const HOME_TO_FOREIGN_FEE: `0x${string}`;
+export declare const FOREIGN_TO_HOME_FEE: `0x${string}`;