Wallet basics

Introduction

Wallets enable you to store your credits and transaction on the chain. It provides you an address for others to send you credits, allows you to sign transactions to transfer credit to others, and check you account credit balance.

New wallet

Let's create you a wallet. Make sure you are in the shell. Firstly, you can check all the available saved by running listWallets.

Wallet list
None

As of now, you do not have any saved wallets yet, so we'll create one.

$ createWallet label:"My first wallet"

Type in the action createWallet. This action requires one option which is the label to name the wallet for you to keep track of different wallets. You would need to enclose the name of the label in double quotes ("") if you have spaces in the value such as in the example above, to indicate the value string.

After you type in the above, you would be prompted to enter a password.

Password: *********

The password is required by default to encrypt your wallet private key so that even if someone were to get a copy of your wallet, the would still not be able to transaction with it without the password. Make sure that you remember the password, as there is no way to recover it. The minimum requirement for the password is 8 characters, at least 1 uppercase and lowercase letter, and 1 digit. However, we recommend you to secure it with a password higher these requirements.

Details

The password is encrypted with AES-GCM-256 and uses Argon2i for key derivation. As much these help protect your wallet, the encryption is only as strong as your password. Consider to use a password manager to generate and manage secure passwords.

Once you have entered the password, you will get the credentials for your wallet.

Info
Label: My first wallet
Private Key:  0x0026cf23c9baf9fdf42a6a777c1b876582d27ea0ab95d6e3dad7faa1f6e3e754fe84b6e8690ed588efdb0eb572c4eda245c3714bac179e34d3daa0c76265f984dd253fc8c133b8f6f5b35e0f55d87c176877db60caf2d434b12240ef59830dc594110e5c752d32410053b30a6e5201d6daabed50c7361cc15e7a18af2de87a547c34b8a7eb15349912185fdf3e3a1b3f67765589f100380311d208e65d170b72745633c8fba74a3f5bab7889d19ed0231208a8c5b89bab77d519236cb4972ddd25f5912e6b527f68590a66e9552d4e3d533ff1e6976a4e446021f0a502fd6375bf9f8283861e
Public Key: 0x3076301006072a8648ce3d020106052b810400220362000459765fd33eeeb2eb5b355c5b3a96723a70ad61078fd4539f1462e43219b28fe18c3a8598c9c08f4bcb8b633b31a2a194136fdb719aba8d644858b57dbf54858868e9ea5b90e0ac96e273a80ae800e88ffd8555b3fa8a22bdd1ed55e68c30461b
Address: 0x0034e57af12566612ae069c67952bd58308b6d034e5180e056

The credentials for your wallet are:

  1. Label - This is to identify your wallet. It can be changed anytime.
  2. Private key - Keep this somewhere safe and never share it with anyone. You can recover your wallet anytime using this private key. The private key is encrypted using the password you entered. Therefore, this value will change if you were to change your password. The private key is used to sign your transactions.
  3. Public key - The public key, generated from decrypting the private key, is included in your transaction for others to verify your transaction signature. There's no need to worry too much about how this works as the transactions are signed automatically using your selected wallet.
  4. Address - This is your public address where others can send you credits. It includes a built-in checksum to prevent accidently sending credits to a wrong or invalid address.

Details

The public/private key pair is generated using P-384 (designated as "secp384r1") elliptic curve for the ECDSA algorithm as it the among the most secure and portable. All private keys are encrypted by default and only decrypted when recovering a wallet or signing a transaction.

The encrypted private key buffer has the following structure:

  1. Version - The first byte indicates the version Currently, there is only 0x00
  2. Salt - The next 16 bytes is the salt for the key derivation function (KDF, argon2i algorithm) to help with hash table and password brute-force attacks
  3. Initialization vector (IV) - The next 12 bytes is the IV for the cipher.
  4. Authentication Tag - The next 16 bytes is the "tag" for AES-GCM integrity check.
  5. Data - The remaining bytes are the encrypted data for the actual private key.

The address always has a length fo 25 bytes. It contains the following values:

  1. Version - The first byte indicates the version Currently, there is only 0x00
  2. Fingerprint - The fingerprint is last 20 bytes of the SHA3-256 output of the public key
  3. Checksum - The checksum is generated from the fingerprint. It consist of the last 4 bytes of the fingerprint hash XXHash output (seed value: 0xe782cbe4)

Select wallet

Once you have create a wallet, you can set a selected wallet. The selected wallet would be used as a default when you need to set a sender for a transaction or set a receiver for mining reward. First, let's list the available wallets.

$ listWallets

You should see the available list of created wallets. It should include the wallet you have just created above.

Wallet list
Label: My first wallet
Private Key:  0x0026cf23c9baf9fdf42a6a777c1b876582d27ea0ab95d6e3dad7faa1f6e3e754fe84b6e8690ed588efdb0eb572c4eda245c3714bac179e34d3daa0c76265f984dd253fc8c133b8f6f5b35e0f55d87c176877db60caf2d434b12240ef59830dc594110e5c752d32410053b30a6e5201d6daabed50c7361cc15e7a18af2de87a547c34b8a7eb15349912185fdf3e3a1b3f67765589f100380311d208e65d170b72745633c8fba74a3f5bab7889d19ed0231208a8c5b89bab77d519236cb4972ddd25f5912e6b527f68590a66e9552d4e3d533ff1e6976a4e446021f0a502fd6375bf9f8283861e
Public Key: 0x3076301006072a8648ce3d020106052b810400220362000459765fd33eeeb2eb5b355c5b3a96723a70ad61078fd4539f1462e43219b28fe18c3a8598c9c08f4bcb8b633b31a2a194136fdb719aba8d644858b57dbf54858868e9ea5b90e0ac96e273a80ae800e88ffd8555b3fa8a22bdd1ed55e68c30461b
Address: 0x0034e57af12566612ae069c67952bd58308b6d034e5180e056

Copy the address of the wallet you wish to select as the default wallet. Run the selectedWallet action to view the currently selected wallet. There should be none if you have not selected it yet.

$ selectedWallet
No selected wallet

To select the wallet, run the selectWallet action with 'address' with the address option. After that, you can run the selectedWallet action again to confirm the selected wallet.

$ selectWallet address:0x0034e57af12566612ae069c67952bd58308b6d034e5180e056

Optional

You can do a confirmation that you have the correct password to access to you wallet. It is to ensure that you can access the credits sent to your address. Run the following with your saved wallet address and input your password after prompted

$ verifyWallet address:0x00d5860cad65704e75f784f29911c5aa9ddc13894e4bdfa657

It should respond with a 'Yes'

Delete wallet

You can delete any of your saved wallets. Once you lose the wallet private key, you will have no way of recovering it. Be sure to keep a copy of the private key if you wish to recover it later. To do so, run deleteWallet and pass the address of the saved wallet as an option.

$ deleteWallet address:0x00d5860cad65704e75f784f29911c5aa9ddc13894e4bdfa657

If the wallet you deleted the selected wallet, then you no longer have any default wallet.

Recover wallet

To recover a wallet from the private key use the recoverWallet action with required options 'privateKey' and 'label'.

$ recoverWallet privateKey:<0x000102...> label:"My recovered wallet"

Reference

That is all for the essentials. For the full list of wallet actions, go to the wallet reference.