Your hubs
Your node settles with its peers through settlement hubs: small ledgers that a few validators keep together, backed by an escrow on the XRP Ledger. The Hubs page shows your account in each hub, and moves money between it and your own account.
Settlement hubs explains what a hub is and why peers settle only through them. This page is about using yours.
On this page
Joining a hub
A node is in at most one hub per asset. It joins a hub when you add
the hub's ledger on Ledgers, such as
XRP in a settlement hub on the XRP Ledger Testnet
(hub-xrpl-testnet-xrp), and stays in that hub for as long
as you keep the ledger. A hub needs the ledger it is funded from: for
the XRP hub, XRP Ledger Testnet, so add and
fund that one first. The DSUSD hub
(hub-xrpl-testnet-dsusd) needs both
DSUSD on the XRP Ledger Testnet, which funds it, and
XRP Ledger Testnet, which pays its escrow's fees.
Once you add the hub's ledger, your node opens its account there by itself: it moves money in from your own ledger of the hub's asset, enough for the account's reserve and some to spend. It does so once that ledger holds enough, unless you stopped your node's own moves. A peer that already has an account in the hub can also pay your node in, once it owes your node enough to open one. Or deposit yourself, as below: your first deposit opens the account.
The testnet's XRP hub and DSUSD hub are built into your release as its
default hubs. Four of the testnet's bootstrap nodes keep them, and the
wallet offers both. A hub's ledger joins the default hub of its asset
when you add it, and stays in that hub even if a later release builds
in another. The wallet joins no hub by itself.
dassie setup joins the XRP hub unless
--hub names others, or none with --hub none.
To join a hub that is not a default, give its scheme that hub's rules
as its config, after the ledger it is funded from:
$sudo dassie setup --passphrase-file <file> --scheme xrpl-testnet-xrp --scheme 'hub-xrpl-testnet-xrp={"rules": "<hex>"}'
dassie setup reads your recovery phrase from that file;
Joining a hub walks
through it. The hub's founder has the rules.
Found a hub says
where they come from, and the
command reference
lists every option of dassie setup.
While your node is in no hub, the Hubs page says so, and links to Ledgers, where you add one.
No hub of real XRP or RLUSD is built in yet. Those come with the live network. What's next
What the page shows
Each hub has a card, named by its ledger. The wallet asks your node for its hubs every few seconds while the page is open, and says "Not current" when it could not.
| On the card | What it means |
|---|---|
| Validators answering | How many of the hub's validators your node hears from now. |
| Hub and your account | The hub's ID, and your account's number in it once it has one. |
| Yours to spend in the hub | Your balance there. |
| Held back as the account's reserve | What the hub keeps for the account itself. You cannot spend it. |
| Deposited, all told; Withdrawn, with ledger fees | Everything that went in and came out of the account. |
| Returned by withdrawals the escrow could not pay | Shown only when it happened: what came back to the account because the escrow could not pay a withdrawal out. |
| Kept near | The target, and whether it is yours or the default: see below. |
| Kept between | The floor and the ceiling: see below. |
| You hold for your peers; Your peers hold for you | The holds, peer by peer, with their total. Beside each of your holds, Share: that peer's share of what you have in the hub. |
| Short of funds for its peers | Shown only while your node takes no new peers over the hub because its funds there would not cover them: see below. |
Amounts are in the asset of the hub's ledger: XRP for an XRP hub, dollars for a DSUSD hub.
Holds, floor and ceiling
A hold is money set aside in the hub for one peer. What you hold for a peer is the credit you give it: the hub pays the peer from that hold, even if your node goes quiet. What a peer holds for you works the same way round: it is what that peer can spend through your node, and your node is paid from it. Holds start at nothing, and grow when a peer asks to be settled with.
Share is each peer's allotment, its share of what you have in the hub, your balance and your holds. While that covers every peer in full, every share is the full amount. When it does not, every peer first gets enough to carry a full load of payments, core peers before the peers that use your node as their way in, and the rest goes to those that earned you the most fees. Every peer can always count on one largest packet. A busy peer may get more than its share, up to the full amount, from what the others leave unused, but never another peer's packet. A hold above its share stays, and shrinks as the peer takes from it.
Your node keeps a generous amount in the hub, its target: a thousand of the largest packets unless you set another, so that it can fund a hold at once when a peer asks. What counts is what it put in: the balance, the reserves and its holds for your peers. What peers hold for you counts once your node takes it.
The floor is a tenth below that amount. Below it, the node deposits from your own account on the XRP Ledger, as much as it holds, keeping a little XRP back for a token hub's fees if it is in one. Whatever it keeps in holds, it keeps enough spendable to fund a hold for each peer that asks, and deposits when it has less.
The ceiling is a tenth above it. When what you receive takes the account past it, the node withdraws what goes beyond to your own account. So if you hold less than that amount, nearly all of it is in the hub, where it settles with your peers.
Set how much your node keeps
To keep less in a hub, or more, set its target. The floor and the ceiling follow, a tenth either side. A lower target leaves more on your own account and less at stake in the hub, but funds fewer holds for your peers.
- Under Moving funds, type the amount in Target.
- Choose Set target. The card shows it beside Kept near, as yours.
- To go back to the default, choose Use the default.
Your node remembers the target. It refuses one below ten of the largest packets, or so low that the account's reserve alone would fill it, and says the least it takes.
Deposit and withdraw
A deposit moves money from your own ledger of the hub's asset into the hub; a withdrawal moves it back. For the XRP hub, that is your XRP Ledger Testnet account.
- Under Moving funds, type the amount.
- Choose Deposit or Withdraw. Pressing Enter moves nothing, so you always pick the way.
- The card shows the move on its way. It is done once the hub's validators agree on it.
Your node makes one move at a time per hub. A move of yours pauses the node's own moves for an hour, so that they don't undo it.
A withdrawal from a token hub, such as a DSUSD hub, can take a moment longer. The hub's escrow pays the XRP Ledger's fees in XRP, so your node first checks that it holds enough and tops it up from your XRP if not. The page says so and sends the withdrawal again by itself every few seconds, for about half a minute. Choose Don't send it again to stop it.
Let your node move funds
Your node keeps each hub account between its floor and its ceiling by itself. The card says whether it does now. To move everything yourself, choose Stop your node's own moves; choose Let your node move funds by itself to turn them back on. Your node remembers the choice.
A late move
A move that is still on its way ten minutes after the XRP Ledger applied it, or after it was sent, is late, and the card marks it. The hub may not be crediting or paying it. Your node waits, and never pays it again by itself.
If you are sure it will not arrive, choose Give up this move and confirm. Your node forgets the move and books nothing. If the hub shows it later anyway, the node books it then, once. Until you move funds yourself or turn its own moves back on, your node moves nothing by itself in that hub.
While a move is on its way, you cannot remove the hub's ledger. Wait for the move, or give it up once it is late.
Short of funds for its peers
Your node gives each peer it settles with over a hub at least one largest packet's worth of room, paid from its funds there: your balance and what it holds for your peers. While your own account can pay, your node deposits whatever that takes, even past the ceiling. When those funds would not cover one more peer that way, the card says so, with how many of your peers they cover, and your node takes on no new peers over that hub. Nodes that use yours as their uplink are refused first; other core nodes only once the funds no longer cover even them.
If the funds stay short of a packet for every peer while no deposit can come, for about ten minutes, long enough for a deposit of yours to land, your node ends as many peerings over the hub as bring it back to a packet each. It ends the nodes that use yours as their uplink first, those that never paid it before those that did, the newest first, and other core nodes only once none of those is left, never the last. The card says from when. A node outside the core ends none of its uplinks.
Fund your own account, or turn your node's own moves back on, to keep them. Once the funds cover your peers with a few packets to spare, your node takes new peers again.
A frozen or ended hub
The issuer of a token, such as DSUSD, can freeze a hub that holds it. The card then says since when. Until the issuer lets go, no payment crosses the hub and nothing moves into or out of it; your node still claims what peers owe it for payments from before the freeze. A deposit to the hub is credited at the thaw.
If a hub stalls or ends, its validators sign a payout to every member. The card shows how many have signed. Once enough have, it lists the transactions that pay you out on the XRP Ledger, with Copy the transactions. Anyone may submit them, in order, if the validators do not.
On the command line
dassie hub does the same from the node's own machine, as
a member of the group dassie-users or with
sudo. Each command below but status names its hub
first, by the scheme over it, as status shows it:
$dassie hub status
$dassie hub deposit hub-xrpl-testnet-xrp 2.5
$dassie hub withdraw hub-xrpl-testnet-xrp 1
$dassie hub auto hub-xrpl-testnet-xrp off
$dassie hub target hub-xrpl-testnet-xrp 10
$dassie hub give-up hub-xrpl-testnet-xrp
$dassie hub payout hub-xrpl-testnet-xrp
Amounts are in the hub's asset. dassie status gives each
hub a line too. The
command reference lists
every option, and Found a hub
covers dassie hub found.
Why it works this way: how the node funds its hubs, and why it never pays a move twice.
