Managing accounts

On this page, you’ll learn how to manage your account directly from the command-line with the CLI of a Klayr node.

Specifically, the following topics below will be covered in detail:

The different credentials for an account
How to create new account credentials
How to create multiple accounts with a single passphrase
How a new account is initialized on the blockchain
Methods used for managing account credentials
Klayr wallet passphrase and security

If you prefer a graphical user interface to manage your account, it is possible to use supported wallets such as Klayr Wallet.

Table of Contents

Overview of the account credentials
- Passphrases
Key pair and address creation
Managing multiple accounts with a single passphrase
Account initialization
- User Substore
Klayr32 address format
Key Management
Klayr wallet passphrase and security best practices
- Security best practices

Overview of the account credentials

Table 1. General account credentials
Name	Example	Description
`passphrase`	"anger system news one finger rifle kiss expect arena swift spirit decline"	Human-readable representation of the `privateKey`. A 12 word mnemonic passphrase. Together with the `keyPath`, it identifies an account on the blockchain.
`keyPath`	"m/44'/134'/0'"	Key derivation allows multiple key pairs to be derived from the same passphrase.
`address`	kly7dqp2w7447pqhuzmhx sxr65qeoq7nbfox28wxc	The address is the main public identifier of the account and the human-readable representation of the `publicKey`. Depending on the context, the address is represented in different formats.
`publicKey`	0ca6a5d44cc366de186a2589e3e51849272fa0ae9c52646766ddb7820dfe770c	A Ed25519 public key. The public identifier of the account. Derived from the `passphrase`, together with the `keyPath`. The first part of the public key is used to derive the `address` for an account.
`privateKey`	bd7e42529df375cb9133ddf299641d38975fa4d0930eff6e7c072d4d3ff190830ca6a5d44cc366de186a2589e3e51849272fa0ae9c52646766ddb7820dfe770c	Ed25519 private key The private identifier of the account. Derived from the `passphrase`, together with the `keyPath`.

Table 2. Credentials required for block generation
`generatorKeyPath`	"m/25519'/134'/0'/0'"	The derivation path for the [generator-keys].
`generatorKey`	e59f2f603b84b9cd91e2 67240a342ba09adaad348e b984cc6e21c14fd02f28e7	The public generator key. An extra Ed25519 key pair, the generator keys, is added to a validator account to sign blocks. A validator node only requires access to the private generator key, but not to the private key that is used for signing transactions. This mitigates the risk, whereby an attacker could acquire the encrypted passphrase and the password used for encryption, and gain full control over the validator account.
`generatorPrivateKey`	398a04e2a001dc4580bb1 fab2c6e71dbbbd81c9f221 70eb073cd4084dd15884fe 59f2f603b84bac491e2672 40a3425a09adaad348b984 cc6e21c14fd02f28e7e	The private generator key.
`blsKeyPath`	"m/12381/134/0/0"	Similarly to the specifications of EIP 2334, Klayr uses the path `m/12381/134/chainIDConverted/0` for the BLS key derived for a chain, where `chainIDConverted = bytesToUint(chainID)`.
`blsKey`	95c7a571ecf569f91fc99 5f9a8dba2e70904cb0793 50372bc6d8a2b698678af 6d4589ca9fffefd952deb c96a17317e18	The public BLS key. An extra key pair, the BLS keys, is added to a validator account, following the key derivation method described in EIP 2333. BLS keys are used by validators to create aggregated signatures for commits in Klayr blockchains, among other functions.
`blsProofOfPossession`	a02f2672621b3adcd2507 9c6646e751517c514c70d 11ec4ec4846310f5f7cdd edd598ade849496bcfe15 d3baa554d06b148a2e9f2 d349e2010df2a17d7a3d5 7f13ab9bf290042c552d4a 7d925c0877596ca8865b9c 6ba2972eea5ce7831b014c	The proof that a validator owns the private key for the corresponding BLS public key. The proof-of-possession is important to prevent "rogue key" attacks, whereby attackers forge aggregate signatures on behalf of other participants.
`blsPrivateKey`	4ce94dc439152ec5e0ae8 8a5cd7c12cf0b5d930411 135dc5f42b49050342ac26	The private BLS key

Passphrases

As previously discussed, Klayr accounts employ a 12-word Mnemonic Passphrase to ensure robust security. It is a sequence of carefully chosen words that acts as a human-readable representation of a complex cryptographic key, as in the example displayed in the Creating a new passphrase section. This passphrase is indispensable for accessing any Klayr wallet and conducting transactions from your account.

Using a 12-word seed phrase encompasses 128 bits of entropy, a metric that gauges the level of unpredictability or randomness in the data employed for generating the phrase. This is due to the fact that each term within the BIP 39 mnemonic phrase embodies 11 bits of entropy, resulting in a cumulative 132 bits for a 12-word sequence. This overall entropy amalgamates 128 bits of inherent entropy and an additional 4 bits designated for the checksum.

Nevertheless, the BIP39 seed phrase relies on a finite pool of 2,048 words, which in turn restricts the potential permutations that can be produced. Conversely, a 24-word seed phrase comprises 256 bits of entropy, as each term encapsulates 11 bits, culminating in a total of 264 bits, including the checksum.

The same rationale holds true for the 256 bits of entropy plus an extra 8 bits for the checksum. While a 12-word phrase offers greater memorability and ease of input, it concurrently becomes more susceptible to guessing or brute-force attacks by malicious actors.

Given the mere 128 bits of entropy, deciphering a 12-word seed phrase would necessitate significantly less time and resources compared to a 24-word counterpart with 256 bits of entropy. Nevertheless, even in the face of heightened susceptibility to guessing, the task of brute-forcing remains nearly insurmountable.

With 12 words offering a staggering 2¹²⁸ potential combinations, the probability of arriving at the correct combination is exceedingly remote.

Key pair and address creation

A private key is derived, as defined in RFC 8032, from a BIP 39 mnemonic passphrase and a Key Derivation path.

Figure 1. Generating multiple private keys from 1 passphrase with key derivation

Any of the child keys could be used to create a Ed25519 private key. However, by default only the child key at the end of the path is used to create the Ed25519 private key.

The corresponding public key can then be obtained following the key generation section of RFC 8032.

Finally, the address is generated by taking the first 20 bytes of the public key.

Key Derivation path

The key derivation path allows to derive a specific key from within a tree of keys.

The derivation path is an array of non-negative integers smaller than 2³². To make it easier to read a derivation path, they are often written in a form that omits a large constant. For example, the path 44'/134'/0' (notice the apostrophe after each number) represents the array [44+2³¹, 134+2³¹, 2³¹].

The whole derivation path is then written as m/44'/134'/0', indicating that we start by deriving a master key before deriving successive child keys.

Creating a new passphrase

A 12 word mnemonic passphrase is required as an input to generate all corresponding account credentials for an account.

You may choose the passphrase for yourself, or generate a new random passphrase.

The node CLI can be utilized to auto-generate the passphrase quickly from the command-line.

First, start the console:

Klayr Core
Klayr app

klayr-core console

./bin/run console

Generate a new mnemonic passphrase using the Klayr Passphrase library:

 > klayr.passphrase.Mnemonic.generateMnemonic()

This will return a randomly generated 12 word mnemonic passphrase.

'anger system news one finger rifle kiss expect arena swift spirit decline'

Creating the other credentials

Next, use the keys:create command to generate all relevant account credentials:

The creation of new account credentials always happens off-chain. To put the new account on-chain, it is necessary to initialize the new account by sending some initial tokens to the address and paying the account initialization fee.

Klayr Core
Klayr app

klayr-core keys:create

./bin/run keys:create

When asked for the passphrase, enter the passphrase previously created in the step Creating a new passphrase.

? Please enter passphrase:  [hidden]
? Please re-enter passphrase:  [hidden]

Next, you will be also asked for a password. This password will be used to encrypt your account credentials symmetrically.

The encrypted credentials are used for example in the config, when the node needs account information to generate new blocks for a validator.

If you do not wish to encrypt your credentials, it is possible to skip this step by adding the --no-encryption flag to the keys:create command.

The password will be required everytime the credentials need to be decrypted, for example when enabling block generation on a node. Hence, it is advisable to store and maintain the password in a secure location similar to the passphrase of the account.

? Please enter password:  [hidden]
? Please re-enter password:  [hidden]

This will then return the credentials for the account:

Example output

{
  "keys": [
    {
      "address": "klyp24b6ev62w67v8qvk8wnvkhh2gv3hcoohes5z3",
      "keyPath": "m/44'/134'/0'",
      "publicKey": "83eac294606806e0f4125203e2d0dac5ef1fc8730d5ec12e77e94f823f2262fa",
      "privateKey": "eafb0bc7f148e60f69fda52e0cc862071871bbfff884aad095ae84bdde8d298283eac294606806e0f4125203e2d0dac5ef1fc8730d5ec12e77e94f823f2262fa",
      "plain": {
        "generatorKeyPath": "m/25519'/134'/0'/0'",
        "generatorKey": "97fe3280b25ca122cf91eb891c157c939becd75a7fed394254b1005608c3bffc",
        "generatorPrivateKey": "67afd3d3eda7c060f8f4e19540a5416c2d29a6dc687b47a5bebcd41d9d0df1e897fe3280b25ca122cf91eb891c157c939becd75a7fed394254b1005608c3bffc",
        "blsKeyPath": "m/12381/134/0/0",
        "blsKey": "a3dcd6dedf3a0cf45608f9e1f3844e8b30c033c186851671ea1a655541b3fda482e4617f67367438012cf0855fadda13",
        "blsProofOfPossession": "954f4f6be134626367353d68cd19d00a3475dd0cb0961605ec925c659c581c0a91e6223715eba261cca817aca134078e014d1f340aac32e21038a861708e8b2c33190d0dc32902fde8b270490a7f81a8ea5736bfcaaaf502704f0d9573623dd3",
        "blsPrivateKey": "07dec698f9b62092196c15b8074dc6a0366722cd77b351f968b2291c1fbcc699"
      },
      "encrypted": {
        "ciphertext": "4e9c24db810fb641d9ad148e0a9c461db5c52b001592c910b2b11a4f4ce9bf271d530d2bfd9a6b50c59b09a4e872ef7a0ff65802e0bde6e685dd07db6b9b4f365b24af0488a5fdb3d4688b5c5a4ffbf302573a53219a1ec120bd1b1bc602e356bdb910ab7be245e7488409fc1ea059ffcb4382cfb309d5673a258cd2cf4114a39ffbb0097f3bef6985c45ea3ffbc2f7b793a2366d9e5921d3ba8490906a17bf458a85c19100834877fde498fc3165a02f68a72e1b6e8509f",
        "mac": "1730decdc41721e0156f9aaad0685b1a65c0edc56d653c0ae6266f08826b13f3",
        "kdf": "argon2id",
        "kdfparams": {
          "parallelism": 4,
          "iterations": 1,
          "memorySize": 2097023,
          "salt": "34ac1bfb751d5f78"
        },
        "cipher": "aes-128-gcm",
        "cipherparams": {
          "iv": "9c6903d0c6e6ab900e9389d8466dd8ff",
          "tag": "8e21a9239cb4d5855e54cf9da34bc5ce"
        },
        "version": "1"
      }
    }
  ]
}

Managing multiple accounts with a single passphrase

Key derivation allows multiple key pairs to be derived from the same secret passphrase as a tree of keys.

This ensures that a user can manage multiple different accounts with ease, as they are only required to remember a single passphrase.

To generate multiple accounts from the same passphrase, use the --count flag of the keys:create command, and set it to the number of accounts that you wish to create.

The key path for the new accounts will always start with the default key-derivation path and increment by +1 onwards. If you wish to start from a different key path, you can specify an --offset.

Klayr Core
Klayr app

klayr-core keys:create --passphrase your-passphrase --no-encrypt --count 2 --offset 1

./bin/run keys:create --passphrase your-passphrase --no-encrypt --count 2 --offset 1

The same passphrase is used for every account, the only change that will occur is the Key Derivation path, for example when signing transactions.

If a user uses the default key-derivation path m/44'/134'/0, it is not necessary to mention it as a parameter when the account credentials are requested.

If you are using a custom key-derivation path, make sure to always specify the key derivation path when providing the passphrase. For example, for the transaction:create command, the key derivation path can be specified as shown in the example snippet below:

./bin/run transaction:create hello createHello 10000000 --key-derivation-path="m/44'/134'/1'" --params='{"message":"Hello world!"}'

Account initialization

To create a new account in the blockchain network, it is necessary to initialize the account.

A new account is initialized by sending tokens to an address for the first time.

When tokens are sent to a new address, it is required to pay an account initialization fee.

In the Klayr Mainnet, the account initialization fee is 0.05 KLY.

The account initialization fee has to be paid on top of the other fees for a transaction, when tokens are sent to a new address for the first time.

Once the address has received its initial tokens, it is then saved in the user substore.

User Substore

The Token module features a user substore that comprises entries exclusively intended for storing user balances for a specific address and tokenID.

The user substore contains the following entries:

key: the concatenation of an address and a token ID: address + tokenID
value: the serialization of an object following the userStoreSchema.

userStoreSchema

{
    "type": "object",
    "required": ["availableBalance", "lockedBalances"],
    "properties": {
        "availableBalance": {
            "dataType": "uint64",
            "fieldNumber": 1
        },
        "lockedBalances": {
            "type": "array",
            "fieldNumber": 2,
            "items": {
                "type": "object",
                "required":[ "module", "amount" ],
                "properties": {
                    "module": {
                        "dataType": "string",
                        "minLength": MIN_MODULE_NAME_LENGTH,
                        "maxLength": MAX_MODULE_NAME_LENGTH,
                        "pattern": "^[a-zA-Z0-9]*$",
                        "fieldNumber": 1
                    },
                    "amount": {
                        "dataType": "uint64",
                        "fieldNumber": 2
                    }
                }
            }
        }
    }
}

Klayr32 address format

The Klayr32 representation displays addresses as a readable string with a checksum and the "kly" prefix. Klayr32 addresses always have a fix length of 41 characters.

Automatic detection of address typing errors

A BCH checksum is used for detection of small errors in the address. Any errors in up to 4 characters are guaranteed to be detected and errors in more than 5 characters are likely to be detected.

Klayr32 address example

kly24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu

To learn how the Klayr32 is derived from the public key, please go to Address Representation for User Interface Level (LIP 0018).

Key Management

There are two recommended ways to manage the account keys, depending on the use case:

Table 3. Account credentials
Key management method	Use Case
Using a secret passphrase	For users that need their key pair only on local machines, e.g., for signing transactions. It is necessary to securely store or remember a secret recovery phrase and password. However, it is not necessary to back up and store any encrypted data locally.
Storing the encrypted secret key	For users that solely require the key pair on a remote server, e.g., a validator node on a remote data center. Storing and backing up an encrypted file is necessary, but the user only needs to remember or securely store one password.

Klayr wallet passphrase and security best practices

Wallets play a crucial role, as they provide a secure means to store, send, and receive both KLY tokens and other tokens/coins. Wallets in general come in different forms, including a variety of software wallets, such as hot wallets, custodial/non-custodial, and web wallets; hardware wallets, and even paper wallets. They operate using a combination of public and private keys, ensuring the safety and authenticity of transactions on the Klayr blockchain. For a more in-depth overview regarding the wallets, see types of wallets.

Security best practices

Safeguarding this passphrase is of the utmost importance, and sharing it with others must be avoided at all costs. If unauthorized access to this passphrase occurs, it could lead to the theft of your funds. Regrettably, in such a scenario, the lost funds cannot be recovered.

To summarise, the optimal method for safeguarding your recovery seed involves storing it across multiple physical mediums, and placing these mediums in at least two distinct locations. Ideally, these physical storage methods should demonstrate resilience against harsh conditions such as water, fire, and other adverse factors. It’s crucial to ensure that these duplicates of your recovery seed remain concealed to prevent unintended discovery.

In the case whereby you suspect the security of your mnemonic phrase has been compromised, possibly due to a copy being discovered or stolen, it is prudent to swiftly transfer your funds to an entirely new wallet with a different recovery seed. Following this, take the time to assess your storage practices to prevent a recurrence of compromise.

As long as you retain your passphrase, your account access remains intact. Furthermore, please note that your passphrase can be used interchangeably within the Klayr ecosystem.