@gibs/bridge-sdk 1.10.1 → 1.13.0

package/dist/chain-names.d.ts

@@ -0,0 +1,160 @@
+/**
+ * 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`.
+ */
+export declare const relayChainIds: {
+    /** Relay's chain id for Solana mainnet (virtual-machine type `svm`). */
+    readonly 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.
+     */
+    readonly eclipse: 9286185;
+    /** Relay's chain id for Bitcoin mainnet (virtual-machine type `bvm`). */
+    readonly bitcoin: 8253038;
+    /** Relay's chain id for Tron mainnet (virtual-machine type `tvm`). */
+    readonly tron: 728126428;
+    /** Relay's chain id for The Open Network (virtual-machine type `tonvm`). */
+    readonly 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`.
+     */
+    readonly 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.
+ */
+export declare const depositAddressChainIds: {
+    /** Zcash mainnet. SLIP-0044 coin type 133, hardened: 0x80000000 + 133. */
+    readonly zcash: 2147483781;
+};
+/**
+ * One member per pay-by-hand origin chain — the union every table keyed by a
+ * pay-by-hand chain must be typed against.
+ *
+ * WHY THIS UNION, NOT `number`. `DepositAddressDeposit`'s own doc says the same
+ * shape will serve Zcash, Dogecoin, Litecoin and the XRP Ledger alike, so a
+ * second member is coming. A table typed `Record<number, X>` or
+ * `Map<number, X>` accepts a member of {@link depositAddressChainIds} being
+ * missing silently; a table typed `Record<DepositAddressChain, X>` cannot
+ * compile until every member has an entry. The dangerous table this protects
+ * is the ecosystem lookup in `relay-quote.ts`: a miss there makes a pay-by-hand
+ * chain read as an Ethereum chain, which has a wallet, a signer and a
+ * transaction.
+ */
+export type DepositAddressChain = keyof typeof depositAddressChainIds;
+/**
+ * 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
+ */
+export declare const isDepositAddressChain: (chainId: number) => boolean;
+/**
+ * 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.
+ */
+export declare const relayChainNames: Map<number, string>;
+/**
+ * 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
+ */
+export declare const registerChainNames: (entries: Iterable<readonly [number, string]>) => void;
+/**
+ * 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
+ */
+export declare const chainDisplayName: (chainId: number) => string;
+/**
+ * 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
+ */
+export declare const knownChainName: (chainId: number) => string | null;

package/dist/chain-names.js

@@ -0,0 +1,200 @@
+/**
+ * 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`.
+ */
+export const 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.
+ */
+export const 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(depositAddressChainIds).map((chain) => [
+    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
+ */
+export const isDepositAddressChain = (chainId) => depositAddressChainNames.has(chainId);
+/**
+ * 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.
+ */
+export const relayChainNames = new Map([
+    [relayChainIds.solana, 'Solana'],
+    [relayChainIds.eclipse, 'Eclipse'],
+    [relayChainIds.bitcoin, 'Bitcoin'],
+    [relayChainIds.tron, 'Tron'],
+    [relayChainIds.ton, 'The Open Network'],
+    [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
+ */
+export const registerChainNames = (entries) => {
+    for (const [chainId, name] of entries) {
+        if (!name)
+            continue;
+        registeredChainNames.set(chainId, name);
+    }
+};
+/**
+ * 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
+ */
+export const chainDisplayName = (chainId) => knownChainName(chainId) ?? `chain ${chainId}`;
+/**
+ * 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
+ */
+export const knownChainName = (chainId) => virtualMachineChainNames.get(chainId) ??
+    relayChainNames.get(chainId) ??
+    depositAddressChainNames.get(chainId) ??
+    registeredChainNames.get(chainId) ??
+    null;

package/dist/chains.d.ts

@@ -0,0 +1,65 @@
+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;
+/**
+ * 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;