Ledgers, books and realms

Your node holds money in a few places and keeps careful books of all of them. This page explains where your funds sit, how your node knows what a ledger really holds, and why a dollar token can pause.

Three words

• A ledger is somewhere money is held: an asset on the XRP Ledger, or your account in a settlement hub. Your node names each one by its scheme and its currency, such as xrpl-testnet-xrp+xrp.
• Books are your node's own records of what it holds on each ledger and who owes what.
• A realm is test or live: test money, or real money. Every node runs in one realm for good.

Owner books

Your funds on the XRP Ledger sit in owner books, one per asset. An owner book holds your money on its ledger, pays the payments you make from it, and funds your settlement hubs. It never settles with peers: peers settle only through hubs.

On the test network there are two:

• xrpl-testnet-xrp, your test XRP. A new account with no funds asks the XRP Ledger testnet's faucet for some.
• xrpl-testnet-dsusd, in DSUSD, Dassie's own test dollar. DSUSD has no faucet: you buy it with test XRP on the testnet's XRP/DSUSD pool, from any XRP Ledger wallet, and your node books what arrives. Your node never buys any on the pool itself.

Both live on one account of your node's on the XRP Ledger testnet, derived from your recovery phrase. One address holds your XRP and your DSUSD, and the XRP pays the ledger's fees and reserves for the DSUSD too. To fund them, see Add and fund a ledger.

Mainnet's owner books, xrpl-xrp for XRP and xrpl-rlusd for RLUSD, are real money, so they run only in the live realm, which a node refuses. Test RLUSD is turned off: it has no dollar price on the testnet, and DSUSD stands in for it.

Accounts in hubs

Your account in a settlement hub is a ledger of its own, beside the owner book of its asset, since what you hold there is a claim on the hub's validators rather than a balance on the XRP Ledger. Money you receive arrives there, and beyond a float moves on to your own account. Your node moves money between the two by itself, as Settlement hubs explains.

People pay you by asset, never by ledger: your node has one wallet address per asset, and it books what arrives in the hub where your node runs one. A dollar token is booked as US dollars, at par, which is why the DSUSD ledgers end in +usd.

Your node's books

Your node keeps double-entry books: every transfer debits one account and credits another, and every one it posts is written to a journal on disk before it counts. For each ledger, the books know what each peer owes your node and what it owes them, and which accounts are yours.

Your funds on a ledger are everything your node holds there beyond what it owes its peers. A ledger fee, or a loss on a peer, comes out of them, and you can never spend money your node does not have.

Your node keeps its books alone. It does not ask its peers to agree with them, and it bounds what any peer can cost it from its own books. The ledger, not the books, says what an account on it really holds: the books follow the ledger, and the wallet's Assets page shows what the ledger says.

Why it works this way

Test and live

A realm is test or live. It decides which ledgers a node may run and the start of its address: a node in the test realm is test.das. followed by its node ID. Your recovery phrase names its realm, and your node takes that realm at setup, for good.

Dassie takes test money only. A node refuses the live realm, its ledgers and a phrase that names it. What it takes before real money is allowed is on Early days.

Checking what the ledger says

Your node does not take an XRP Ledger server's word for anything. It books a payment, a balance or a missing account only once it has a proof: that the ledger was signed by enough of the XRP Ledger's own validators, and that what it reads is in that ledger.

• The validators it trusts come from signed lists, which it fetches from their publishers, as XRP Ledger servers do, and checks itself.
• The proofs come from a proof server: an XRP Ledger server with a small patch that answers three proof methods. Your node uses the project's server for its network by default, wss://testnet.xrpl.dassieland.net on the testnet, and you can name another patched server.
• A proof server is relied on to answer, never trusted. A server that lies is caught. One that goes quiet stalls your account until it answers again, and your node says why, but it never falls back to trusting a server.

The XRP Ledger testnet is reset now and then. Your node counts a reset only once the testnet's validators have signed the new chain. Then it writes off what the old chain held, and your account starts again, from the faucet. Proof servers lists the servers.

Why it works this way

The peg guard

Your node books a dollar token at a dollar. If the token drifted off its dollar and your node kept converting it at par, others could buy it cheap elsewhere and trade it to your node for something worth more. So the owner book of a dollar token has a guard.

• Once a minute, it reads the token's price from its pool on the XRP Ledger, proven like everything else, and turns it into dollars with your node's own XRP rate. DSUSD reads the testnet's DSUSD/XRP pool.
• When every reading for ten minutes is more than 3% off a dollar, up or down, it pauses the token. It lets it go again once every reading for an hour is within 1%.
• With no reading it can count for ten minutes, it pauses too: it fails closed.

While a token is paused, your node converts nothing to or from it, or to or from its hub. You can still pay out of it, what arrives is still booked, and settling over its hub goes on. The wallet shows the last price, and why a token is paused. Dollar tokens and the peg guard says what you see.

Why it works this way, and the guard in full in the spec