Setting up an Ergo testnet node

Install, configure and run the Ergo testnet node that Lithos depends on.

Standard6 min readFor anyone setting up Lithos for the first time. No Ergo experience needed.

Lithos runs on top of a local Ergo node. This page covers installing the node, writing its configuration file, creating and unlocking a wallet, and confirming that the node is ready. Finish it before you configure the Lithos client.

It does not cover the Lithos client itself. That is the startup guide.

What Lithos uses the node for#

The Lithos client does not talk to the Ergo network directly. It talks to your node, which does four jobs for it:

Syncs the blockchain and serves the chain state Lithos reads.
Signs transactions using the node wallet's keystore.
Produces the block candidates you mine, and accepts the solutions you find.
Serves the box, token and address lookups Lithos needs to find collateral and rollups.

The node must be running, fully synced, and its wallet unlocked before Lithos can do anything.

Step 1: Download the node#

Download the latest release JAR from the Ergo releases page.

Step 2: Create the node directory#

Create a folder for the node and put the JAR inside it:

powershell

mkdir C:\ergo-testnet

bash

sudo mkdir -p /opt/ergo-testnet

The node writes its blockchain data into this folder. Plan for tens of gigabytes, and more once indexing is on.

Step 3: Write the node configuration#

Create a file named ergo.conf in the node directory with the following contents:

ergo.conf

hocon

ergo {
  networkType = "testnet"
  node {
    useExternalMiner = true
    offlineGeneration = false
    mining = true
    extraIndex = true
  }
}
 
scorex {
  restApi {
    # Blake2b256 hash of the API key "hello". Change this. See "Changing the API key" below.
    apiKeyHash = "324dcf027dd4a30a932c441f365a25e86b173defa4b8e58948253471b81b72cf"
  }
  network {
    knownPeers = [
      "128.253.41.110:9020",
      "213.239.193.208:9023"
    ]
    nodeName = "lithos-testnet-node"
  }
}

Each setting Lithos depends on:

Setting	Why Lithos needs it
`networkType`	Selects testnet. Also sets the REST API port to `9052`
`mining`	Lets the node build block candidates
`useExternalMiner`	Tells the node that something else does the hashing. Lithos and your mining software are that something else
`offlineGeneration`	Must stay `false`. When true, the node mines against itself rather than the network
`extraIndex`	Builds the address, token and script indexes. Lithos finds collateral boxes and rollups through them, and without indexing those lookups return nothing
`apiKeyHash`	The hash of the key that guards the node's REST API. Lithos authenticates with the key behind this hash
`knownPeers`	Testnet peers to connect to on first start

Changing the API key#

The shipped hash is the hash of the string hello, which is public. Replace it before you run anything you care about.

Start the node once with the configuration above.
Open the node's Swagger panel at http://127.0.0.1:9052/swagger.
Under /utils, call POST /utils/hash/blake2b with your chosen key as the request body.
Copy the returned hash into apiKeyHash in ergo.conf.
Restart the node.

Your API key is the original string, not the hash. Give that string to the Lithos client as node.key, and update anything else that talks to your node.

Step 4: Start the node#

Confirm you are on Java 11 first. Later versions are not supported.

powershell

java -version

If the version is not 11, install a JDK 11 build such as Temurin or Zulu.

powershell

cd C:\ergo-testnet
java -jar ergo-testnet.jar --testnet -c ergo.conf

bash

sudo apt update
sudo apt install openjdk-11-jdk -y
java -version

bash

cd /opt/ergo-testnet
java -jar ergo-testnet.jar --testnet -c ergo.conf

Replace ergo-testnet.jar with the filename you downloaded.

The node now exposes two interfaces on port 9052, both only while it runs:

Interface	Address	Use it for
Node panel	`http://127.0.0.1:9052/panel`	Sync status, peers, wallet, mining info
Swagger	`http://127.0.0.1:9052/swagger`	Every REST endpoint, with a form to call it

Step 5: Create a wallet#

Lithos signs with this wallet's keystore, so the node needs one before the client starts.

Open http://127.0.0.1:9052/panel.
Go to the Wallet tab.
Click Create Wallet.
Set a wallet password and record it. The Lithos client needs it as node.pass.
Save the mnemonic.

Open http://127.0.0.1:9052/swagger.
Authorize with your API key.
Call POST /wallet/init with your chosen wallet password in the request body.

This produces the same keystore file as the panel.

Either method writes the keystore to the node's data directory:

C:\ergo-testnet\data\wallet\keystore\keyfile.json

/opt/ergo-testnet/data/wallet/keystore/keyfile.json

Give that full path to the Lithos client as node.storagePath.

Step 6: Unlock the wallet#

The node wallet locks every time the node restarts. Lithos reads addresses from the node wallet and derives lender keys through it, and both fail against a locked wallet. Symptoms include errors about reading wallet addresses, and emission transactions that never build.

Unlock it from the Wallet tab of the node panel, or by calling POST /wallet/unlock in Swagger with your wallet password. Do this every time you restart the node, before starting Lithos.

Step 7: Fund the wallet#

Lithos pays ordinary transaction fees for the work it does on your behalf, at roughly 0.001 ERG per transaction. Send some testnet ERG to the wallet's primary address, which the panel shows on the Wallet tab.

Step 8: Confirm the node is ready#

Wait for the node to finish syncing. The panel shows the current height against the network height.

Then check the API from a terminal:

powershell

curl http://127.0.0.1:9052/info

bash

curl http://127.0.0.1:9052/info

A working node returns something like this:

json

{
  "fullHeight": 479000,
  "headersHeight": 479000,
  "isMining": true
}

Check three things in the response:

fullHeight and headersHeight match, which means the node is synced.
isMining is true.
fullHeight matches the network height reported by a testnet explorer.

You are ready for Lithos#

Before moving on, collect the four values the Lithos client asks for:

Value	Where it comes from
API key	The string you hashed in step 3
Wallet password	The password you set in step 5
Keystore path	The full path to `keyfile.json` from step 5
Node address	`http://127.0.0.1`, with no port. Lithos appends `9052` itself

Next steps#

Startup guide: configure and run the Lithos client against this node.

Edit this page on GitHubsynced from e0ca86a

← PreviousStartup guide Next →Configuration

Setting up an Ergo testnet node

Install, configure and run the Ergo testnet node that Lithos depends on.

Standard6 min readFor anyone setting up Lithos for the first time. No Ergo experience needed.

It does not cover the Lithos client itself. That is the startup guide.

What Lithos uses the node for#

The Lithos client does not talk to the Ergo network directly. It talks to your node, which does four jobs for it:

Syncs the blockchain and serves the chain state Lithos reads.
Signs transactions using the node wallet's keystore.
Produces the block candidates you mine, and accepts the solutions you find.
Serves the box, token and address lookups Lithos needs to find collateral and rollups.

The node must be running, fully synced, and its wallet unlocked before Lithos can do anything.

Step 1: Download the node#

Download the latest release JAR from the Ergo releases page.

Step 2: Create the node directory#

Create a folder for the node and put the JAR inside it:

powershell

mkdir C:\ergo-testnet

bash

sudo mkdir -p /opt/ergo-testnet

The node writes its blockchain data into this folder. Plan for tens of gigabytes, and more once indexing is on.

Step 3: Write the node configuration#

Create a file named ergo.conf in the node directory with the following contents:

ergo.conf

hocon

ergo {
  networkType = "testnet"
  node {
    useExternalMiner = true
    offlineGeneration = false
    mining = true
    extraIndex = true
  }
}
 
scorex {
  restApi {
    # Blake2b256 hash of the API key "hello". Change this. See "Changing the API key" below.
    apiKeyHash = "324dcf027dd4a30a932c441f365a25e86b173defa4b8e58948253471b81b72cf"
  }
  network {
    knownPeers = [
      "128.253.41.110:9020",
      "213.239.193.208:9023"
    ]
    nodeName = "lithos-testnet-node"
  }
}

Each setting Lithos depends on:

Setting	Why Lithos needs it
`networkType`	Selects testnet. Also sets the REST API port to `9052`
`mining`	Lets the node build block candidates
`useExternalMiner`	Tells the node that something else does the hashing. Lithos and your mining software are that something else
`offlineGeneration`	Must stay `false`. When true, the node mines against itself rather than the network
`extraIndex`	Builds the address, token and script indexes. Lithos finds collateral boxes and rollups through them, and without indexing those lookups return nothing
`apiKeyHash`	The hash of the key that guards the node's REST API. Lithos authenticates with the key behind this hash
`knownPeers`	Testnet peers to connect to on first start

Changing the API key#

The shipped hash is the hash of the string hello, which is public. Replace it before you run anything you care about.

Start the node once with the configuration above.
Open the node's Swagger panel at http://127.0.0.1:9052/swagger.
Under /utils, call POST /utils/hash/blake2b with your chosen key as the request body.
Copy the returned hash into apiKeyHash in ergo.conf.
Restart the node.

Your API key is the original string, not the hash. Give that string to the Lithos client as node.key, and update anything else that talks to your node.

Step 4: Start the node#

Confirm you are on Java 11 first. Later versions are not supported.

powershell

java -version

If the version is not 11, install a JDK 11 build such as Temurin or Zulu.

powershell

cd C:\ergo-testnet
java -jar ergo-testnet.jar --testnet -c ergo.conf

bash

sudo apt update
sudo apt install openjdk-11-jdk -y
java -version

bash

cd /opt/ergo-testnet
java -jar ergo-testnet.jar --testnet -c ergo.conf

Replace ergo-testnet.jar with the filename you downloaded.

The node now exposes two interfaces on port 9052, both only while it runs:

Interface	Address	Use it for
Node panel	`http://127.0.0.1:9052/panel`	Sync status, peers, wallet, mining info
Swagger	`http://127.0.0.1:9052/swagger`	Every REST endpoint, with a form to call it

Step 5: Create a wallet#

Lithos signs with this wallet's keystore, so the node needs one before the client starts.

Open http://127.0.0.1:9052/panel.
Go to the Wallet tab.
Click Create Wallet.
Set a wallet password and record it. The Lithos client needs it as node.pass.
Save the mnemonic.

Open http://127.0.0.1:9052/swagger.
Authorize with your API key.
Call POST /wallet/init with your chosen wallet password in the request body.

This produces the same keystore file as the panel.

Either method writes the keystore to the node's data directory:

C:\ergo-testnet\data\wallet\keystore\keyfile.json

/opt/ergo-testnet/data/wallet/keystore/keyfile.json

Give that full path to the Lithos client as node.storagePath.

Step 6: Unlock the wallet#

Unlock it from the Wallet tab of the node panel, or by calling POST /wallet/unlock in Swagger with your wallet password. Do this every time you restart the node, before starting Lithos.

Step 7: Fund the wallet#

Step 8: Confirm the node is ready#

Wait for the node to finish syncing. The panel shows the current height against the network height.

Then check the API from a terminal:

powershell

curl http://127.0.0.1:9052/info

bash

curl http://127.0.0.1:9052/info

A working node returns something like this:

json

{
  "fullHeight": 479000,
  "headersHeight": 479000,
  "isMining": true
}

Check three things in the response:

fullHeight and headersHeight match, which means the node is synced.
isMining is true.
fullHeight matches the network height reported by a testnet explorer.

You are ready for Lithos#

Before moving on, collect the four values the Lithos client asks for:

Value	Where it comes from
API key	The string you hashed in step 3
Wallet password	The password you set in step 5
Keystore path	The full path to `keyfile.json` from step 5
Node address	`http://127.0.0.1`, with no port. Lithos appends `9052` itself

Next steps#

Startup guide: configure and run the Lithos client against this node.

Edit this page on GitHubsynced from e0ca86a

← PreviousStartup guide Next →Configuration