Setting up an Ergo node

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.

Every port and command on this page is for Ergo mainnet. If you run a testnet node instead, read Running a testnet node for the values that differ.

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:

mkdir C:\ergo

sudo mkdir -p /opt/ergo

The node writes its blockchain data into this folder. Plan for 60 GB of free disk space, because the chain keeps growing.

Step 3: Write the node configuration#

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

ergo {
  networkType = "mainnet"
  node {
    useExternalMiner = true
    offlineGeneration = false
    mining = true
    extraIndex = true
  }
  chain.reemission.checkReemissionRules = true
  wallet.checkEIP27 = true
}
 
scorex {
  restApi {
    # Blake2b256 hash of the API key "hello". Change this. See "Changing the API key" below.
    apiKeyHash = "324dcf027dd4a30a932c441f365a25e86b173defa4b8e58948253471b81b72cf"
  }
  network {
    nodeName = "lithos-mainnet-node"
  }
}

Each setting Lithos depends on:

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.

1. Start the node once with the configuration above.
2. Open the node's Swagger panel at http://127.0.0.1:9053/swagger.
3. Under /utils, call POST /utils/hash/blake2b with your chosen key as the request body.
4. Copy the returned hash into apiKeyHash in ergo.conf.
5. 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.

java -version

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

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

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

Replace ergo.jar with the filename you downloaded.

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

Step 5: Create a wallet#

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

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

C:\ergo\.ergo\wallet\keystore\keyfile.json

/opt/ergo/.ergo/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 Launcher unlocks it for you, but a node you run yourself has to be unlocked by hand. 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 from this wallet for the work it does on your behalf: your difficulty commitment, the refundable bond on every proof you submit, and ordinary transaction fees of about 0.001 ERG each. Send at least 0.05 ERG to the wallet's primary address, which the panel shows on the Wallet tab. Rigs with a high hashrate commit to a higher difficulty and post larger bonds, so they need more. The startup guide explains how the bond is priced.

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:

curl http://127.0.0.1:9053/info

curl http://127.0.0.1:9053/info

A working node returns something like this:

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

Check three things in the response:

1. fullHeight and headersHeight match, which means the node is synced.
2. isMining is true.
3. fullHeight matches the network height reported by an Ergo explorer.

You are ready for Lithos#

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

Running a testnet node#

The Lithos client also runs against the Ergo testnet, which is useful for trying the client without real funds. A testnet node differs from a mainnet node in the following ways:

A testnet node may also need peers to connect to on first start. Add them under scorex.network:

knownPeers = [
  "128.253.41.110:9020",
  "213.239.193.208:9023"
]

Use a separate key for testnet, unrelated to any mainnet wallet you own. If you run a testnet client and a mainnet client on the same machine, give each its own stratum.stratumPort.

Next steps#

• Startup guide: configure and run the Lithos client against this node.
• Node connection and security: every setting that connects the client to this node.