HD wallets - Cosmos Docs

This page is for anyone creating or recovering a Cosmos Hub wallet key with gaiad keys (gaiad reference), Keplr, or a Ledger. It explains how a hierarchical deterministic (HD) wallet yields many addresses from one phrase, and which flags pick them. With that, a recovered wallet produces the expected address.

Terms

Five terms cover everything on this page. The mnemonic is the one that matters most, because it reproduces all the others.

Mnemonic (seed phrase): 24 words from which every key in the wallet is derived. It is the wallet. Everything else can be recomputed from it.
Private key: the secret that signs transactions for one account. Derived from the mnemonic and a path.
Public key: computed from the private key with a one way function. The chain stores it after the account’s first signed transaction.
Address: a hash of the public key, shown with a readable prefix (cosmos1...). The same key also has cosmosvaloper1... and cosmosvalcons1... encodings, which are prefixes, not separate keys.
Account (in HD terms): one private key, public key, and address derived from the mnemonic at one path.

Each step is one way. The mnemonic produces the private key, the private key produces the public key, and the public key produces the address. None of these steps can be reversed.

   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
       ^                    ^                    ^
       +--------------------+--------------------+
                            |
                     Mnemonic (seed)

The derivation path

Cosmos wallets follow BIP-32 and BIP-44 (Bitcoin Improvement Proposals 32 and 44). The path gaiad uses by default is:

m/44'/118'/0'/0/0

The first element, 44', marks BIP-44. The second, 118', is the coin type registered for Cosmos. The third number is the account, the fourth is the change field (always 0 for Cosmos), and the last is the address index. Changing the account or the index gives a different, unrelated address from the same mnemonic. The same path always gives the same address, which is what makes recovery possible.

gaiad keys add mykey
gaiad keys add mykey-1 --recover --index 1
gaiad keys add mykey-acct1 --recover --account 1
gaiad keys add mykey-custom --recover --hd-path "m/44'/118'/0'/0/5"

The first command creates a new mnemonic. The others use --recover and prompt for one. Enter the same words each time to derive more addresses from that mnemonic. Without --recover, every keys add generates a fresh, unrelated mnemonic. The --account and --index flags set the third and fifth path elements. The --hd-path flag sets the whole path and overrides both. The --coin-type flag (default 118) changes the second element. Both --index 1 and --hd-path "m/44'/118'/0'/0/1" produce the same address. Keplr and Ledger use the same path, so a key created in one tool recovers in another as long as the path matches. Add --dry-run to see the address a path would produce without saving the key.

Recover a wallet

gaiad keys add mykey --recover

The --recover flag prompts for the mnemonic and derives the key at the default path. If the resulting address is not the one expected, the original key was created at another index or account. Retry with --index or --account until the address matches, or check the expected address in the explorer first. Recovery writes the private key into the keyring selected by --keyring-backend (Keyring), so recover on a trusted machine only.

Keep offline copies of the 24 words in more than one safe place. Never type the words into a web page. Never store them next to the keyring they recover. Anyone with the words controls every account derived from them, on every chain that uses the same coin type.

What the mnemonic does not cover

A validator’s consensus key (priv_validator_key.json) and node key (node_key.json) are ed25519 keys generated by gaiad init, not derived from a mnemonic. Back up those files separately (Validator setup). Multisig entries in the keyring are combinations of public keys. They are rebuilt from the member keys, not from a phrase. A Ledger key’s mnemonic is stored on the device (Ledger).

Verify

gaiad keys add check --dry-run --recover --index 0
gaiad keys add check --dry-run --recover --index 1

Both prompts accept the same mnemonic and print different addresses. Repeating either command prints the same address again, which confirms the derivation is deterministic. Nothing is saved with --dry-run.

gaiad reference for the full keys command set and keyring backends.
Ledger for keys that never leave a hardware device.
Delegator security for how to store the phrase and spot phishing.

​Terms

​The derivation path

​Recover a wallet

​What the mnemonic does not cover

​Verify

​Next

Terms

The derivation path

Recover a wallet

What the mnemonic does not cover

Verify

Next