Node connection and security

The node block tells the client where your Ergo node is and how to authenticate with it. Two more settings guard the client's own HTTP API. This page covers both, and it is the only configuration page where every setting is required.

It does not cover setting up the node itself. For that, read Setting up an Ergo testnet node.

Node connection#

Every setting here is required. The client refuses to start if any is missing:

The client reads the chain from your node alone#

Every box, transaction and block the client uses comes from your node. node.explorerURL exists only because the Ergo SDK the client is built on requires one, and leaving it at default is correct. This is also why the node must run with extraIndex = true: the client looks boxes up by token and script through the node's own index.

The port is appended, not required#

The client parses node.url and appends a default port only when the URL does not already name one: 9052 on testnet, 9053 on mainnet. Both of these work and mean the same thing on testnet:

node.url = "http://127.0.0.1"
node.url = "http://127.0.0.1:9052"

A URL without a scheme does not work. 127.0.0.1 alone is rejected at startup, because the client cannot tell a host from a path without one.

Why numAddresses matters more than it looks#

The client builds its signing prover with one secret per address index, from zero to numAddresses - 1. Any box paid to an address past that last index is one the client cannot sign for.

Lender keys are derived from these addresses, which is why emission.maxLenderKeys must not exceed numAddresses. Startup refuses the pair and names the value to raise.

Matching the node's mempool rule#

Ergo nodes rank the mempool either by fee per serialized byte or by fee per unit of execution cost, and the node does not report which it uses. The client has to be told, so that the blocks it builds are packed against the rule your node actually applies.

Set it to match ergo.node.mempoolSorting in your ergo.conf. The node's own default is bySize, which is also the client's.

This setting is not validated at startup. Anything the client does not recognise reads as bySize, so a typo here fails silently rather than refusing to start. Check the spelling against your ergo.conf by eye.

Client API security#

Both ship with published placeholder values and both should change before you run anything you care about.

Setting your own API key hash#

The value in the file is the hash, not the key. The key is what you send with a request. To generate a hash, use your node's own hashing endpoint:

1. Open your node's Swagger panel at http://127.0.0.1:9052/swagger on testnet.
2. Under /utils, call POST /utils/hash/blake2b with your chosen key as the request body.
3. Copy the returned hash into lithos.apiKeyHash.
4. Keep the original string. That is what you authenticate with.

Startup checks that the value is 64 hexadecimal characters and nothing else, so pasting the key instead of the hash is caught immediately.

Mainnet node settings#

Two settings belong in your node's configuration rather than the client's, and only for mainnet mining:

ergo.chain.reemission.checkReemissionRules = true
ergo.wallet.checkEIP27 = true

The first validates consensus. The second handles payments made by the node wallet. Neither applies on testnet.

Next steps#

• Stratum and difficulty: connecting your mining software and choosing diff.
• Setting up an Ergo testnet node: the node side of this page.