@gibs/bridge-sdk 1.13.1 → 1.17.0

package/dist/cjs/chain-names.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.knownChainName = exports.chainDisplayName = exports.registerChainNames = exports.relayChainNames = exports.isDepositAddressChain = exports.depositAddressChainIds = exports.relayChainIds = void 0;
+/**
+ * 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`.
+ */
+exports.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.
+ */
+exports.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(exports.depositAddressChainIds).map((chain) => [
+    exports.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
+ */
+const isDepositAddressChain = (chainId) => depositAddressChainNames.has(chainId);
+exports.isDepositAddressChain = isDepositAddressChain;
+/**
+ * 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.
+ */
+exports.relayChainNames = new Map([
+    [exports.relayChainIds.solana, 'Solana'],
+    [exports.relayChainIds.eclipse, 'Eclipse'],
+    [exports.relayChainIds.bitcoin, 'Bitcoin'],
+    [exports.relayChainIds.tron, 'Tron'],
+    [exports.relayChainIds.ton, 'The Open Network'],
+    [exports.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'],
+    [369, 'PulseChain'],
+    [943, 'PulseChain Testnet V4'],
+    [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
+ */
+const registerChainNames = (entries) => {
+    for (const [chainId, name] of entries) {
+        if (!name)
+            continue;
+        registeredChainNames.set(chainId, name);
+    }
+};
+exports.registerChainNames = registerChainNames;
+/**
+ * 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
+ */
+const chainDisplayName = (chainId) => (0, exports.knownChainName)(chainId) ?? `chain ${chainId}`;
+exports.chainDisplayName = chainDisplayName;
+/**
+ * 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
+ */
+const knownChainName = (chainId) => virtualMachineChainNames.get(chainId) ??
+    exports.relayChainNames.get(chainId) ??
+    depositAddressChainNames.get(chainId) ??
+    registeredChainNames.get(chainId) ??
+    null;
+exports.knownChainName = knownChainName;

package/dist/cjs/chains.d.ts

@@ -0,0 +1,90 @@
+import { Chains } from './config.js';
+import type { ChainsMetadata } from './types.js';
+/**
+ * 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 declare const chainsMetadata: 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 declare const demoRpcUrls: Readonly<Record<Chains, readonly string[]>>;
+/**
+ * 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 declare const demoRpcUrlsFor: (chainId: number) => string[];
+/**
+ * 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 declare const bridgeNetworkChainIds: readonly number[];
+/**
+ * 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 declare const testNetworkChainIds: ReadonlySet<number>;
+/**
+ * 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 declare const isTestNetwork: (chainId: number) => boolean;

package/dist/cjs/chains.js

@@ -0,0 +1,357 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTestNetwork = exports.testNetworkChainIds = exports.bridgeNetworkChainIds = exports.demoRpcUrlsFor = exports.demoRpcUrls = exports.chainsMetadata = void 0;
+// 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.
+const chain_names_js_1 = require("./chain-names.js");
+const config_js_1 = require("./config.js");
+const imageLinks = __importStar(require("./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.
+const chains_1 = require("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
+ * 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.
+ */
+exports.chainsMetadata = {
+    [config_js_1.Chains.PLS]: {
+        ...chains_1.pulsechain,
+        name: (0, chain_names_js_1.chainDisplayName)(chains_1.pulsechain.id),
+        chainId: config_js_1.Chains.PLS,
+        get logoURI() {
+            return imageLinks.network(chains_1.pulsechain.id);
+        },
+        alt: 'a pink blue and purple hexagon with an ekg line running horizontally',
+        rpcUrls: {
+            default: {
+                http: ['https://rpc.pulsechain.com'],
+            },
+        },
+        contracts: {
+            ...chains_1.pulsechain.contracts,
+            ensRegistry: {
+                address: '0xbd5133993FCDED5945c5539D9f032261F0d13170',
+            },
+            ensUniversalResolver: {
+                address: '0x2FDBb906b4FE68e31D928C1ED0b6a3bD1f204374',
+                blockCreated: 19_400_610,
+            },
+        },
+    },
+    [config_js_1.Chains.ETH]: {
+        ...chains_1.mainnet,
+        name: (0, chain_names_js_1.chainDisplayName)(chains_1.mainnet.id),
+        chainId: config_js_1.Chains.ETH,
+        get logoURI() {
+            return imageLinks.network(chains_1.mainnet.id);
+        },
+        alt: 'two pyramids joined on one side',
+        rpcUrls: {
+            default: {
+                // 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: [
+                    'https://rpc-ethereum.g4mm4.io',
+                    'https://ethereum-rpc.publicnode.com',
+                ],
+            },
+        },
+    },
+    [config_js_1.Chains.BNB]: {
+        ...chains_1.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: (0, chain_names_js_1.chainDisplayName)(chains_1.bsc.id),
+        chainId: config_js_1.Chains.BNB,
+        get logoURI() {
+            return imageLinks.network(chains_1.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'],
+            },
+        },
+    },
+    [config_js_1.Chains.SEP]: {
+        ...chains_1.sepolia,
+        name: (0, chain_names_js_1.chainDisplayName)(chains_1.sepolia.id),
+        chainId: config_js_1.Chains.SEP,
+        get logoURI() {
+            return imageLinks.network(chains_1.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 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.
+                //
+                // 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: [
+                    'https://sepolia.gateway.tenderly.co',
+                    'https://1rpc.io/sepolia',
+                    'https://ethereum-sepolia-rpc.publicnode.com',
+                ],
+            },
+        },
+    },
+    [config_js_1.Chains.V4PLS]: {
+        ...chains_1.pulsechainV4,
+        name: (0, chain_names_js_1.chainDisplayName)(chains_1.pulsechainV4.id),
+        chainId: config_js_1.Chains.V4PLS,
+        get logoURI() {
+            return imageLinks.network(chains_1.pulsechainV4.id);
+        },
+        alt: 'a pink blue and purple hexagon with an ekg line running horizontally',
+        rpcUrls: {
+            default: {
+                // 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: [
+                    'https://rpc-testnet-pulsechain.g4mm4.io',
+                    'https://rpc.v4.testnet.pulsechain.com',
+                ],
+            },
+        },
+        contracts: {
+            ...chains_1.pulsechainV4.contracts,
+            ensRegistry: {
+                address: '0xaDB38309aF7F85034FDC35bd6E6B45d1216CfB56',
+            },
+            ensUniversalResolver: {
+                address: '0xDDFde3fA938dE0cdff82645579d03Ed750DE2e69',
+            },
+        },
+    },
+};
+/**
+ * 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.
+ */
+exports.demoRpcUrls = Object.freeze({
+    [config_js_1.Chains.PLS]: [valveCity(chains_1.pulsechain.id), ...exports.chainsMetadata[config_js_1.Chains.PLS].rpcUrls.default.http],
+    [config_js_1.Chains.ETH]: [valveCity(chains_1.mainnet.id), ...exports.chainsMetadata[config_js_1.Chains.ETH].rpcUrls.default.http],
+    [config_js_1.Chains.BNB]: [...exports.chainsMetadata[config_js_1.Chains.BNB].rpcUrls.default.http],
+    [config_js_1.Chains.SEP]: [valveCity(chains_1.sepolia.id), ...exports.chainsMetadata[config_js_1.Chains.SEP].rpcUrls.default.http],
+    [config_js_1.Chains.V4PLS]: [valveCity(chains_1.pulsechainV4.id), ...exports.chainsMetadata[config_js_1.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
+ */
+const demoRpcUrlsFor = (chainId) => [
+    ...(exports.demoRpcUrls[(0, config_js_1.toChain)(chainId)] ?? []),
+];
+exports.demoRpcUrlsFor = demoRpcUrlsFor;
+/**
+ * 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.
+ */
+exports.bridgeNetworkChainIds = Object.values(exports.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.
+ */
+exports.testNetworkChainIds = new Set(Object.values(exports.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
+ */
+const isTestNetwork = (chainId) => exports.testNetworkChainIds.has(chainId);
+exports.isTestNetwork = isTestNetwork;