CAIP-5: Blockchain Reference for the Cosmos Namespace

Metadata

Status: SupersededStandardCreated: 2019-12-05

Authors

Simon Warta (@webmaster128)

Requires

EIP-2

Links

GitHub page Discussion on Ethereum Magicians

Simple Summary

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

Abstract

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

Motivation

See CAIP-2.

Specification

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.

Direct

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.

Hashed

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:

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

Rationale

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.