Keyring Setup
The keyring is the local key storage system used by monod for signing transactions. It stores private keys and provides access to them through different security backends.
Backends
Monolythium supports three keyring backends, each with different security trade-offs:
| Backend | Flag | Storage | Encryption | Best For |
|---|---|---|---|---|
test | --keyring-backend test | ~/.mono/keyring-test/ | None | Local development, CI |
file | --keyring-backend file | ~/.mono/keyring-file/ | Password-encrypted (AES-256) | Servers, automation |
os | --keyring-backend os | System keychain | OS-level encryption | Desktop workstations |
test
Stores keys in plaintext. No password required for any operation.
# No password prompts
monod keys add devkey --keyring-backend test
monod tx bank send devkey mono1... 1000000000000000000alyth \
--keyring-backend test --yes
The test backend stores keys unencrypted on disk. Anyone with filesystem access can read your private keys. Only use this for local development and throwaway accounts.
file
Keys are encrypted with a password using AES-256. The password is prompted on every signing operation.
# Password prompted on creation
monod keys add mykey --keyring-backend file
# Password prompted on every transaction
monod tx bank send mykey mono1... 1000000000000000000alyth \
--keyring-backend file --yes
For automated scripts, pipe the password via stdin:
echo "your-password" | monod tx bank send mykey mono1... 1000000000000000000alyth \
--keyring-backend file --yes
The file backend is recommended for server environments where you need automation but want encrypted key storage. Store the keyring password securely (e.g., environment variable, secrets manager).
os
Uses the operating system's native credential store:
| OS | Credential Store |
|---|---|
| macOS | Keychain |
| Linux | libsecret (GNOME Keyring, KWallet) |
| Windows | Windows Credential Manager |
# Uses OS keychain — may prompt for system password
monod keys add mykey --keyring-backend os
On Linux, the os backend requires libsecret and a running secret service (e.g., GNOME Keyring). Install with: sudo apt install libsecret-1-dev.
Creating Keys
Generate a New Key
monod keys add mykey --keyring-backend file
Output:
- address: mono1abc123def456...
name: mykey
pubkey: '{"@type":"/ethermint.crypto.v1.ethsecp256k1.PubKey","key":"..."}'
type: local
**Important** write this mnemonic phrase in a safe place.
It is the only way to recover your account if you ever forget your password.
word1 word2 word3 ... word24
The 24-word mnemonic is the only way to recover your key. Write it down and store it securely offline. It is displayed once and cannot be retrieved again.
Generate with a Specific HD Path
# Default (coin type 60, Ethereum-compatible)
monod keys add mykey --keyring-backend file
# Explicit HD path (useful for verifying derivation)
monod keys add mykey --keyring-backend file \
--hd-path "m/44'/60'/0'/0/0"
# Alternative account index
monod keys add mykey-2 --keyring-backend file \
--hd-path "m/44'/60'/0'/0/1"
Recovering from Mnemonic
monod keys add recovered-key --recover --keyring-backend file
You will be prompted to enter the 24-word mnemonic. The same mnemonic with the same HD path always produces the same key.
# Recover with explicit HD path
monod keys add recovered-key --recover --keyring-backend file \
--hd-path "m/44'/60'/0'/0/0"
Listing Keys
# List all keys
monod keys list --keyring-backend file
# Show a specific key with address
monod keys show mykey --keyring-backend file
# Show only the address
monod keys show mykey -a --keyring-backend file
# Show the public key
monod keys show mykey --pubkey --keyring-backend file
# Show the Bech32 validator operator address
monod keys show mykey --bech val --keyring-backend file
Exporting and Importing Keys
Export (Encrypted)
# Export as encrypted armor (prompts for export password)
monod keys export mykey --keyring-backend file
Import
# Import from encrypted armor
monod keys import imported-key keyfile.armor --keyring-backend file
Export Private Key (Unencrypted)
# Export raw hex private key (use with extreme caution)
monod keys unsafe-export-eth-key mykey --keyring-backend file
unsafe-export-eth-key outputs the raw private key in hex. This is the same key used by MetaMask and other EVM wallets. Handle with extreme care and never log or share it.
Deleting Keys
# Delete a key (prompts for confirmation)
monod keys delete mykey --keyring-backend file
# Force delete without confirmation
monod keys delete mykey --keyring-backend file --yes
Security Comparison
| Aspect | test | file | os |
|---|---|---|---|
| Key encryption | None | AES-256 (password) | OS-native |
| Password per sign | No | Yes | OS-dependent |
| Filesystem readable | Yes | Encrypted blob | OS-managed |
| Automation friendly | Best | Good (pipe password) | Limited |
| Suitable for production | Never | Yes (with strong password) | Yes (desktop) |
| Multi-user safe | No | Yes | Yes |
Setting a Default Backend
To avoid passing --keyring-backend on every command, set it in your shell profile:
# Add to ~/.bashrc or ~/.zshrc
export MONOD_KEYRING_BACKEND=file
Or configure it in the client config:
monod config keyring-backend file
This writes to ~/.mono/config/client.toml:
keyring-backend = "file"
Migrating Between Backends
To move keys from one backend to another:
# 1. Export from the source backend
monod keys export mykey --keyring-backend test > mykey.armor
# 2. Import into the destination backend
monod keys import mykey mykey.armor --keyring-backend file
# 3. Verify
monod keys show mykey -a --keyring-backend file
# 4. Delete from old backend (optional)
monod keys delete mykey --keyring-backend test --yes
# 5. Clean up the export file
rm mykey.armor
Related
- Account Model -- Key derivation, coin type 60, dual addresses
- Security Guide -- Production key management and server hardening
- Wallets -- GUI wallet options
- KMS -- Hardware security module setup for validators