Validate a settlement hub

A settlement hub is a small ledger that a few nodes keep together, its validators, backed by money held on the XRP Ledger. Your node can be one of them. This page turns the validator on, and shows what to watch once it runs.

Before you start

Settlement hubs explains what a hub is and why validators matter. A validator keeps other people's money safe together with the others, so it asks more of you than a node does:

• A node on a server, with a hostname, set up and running. Other validators and members reach it at its own address, over QUIC on UDP port 443, so a node in the desktop app or without a public address cannot validate.
• A server that stays up. A hub needs most of its validators to agree on each block. If a validator is gone for longer than the hub's terms allow, three days unless its sponsor chose otherwise, the hub shuts down and pays everyone out.
• A sponsor you trust. Every hub has a sponsor, the node that founds it. Your node validates only for sponsors you list, and the sponsor asks you to join a hub when it founds one. To found a hub yourself, see Found a hub.

Your node validates at most four hubs, those it was asked to join and those you list, together.

The validator config

Validating is off until you name a config file in DASSIE_VALIDATOR_CONFIG. The file is JSON. It holds no secret, so it may be readable by everyone, which the node's service needs. The smallest one lists the sponsors you validate for:

{
  "sponsors": ["<the sponsor's node ID>"],
  "hubs": []
}

sponsors

The node IDs of the sponsors whose hubs your node may validate. Required.

hubs

Hubs to validate that were not founded with your node, written in by hand, each with its rules (the hub's rules as hex), its genesisMs (the time its first block is stamped with, which every validator must use alike) and, optionally, its own xrpl server. Required, and usually empty: the hubs a sponsor founds with you are added on their own, and kept across restarts.

network

The XRP Ledger network every hub you validate is on: testnet, the default. A hub on another network is refused, and so is mainnet, which holds real money.

xrpl

The XRP Ledger server your node follows each hub's escrow on, as a wss:// URL. By default, Dassie's proof server for the network. Another server must answer the same proofs, since your node checks everything the server says against the XRP Ledger's own validators.

publishers

The validator list publishers whose lists your node trusts to check those proofs, each with its key and sites. By default, the network's own. Leave it out unless you run a network of your own for testing.

hubVersion

The version of the hub protocol your node votes to move every hub it validates to, while a hub runs an older one, such as 2. Once enough of a hub's validators vote for it, the hub runs it once its notice for new rules has passed, a day on Dassie's hubs, and dassie status shows when. Leave it out unless the project asks validators to move: every validator and every node in the hub must run a release that knows the version first, or they stop following the hub.

Turn it on

1. Write the file, and make it readable:

   $sudo install -d /etc/dassie
   $sudoedit /etc/dassie/validator.json
   $sudo chmod 644 /etc/dassie/validator.json

2. Name it in the node's environment:

   $sudo systemctl edit dassie

   and add:

   [Service]
   Environment=DASSIE_VALIDATOR_CONFIG=/etc/dassie/validator.json

   On NixOS, set services.dassie.environment.DASSIE_VALIDATOR_CONFIG instead: NixOS module options.

3. Restart the node, which reads the file only when it starts:

   $sudo systemctl restart dassie

4. Tell the sponsor your node ID, which dassie status shows on its Setup line, and your node's host and port, such as node.example.com:443. It names you by both when it founds the hub.

If the file has a problem, the node does not start, and its log says what is wrong, naming DASSIE_VALIDATOR_CONFIG: journalctl -u dassie. A hub of a sponsor you do not list, or whose rules do not check, stops it the same way. A hub whose rules do not name your node is left out, and the log says so.

When a sponsor asks

When a sponsor you list founds a hub, your node answers on its own. It accepts the terms if they check, are on the network of your file, and your node has a place left for another hub. It then signs the hub's first block, once, and starts validating as soon as enough of the validators have signed. You do nothing; you watch.

Your node keeps what it votes on disk before it sends the vote, so that it never contradicts itself after a crash. That is also why a validator must only ever run on its newest database.

Status and hints

dassie status has a Validating line for each hub your node validates. A hub that runs well reads like this:

$dassie status
…
  Validating   hub 3f9a0c51d2e4b7a8…, validator 2 of 4, block 1234 in view 1300

It names the hub by the start of its ID, your node's place among its validators, and the newest final block. Where the hub's validators have changed and your node is no longer among them, the line says no longer one of its 4 validators where it would say validator 2 of 4. A hint follows at the end only when something needs you:

The node's log says more. When a validator breaks the hub's rules, your node logs which one.

Publishing the proof against such a validator is not there yet, and neither is gathering the old validators' signatures after a hub's escrow keys change. What's next

How the validator works, in the spec, and why hubs.