# Accounts

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 PrivKey. The 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 message. The PrivKey is used to generate digital signatures to prove that an Address associated with the PrivKey approved of a given message.

To derive PubKeys and 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.

Copy Account 0 Account 1 Account 2 +------------------+ +------------------+ +------------------+ | | | | | | | Address 0 | | Address 1 | | Address 2 | | ^ | | ^ | | ^ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | + | | + | | + | | Public key 0 | | Public key 1 | | Public key 2 | | ^ | | ^ | | ^ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | + | | + | | + | | Private key 0 | | Private key 1 | | Private key 2 | | ^ | | ^ | | ^ | +------------------+ +------------------+ +------------------+ | | | | | | | | | +--------------------------------------------------------------------+ | | +---------+---------+ | | | Master PrivKey | | | +-------------------+ | | +---------+---------+ | | | Mnemonic (Seed) | | | +-------------------+

In the Cosmos SDK, accounts are stored and managed via an object called a Keyring.

# Keyring

A Keyring is an object that stores and manages accounts. In the Cosmos SDK, a Keyring implementation follows the Keyring interface:

Copy // Keyring exposes operations over a backend supported by github.com/99designs/keyring. type Keyring interface { // List all keys. List() ([]Info, error) // Supported signing algorithms for Keyring and Ledger respectively. SupportedAlgorithms() (SigningAlgoList, SigningAlgoList) // Key and KeyByAddress return keys by uid and address respectively. Key(uid string) (Info, error) KeyByAddress(address sdk.Address) (Info, error) // Delete and DeleteByAddress remove keys from the keyring. Delete(uid string) error DeleteByAddress(address sdk.Address) error // NewMnemonic generates a new mnemonic, derives a hierarchical deterministic // key from that, and persists it to the storage. Returns the generated mnemonic and the key // Info. It returns an error if it fails to generate a key for the given algo type, or if // another key is already stored under the same name. NewMnemonic(uid string, language Language, hdPath string, algo SignatureAlgo) (Info, string, error) // NewAccount converts a mnemonic to a private key and BIP-39 HD Path and persists it. NewAccount(uid, mnemonic, bip39Passwd, hdPath string, algo SignatureAlgo) (Info, error) // SaveLedgerKey retrieves a public key reference from a Ledger device and persists it. SaveLedgerKey(uid string, algo SignatureAlgo, hrp string, coinType, account, index uint32) (Info, error) // SavePubKey stores a public key and returns the persisted Info structure. SavePubKey(uid string, pubkey tmcrypto.PubKey, algo hd.PubKeyType) (Info, error) // SaveMultisig stores and returns a new multsig (offline) key reference. SaveMultisig(uid string, pubkey tmcrypto.PubKey) (Info, error) Signer Importer Exporter }

The default implementation of Keyring comes from the third-party 99designs/keyring (opens new window) library.

A few notes on the Keyring methods:

  • Sign(uid string, payload []byte) ([]byte, tmcrypto.PubKey, error) strictly deals with the signature of the payload bytes. Some preliminary work should be done beforehand to prepare and encode the transaction into a canonical []byte form. Protobuf being not deterministic, it has been decided in ADR-020 that the canonical payload to sign is the SignDoc struct, deterministically encoded using ADR-027. Note that signature verification is not implemented in the SDK by default, it is deferred to the anteHandler. Copy // SignDoc is the type used for generating sign bytes for SIGN_MODE_DIRECT. message SignDoc { // body_bytes is protobuf serialization of a TxBody that matches the // representation in TxRaw. bytes body_bytes = 1; // auth_info_bytes is a protobuf serialization of an AuthInfo that matches the // representation in TxRaw. bytes auth_info_bytes = 2; // chain_id is the unique identifier of the chain this transaction targets. // It prevents signed transactions from being used on another chain by an // attacker string chain_id = 3; // account_number is the account number of the account in state uint64 account_number = 4; }

  • 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 PrivKey is encrypted with a passphrase before being persisted (opens new window), it is never stored unencrypted). In the context of this method, the account and address parameters refer to the segment of the BIP44 derivation path (e.g. 0, 1, 2, ...) used to derive the PrivKey and PubKey from the mnemonic (note that given the same mnemonic and account, the same PrivKey will be generated, and given the same account and address, the same PubKey and Address will be generated). Finally, note that the NewAccount method derives keys and addresses using the algorithm specified in the last argument algo. Currently, the SDK supports two public key algorithms:

  • 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

Addresses and PubKeys are both public information that identify actors in the application. There are 3 main types of Addresses/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 secp256k1 curve.
  • Addresses and Keys for validator operators, which identify the operators of validators. They are derived using the secp256k1 curve.
  • Addresses and Keys for consensus nodes, which identify the validator nodes participating in consensus. They are derived using the ed25519 curve.
Address bech32 Prefix Pubkey bech32 Prefix Curve Address byte length Pubkey byte length
Accounts cosmos cosmospub secp256k1 20 33
Validator Operator cosmosvaloper cosmosvaloperpub secp256k1 20 33
Consensus Nodes cosmosvalcons cosmosvalconspub ed25519 20 32

# PubKeys

PubKeys used in the Cosmos SDK are Protobuf messages and have the following methods:

Copy // PubKey defines a public key and extends proto.Message. type PubKey interface { proto.Message Address() Address Bytes() []byte VerifySignature(msg []byte, sig []byte) bool Equals(PubKey) bool Type() string }

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 x-coordinate.

Note that in the Cosmos SDK, Pubkeys are not manipulated in their raw bytes form. Instead, they are encoded to string using Amino and 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 bech32.

Copy // MustBech32ifyAddressBytes returns a bech32 representation of address bytes. // Returns an empty sting if the byte slice is 0-length. It panics if the bech32 conversion // fails or the prefix is empty. func MustBech32ifyAddressBytes(prefix string, bs []byte) string { s, err := Bech32ifyAddressBytes(prefix, bs) if err != nil { panic(err) } return s } // Format implements the fmt.Formatter interface. // nolint: errcheck func (ca ConsAddress) Format(s fmt.State, verb rune) { switch verb { case 's': s.Write([]byte(ca.String())) case 'p': s.Write([]byte(fmt.Sprintf("%p", ca))) default: s.Write([]byte(fmt.Sprintf("%X", []byte(ca)))) } } // ---------------------------------------------------------------------------- // auxiliary // ---------------------------------------------------------------------------- // Bech32PubKeyType defines a string type alias for a Bech32 public key type. type Bech32PubKeyType string // Bech32 conversion constants const ( Bech32PubKeyTypeAccPub Bech32PubKeyType = "accpub" Bech32PubKeyTypeValPub Bech32PubKeyType = "valpub" Bech32PubKeyTypeConsPub Bech32PubKeyType = "conspub" ) // Bech32ifyPubKey returns a Bech32 encoded string containing the appropriate // prefix based on the key type provided for a given PublicKey. func Bech32ifyPubKey(pkt Bech32PubKeyType, pubkey crypto.PubKey) (string, error) { var bech32Prefix string switch pkt { case Bech32PubKeyTypeAccPub: bech32Prefix = GetConfig().GetBech32AccountPubPrefix() case Bech32PubKeyTypeValPub: bech32Prefix = GetConfig().GetBech32ValidatorPubPrefix() case Bech32PubKeyTypeConsPub: bech32Prefix = GetConfig().GetBech32ConsensusPubPrefix() } // This piece of code is to keep backwards-compatibility. // For ed25519 keys, our own ed25519 is registered in Amino under a // different name than TM's ed25519. But since users are already using // TM's ed25519 bech32 encoding, we explicitly say to bech32-encode our own // ed25519 the same way as TM's ed25519. // TODO: Remove Bech32ifyPubKey and all usages (cosmos/cosmos-sdk/issues/#7357) pkToMarshal := pubkey if ed25519Pk, ok := pubkey.(*ed25519.PubKey); ok { pkToMarshal = ed25519Pk.AsTmPubKey() } return bech32.ConvertAndEncode(bech32Prefix, legacy.Cdc.MustMarshalBinaryBare(pkToMarshal)) } // MustBech32ifyPubKey calls Bech32ifyPubKey except it panics on error. func MustBech32ifyPubKey(pkt Bech32PubKeyType, pubkey crypto.PubKey) string { res, err := Bech32ifyPubKey(pkt, pubkey) if err != nil { panic(err) } return res } // GetPubKeyFromBech32 returns a PublicKey from a bech32-encoded PublicKey with // a given key type. func GetPubKeyFromBech32(pkt Bech32PubKeyType, pubkeyStr string) (crypto.PubKey, error) { var bech32Prefix string switch pkt { case Bech32PubKeyTypeAccPub: bech32Prefix = GetConfig().GetBech32AccountPubPrefix() case Bech32PubKeyTypeValPub: bech32Prefix = GetConfig().GetBech32ValidatorPubPrefix() case Bech32PubKeyTypeConsPub: bech32Prefix = GetConfig().GetBech32ConsensusPubPrefix() } bz, err := GetFromBech32(pubkeyStr, bech32Prefix) if err != nil { return nil, err } aminoPk, err := cryptocodec.PubKeyFromBytes(bz) if err != nil { return nil, err } var protoPk crypto.PubKey switch aminoPk.(type) { // We are bech32ifying some secp256k1 keys in tests. case *secp256k1.PubKey: protoPk = aminoPk case *ed25519.PubKey: protoPk = aminoPk // Real-life case. case tmed25519.PubKey: protoPk = &ed25519.PubKey{ Key: aminoPk.Bytes(), } default: // We only allow ed25519 pubkeys to be bech32-ed right now. return nil, sdkerrors.Wrapf(sdkerrors.ErrInvalidType, "bech32 pubkey does not support %T", aminoPk) } return protoPk, nil } // MustGetPubKeyFromBech32 calls GetPubKeyFromBech32 except it panics on error. func MustGetPubKeyFromBech32(pkt Bech32PubKeyType, pubkeyStr string) crypto.PubKey { res, err := GetPubKeyFromBech32(pkt, pubkeyStr) if err != nil { panic(err) } return res } // GetFromBech32 decodes a bytestring from a Bech32 encoded string. func GetFromBech32(bech32str, prefix string) ([]byte, error) { if len(bech32str) == 0 { return nil, errors.New("decoding Bech32 address failed: must provide an address") } hrp, bz, err := bech32.DecodeAndConvert(bech32str) if err != nil { return nil, err } if hrp != prefix {

# Addresses

The Cosmos SDK comes by default with 3 types of addresses:

  • AccAddress for accounts.
  • ValAddress for validator operators.
  • ConsAddress for 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 Pubkey pub:

Copy aa := sdk.AccAddress(pub.Address().Bytes())

These addresses implement the Address interface:

Copy Bech32PrefixConsPub = Bech32MainPrefix + PrefixValidator + PrefixConsensus + PrefixPublic ) // Address is a common interface for different types of addresses used by the SDK type Address interface { Equals(Address) bool Empty() bool Marshal() ([]byte, error) MarshalJSON() ([]byte, error) Bytes() []byte

Of note, the Marshal() and 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:

Copy return aa } // String implements the Stringer interface. func (aa AccAddress) String() string { if aa.Empty() { return "" } bech32PrefixAccAddr := GetConfig().GetBech32AccountAddrPrefix() bech32Addr, err := bech32.ConvertAndEncode(bech32PrefixAccAddr, aa.Bytes()) if err != nil { panic(err) }

# Next

Learn about gas and fees