Skip to content

Ergo Wallet Setup and Security#

To securely store your private keys and sign transactions, an Ergo node provides a built-in wallet. This section provides instructions on setting up and protecting your Ergo wallet.

The wallet utilizes the BIP39 standard, which generates a seed from a mnemonic sentence. This seed is then used to generate private keys according to the BIP32 standard, also known as Hierarchical Deterministic Wallets. You can compose your own mnemonic sentence using words from one of the provided wordlists if desired.

The mnemonic sentence length determines the security level, with the following allowed options: 12, 15, 18, 21, or 24 words representing 128, 160, 192, 224, or 256 bits of security, respectively. To initialize a wallet using a mnemonic, you should utilize the wallet/restore API endpoint. However, it is highly recommended to use the mnemonic generated by the wallet for enhanced security.

All wallet interactions are currently performed through the node's REST API. Before proceeding, ensure that you have set an API key in your node.

Configuring the Wallet#

The wallet's configuration is managed through the node configuration file. Pay attention to the following parameters when configuring the wallet for the first time:

  • ergo.wallet.seedStrengthBits: Specifies the bit-length of the seed generated by the node. A stronger seed corresponds to a longer mnemonic sentence length. Options: 128, 160, 192, 224, 256.
  • ergo.wallet.secretStorage.secretDir: Specifies the directory where secrets will be stored in an encrypted form.
  • ergo.wallet.mnemonicPhraseLanguage: Specifies the language used in the mnemonic sentence. Options: "chinese_simplified", "chinese_traditional", "english", "french", "italian", "japanese", "korean", "spanish".

Initializing the Wallet for the First Time#

To initialize the wallet via the REST API when running the node for the first time, you have two options:

  1. Initializing from scratch (seed generated by the node): Make a POST request to /wallet/init with the following data: body: {"pass": "123", "mnemonicPass": "abc"}. Remember to save the mnemonic phrase provided in the response from the node. The mnemonicPass parameter in the request body is optional and is used to protect the mnemonic phrase.
  2. Restoring the wallet from an existing seed: Provide your mnemonic phrase when using this option. Make a POST request to /wallet/restore with the following data: body: {"pass": "123", "mnemonic": "abandon abandon ...", "mnemonicPass": "abc"}. The mnemonicPass field is required only if your mnemonic phrase was protected by an additional password during creation.

Unlocking the Wallet#

After initialization and before every use, the wallet must be unlocked. To unlock the wallet, make a POST request to /wallet/unlock with the following data: body: {"pass": "123"}. Use the password you selected during the initialization stage.

Remember to perform this step every time the node is restarted or the wallet is locked. The wallet must be unlocked for the following operations:

  • Using the internal miner.
  • Signing transactions.
  • Tracking boxes.

Locking the Wallet#

The wallet is automatically locked after a certain period, which flushes all currently loaded secrets

from memory. You can also lock the wallet manually by making a GET request to /wallet/lock via the REST API. 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#

The wallet implements BIP32, enabling the creation of hierarchical deterministic wallets. During wallet initialization, only the root key is created. To derive additional key pairs corresponding to specific derivation paths, you can use the /wallet/deriveKey API route with a method of POST and a request body of {"derivationPath": "m/1/2"}.

Alternatively, you can simply create additional key pairs by utilizing the /wallet/deriveNextKey API route with a method of GET.

Note: The current wallet operations can only be performed via the Ergo node's REST API.

Feel free to explore the various features of Ergo and the extensive capabilities of the Ergo wallet.