CAIP-5: Blockchain Reference for the Cosmos Namespace Source

Author Simon Warta
Status Superseded
Type Standard
Created 2019-12-05
Updated 2020-01-17
Requires 2
Superseded By

Simple Summary

This document is about the details of the Cosmos namespaces and references for CAIP-2.


In CAIP-2 a general blockchain identification scheme is defined. This is the implementation of CAIP-2 for Cosmos.


See CAIP-2.


Cosmos Namespace

The namespace “cosmos” refers to the wider Cosmos ecosystem.

Reference Definition

The reference relies on Tendermint’s chain_id from the genesis file (a JSON-compatible unicode string). In some cases we use it directly, otherwise it is hashed. An empty chain_id must be treated as an error.


If the chain_id matches the case-sensitive pattern [-a-zA-Z0-9]{1,32} and does not start with “hashed-“, it is used the reference directly.


Otherwise the reference is defined as first_16_chars(hex(sha256(utf8(chain_id)))), with

  • the Tendermint chain_id from the genesis file (a JSON-compatible unicode string)
  • utf8 being the UTF-8 encoding
  • sha256 being the SHA256 hash function
  • hex being a lowercase hex encoder
  • first_16_chars being the first 16 characters

Resolution Method

To resolve a blockchain reference for the Cosmos namespace, make a REST GET request to the blockchain node with endpoint /node_info, for example:

// Request
curl -X GET "" -H "accept: application/json"

// Response
  "application_version": {
    "build_tags": "string",
    "client_name": "string",
    "commit": "string",
    "go": "string",
    "name": "string",
    "server_name": "string",
    "version": "string"
  "node_info": {
    "id": "string",
    "moniker": "validator-name",
    "protocol_version": {
      "p2p": 7,
      "block": 10,
      "app": 0
    "network": "gaia-2",
    "channels": "string",
    "listen_addr": "",
    "version": "0.15.0",
    "other": {
      "tx_index": "on",
      "rpc_address": "tcp://"

The response will return a JSON object which will include node information and the blockchain reference can be retrieved from to be CAIP-5 compatible.


Blockchains in the “cosmos” namespace are Cosmos SDK blockchains (e.g. Cosmoshub, Binance, Cosmos Testnets) and Weave based blockchains (e.g. IOV).

While there is no enforced restriction on chain_id, the author of this document did not find a chain ID in the wild that does not conform to the restrictions of the direct reference definition. There is a discussion about documenting a best practice chain ID pattern.

Cosmos blockchains with a chain ID not matching [-a-zA-Z0-9]{1,32} or prefixed with “hashed-“ need to be hashed in order to comply with CAIP-2. No real world example is known to the author yet.

During the development of this chain ID definition, we came across changing chain IDs for Cosmos Hub (cosmoshub-1, cosmoshub-2, cosmoshub-3). A new chain ID is assigned every time Cosmos Hub dumps the current blockchain state and creates a new genesis from the old state. Technically this leads to different blockchains and can (and maybe should) treated as such. For this specification, we treat them as different blockchains. It is the responsibility of a higher level application to interpret some chains as sequels of each other or create equality sets.

Backwards Compatibility

Not applicable

Test Cases

This is a list of manually composed examples

# Cosmos Hub (Tendermint + Cosmos SDK)

# Binance chain (Tendermint + Cosmos SDK; see

# IOV Mainnet (Tendermint + Weave)

# chain_ids "x", "hash-", "hashed" (are direct)

# chain_ids "hashed-", "hashed-123" (invalid prefix for the direct definition)

# chain_id "123456789012345678901234567890123456789012345678" (too long for the direct definition)

# chain_ids " ", "wonderland🧝‍♂️" (invalid character for the direct definition)

Copyright and related rights waived via CC0.


Please cite this document as:

Simon Warta, "CAIP-5: Blockchain Reference for the Cosmos Namespace," Chain Agnostic Improvement Proposals, no. 5, December 2019. [Online serial]. Available: