Chainlist: Registry Chain ID và Metadata EVM
/chains
Chainlist là dữ liệu gốc mà phần lớn các tra cứu chain ID EVM cuối cùng đều quay về — một repo Git với một file JSON cho mỗi chain, không phải một website. Chainlist giữ vị trí đó nhờ quy tắc chống trùng lặp chặt chẽ: ai đăng ký chain ID trước thì giữ ID đó, và PR nào cố chiếm lại một ID đã có sẽ bị đóng thẳng. Cái giá phải trả là sự rườm rà — thêm một chain nghĩa là phải đọc EIP-155 và vượt qua CI chạy bằng gradle, chứ không chỉ mở một PR.
Repository Chainlist chứa những gì
Chainlist là repo base/chains trên GitHub, lưu metadata cho các mạng tương thích EVM: mỗi chain một file JSON, đặt trong _data/chains và đặt tên theo định danh CAIP-2. Mỗi file liệt kê name, chainId, networkId, native currency, RPC endpoint và explorer của chain đó, cộng thêm một liên kết parent tùy chọn cho các L2. Một thư mục _data/icons riêng lưu tham chiếu icon qua IPFS, dùng chung giữa các entry.
Các trường metadata cho mỗi chain EVM
- ✓Mỗi chain có một file JSON riêng trong _data/chains, đặt tên theo định danh CAIP-2, chứa chainId, networkId, name và shortName.
- ✓nativeCurrency là một object lồng nhau (name, symbol, decimals) thay vì một field phẳng, khớp với cách ví cần hiển thị số dư.
- ✓explorers là một array, mỗi entry có thể khai báo một standard như EIP3091 để tooling biết định dạng URL cần dùng.
- ✓features liệt kê các EIP mà chain đó hỗ trợ (entry ví dụ trong README có EIP155 và EIP1559) thay vì mặc định mọi chain EVM đều giống nhau.
- ✓Các L2 hoặc shard có thể khai báo một object parent trỏ tới CAIP-2 ID của chain gốc đã tồn tại, kèm một list bridges tùy chọn.
- ✓Field status đánh dấu một chain là active, incubating hay deprecated — entry deprecated vẫn được giữ lại trong repo thay vì bị xóa, nên ID cũ vẫn có thể truy vết.
- ✓Icon nằm trong một thư mục _data/icons riêng, dưới dạng tham chiếu IPFS (url, width, height, format), được dùng lại giữa các entry chain và explorer theo tên.
Quy tắc và ràng buộc khi thêm chain mới
- △Đóng góp có ma sát thật: thêm một chain cần một file JSON đúng định dạng, vượt qua CI bằng lệnh `./gradlew run`, và icon phải resolve được qua `ipfs get` — icon pin trên Pinata bị từ chối rõ ràng ở thời điểm hiện tại.
- △Không có web UI chính thức ở đây — đây là nguồn metadata gốc; muốn một danh sách duyệt được trên trình duyệt thì phải qua các site phái sinh như chainid.network hay chainlist.org, không phải repo này.
- △Topics trên repo GitHub đang để trống, nên việc tìm kiếm trong GitHub phải dựa vào tên repo thay vì nhãn topic.
- △Việc gán chain ID theo kiểu ai đăng ký trước được trước, không có quy trình khiếu nại — README nói rõ những PR tranh giành lại một ID với lý do "chain của tôi tốt hơn" sẽ bị đóng thẳng.
Chainlist khác gì so với eth-chains và chainid.network
Câu hỏi thường gặp
Chain ID của Ethereum mainnet là 1 (networkId cũng là 1), đúng như entry ví dụ trong chính Chainlist cho eip155-1 — cùng ID được định nghĩa trong EIP-155.
Có — base/chains được phát hành theo giấy phép MIT, nên việc đưa metadata chain của Chainlist vào một ví, explorer hay sản phẩm RPC thương mại là được phép; điều khoản MIT tiêu chuẩn, như giữ lại thông báo bản quyền, vẫn áp dụng.
Thêm một file JSON cho chain đó trong _data/chains, đặt tên theo CAIP-2 ID, theo đúng schema đã tài liệu hóa (chainId, name, shortName, rpc, nativeCurrency, explorers), rồi chạy `./gradlew run` ở local để các check CI pass trước khi mở PR.
Chainlist chặn chain ID trùng vì một ID bị dùng lại cho phép một transaction ký cho chain này bị replay sang chain khác — đúng rủi ro replay attack mà EIP-155 được viết ra để chặn. Repo gán mỗi ID cho người đăng ký trước và đóng thẳng các PR cố chiếm lại một ID đã có.
File tổng hợp gộp mọi entry chain của Chainlist được publish tại chainid.network/chains.json, và có bản chains_mini.json nhỏ hơn nếu chỉ cần một tập field rút gọn.
Một chain bị deprecated trong Chainlist sẽ có field status chuyển thành "deprecated" thay vì bị xóa, và chain ID của nó mặc định không được gán lại cho chain mới — muốn dùng lại phải qua một ngoại lệ rõ ràng, kích hoạt cờ cảnh báo "reusedChainId" để ví hiển thị.
Các trường hợp sử dụng tốt nhất
- •Đổ dữ liệu vào flow "add network" của một ví — RPC URL, native currency, explorer link — thay vì tự duy trì danh sách đó bằng tay.
- •Tra chain ID hoặc networkId trước khi ký một transaction, để tránh đúng kịch bản replay cross-chain mà EIP-155 xử lý.
- •Kéo file chains.json đã gộp sẵn (hoặc bản chains_mini.json nhỏ hơn) vào một backend service cần cấu hình network EVM mà không cần clone repo.
- •Đăng ký một chain EVM hoàn toàn mới và nhận một chain ID đã được kiểm tra trùng với mọi chain hiện có trước khi được chấp nhận.
- •Resolve URL explorer cho một chain theo standard đã khai báo (ví dụ EIP3091) thay vì tự đoán pattern URL.
Cách sử dụng
Không có bước cài đặt nào — Chainlist được dùng bằng cách clone base/chains rồi đọc trực tiếp các file _data/chains/<chain-id>.json, hoặc fetch các bản tổng hợp dựng sẵn tại chainid.network/chains.json (đầy đủ mọi chain, full schema) hay chains_mini.json (ít field hơn, payload nhỏ hơn). Mỗi file per-chain theo đúng shape JSON đã tài liệu hóa (chainId, name, shortName, nativeCurrency, rpc, explorers, và các field tùy chọn features/parent/status); tham chiếu icon trong _data/icons resolve về URL IPFS thay vì file ảnh local.
Ai nên dùng — và ai nên bỏ qua
Dùng Chainlist nếu bạn đang xây hoặc maintain một ví, RPC client, hay block explorer và cần một nguồn chain ID, RPC URL, explorer link được duy trì và review qua PR, thay vì tự hardcode danh sách riêng. Đây cũng là điểm dừng đúng nếu bạn đang đăng ký một chain EVM hoàn toàn mới và muốn một ID không trùng với ai khác. Bỏ qua nếu bạn chỉ cần một trang web để bấm "add network vào MetaMask" — đó là chainlist.org hoặc chainid.network, không phải repo này — hoặc nếu bạn cần dữ liệu chain nhiều field hơn schema ở đây (schema của repo này cố tình tối giản: identity, currency, RPC và thông tin explorer, không có gas price hay lịch sử thống kê).
Chưa chắc chains có hợp với bạn?
Để ChatGPT, Claude hoặc Perplexity tìm hiểu giúp — bấm bên dưới và xem AI nói gì về chains.