Found a hub

Anyone can start a settlement hub. The node that does is its sponsor: it picks the validators, proposes the terms, and pays for the hub's account on the XRP Ledger. This page walks through it with dassie hub found.

Before you start

Settlement hubs explains what a hub is for. To found one, you need:

• Your node, set up, with its XRP ledger xrpl-testnet-xrp running and funded. The hub's account on the XRP Ledger, its escrow, is paid for from it: 2 XRP unless you say otherwise. Add and fund a ledger shows how to add it. It need not peer with anyone.
• Four to sixteen validators, each a node on a server with a hostname, whose operator has turned the validator on and lists your node ID as a sponsor. Validate a settlement hub is the page to send them. Your own node can be one of them, if it is on a server and lists itself.
• Each validator's node ID and its host and port, such as v1.example.com:443.

Pick validators run by different people, in different places, who keep their servers up. A hub needs most of them to agree on each block; if too many are gone at once it stops, and if one is gone for too long it shuts down and pays its members out.

The hub runs on the XRP Ledger network of your node's realm, the testnet. A node of the live realm, which would found on mainnet, is refused.

Terms

The terms are the hub's fees, the bounds of its tables and its timers. Without a file of terms, your node proposes Dassie's starting terms, which are a fine place to begin. To change some, write the ones that differ in a JSON file:

{
  "fees": { "operation": 10 },
  "limits": { "accounts": 2000 },
  "timers": { "stall": 7200000 }
}

• Fees are amounts in the smallest unit of the hub's asset: drops of XRP in an XRP hub, millionths of the token in a token hub. Two are not: gas is always in drops of XRP, and reserve_share_ppm is a share, in parts per million. operation, ledger, gas, reserve_share_ppm, account_reserve, hold_reserve, starting_balance, least_payout.
• Limits bound the hub's tables: accounts, holds, holds_per_account, withdrawals, pending_deposits, recent_deposits, block_operations, deadline_operations, claimed_per_hold, commitments_per_claim, vote_window.
• Timers are in milliseconds: hold_notice, shutdown_notice, reconfigure_notice, absence, stall, margin, allowance. absence is how long a validator may be gone before the hub shuts down.

A field the terms do not have is refused, so a typo never founds a hub on a value nobody chose. Terms that do not add up are refused too, with the reason. The starting values are in crates/dassie-hub/src/founding/mod.rs, and what each one means in crates/dassie-hub/src/rules.rs.

Token hubs

A hub holds XRP unless its terms name a token. On the testnet, the one token a hub may hold is DSUSD, Dassie's test dollar, named by its currency code in hex and its issuer:

{
  "asset": {
    "currency": "4453555344000000000000000000000000000000",
    "issuer": "rURgPoYNN7tGqBzGXFeCLmKYgpSjYgJP6M"
  }
}

A token hub's escrow pays the XRP Ledger's fees in XRP, never out of the token. So it takes no ledger fee from its members, and instead names a gas fee in drops of XRP, at least enough for the largest set of validators it could come to have. Your XRP ledger still pays for the escrow, and the escrow needs a little more XRP, for its trust line to the token. Before a member's node withdraws from a token hub, it checks the escrow's XRP, and tops it up from its own XRP ledger when it runs low.

Why token hubs work this way

Found it

Name every validator, each as its node ID, @, and its host and port:

$dassie hub found \
    <node ID 1>@v1.example.com:443 \
    <node ID 2>@v2.example.com:443 \
    <node ID 3>@v3.example.com:443 \
    <node ID 4>@v4.example.com:443 \
    --terms terms.json
Founding the hub 9c4e…: `dassie hub foundings` shows how far it is.

Two more options:

--escrow-funding <XRP>

What your node pays the escrow, in XRP, such as 2.5. It covers the escrow's reserves on the XRP Ledger and the fees of the hub's own transactions. 2 XRP unless you say otherwise, and never less than the reserves and setup fees need: your node says how many drops that is if you ask for less.

--xrpl <url>

The XRP Ledger server to set the escrow up on. By default, the server your node's XRP ledger uses.

Watch it

A founding goes through these stages, on its own:

1. Asking the validators to accept the terms. Every one must accept. A validator that does not answer, or refuses, is asked again after a wait that doubles, up to a minute.
2. The rules are fixed; asking for the genesis. Your node fixes the rules and the time of the first block, and asks each validator to sign that block.
3. The genesis is certified; starting the hub. Once enough have signed, your node hands each the certificate, and they start the hub.
4. The hub runs; setting up its escrow. Your node pays the escrow from its XRP ledger, and sets it up so that only a quorum of the validators can move what it holds.
5. Founded: the escrow is checked. Enough validators have checked the escrow on the XRP Ledger, and the hub credits deposits.

$dassie hub foundings

  Founding     9c4e…
  Stage        the hub runs; setting up its escrow
  Started      …
  Hub          …
  Escrow       r…, funded, being set up; 0 of 4 validators say it is checked
  Validator    <node ID 1> at v1.example.com:443: accepted
               signed the genesis
               runs the hub
  …
  Rules        …

dassie status sums each founding up in one Founding line. Your node keeps every founding on disk, so a restart picks it up where it stopped.

If it gets stuck

• A validator refused. The Validator line says why, such as a sponsor it does not list, or no place for another hub. Ask its operator, then wait: your node asks again.
• The escrow's payment failed. The Problem line says so. Your node never pays it twice: drop the founding and found again, with more --escrow-funding if the reserve was the problem.

dassie hub drop <nonce> drops a founding, by the ID that dassie hub foundings shows. Your node keeps up to eight foundings, until you drop them.

Replacing a validator that refuses or fails before the hub starts, and seeing foundings in the wallet, are not there yet. What's next

Members

Once the rules are fixed, dassie hub foundings shows them on its Rules line, as hex. That is what a node needs to join your hub: it adds the hub's scheme, hub-xrpl-testnet-xrp for an XRP hub or hub-xrpl-testnet-dsusd for a DSUSD hub, with {"rules": "<hex>"} as its config.

The wallet offers only the testnet's default hubs, which are built into Dassie, so today a member adds another hub's scheme with dassie setup --scheme, after the owner book the hub is funded from:

$sudo dassie setup --passphrase-file <file> \
    --scheme xrpl-testnet-xrp \
    --scheme 'hub-xrpl-testnet-xrp={"rules": "<hex>"}'

A DSUSD hub's member adds xrpl-testnet-xrp and then xrpl-testnet-dsusd before hub-xrpl-testnet-dsusd. Without --hub none, setup on the testnet also joins the default XRP hub, so a member that wants only your hub passes it:

$sudo dassie setup --passphrase-file <file> --hub none \
    --scheme xrpl-testnet-xrp \
    --scheme xrpl-testnet-dsusd \
    --scheme 'hub-xrpl-testnet-dsusd={"rules": "<hex>"}'

A node is in one hub per asset, so a node already in the testnet's default XRP hub is not in yours as well. A new member needs no money in your hub to start: a member with an account there pays it in. Schemes and hubs lists the schemes.

Payouts

When a hub ends, or stalls for good, each validator signs one last set of XRP Ledger transactions: the payments of every member's balance out of the escrow. A member's node fetches these from the validators every minute and keeps them. Once enough validators have signed the same set, it puts the transactions together:

$dassie hub payout hub-xrpl-testnet-xrp
  Hub          …
  Signed       validator 1 signed the payout of block 5210, 3 transactions
  …
  Ready        a quorum signed the payout of block 5210: submit these to the XRP Ledger in order

Anyone can submit them, in order, to an XRP Ledger server, so members are paid out even when no validator is left. The wallet's Hubs page shows them too.

A node submitting the payout itself, once its hub's validators are gone, is not there yet. What's next

Why founding works this way, and the details in the spec.