Cardano Improvement Proposals


CIP 5 - Common Bech32 Prefixes

Contents

Abstract

This CIP defines a set of common prefixes (or so-called human-readable part in the bech32) encoding format) for various bech32-encoded binary data across the Cardano eco-system.

Motivation

Many tools used within the Cardano eco-system are manipulating binary data. Binary data are typically encoded as hexadecimal text strings when shown in a user interface (might it be a console, a url or a structured document from a server). From the user perspective, it can be difficult to distinguish between various encoded data. From the tools developer perspective, it can also be difficult to validate inputs based only on raw bytes (in particular when encoded data often have the same length).

Therefore, we can leverage bech32 for binary data encoding, with a set of common prefixes that can be used across tools and software to disambiguate payloads.

Specification

We define the following set of common prefixes with their corresponding semantic. Any software willing to represent binary data in a human-friendly way should abide by these guidelines. Should a data-type be missing, we encourage developers to update this CIP and register a new prefix.

Keys

Prefix Meaning Contents
acct_sk CIP-1852's account private key Ed25519 private key
acct_vk CIP-1852's account public key Ed25519 public key
acct_xsk CIP-1852's extended account private key Ed25519-bip32 extended private key
acct_xvk CIP-1852's extended account public key Ed25519 public key with chain code
acct_shared_sk CIP-1854's account private key Ed25519 private key
acct_shared_vk CIP-1854's account public key Ed25519 public key
acct_shared_xsk CIP-1854's extended account private key Ed25519-bip32 extended private key
acct_shared_xvk CIP-1854's extended account public key Ed25519 public key with chain code
addr_sk CIP-1852's address signing key Ed25519 private key
addr_vk CIP-1852's address verification key Ed25519 public key
addr_xsk CIP-1852's address extended signing key Ed25519-bip32 extended private key
addr_xvk CIP-1852's address extended verification key Ed25519 public key with chain code
addr_shared_sk CIP-1854's address signing key Ed25519 private key
addr_shared_vk CIP-1854's address verification key Ed25519 public key
addr_shared_xsk CIP-1854's address extended signing key Ed25519-bip32 extended private key
addr_shared_xvk CIP-1854's address extended verification key Ed25519 public key with chain code
kes_sk KES signing key KES signing key
kes_vk KES verification key KES verification key
pool_sk Pool operator signing key Ed25519 private key
pool_vk Pool operator verification key Ed25519 public key
root_sk CIP-1852's root private key Ed25519 private key
root_vk CIP-1852's root public key Ed25519 public key
root_xsk CIP-1852's extended root private key Ed25519-bip32 extended private key
root_xvk CIP-1852's extended root public key Ed25519 public key with chain code
root_shared_sk CIP-1854's root private key Ed25519 private key
root_shared_vk CIP-1854's root public key Ed25519 public key
root_shared_xsk CIP-1854's extended root private key Ed25519-bip32 extended private key
root_shared_xvk CIP-1854's extended root public key Ed25519 public key with chain code
stake_sk CIP-1852's stake address signing key Ed25519 private key
stake_vk CIP-1852's stake address verification key Ed25519 public key
stake_xsk CIP-1852's extended stake address signing key Ed25519-bip32 extended private key
stake_xvk CIP-1852's extended stake address verification key Ed25519 public key with chain code
stake_shared_sk CIP-1854's stake address signing key Ed25519 private key
stake_shared_vk CIP-1854's stake address verification key Ed25519 public key
stake_shared_xsk CIP-1854's extended stake address signing key Ed25519-bip32 extended private key
stake_shared_xvk CIP-1854's extended stake address verification key Ed25519 public key with chain code
vrf_sk VRF signing key VRF signing key
vrf_vk VRF verification key VRF verification key

Hashes

Prefix Meaning Contents
asset Fingerprint of a native asset for human comparison See CIP-0014
pool Pool operator verification key hash (pool ID) blake2b_224 digest of an operator verification key
script Script hash blake2b_224 digest of a serialized transaction script
addr_vkh Address verification key hash blake2b_224 digest of a payment verification key
addr_shared_vkh Shared address verification key hash blake2b_224 digest of a payment verification key
stake_vkh Stake address verification key hash blake2b_224 digest of a delegation verification key
stake_shared_vkh Shared stake address verification key hash blake2b_224 digest of a delegation verification key
vrf_vkh VRF verification key hash blake2b_256 digest of a VRF verification key

Miscellaneous

Prefix Meaning Contents
addr Mainnet address Network tag, payment credential and optional stake credential
addr_test Testnet address Network tag, payment credential and optional stake credential
stake Mainnet stake address Network tag and stake credential
stake_test Testnet stake address Network tag and stake credential

Rationale

About the _test suffix

Address already contains a discriminant tag, yet it requires one to peek at the internal binary payload. With Base58-encoded addresses, people have been used to look at first few characters and distinguish address this way. Not only this is cumbersome, but it is also made harder with both Shelley and Bech32-encoded addresses. On the one hand, the "common" part of the internal payload is much less than in Byron addresses and thus, the first bytes of the payload are varying much more. Plus, the bech32 prefix which can now be fixed makes it even more error-prone.

Therefore, having a clear human-readable indicator regarding the network discrimination is useful.

About addr

Addresses probably are the most user-facing object in the current Cardano eco-system. Being able to clearly identify them

:bulb: Open question: with side-chains and multi-currencies coming soon, would it make sense to include the currency in the bech32 prefix? e.g. ada1... or ada_addr1.

About stake

Stake addresses are references to reward account. They are used in many manipulation involving rewards (registering stake key, delegating, fetching reward balance etc..). We therefore make it a "first-class" object and assign it a dedicated prefix.

About sk & vk

Both are rather transparent abbreviations for signing key and verification key.

About xsk & xvk

The prefix x is typically used in cryptography to refer to extended keys (e.g. xpub, xprv …). Following this convention, we prefix sk and vk as such when they refer to extended keys.

About vkh

An abbreviation for verification key hash.

Verification key hashes are commonly utilized throughout the Cardano eco-system. For example, they're used in stake pool registration and retirement certificates, stake key registration, delegation, and deregistration certificates, etc. As a result, it seems useful to have a human-readable prefix by which one can discern the different kinds of verification key hashes.

Backwards compatibility

The only prior work done towards that direction has been jcli. Historically, prefixes evolved very organically and without any agreed-upon standard. jcli is however only compatible with Jörmungandr and is not intended to be compatible with the cardano-node. Therefore, there's little concern regarding compatibility here.

Reference implementation

N/A

This CIP is licensed under Apache-2.0.