Create, import, export and delete keys using the CLI keyring
The keyring holds the private/public keypairs used to interact with the node. For instance, a validator key needs to be set up before running the node, so that blocks can be correctly signed. The private key can be stored in different locations, called "backends", such as a file or the operating system's own key storage.
# Add keys
You can use the following commands for help with the
keys command and for more information about a particular subcommand, respectively:
To create a new key in the keyring, run the
add subcommand with a
<key_name> argument. You will have to provide a password for the newly generated key. This key will be used in the next section.
This command generates a new 24-word mnemonic phrase, persists it to the relevant backend, and outputs information about the keypair. If this keypair will be used to hold value-bearing tokens, be sure to write down the mnemonic phrase somewhere safe!
By default, the keyring generates a
eth_secp256k1 key. The keyring also supports
ed25519 keys, which may be created by passing the
--algo flag. A keyring can of course hold both types of keys simultaneously.
Note: The Ethereum address associated with a public key can be derived by taking the full Ethereum public key of type
eth_secp256k1, computing the
Keccak-256 hash, and truncating the first twelve bytes.
secp256k1 keys are not supported on Evmos due to compatibility issues with Ethereum transactions.
# Keyring Backends
os is the default option since operating system's default credentials managers are
designed to meet users' most common needs and provide them with a comfortable
experience without compromising on security.
os backend relies on operating system-specific defaults to handle key storage
securely. Typically, an operating system's credential sub-system handles password prompts,
private keys storage, and user sessions according to the user's password policies. Here
is a list of the most popular operating systems and their respective passwords manager:
- macOS (since Mac OS 8.6): Keychain (opens new window)
- Windows: Credentials Management API (opens new window)
GNU/Linux distributions that use GNOME as default desktop environment typically come with
Seahorse (opens new window). Users of KDE based distributions are
commonly provided with KDE Wallet Manager (opens new window).
Whilst the former is in fact a
libsecret convenient frontend, the latter is a
The recommended backends for headless environments are
file stores the keyring encrypted within the app's configuration directory. This
keyring will request a password each time it is accessed, which may occur multiple
times in a single command resulting in repeated password prompts. If using bash scripts
to execute commands using the
file option you may want to utilize the following format
for multiple prompts:
The first time you add a key to an empty keyring, you will be prompted to type the password twice.
# Password Store
pass backend uses the pass (opens new window) utility to manage on-disk
encryption of keys' sensitive data and metadata. Keys are stored inside
gpg encrypted files
within app-specific directories.
pass is available for the most popular UNIX
operating systems as well as GNU/Linux distributions. Please refer to its manual page for
information on how to download and install it.
pass uses GnuPG (opens new window) for encryption.
gpg automatically invokes the
daemon upon execution, which handles the caching of GnuPG credentials. Please refer to
man page for more information on how to configure cache parameters such as credentials TTL and
The password store must be set up prior to first use:
<GPG_KEY_ID> with your GPG key ID. You can use your personal GPG key or an alternative
one you may want to use specifically to encrypt the password store.
# KDE Wallet Manager
kwallet backend uses
KDE Wallet Manager, which comes installed by default on the
GNU/Linux distributions that ships KDE as default desktop environment. Please refer to
KWallet Handbook (opens new window) for more
test backend is a password-less variation of the
file backend. Keys are stored
unencrypted on disk. This keyring is provided for testing purposes only. Use at your own risk!
🚨 DANGER: Never create your mainnet validator keys using a
test keying backend. Doing so might result in a loss of funds by making your funds remotely accessible via the
eth_sendTransaction JSON-RPC endpoint.
# In Memory
memory backend stores keys in memory. The keys are immediately deleted after the program has exited.
IMPORTANT: Provided for testing purposes only. The
memory backend is not recommended for use in production environments. Use at your own risk!