@zig-zag/chains

A typed chain registry for Polkadot SDK chains. Provides rich, tree-shakeable metadata for relay chains, system parachains, third-party parachains, and testnets -- including named RPC providers, genesis hashes, Subscan integration, light client URLs, and network topology.

Works with Dedot, PAPI, LunoKit, or standalone.

Installation

npm i @zig-zag/chains

pnpm add @zig-zag/chains

yarn add @zig-zag/chains

Zero runtime dependencies. If your bundler supports tree-shaking, only the chains you import will be included in your bundle.

Quick Start

import { polkadot, kusama, polkadotAssetHub } from "@zig-zag/chains";

// Connect to a named RPC provider
const ws = new WebSocket(polkadot.rpcUrls.dwellir);

// Use the genesis hash as a chain identifier
console.log(polkadot.genesisHash);
// '0x91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3'

// Access native currency info
console.log(polkadot.nativeCurrency);
// { name: 'Polkadot', symbol: 'DOT', decimals: 10 }

// Check the network topology
console.log(polkadotAssetHub.paraId);      // 1000
console.log(polkadotAssetHub.relayChain);  // 'polkadot'

// Chain logos (base64 SVG data URIs)
console.log(polkadot.chainIconUrl);        // 'data:image/svg+xml;base64,...'

Supported Chains

Relay Chains

Export	Chain	Symbol	SS58
`polkadot`	Polkadot	DOT	0
`kusama`	Kusama	KSM	2

System Parachains -- Polkadot

Export	Chain	Para ID
`polkadotAssetHub`	Polkadot Asset Hub	1000
`polkadotCollectives`	Polkadot Collectives	1001
`polkadotBridgeHub`	Polkadot Bridge Hub	1002
`polkadotPeople`	Polkadot People	1004
`polkadotCoretime`	Polkadot Coretime	1005

System Parachains -- Kusama

Export	Chain	Para ID
`kusamaAssetHub`	Kusama Asset Hub	1000
`kusamaBridgeHub`	Kusama Bridge Hub	1002
`kusamaPeople`	Kusama People	1004
`kusamaCoretime`	Kusama Coretime	1005

Third-Party Parachains

Export	Chain	Symbol	Para ID	EVM
`acala`	Acala	ACA	2000
`moonbeam`	Moonbeam	GLMR	2004	Yes
`astar`	Astar	ASTR	2006
`hydration`	Hydration	HDX	2034
`phala`	Phala	PHA	2035

Testnets

Export	Chain	Symbol	Type
`westend`	Westend	WND	Relay
`paseo`	Paseo	PAS	Relay
`westendAssetHub`	Westend Asset Hub	WND	System
`paseoAssetHub`	Paseo Asset Hub	PAS	System

Chain Data Model

Every chain object satisfies the Chain interface:

import type { Chain } from "@zig-zag/chains";

Required Fields

Field	Type	Description
`id`	`number`	Unique numeric identifier
`name`	`string`	Human-readable chain name
`network`	`string`	URL-safe slug (`"polkadot"`, `"kusama-asset-hub"`)
`genesisHash`	`0x${string}`	Genesis block hash -- the primary on-chain identifier
`ss58Format`	`number`	SS58 address encoding prefix
`nativeCurrency`	`Currency`	Token name, symbol (2-6 chars), and decimals
`rpcUrls`	`Record<string, string>`	Named WebSocket RPC providers with a required `default` key

Optional Fields

Field	Type	Description
`paraId`	`number`	Parachain ID on the relay chain
`relay`	`boolean`	Whether this is a relay chain
`testnet`	`boolean`	Whether this is a test network
`ethereum`	`boolean`	Whether this chain is EVM-compatible
`relayChain`	`string`	Parent relay chain slug (for parachains)
`signType`	`"sr25519" \| "ed25519" \| "secp256k1"`	Default signing curve
`httpUrls`	`Record<string, string>`	Named HTTP RPC endpoints
`lightClientUrls`	`Record<string, string>`	Substrate Connect light client URLs
`website`	`string`	Project website URL
`chainIconUrl`	`string`	Chain logo URL or data URI
`blockExplorers`	`Record<string, BlockExplorer>`	Named block explorers with a `default` key
`subscan`	`SubscanConfig`	Subscan web URL and API URL

Named RPC Providers

Unlike libraries that use flat arrays for RPC URLs, @zig-zag/chains uses named keys so you can target a specific provider:

import { polkadot } from "@zig-zag/chains";

polkadot.rpcUrls.default;      // 'wss://rpc.polkadot.io'
polkadot.rpcUrls.dwellir;      // 'wss://polkadot-rpc.n.dwellir.com'
polkadot.rpcUrls.ibp1;         // 'wss://polkadot.ibp.network'
polkadot.rpcUrls.onfinality;   // 'wss://polkadot.api.onfinality.io/public-ws'
polkadot.rpcUrls.radiumblock;  // 'wss://polkadot.public.curie.radiumblock.co/ws'

Relay chains have 9+ named providers. System parachains and third-party chains have 3-7 each.

Utilities

Chain Groups

Pre-built arrays for common filtering needs:

import {
  allChains,       // All 20 chains
  relayChains,     // Polkadot, Kusama, Westend, Paseo
  systemChains,    // Asset Hub, People, Coretime, Collectives, Bridge Hub
  parachainChains, // Astar, Acala, Moonbeam, Phala, Hydration
  testnetChains,   // Westend, Paseo, Westend Asset Hub, Paseo Asset Hub
  mainnetChains,   // Everything except testnets
} from "@zig-zag/chains";

Lookup Helpers

Find chains by ID, network slug, or genesis hash:

import { getChainById, getChainByNetwork, getChainByGenesisHash } from "@zig-zag/chains";

const dot = getChainById(0);                // polkadot
const ksm = getChainByNetwork("kusama");    // kusama
const chain = getChainByGenesisHash("0x91b171bb...");  // polkadot

All lookups return Chain | undefined.

Define Custom Chains

Use defineChain to create chain objects that satisfy the Chain interface with full type inference:

import { defineChain } from "@zig-zag/chains";

const myChain = defineChain({
  id: 99999,
  name: "My Chain",
  network: "my-chain",
  genesisHash: "0xabcdef...",
  ss58Format: 42,
  nativeCurrency: { name: "My Token", symbol: "MYT", decimals: 12 },
  rpcUrls: { default: "wss://rpc.my-chain.io" },
});

Usage Examples

With Dedot

import { DedotClient, WsProvider } from "dedot";
import { polkadot } from "@zig-zag/chains";

const client = await DedotClient.new(
  new WsProvider(polkadot.rpcUrls.default)
);

With PAPI (polkadot-api)

import { createClient } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws-provider/web";
import { kusama } from "@zig-zag/chains";

const client = createClient(
  getWsProvider(kusama.rpcUrls.default)
);

Encoding Addresses

import { encodeAddress } from "@polkadot/keyring";
import { astar } from "@zig-zag/chains";

const astarAddress = encodeAddress(
  "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
  astar.ss58Format
);

Subscan API

import { polkadot } from "@zig-zag/chains";

const response = await fetch(`${polkadot.subscan?.api}/api/scan/blocks`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ row: 10, page: 0 }),
});

Light Client

import { polkadot } from "@zig-zag/chains";

if (polkadot.lightClientUrls) {
  console.log(polkadot.lightClientUrls.default);
  // 'light://substrate-connect/polkadot'
}

TypeScript Support

Every chain is defined with as const satisfies Chain, giving you full literal type inference:

import { polkadot } from "@zig-zag/chains";

// TypeScript knows the exact literal types
polkadot.network;                // type: "polkadot" (not string)
polkadot.ss58Format;             // type: 0 (not number)
polkadot.nativeCurrency.symbol;  // type: "DOT" (not string)

All types are exported:

import type { Chain, Currency, BlockExplorer, SubscanConfig, HexString } from "@zig-zag/chains";

Project Structure

src/
  index.ts                  # Barrel exports for all chains and types
  types/
    chain.ts                # Chain, Currency, BlockExplorer, SubscanConfig, HexString
  chains/
    relay/                  # Relay chains (Polkadot, Kusama)
    system/                 # System parachains (Asset Hub, People, Coretime, ...)
    parachains/             # Third-party parachains (Astar, Acala, Moonbeam, ...)
    testnet/                # Test networks (Westend, Paseo, ...)
  __tests__/
    chains.test.ts          # Schema validation and uniqueness tests (247 tests)

Each chain is a single file exporting one const object. Adding a new chain means creating one file and adding one export line to index.ts.

Development

Prerequisites

Node.js 18+

Setup

git clone https://github.com/zigzag-js/chains.git
cd chains
npm install

Scripts

Command	Description
`npm run build`	Build CJS + ESM + type declarations with tsup
`npm test`	Run validation tests (247 tests)
`npm run test:watch`	Run tests in watch mode
`npm run type-check`	Type-check without emitting
`npm run clean`	Remove `dist/`

Contributing

Adding a chain takes about 5 minutes:

Create a new file in the appropriate directory under src/chains/
Export a const using as const satisfies Chain
Add the export to src/index.ts
Run npm test to validate
Open a pull request

Minimum required data

Field	Where to find it
`genesisHash`	`chain_getBlockHash(0)` RPC call
`ss58Format`	`system_properties` RPC call or ss58-registry
`nativeCurrency`	`system_properties` RPC call
`rpcUrls`	polkadot-js/apps endpoints or chain docs

At least 2 RPC providers (including a default) are required to pass validation.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.github/workflows		.github/workflows
scripts		scripts
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

@zig-zag/chains

Table of Contents

Installation

Quick Start

Supported Chains

Relay Chains

System Parachains -- Polkadot

System Parachains -- Kusama

Third-Party Parachains

Testnets

Chain Data Model

Required Fields

Optional Fields

Named RPC Providers

Utilities

Chain Groups

Lookup Helpers

Define Custom Chains

Usage Examples

With Dedot

With PAPI (polkadot-api)

Encoding Addresses

Subscan API

Light Client

TypeScript Support

Project Structure

Development

Prerequisites

Setup

Scripts

Contributing

Minimum required data

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 10

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages