@anywalletkit/networks

One table of networks for every wallet build: the catalog mainnets with their public RPC failover lists, the default testnets for every chain family, the networks and RPCs the user adds, and a verifier that proves an endpoint serves the network it claims. The mobile app and the extension kit read the same table.

Install

npm install @anywalletkit/networks
# or: pnpm add @anywalletkit/networks  ·  yarn add @anywalletkit/networks

On npm: @anywalletkit/networks, published from the release workflow with provenance.

Pure TypeScript, no runtime dependencies beyond @anywalletkit/swap2-assets (for isCatalogChain). Runs under Hermes (no URL, no atob, no structuredClone).

import { NetworksTable, verifyNetwork, parseAddChainParams, checkRpcUrl } from '@anywalletkit/networks'

const table = new NetworksTable(myJsonStorage)          // AsyncStorage / chrome.storage / memoryJsonStorage()
await table.load()                                      // once at cold start; before it rpcUrlsForSync / usesUserRpcSync throw (not-loaded)

await table.addRpc('eip155:8453', 'https://my.base.rpc')
await table.rpcUrlsFor('eip155:8453')                   // ['https://my.base.rpc', 'https://base-rpc.publicnode.com', …]
await table.setOnlyOwnRpc('eip155:8453', true)          // → ['https://my.base.rpc'] (no public fallback)
table.rpcUrlsForSync('eip155:8453')                     // same, from memory — for a sync client factory
table.usesUserRpcSync('eip155:8453')                    // true → label the review sheet "Custom RPC — simulation not trusted"

const r = await verifyNetwork(await table.get('eip155:8453')!, { rpc: 'https://my.base.rpc' })
// { ok: true, latencyMs: 212, tip: 52896400, reported: '8453' }  |  { ok: false, error: 'chain-id-mismatch: Endpoint serves chain 1, not 8453.', reported: '1', … }
await table.markRpc('eip155:8453', 'https://my.base.rpc', r)   // a failure parks the URL (skipped by rpcUrlsFor) with the reason

Model

interface Network {
  caip2: string            // eip155:11155111, solana:EtWT…, bip122:<genesis>, ton:-3, tron:nile, near:testnet, zcash:testnet
  family: 'evm' | 'solana' | 'ton' | 'tron' | 'btc' | 'near' | 'zcash'
  name: string; symbol: string; decimals: number
  kind: 'catalog' | 'testnet' | 'custom'
  rpcs: string[]           // tried in order
  explorer?: string
  source: 'builtin' | 'user' | { origin: string; addedAt: number }   // a site-added network carries its origin
  onlyOwnRpc?: boolean     // drop the public fallback
  balancesViaOwnRpc?: boolean
  enabled: boolean         // testnets ship off
}

Rules the table enforces:

• a builtin entry (catalog mainnet or default testnet) cannot be removed; the user can only prepend RPCs and flip toggles — the shipped list stays as the fallback unless onlyOwnRpc;
• a custom network has no fallback by definition and needs at least one RPC; a stored custom entry for a builtin chain id is ignored (a site must not replace Ethereum's endpoints);
• rpcUrlsFor(caip2) = healthy user RPCs, then the builtin list (unless onlyOwnRpc and at least one user RPC is healthy);
• markRpc(caip2, url, result) parks a failed user RPC with its error until it passes again or is removed — an endpoint that changes chain id under us is treated as poisoning, not as an outage;
• only the deltas are persisted (NetworksState: overrides per builtin, custom networks, issues, the http opt-in), so a shipped list update reaches every install.

URL policy (owner decision 2)

checkRpcUrl(url, { allowHttpLocal }): https:// anywhere; http:// only for private addresses — localhost, *.local, *.internal, *.home.arpa, *.lan, 0/8, 10/8, 100.64/10, 127/8, 169.254/16, 172.16/12, 192.168/16, 198.18/15, IPv4 written any way a URL parser reads it (127.1, 2130706433, 0x7f.0.0.1), any host that is not printable ASCII (a URL parser maps 127.0.0.１ to 127.0.0.1), IPv6 loopback / ULA / link-local / multicast and the IPv4 inside a mapped, NAT64 or 6to4 address — and only with allowHttpLocal (the Advanced toggle, stored in the table). No credentials in the URL, and no backslash, tab, CR/LF or other control character anywhere in it (a WHATWG parser ends the host at \ and drops tab/CR/LF, so the host fetch connects to would not be the one checked). parseAddChainParams never grants the local exception to a site.

isPrivateHost(host) is that test on its own, and isPublicHttpsUrl(url) the one for URLs a wallet fetches on someone else's word (ENS gateways, avatars): https, no credentials, a public host. Both are also in @anywalletkit/networks/url, which does not load the catalog. A public name that resolves to a private address (DNS rebinding) is not caught by a host test.

verifyNetwork(network, { rpc?, fetch?, allowHttpLocal?, timeoutMs? })

Returns { ok, latencyMs, tip?, error?, reported? } and never throws. Errors are prefixed with a code: chain-id-mismatch, url-policy, redirected, http-<status>, rpc-error, bad-json, timeout, unreachable, no-rpc, bad-network. Redirects are refused (redirect: 'error', and an answer whose url / redirected / 3xx status shows a redirect is redirected: Endpoint redirected to <host>; enter the final URL): the URL policy judged the address the user or site gave, not where it points. A custom fetch that cannot refuse redirects should report url or redirected, or the redirected request goes out before the check sees it. http-<status> and bad-json carry no body text. Answer a site (wallet_addEthereumChain) with a generic error, not with error. verifyRpcs(network) checks every endpoint. scripts/verify-live.mjs runs the real thing against every builtin endpoint.

Builtin table

CATALOG_NETWORKS — the 30 EVM mainnets of the asset catalog (Ethereum, Base, BNB, Arbitrum, Optimism, Polygon, Avalanche, HyperEVM, Robinhood, zkSync, Celo, MegaETH, Unichain, Monad, Plasma, Linea, Gnosis, Sonic, World Chain, Sei, Ink, Plume, X Layer, Scroll, Berachain, Arc, Mantle, Katana, Morph, Flare) with the public failover lists, plus Solana, TON, Tron, Bitcoin, NEAR and Zcash with public endpoints (the mobile app prepends its keyed proxies through the table).

DEFAULT_TESTNETS (shipped enabled: false; endpoints and identities called on 2026-10-21):

EIP-3085

parseAddChainParams(params, { known?, origin? }) turns a wallet_addEthereumChain request into a Network (kind: 'custom', source: { origin, addedAt }) or the EIP-1193 error to answer with (-32602 bad params, 4902 chain not in the catalog). https RPCs only; nativeCurrency.decimals must be 18. Pass known to accept chains outside the asset catalog.