Skip to content

Keyring Keyring

Create, import, export, and delete keys using the CLI keyring.

The keyring holds private/public key pairs used to interact with nodes. For example, a validator key needs to be set up before running a node so that blocks can be properly signed. Private keys can be stored in various locations, called "backends", such as files or the operating system's own keystore.

📣 Tips: If you need a refresher on private keys and key management, please refer to our Key Management.

Add key

You can get help on the keys command and more information on specific subcommands using the following command, respectively:

stcd keys

stcd keys [command] --help

To create a new key in the keyring, run the add subcommand with the <key_name> argument. You will have to provide a password for newly generated keys. This key will be used in the next section.

stcd keys add dev0

# Put the generated address in a variable for later use.
MY_VALIDATOR_ADDRESS=$(stcd keys show dev0 -a)

This command generates a new 24-word mnemonic, persists it to the relevant backend, and outputs information about the key pair. If this key pair will be used to hold valuable tokens, be sure to write the seed phrase in a safe place!

By default, keyring generates an eth_secp256k1 key. Keyring also supports ed25519 keys, which can be created by passing the --algo flag. A key ring can of course hold both types of keys.

📣 Tip: The Ethereum address associated with the 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.

🚨 DANGER: Daodst does not support Cosmos secp256k1 keys due to compatibility issues with Ethereum transactions.

Keyring backend

OS

📣 Tips: os is the default option because the operating system's default credential manager is designed to meet the most common needs of users and provide them with a comfortable experience without compromising security.

The os backend relies on OS-specific defaults to handle key storage securely. Typically, the operating system's credential subsystem handles password prompting, private key storage, and user sessions according to the user's password policy. Below is a list of the most popular operating systems and their respective password managers:

GNU/Linux distributions that use GNOME as their default desktop environment usually come with Seahorse. Users of KDE-based distributions usually get the KDE Wallet Manager. The former is actually a convenient libsecret front-end, while the latter is a kwallet client.

The recommended backends for headless environments are file and pass.

File

file stores the encrypted keyring in the application's configuration directory. The password is requested every time this keyring is accessed, which may occur multiple times in a single command, resulting in repeated password prompts. If using a bash script to execute commands via the file option, you may wish to use the following format for multiple prompts:

# assuming that KEYPASSWD is set in the environment
yes $KEYPASSWD | stcd keys add me
yes $KEYPASSWD | stcd keys show me
# start stcd with keyring-backend flag
stcd --keyring-backend=file start

📣 Tip: The first time you add a key to an empty keyring, you will be prompted for the passphrase twice.

Pass

The pass backend uses the pass utility to manage disk encryption of sensitive data and metadata for keys. Keys are stored in "gpg" encrypted files in application-specific directories. pass is available for most popular UNIX operating systems as well as GNU/Linux distributions. See its man page for how to download and install it.

📣 Hint: pass uses GnuPG for encryption. gpg automatically invokes the gpg-agent daemon upon execution, which handles the caching of GnuPG credentials. See the gpg-agent man page for more information on how to configure caching parameters such as credential TTL and password expiration.

Password storage must be set up before first use:

pass init <GPG_KEY_ID>

Replace <GPG_KEY_ID> with your GPG key ID. You can use your personal GPG key or an alternative key that you might want to use specifically to encrypt password storage.

Kwallet

The kwallet backend uses KDE Wallet Manager, which is installed by default on GNU/Linux distributions with KDE as the default desktop environment. For more information, please refer to KWallet Manual.

Testing

The test backend is a passwordless variant of the file backend. Keys are stored on disk in unencrypted form. This keyring is for testing purposes only. Use at your own risk!

🚨 DANGER: NEVER use the test keying backend to create your mainnet validator keys. Doing so may result in Remote access to your funds through the eth_sendTransaction JSON-RPC endpoint, resulting in loss of funds.

Memory

The memory backend stores keys in memory. The key will be deleted immediately after the program exits.

🚨 DANGER: For testing purposes only. The memory backend is NOT recommended for production use. Use at your own risk!