Set up a full node
This tutorial explains how to install and run a full Ergo node. It does not cover mining.
Windows users can also watch the video tutorial.
There are a few important aspects of node usage that your wallet and money's safety depends on:
- An Ergo node requires storing security-critical parameters in the configuration file. You should never make this file public.
- An Ergo node provides a REST API for interacting with the built-in wallet. Sensitive API methods require a security token, which should never be sent over untrusted channels.
- Access to the Ergo REST API must be restricted to known hosts. In particular, the API must not be accessible from the Internet.
To run an Ergo node you need a JDK/JRE version >= 9 installed on your system. We strongly recommend either version 9 or 11. One way to do this is to install Oracle Java SE.
Note that Oracle JDK/JRE <= 8 is no longer supported.
The next step is to download the latest Ergo client release jar file and create a node configuration file.
Note that instead of downloading the precompiled Ergo jar, you can clone the repository and compile the jar from the source using SBT by issuing the sbt assembly command.
Create a dedicated folder (such as ~/ergo) for running the node.
Denote by ergo_folder the folder where the jar is kept.
Create a configuration file ergo.conf with the following text in ergo_folder.
ergo {
node {
mining = false
}
}
Open a command prompt and cd to ergo_folder. Then issue the following command to run the node for the first time:
java -Xmx4g -jar ergo-<release>.jar --mainnet -c ergo.conf
It is better to use more memory on heap-Xmx4g for initial syncing. -Xmx1g should be enough when node is full synced.
The node will start syncing immediately after this. Wait for a few minutes for the API to start and go to the next step.
Note: You can use any name for the file instead of ergo.conf. All configuration parameters are to be passed through this file and you only need to rewrite parameters that you want to change from the default values. The above config file actually has the default values.
First, select a secret to protect your API. Then go to http://127.0.0.1:9053/swagger#/utils/hashBlake2b and call the API to compute the hash of your secret. Refer to the image below.
Copy the response containing the hash for use in the next step (see below image). In our example, the secret is hello whose hash corresponds to 324dcf027dd4a30a932c441f365a25e86b173defa4b8e58948253471b81b72cf.
IMPORTANT You must use a different and strong secret.
Edit the config file ergo.conf and paste the hash copied in the previous step. The file should look as follows:
ergo {
node {
mining = false
}
}
scorex {
restApi {
# Hex-encoded Blake2b256 hash of an API key.
# Should be 64-chars long Base16 string.
# below is the hash of the string 'hello'
# replace with your actual hash
apiKeyHash = "324dcf027dd4a30a932c441f365a25e86b173defa4b8e58948253471b81b72cf"
}
}
Restart the node and go to http://127.0.0.1:9053/panel to access the panel. Then set the API key secret from the previous step. Note that you need to set the secret and not the hash from the config file. In our example, this is the string hello.
Click on Initialize wallet. After the pop-up opens, there are two ways to proceed depending on your scenario.
- If this is the first time you are running the node then you need to initialize it with a new mnemonic sentence.
- If you had created a wallet earlier and would like to obtain the same address (possibly because there are funds stored in it), then you have to restore the wallet using the mnemonic sentence you had saved earlier.
Follow one of the below steps depending on your situation.
In the pop-up that opens, you must enter a wallet password. The mnemonic password is optional. After you click send, the wallet will return a mnemonic sentence as shown below.
You must copy this sentence and save it in a safe place. This sentence will be needed to restore the wallet on a different computer.
Copy the mnemonic sentence from earlier paste it into the "Mnemonic" field in the Restore-wallet form. Enter a secure wallet password. Leave the Mnemonic password empty (it is only for advanced users). Refer to the figure below.
After the wallet has been successfully restored from the mnemonic sentence, you will see a confirmation as shown in the figure below.
This is a test to ensure you have set up the node properly. It will return the current addresses in the wallet.
In the panel at http://127.0.0.1:9053/panel click on the Wallet tab on the left and then on Get all wallet addresses to view the addresses currently maintained by the wallet. It should return at least one address if the node is set correctly.
While the node is syncing, the panel will show "Active synchronization" (see the image below).
After the node is fully synced, the text will change to "Node is synced", as shown below.
Once the node is synced, use the wallet API in the panel to see your balance, as shown below.
If there is a non-zero balance, you can send Ergs to any other address using the panel as shown below:
A Swagger UI is available at http://127.0.0.1:9053/swagger. You had already used it earlier to compute the hash of your secret. You can also use this UI to make API calls for advanced operations that are not (yet) available in the panel. Some examples of this are:
- Creating non-standard transactions with registers and context variables.
- Creating transactions that issue tokens.
- Creating transactions that use certain boxes as inputs.
A future article will discuss each of these operations in detail.
Note that most methods in the API are protected and you would need to use your secret (from earlier) to access these methods. The following images show the process of setting this secret in the Swagger UI.
Navigate to the top of the page and click the "Authorize" button. Enter your secret in the form that pops-up as shown in the figure below.
After the password is entered and you have clicked "Authorize", you will be shown the popup below:
Now navigate to http://127.0.0.1:9053/swagger#/wallet/walletAddresses in the same tab where you entered the password and click on "Try it out". You should see the same list of addresses as you saw earlier from the panel.
