The base/chains repository serves as a comprehensive metadata registry for EVM-based blockchain networks, providing standardized chain identification and configuration data. Written in Kotlin, the repository maintains a centralized source of truth for network IDs and chain IDs that is consumed by wallets, explorers, and other blockchain infrastructure tools across the ecosystem.
The repository's core function is to store chain metadata in a structured format within the _data/chains directory, where each blockchain network has its own JSON file named according to the CAIP-2 standard. This standardized naming convention ensures consistency and interoperability across different blockchain applications. The metadata includes essential information such as chain names, short names, network parameters, and references to associated icons and explorers. Icon data is maintained separately in _data/icons with specific requirements including IPFS URLs for public resolution and defined dimensions and formats.
A key feature of the repository is its support for hierarchical chain relationships, allowing Layer 2 solutions and shards to be linked to their parent chains through a parent reference field. This capability enables the registry to accurately represent the complex topology of modern blockchain ecosystems where multiple scaling solutions and sidechains operate alongside primary networks. The system also supports optional bridge information for chains that implement cross-chain functionality.
The repository implements a status field system that allows chains to be marked as active, incubating, or deprecated. This approach prevents the deletion of chain records, which is critical for security as removing chain data could create vulnerabilities to replay attacks. The deprecation mechanism provides a path for managing short-lived testnets and other temporary networks while maintaining historical integrity.
Collision management represents a core governance principle in this repository. The system enforces strict uniqueness constraints on chain IDs and short names to prevent replay attack vulnerabilities. The first pull request to claim a chain ID receives the assignment, and subsequent attempts to reassign IDs are rejected unless the original chain is deprecated. This first-come-first-served approach is documented in EIP-155 and creates a clear, conflict-free allocation mechanism.
The repository provides aggregated JSON files at chainid.network that automatically assemble all chain data into two formats: a comprehensive chains.json file and a miniaturized chains_mini.json version optimized for smaller file sizes. This dual-format approach accommodates different use cases from detailed configuration needs to bandwidth-constrained environments.
The registry has achieved significant adoption across the blockchain ecosystem. Major wallet implementations including WallETH, TREZOR, and Minerva Wallet rely on this data, as do blockchain explorers like Otterscan. The metadata is referenced by multiple Ethereum Improvement Proposals including EIP-155, EIP-3014, EIP-3770, and EIP-4527, establishing it as a foundational standard. Numerous chain listing websites and services consume the repository's data, including chainid.network, chainlist.org, and specialized platforms like chaindirectory.xyz and chainmap.io. The repository also integrates with developer tools such as Wagmi-compatible chain configurations and the Sourcify playground, demonstrating its importance as infrastructure for blockchain development and user-facing applications.
