Skip to content

Ergo Wallet Setup and Security#

The Ergo node includes a built-in wallet function to securely store your private keys and sign transactions. This section provides instructions on setting up and protecting your Ergo node wallet.

The wallet utilizes the BIP-39 standard to generate a master seed from a mnemonic sentence (seed phrase). This seed is then used to derive private keys according to the BIP-32 standard for Hierarchical Deterministic (HD) Wallets. While you can compose your own mnemonic sentence using words from the provided wordlists, it is strongly recommended for security to use a mnemonic generated by a trusted source (like the node itself or a secure hardware wallet).

The length of the mnemonic sentence determines the security level (entropy): 12, 15, 18, 21, or 24 words correspond to 128, 160, 192, 224, or 256 bits of security, respectively. To restore a wallet from an existing mnemonic, use the /wallet/restore API endpoint.

All wallet interactions with the node are performed through its REST API. Before proceeding, ensure you have set an API key hash in your node's configuration file to protect sensitive API calls.

Configuring the Wallet#

Wallet-related settings are managed in the ergo.wallet section of the node configuration file. Key parameters include:

  • seedStrengthBits: Specifies the bit-length (entropy) for newly generated seeds. A higher value results in a longer, more secure mnemonic phrase. Options: 128, 160, 192, 224, 256. Default is usually 128.
  • secretStorage.secretDir: Defines the directory where the encrypted wallet file (wallet.dat) will be stored.
  • mnemonicPhraseLanguage: Sets the language for generating or restoring mnemonic phrases. Options: "chinese_simplified", "chinese_traditional", "english", "french", "italian", "japanese", "korean", "spanish". Default is "english".

Initializing the Wallet for the First Time#

When running a node for the first time, you initialize its wallet via the REST API using one of two methods:

  1. Initialize a New Wallet: The node generates a new seed phrase for you.
  2. Endpoint: POST /wallet/init
  3. Request Body: {"pass": "YOUR_WALLET_PASSWORD", "mnemonicPass": "OPTIONAL_PASSPHRASE"}

  4. Action: Creates a new wallet file encrypted with YOUR_WALLET_PASSWORD. The response will contain the newly generated mnemonic phrase – save this phrase securely and offline immediately! The mnemonicPass (BIP-39 passphrase) is optional and adds an extra layer of security to the seed derivation. If used, it must be provided every time the seed is restored.

  5. Restore from Existing Mnemonic: Use a previously generated mnemonic phrase.

  6. Endpoint: POST /wallet/restore
  7. Request Body: {"pass": "YOUR_WALLET_PASSWORD", "mnemonic": "word1 word2 word3 ...", "mnemonicPass": "OPTIONAL_PASSPHRASE"}
  8. Action: Recreates the wallet state from the provided mnemonic. Use the same mnemonicPass that was used when the mnemonic was originally generated or used, if any.

Unlocking the Wallet#

After initialization or restoration, and after every node restart, the wallet must be unlocked before use. To unlock it, make a POST request to /wallet/unlock with your wallet password: {"pass": "YOUR_WALLET_PASSWORD"}.

The wallet must be unlocked to perform operations such as:

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

Locking the Wallet#

The wallet typically locks automatically after a period of inactivity or upon node shutdown, flushing secrets from memory. You can also lock it manually by making a GET request to /wallet/lock. Locking the wallet when not actively using it is recommended for security. You will need to unlock it again before performing further operations.

Managing Keys#

The wallet implements BIP-32, enabling the creation of hierarchical deterministic wallets. During initialization, the master key is derived from the seed. To derive additional keys (and their corresponding addresses) based on specific derivation paths (e.g., following EIP-3 standard paths like m/44'/429'/0'/0/0), use the POST /wallet/deriveKey endpoint with the desired path in the request body: {"derivationPath": "m/44'/429'/0'/0/0"}.

Alternatively, you can derive the next available key in the sequence according to the wallet's internal counter using the GET /wallet/deriveNextKey endpoint.

Note: All these wallet operations are performed via the Ergo node's REST API, typically accessed through the Swagger UI or programmatically.