Settlement hubs

Packets move money in the nodes' books. Settlement hubs are where peers pay what they owe each other for real. This page explains what a hub is, why Dassie settles only through hubs, and what happens to your money there.

What a hub is

A settlement hub is a small shared ledger for one asset, kept by a few validators, which are Dassie nodes too. Together they hold every member's money in one escrow account on the XRP Ledger, which none of them controls alone: a withdrawal needs the signatures of more than two thirds of them.

• Members are ordinary nodes, yours among them. Each has an account in the hub, opened with a deposit to the escrow or by a peer paying it in.
• Validators agree on every operation in the hub, in order, block by block. A hub of four validators keeps working with one of them down or misbehaving. They sit close to each other on the network, within a few tens of milliseconds, so that a block is final soon after it is proposed. Members can be anywhere.
• The escrow is one account on the XRP Ledger that holds what the hub owes its members. Validators credit a deposit only once they have proven it in a ledger the XRP Ledger's own validators signed, never on a server's word.

Dassie has the test network's two hubs built in, one per asset: an XRP hub and a DSUSD hub, DSUSD being Dassie's test dollar. Both were founded by boot1, and boot1 to boot4, four of the five bootstrap nodes, are their validators. Your node joins one by running its settlement scheme: hub-xrpl-testnet-xrp for the XRP hub, and hub-xrpl-testnet-dsusd for the DSUSD hub. It is in at most one hub per asset, and can be in both. Schemes and hubs lists them all.

Mainnet's hubs are not built in yet. What's next

Why only hubs

Two peers could settle directly, each paying the other on the XRP Ledger. But then settling is up to the one who owes. A peer can always walk away with what it owes, so every direct peering is a loan without security, and a newcomer could run up debts with every peer and vanish, again and again under new keys.

In a hub, the money that backs a peering is already set aside, and the peer you pay can take it whether or not you cooperate. So Dassie settles only through hubs. Two nodes peer only if they share a hub, and every hub they share is a way they settle, one per asset. Nothing falls back to settling directly.

Why it works this way and what it gives up

Holds: the money behind a peering

Your node does not ask the hub to move money for every packet. It sets money aside instead.

1. For each peer it pays over a hub, your node keeps a hold in the hub: part of its balance there, set aside for that peer.
2. With every Prepare it sends that peer, your node signs a commitment: a promise the hub honors if the peer shows the packet's fulfillment in time.
3. When the peer's Fulfill comes back, your node answers with a claim: a signed running total of what it owes the peer.
4. The peer takes its money from the hold with the claim, or with the commitment and the fulfillment if your node never sent the claim. It does not need your node's help either way.

The hub never sees the packets. It sees only what members take from holds, put into them, and move in or out.

The hold is the credit. The credit your node gives a peer is its own hold toward that peer: money set aside, all of it and nothing more. The peer can take from it what your node owes it, and never more, so a peer can cost you at most that hold and the packets in flight beyond it. A hold starts at nothing. When a peer asks your node to settle, your node puts more into its hold toward that peer. The other way round, what a peer can send through your node is bounded by its own hold toward you.

Short of funds, your node shares them out. When what your node has in the hub, its balance and its holds, cannot give every peer a full hold, each peer gets a share: first enough to carry a full load of packets in flight, peers in the core of the network before peers that use your node as their way in, and what is left to those that earned your node the most fees, with a little spread over all, so a new peer can start to earn. Every peer can always count on one largest packet. A busy peer may take more, up to a full hold, from what idle peers leave unused, but never another peer's packet. A hold above its share is never taken back; it shrinks as the peer takes from it.

Why peers share your hub funds this way

Peers and holds says how peers find each other and when they ask to settle.

Joining a hub

On the testnet, dassie setup joins the XRP hub unless you say otherwise. Each --hub names a hub to join instead, by its scheme, and --hub none joins none. This joins both:

$sudo dassie setup --passphrase-file phrase.txt \
    --hub hub-xrpl-testnet-xrp --hub hub-xrpl-testnet-dsusd

In the wallet, your node joins a hub when you add the hub's scheme, on the Ledgers page. Unless you give it another hub's rules, the scheme takes the hub built in for its asset, and stays in that hub whatever a later release builds in.

A node gets its account in a hub in one of two ways.

• By a deposit. Your node pays the escrow by itself from its own account on the XRP Ledger, once that has funds, with destination tag 0 and a memo that names the new account's key. The hub opens the account, locks its reserve, and keeps the rest as its balance. Later deposits are your node's too, naming the account by its number as the destination tag. You deposit to your own account, never to the escrow, and your node moves into the hub what it needs.
• By being paid in. A node with no account yet can still peer with a member that has one. It takes that peer's packets on what the peer owes it, and spends only that, through the same peer. Once the peer owes it the hub's minimum for a new account, the peer pays it in: the hub opens the new account with what is owed. Until then, the newcomer risks what it is owed, up to that minimum, if the peer goes away.

A new account first names where its money goes if the hub ever shuts down: your node's own account on the XRP Ledger, the one your recovery phrase derives.

Your funds in a hub

Your node moves money between its own account on the XRP Ledger and the hub by itself. It keeps a generous amount in the hub, its target: a thousand of the largest packets unless you set another, more than its holds for its peers are likely ever to need. What counts is what your node put in, its holds for peers included. If you have less than that, your node keeps all of it in the hub, apart from a little XRP for a token hub's fees if it is in one. It always keeps enough spendable to answer a request to settle from each peer at once.

• The floor is a tenth below that amount. Below it, your node deposits from your own account back up to it.
• The ceiling is a tenth above it. What you receive arrives in the hub, and once it takes the account above the ceiling, your node withdraws the excess to your own account, back down to it.

A payment larger than what the hub holds still goes. Your node first moves the difference into the hub from your own account, with enough to bring the hub back to that amount, and the payment starts once the hub credits it, a few seconds later. It counts what payments still have to send as already gone, so it never withdraws what they need.

You can move money yourself too, in the wallet's Hubs page or with dassie hub. A move of yours pauses your node's own moves for a while, so it does not undo yours. A move that is late, sent but not yet seen on the other side, is never sent again by itself; you look, and decide. Your hubs walks through it.

To keep less in a hub, or more, set its target, on the Hubs page or with dassie hub target: the floor and the ceiling follow, a tenth either side. Less in the hub is less at stake if it fails, and funds fewer holds for your peers.

$dassie hub status
$dassie hub target hub-xrpl-testnet-xrp 10

Closing your account in a hub, and being in more than one hub of an asset are not there yet. What's next

When a hub fails

A hub can end in two ways.

• Shutdown. The validators vote to close it, or one of them has been gone for days and was not replaced. The hub stops taking new holds and transfers, gives payees a notice period to take what holds owe them, and then pays every account out to the address it named.
• Stall. Too many validators are gone for the hub to agree on anything. The others declare it stalled and sign a payout from the last block that became final. There is no notice period, so a payee loses what it had not yet taken from a hold. A payout needs signatures from more than two thirds of the validators, and may wait until enough of them come back.

Either way, your node stops settling over that hub at once, on every peering. Peerings keep their other hubs, of other assets, and a peering left with none ends. Until you are in a working hub of that asset again, your node is cut off in it. Dassie chooses to pause rather than to fall back on unsecured credit: a peering that waits is better than one that can lose money.

A hub of a dollar token has two more cases, since the token's issuer can act on the escrow's balance.

• Freeze. While the issuer freezes the balance, the hub is frozen: your node sends nothing over it until the thaw, and keeps what is waiting.
• Clawback. If the issuer claws back from the escrow, the hub shuts down. Withdrawals already on their way are paid in full, and every account gets its share of what is left.

What it costs

• Reserves: your account locks one while it is open, and each hold locks a small one of its own.
• The hub's fees, which its rules set, flat and capped.
• The XRP Ledger's fees for moving money into the hub and out of it.
• Trust in the validators, with what you keep in the hub. That is why your node keeps it between the floor and the ceiling, so a failing hub costs you little.

To run a hub, see Validate a settlement hub and Found a hub.

Why it works this way and the full design, in settlement hubs