Skip to main content

CIP-0005

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

PrefixMeaningContents
acct_skCIP-1852's account private keyEd25519 private key
acct_vkCIP-1852's account public keyEd25519 public key
acct_xskCIP-1852's extended account private keyEd25519-bip32 extended private key
acct_xvkCIP-1852's extended account public keyEd25519 public key with chain code
acct_shared_skCIP-1854's account private keyEd25519 private key
acct_shared_vkCIP-1854's account public keyEd25519 public key
acct_shared_xskCIP-1854's extended account private keyEd25519-bip32 extended private key
acct_shared_xvkCIP-1854's extended account public keyEd25519 public key with chain code
addr_skCIP-1852's address signing keyEd25519 private key
addr_vkCIP-1852's address verification keyEd25519 public key
addr_xskCIP-1852's address extended signing keyEd25519-bip32 extended private key
addr_xvkCIP-1852's address extended verification keyEd25519 public key with chain code
addr_shared_skCIP-1854's address signing keyEd25519 private key
addr_shared_vkCIP-1854's address verification keyEd25519 public key
addr_shared_xskCIP-1854's address extended signing keyEd25519-bip32 extended private key
addr_shared_xvkCIP-1854's address extended verification keyEd25519 public key with chain code
gov_skGovernance vote signing keyEd25519 private key
gov_vkGovernance vote verification keyEd25519 public key
kes_skKES signing keyKES signing key
kes_vkKES verification keyKES verification key
policy_skCIP-1855's policy private keyEd25519 private key
policy_vkCIP-1855's policy public keyEd25519 public key
pool_skPool operator signing keyEd25519 private key
pool_vkPool operator verification keyEd25519 public key
root_skCIP-1852's root private keyEd25519 private key
root_vkCIP-1852's root public keyEd25519 public key
root_xskCIP-1852's extended root private keyEd25519-bip32 extended private key
root_xvkCIP-1852's extended root public keyEd25519 public key with chain code
root_shared_skCIP-1854's root private keyEd25519 private key
root_shared_vkCIP-1854's root public keyEd25519 public key
root_shared_xskCIP-1854's extended root private keyEd25519-bip32 extended private key
root_shared_xvkCIP-1854's extended root public keyEd25519 public key with chain code
stake_skCIP-1852's stake address signing keyEd25519 private key
stake_vkCIP-1852's stake address verification keyEd25519 public key
stake_xskCIP-1852's extended stake address signing keyEd25519-bip32 extended private key
stake_xvkCIP-1852's extended stake address verification keyEd25519 public key with chain code
stake_shared_skCIP-1854's stake address signing keyEd25519 private key
stake_shared_vkCIP-1854's stake address verification keyEd25519 public key
stake_shared_xskCIP-1854's extended stake address signing keyEd25519-bip32 extended private key
stake_shared_xvkCIP-1854's extended stake address verification keyEd25519 public key with chain code
vrf_skVRF signing keyVRF signing key
vrf_vkVRF verification keyVRF verification key

Hashes

PrefixMeaningContents
assetFingerprint of a native asset for human comparisonSee CIP-0014
poolPool operator verification key hash (pool ID)blake2b_224 digest of an operator verification key
scriptScript hashblake2b_224 digest of a serialized transaction script
addr_vkhAddress verification key hashblake2b_224 digest of a payment verification key
addr_shared_vkhShared address verification key hashblake2b_224 digest of a payment verification key
policy_vkhPolicy verification key hashblake2b_224 digest of a policy verification key
stake_vkhStake address verification key hashblake2b_224 digest of a delegation verification key
stake_shared_vkhShared stake address verification key hashblake2b_224 digest of a delegation verification key
req_signer_vkhRequired signer verification key hashblake2b_224 digest of a required signer verification key
vrf_vkhVRF verification key hashblake2b_256 digest of a VRF verification key
datumOutput datum hashblake2b_256 digest of output datum
script_dataScript data hashblake2b_256 digest of script data

Miscellaneous

PrefixMeaningContents
addrMainnet addressNetwork tag, payment credential and optional stake credential
addr_testTestnet addressNetwork tag, payment credential and optional stake credential
stakeMainnet stake addressNetwork tag and stake credential
stake_testTestnet stake addressNetwork 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

💡 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

cip5-js

This CIP is licensed under Apache-2.0.

CIP Information

This Standards ./CIP-0005 created on 2020-05-28 has the status: Active.
This page was generated automatically from: cardano-foundation/CIPs.