Managing accounts

On this page, you’ll learn how to manage your account directly from the command-line with the CLI of a Lisk 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

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

Table of Contents

Overview of the account credentials
Key pair and address creation
Managing multiple accounts with a single passphrase
Account initialization
- User Substore
Account address formats
- Hexadecimal representation
- Lisk32 representation
Key Management

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`	lsk7dqp2w7447pqhuzmhx 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, Lisk 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 Lisk 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

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^32. 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^31, 134+2^31, 2^31].

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:

Lisk Core
Lisk app

lisk-core console

./bin/run console

Generate a new mnemonic passphrase using the Lisk Passphrase library:

 > lisk.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.

Lisk Core
Lisk app

lisk-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": "lsk7dqp2w7447pqhuzmhxsxr65qeoq7nbfox28wxc",
      "keyPath": "m/44'/134'/0'",
      "publicKey": "0ca6a5d44cc366de186a2589e3e51849272fa0ae9c52646766ddb7820dfe770c",
      "privateKey": "bd7e42529df375cb9133ddf299641d38975fa4d0930eff6e7c072d4d3ff190830ca6a5d44cc366de186a2589e3e51849272fa0ae9c52646766ddb7820dfe770c",
      "plain": {
        "generatorKeyPath": "m/25519'/134'/0'/0'",
        "generatorKey": "e59f2f603b84b9c491e267240a3425a09adaad348b984cc6e21c14fd02f28e7e",
        "generatorPrivateKey": "398a04e2a001dc4580bb1fab2c6e71dbbbd81c9f22170e1073cd4084d81588f4e59f2f603b84b9c491e267240a3425a09adaad348b984cc6e21c14fd02f28e7e",
        "blsKeyPath": "m/12381/134/0/0",
        "blsKey": "95c7a571ecf569f91f6995f9a8d8a2e70904cb079350372b66d8a2b6986788f6d4589c79fffefd952debc96a17317e18",
        "blsProofOfPossession": "a02f2672621b3adcd25079c6646e751517c514c70d11ec4ec4846310f5f7cddedd598ade849496bcfe15d3baa554d06b148a2e9f2d349e2010df2a17d7a3d57f13ab9bf290042c552d47d925c0877596ca8865b96ba2972eea5ce7831b014cca",
        "blsPrivateKey": "4ce94d4439152ec5e0ae88a5c77c12cf0b5d9304111359c5f42b490503429c26"
      },
      "encrypted": {
        "ciphertext": "5cc26d74c2b6ed7d56a1268eb04cd3878190695bd2546bca82885cc5d7171d71e397cab265544436d9feadd143e17deeeb5f32a00e6d6cf8d0e64afc5475067875a6836a5c7f78d3e0b4937c464817f40359c869bd0b01762a18169296774d1c76821a752e53dc96390c27a15ba8b1b3eef7016335dabcef424ed0dd3bf972f89451d2ea8db113b310e9ecda7ea3a044c68e4dc57f8c992e84729c62f952c7c24688f375b39311ef069d8a2ccde6c272ce65645839da3dfb",
        "mac": "ebdb87bb0be482ea6ec867bb3355d3c9aece28520d56d7b1c17463dc06e1eb97",
        "kdf": "argon2id",
        "kdfparams": {
          "parallelism": 4,
          "iterations": 1,
          "memorySize": 2024,
          "salt": "63092ee970b05d28017a606c39ff799b"
        },
        "cipher": "aes-256-gcm",
        "cipherparams": {
          "iv": "1a188eb0d5eab9eca50b7b3c",
          "tag": "2578354b532bec4485eeb7123c27f855"
        },
        "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.

Lisk Core
Lisk app

lisk-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 Lisk Mainnet, the account initialization fee is 0.05 LSK.

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
                    }
                }
            }
        }
    }
}

Account address formats

The account address can be displayed in different formats, depending on the context.

Hexadecimal representation

The hexadecimal representation of the address is directly derived from the first 20 bytes of the public key. The address in hex format is often used internally as a parameter.

Hex-format address example

0xc247a42e09e6aafd818821f75b2f5b0de47c8235

Hex address computation

To compute the address in hex format, the following information is required:

account public key, e.g. 0x0eb0a6d7b862dc35c856c02c47fde3b4f60f2f3571a888b9a8ca7540c6793243

First, create the SHA-236 hash of the public key:

SHA-256(pubkey) = 0xc247a42e09e6aafd818821f75b2f5b0de47c8235b580881bd7750c9365993d25

To get the address, take the first 160 bits of the hash:

address = 0xc247a42e09e6aafd818821f75b2f5b0de47c8235

Lisk32 representation

The Lisk32 address representation provides a user-friendly address format for frontends.

Each address starts with the prefix “lsk" and a checksum is appended.

Lisk32 address example

lsk24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu

The Lisk32 representation displays addresses as a checksum with the "lsk" prefix to prevent accidental typing mistakes.

Lisk32 address computation

The procedure to obtain the Lisk32 representation of a Hexadecimal representation of an address is as follows:

The hex address is used to create a 30-bit checksum of the address, using a BCH code^[1]. This step provides protection against accidental typing mistakes.
Concatenate the address and the output of step 1.
Encode the output of step 2 in a custom Base32 format, see LIP 0018 for details. Lower-case letters and digits are used, and to improve usability the characters i, l, 1 and 0 have been excluded.
Add the prefix "lsk" to the output of step 3.

The Lisk32 representation always starts with "lsk" and the final address consists of an amount of 41 characters.

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.

1. See BIP173