Skip to content

Wallet documentation

Jump to bottom
Ilya Oskin edited this page Jun 4, 2019 · 1 revision

An Ergo node provides a built-in wallet for storing private keys and signing transactions. The following describes how to set up and protect your Ergo wallet.

The wallet uses the BIP39 standard to generate a seed from a mnemonic sentence, which is then used to generate the private keys according to the BIP32 standard (Hierarchical Deterministic Wallets). You can use your own mnemonic sentence composed of the words from one of these wordists if you want to. The allowed sentence lengths are 12, 15, 18, 21, 24 representing respectively, 128, 160, 192, 224, 256 bits of security. In order to initialize a wallet with such a mnemonic, you should use the wallet/restore API endpoint. However, it is far more secure to use the mneomnic generated by the wallet.

At this stage, all interactions with the wallet can only be done through the node's REST API. Please ensure that you have set an API key in your node before performing the next steps.

Configuring the wallet

The wallet is configured through the node configuration file. Below are the configuration parameters worth paying attention to when configuring wallet for the first time:

  • ergo.wallet.seedStrengthBits - Bit-length of a seed in case it will be generated by the node. Note: the stronger the seed the longer the mnemonic sentence length is. Options: 128, 160, 192, 224, 256
  • ergo.wallet.secretStorage.secretDir - Directory where secret will be stored in encrypted form
  • ergo.wallet.mnemonicPhraseLanguage - Language to be used in mnemonic sentence. Options: "chinese_simplified", "chinese_traditional", "english", "french", "italian", "japanese", "korean", "spanish"

Using the wallet for the first time

The wallet needs to be initialized via the REST API when running the node for the first time. Two options are available here:

  1. Initialize it from scratch (seed will be generated by the node) by making a POST request to /wallet/init with data body: {"pass": "123", "mnemonicPass": "abc"}. Don't forget to save the mnemonic phrase that the node responds with. (Note: The parameter mnemonicPass in request body is optional and is used for protecting the mnemonic phrase).
  2. Restore the wallet from an existing seed. You will have to provide your mnemonic phrase When using this option. This is done by making a POST request to /wallet/restore with data body: {"pass": "123", "mnemonic": "abandon abandon ...", "mnemonicPass": "abc"} (Note: the mnemonicPass field is required only in case your mnemonic phrase was protected by an additional password at creation).

Unlocking the wallet

After initialization and before every use the wallet needs to be unlocked by making a POST request to /wallet/unlock with data body: {"pass": "123"}. (Note: use the password you had chosen at initialization stage)

You must perform this step every time the node is restarted or the wallet is locked. In particular, the wallet must be unlocked for the following operations:

  • Using internal miner
  • Signing transactions
  • Tracking boxes

Locking the wallet

A wallet is automatically locked after some time, which means that all currently loaded secrets are flushed from the memory. You can also use the REST API to lock the wallet by making a GET request to /wallet/lock. It is recommended to lock the wallet when it is not in use. After locking, you will need to unlock the wallet to use it again.

Managing keys

A wallet implements BIP32 ("Hierarchical deterministic wallets"). When the wallet is initialized the only root key is created. In order to derive additional key pair corresponding to a specific derivation path (method: POST, request body: {"derivationPath": "m/1/2"}) the /wallet/deriveKey API route can be used. In order to simply create additional key pair use a /wallet/deriveNextKey API route (method: GET).

Clone this wiki locally