CAIP-2: Blockchain ID Specification

Simple Summary

CAIP-2 defines a way to identify a blockchain (e.g. Ethereum Mainnet, Görli, Bitcoin, Cosmos Hub) in a human-readable, developer-friendly and transaction-friendly way.

Abstract

Often you need to reference a blockchain, for example when you want to state where some asset or smart contract is located. In Ethereum the EIP155 chain ID is used most of the time. But with an Ethereum chain ID you cannot reference e.g. a Bitcoin or Cosmos chain.

Motivation

The final trigger to create this CAIP (and the CAIP process itself) was a discussion around [EIP2256] at Ethereum-Magicians. Independently, the Universal Chain Registry was created that needs properly specified chain identifiers at its core. A discussion about the network ID format brought this group together with ChainAgnostic.

Specification

The blockchain ID (short “chain ID”) is a string designed to uniquely identify blockchains in a developer-friendly fashion.

Syntax

The chain_id is a case-sensitive string in the form

chain_id:    namespace + ":" + reference
namespace:   [-a-z0-9]{3,8}
reference:   [-_a-zA-Z0-9]{1,32}

Semantics

Each namespace covers a class of similar blockchains. Usually it describes an ecosystem or standard, such as e.g. cosmos or eip155. One namespace should refer to one resolution method to resolve the chain’s reference. A reference is a way to identify a blockchain within a given namespace. The semantics as well as the more granular syntax which are delegated to each namespace specification shall be defined in separate CAIPs describing resolution methods.

Rationale

The goals of the general chain ID format is:

• Uniqueness within the entire blockchain ecosystem
• To some degree human-readable and helps for basic debugging
• Restricted in a way that it can be stored on chain
• Character set basic enough to display in hardware wallets as part of a transaction content

The following secondary goals can easily be achieved:

• Can be used unescaped in URL paths
• Can be used as filename in a case-sensitive UNIX file system (Linux/git).

These secondary goals have been given up along the way:

• Can be used as filename in a case-insensitive UNIX file system (macOS).
• Can be used as filename in a Windows file system.

Test Cases

This is a list of manually composed examples

# Ethereum mainnet
eip155:1

# Bitcoin mainnet (see https://github.com/bitcoin/bips/blob/master/bip-0122.mediawiki#definition-of-chain-id)
bip122:000000000019d6689c085ae165831e93

# Litecoin
bip122:12a765e31ffd4059bada1e25190f6e98

# Feathercoin (Litecoin fork)
bip122:fdbe99b90c90bae7505796461471d89a

# Cosmos Hub (Tendermint + Cosmos SDK)
cosmos:cosmoshub-2
cosmos:cosmoshub-3

# Binance chain (Tendermint + Cosmos SDK; see https://dataseed5.defibit.io/genesis)
cosmos:Binance-Chain-Tigris

# IOV Mainnet (Tendermint + weave)
cosmos:iov-mainnet

# StarkNet Testnet
starknet:SN_GOERLI

# Lisk Mainnet (LIP-0009; see https://github.com/LiskHQ/lips/blob/master/proposals/lip-0009.md)
lip9:9ee11e9df416b18b

# Dummy max length (8+1+32 = 41 chars/bytes)
chainstd:8c3444cf8970a9e41a706fab93e7a6c4

Links

• EIP155
• BIP122
• EIP2256
• LIP9
• Cosmos chain ID best practice

Copyright

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Simon Warta, ligi, Pedro Gomes, Antoine Herzog, "CAIP-2: Blockchain ID Specification," Chain Agnostic Improvement Proposals, no. 2, December 2019. [Online serial]. Available: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md