Skip to main content

Keys & accounts

Overview​

An account in the Cosmos SDK, consists of a pair of a public key PubKey and a private key PrivKey. The PubKey can be used to generate various Addresses, which identify users and other parties in the application and are associated with messages to identify the sender. The PrivKey is used to generate digital signatures to prove that an Address associated with the PrivKey has approved a specific message.

KIRA accounts only exist on the blockchain if they have a non-zero balance. This is a feature of the Cosmos SDK that helps prevent the creation of "spam" accounts that do not hold any value. All KIRA addresses are 44 characters long and are Bech32 encoded with a kira prefix (e.g. kira1d52rts8wf508uy2sdcx4a0qxjzvqr3dsnesm4w). These accounts are derived from BIP39 mnemonic words, which must be kept safe by the account holder at all times. Losing access to the mnemonic or revealing its contents will result in permanent and irrecoverable loss of funds.

KIRA network defines 3 types of addresses that specify a context where an account is used:

  • AccAddress identifies users (the sender of a message).
  • ValAddress identifies consensus node operators (a.k.a validators).
  • ConsAddress identifies consensus nodes that are participating in consensus. Consensus nodes are derived using the ed25519 curve.

Keyring​

Like in every Cosmos-based network, Private/Public keys are stored and managed by using an object called a Keyring which default implementation comes from the third-party 99designs/keyring library. The private key can be stored in different "backends", such as a file or the operating system's own key storage system. The keyring allows users to manage their keys in a secure and convenient way, and can be integrated with various backend storage options to suit the needs of the user. These backends can be specified in the CLI using the --keyring-backend flag (cf. ).

  • The os backend: This backend relies on operating system-specific defaults to handle key storage securely. It is the default option and is designed to meet users' most common needs and provide a comfortable experience without compromising on security.
  • The file backend: This backend stores the keyring encrypted within the app's configuration directory. It requires a password each time it is accessed, which may result in multiple prompts.
  • The pass backend: This backend uses the pass utility to manage on-disk encryption of keys' sensitive data and metadata. Keys are stored inside gpg encrypted files within app-specific directories.
  • The kwallet backend: This backend uses KDE Wallet Manager, which comes installed by default on the GNU/Linux distributions that ships KDE as default desktop environment.
  • The test backend: This backend is a password-less variation of the file backend and is provided for testing purposes only. It stores keys unencrypted on disk and is not recommended for use in production environments.
  • The memory backend: This backend stores keys in memory, which are immediately deleted after the program has exited. It is provided for testing purposes only and is not recommended for use in production environments.

CLI Syntax & Examples​

note

Each CLI command and proposal process in KIRA requires specific permissions. These permissions must be added to the account's whitelist or obtained as sudo permissions for direct changes. Refer to the Roles & Permissions documentation for more details.

note

$SIGNER represents the transaction signer's account name or address. For instructions on setting common flags as environment variables, such as $FLAGS_TX and $FLAGS_QR, see the CLI Guide page.

Transactions​

keys addAdd or recover an encrypted private key.
keys deleteDelete a key from the keyring.
keys recoverRecover a key using a mnemonic.

Creating an Account​

To create a new key in the keyring, use the add subcommand and provide the desired account key name as an argument. You can also specify the keyring backend to use by setting the $FLAGS_TX environment variable or by manually using the --keyring-backend flag. This is important as it determines where the private/public keypair will be stored and how it will be managed. A --multisig flag can also be provided to group multiple keys together to create a multisig key.

Flags

  • $MULTISIG: List of key names for constructing a legacy multisig key.
  • $MULTISIGTHRESHOLD: K out of N required signatures for multisig.
  • $NOSORT: Keys are taken in the order supplied if true.
  • $PUBLICKEY: Saves key info to file from a JSON format public key.
  • $INTERACTIVE: Interactively prompt for BIP39 passphrase and mnemonic.
  • $USELEDGER: Store a reference to a private key on a Ledger device.
  • $RECOVER: Recover an existing key using a seed phrase.
  • $NOBACKUP: Don't print out the seed phrase.
  • $DRYRUN: Perform action without adding key to local keystore.
  • $HDPATH: Manual HD Path derivation.
  • $COINTYPE: Coin type number for HD derivation.
  • $ACCOUNT: Account number for HD derivation.
  • $INDEX: Address index number for HD derivation.
  • $KEYALGORITHM: Key signing algorithm for generating keys.
  • $ACCOUNT_NAME: The account key name.
sekaid keys add $ACCOUNT_NAME $FLAGS_TX

Deleting an Account​

To delete a key from the keyring, use the delete subcommand and provide the desired account key address as an argument and specify the keyring backend to delete from by setting the $FLAGS_TX environment variable or by manually using the --keyring-backend flag. --force flag can be specified to skip passphrase check and force key deletion unconditionally.

note

Removing offline or ledger keys will remove only the public key references stored locally, i.e. private keys stored in a ledger device cannot be deleted with the CLI.

Flags

  • $YES: Skip confirmation prompt when deleting keys.
  • $FORCE: Remove the key unconditionally without asking for the passphrase.
sekaid keys delete $ACCOUNT_NAME $FLAGS_TX --force --yes

Recovering an Account Using Mnemonic​

To recover an account using its respective mnemonic, use the add subcommand with the —recover flag and provide the desired account key name as an argument.

Args

  • $ACCOUNT_MNEMONIC: The account’s mnemonic.
yes "$ACCOUNT_MNEMONIC" | sekaid keys add $ACCOUNT_NAME $FLAGS_TX --recover