This document describes the in-built accounts system of the Cosmos SDK.
# Pre-requisite Readings
# Account Definition
In the Cosmos SDK, an account designates a pair of public key
PubKey and private key
PubKey can be derived to generate various
Addresses, which are used to identify users (among other parties) in the application.
Addresses are also associated with
messages to identify the sender of the
PrivKey is used to generate digital signatures to prove that an
Address associated with the
PrivKey approved of a given
PrivKeys, the Cosmos SDK uses a standard called BIP32 (opens new window). This standard defines how to build an HD wallet, where a wallet is a set of accounts. At the core of every account, there is a seed, which takes the form of a 12 or 24-words mnemonic. From this mnemonic, it is possible to derive any number of
PrivKeys using one-way cryptographic function. Then, a
PubKey can be derived from the
PrivKey. Naturally, the mnemonic is the most sensitive information, as private keys can always be re-generated if the mnemonic is preserved.
In the Cosmos SDK, accounts are stored and managed via an object called a
Keyring is an object that stores and manages accounts. In the Cosmos SDK, a
Keyring implementation follows the
The default implementation of
Keyring comes from the third-party
99designs/keyring (opens new window) library.
A few notes on the
Sign(uid string, payload byte) (byte, tmcrypto.PubKey, error)strictly deals with the signature of the
payloadbytes. Some preliminary work should be done beforehand to prepare and encode the transaction into a canonical
byteform. Protobuf being not deterministic, it has been decided in ADR-020 that the canonical
payloadto sign is the
SignDocstruct, deterministically encoded using ADR-027. Note that signature verification is not implemented in the SDK by default, it is deferred to the
NewAccount(uid, mnemonic, bip39Passwd, hdPath string, algo SignatureAlgo) (Info, error)creates a new account based on the
bip44 path(opens new window) and persists it on disk (note that the
PrivKeyis encrypted with a passphrase before being persisted (opens new window), it is never stored unencrypted). In the context of this method, the
addressparameters refer to the segment of the BIP44 derivation path (e.g.
2, ...) used to derive the
PubKeyfrom the mnemonic (note that given the same mnemonic and
account, the same
PrivKeywill be generated, and given the same
address, the same
Addresswill be generated). Finally, note that the
NewAccountmethod derives keys and addresses using the algorithm specified in the last argument
algo. Currently, the SDK supports two public key algorithms:
secp256k1, as implemented in the SDK's
crypto/keys/secp256k1package (opens new window),
ed25519, as implemented in the SDK's
crypto/keys/ed25519package (opens new window).
ExportPrivKeyArmor(uid, encryptPassphrase string) (armor string, err error)exports a private key in ASCII-armored encrypted format, using the given passphrase. You can then either import it again into the keyring using the
ImportPrivKey(uid, armor, passphrase string)function, or decrypt it into a raw private key using the
UnarmorDecryptPrivKey(armorStr string, passphrase string)function.
Also see the
Addresses section for more information.
# Addresses and PubKeys
PubKeys are both public information that identify actors in the application. There are 3 main types of
PubKeys available by default in the Cosmos SDK:
- Addresses and Keys for accounts, which identify users (e.g. the sender of a
message). They are derived using the
- Addresses and Keys for validator operators, which identify the operators of validators. They are derived using the
- Addresses and Keys for consensus nodes, which identify the validator nodes participating in consensus. They are derived using the
|Address bech32 Prefix||Pubkey bech32 Prefix||Curve||Address byte length||Pubkey byte length|
|Accounts||cosmos||cosmospub|| || |
|Validator Operator||cosmosvaloper||cosmosvaloperpub|| || |
|Consensus Nodes||cosmosvalcons||cosmosvalconspub|| || |
PubKeys used in the Cosmos SDK are Protobuf messages and have the following methods:
secp256k1keys, the actual implementation can be found here (opens new window).
ed25519keys, it can be found here (opens new window).
In both case, the actual key (as raw bytes) is the compressed form of the pubkey. The first byte is a
0x02 byte if the
y-coordinate is the lexicographically largest of the two associated with the
x-coordinate. Otherwise the first byte is a
0x03. This prefix is followed with the
Note that in the Cosmos SDK,
Pubkeys are not manipulated in their raw bytes form. Instead, they are encoded to string using
bech32 (opens new window). In the SDK, it is done by first calling the
Bytes() method on the raw
Pubkey (which applies amino encoding), and then the
ConvertAndEncode method of
The Cosmos SDK comes by default with 3 types of addresses:
ValAddressfor validator operators.
ConsAddressfor validator nodes.
Each of these address types are an alias for an hex-encoded
byte array of length 20. Here is the standard way to obtain an address
aa from a
These addresses implement the
Of note, the
Bytes() method both return the same raw
byte form of the address, the former being needed for Protobuf compatibility. Also, the
String() method is used to return the
bech32 encoded form of the address, which should be the only address format with which end-user interract. Here is an example:
Learn about gas and fees