Schemes and hubs

A settlement scheme is how your node holds and moves one asset on one ledger. This page lists every scheme a node can run, by the ID that dassie status, dassie hub and dassie setup --scheme use, beside the name the wallet shows for it.

Reading an ID

A scheme's ID names its ledger, its network and its asset, in that order: <ledger>-<network>-<asset>. The network is left out on mainnet, so xrpl-testnet-xrp is XRP on the XRP Ledger testnet, and xrpl-xrp is XRP on mainnet. A settlement hub's scheme puts hub- before the ID of the owner book it sits on: hub-xrpl-testnet-xrp is a hub of testnet XRP.

Each scheme books on a ledger of its own in your node, <scheme>+<asset>, such as xrpl-testnet-xrp+xrp. Dollar tokens book as USD, one to one. People pay you at a wallet address that names the asset alone, such as /pay/xrp; a hub's ledger shares the address of its asset.

Each scheme belongs to one realm. A node runs only its own realm's schemes, fixed when it is set up, and the wallet offers only those. The live realm, which holds real money, is refused.

Why the names read this way

At a glance

Owner books

The schemes on the XRP Ledger itself are owner books: they keep the books of what your node holds on its own XRP Ledger account, with your deposits and withdrawals, the ledger's fees and reserve. They peer with nobody. Peers settle with each other only over settlement hubs, and a hub is funded from the owner book of its asset.

Your node has one account on each network, whose keys come from your recovery phrase. The XRP and the dollar token of a network sit on the same account, and a token's fees are paid in that account's XRP. An owner book takes no config of its own: leave it empty.

xrpl-testnet-xrp

XRP on the XRP Ledger testnet, on ledger xrpl-testnet-xrp+xrp. It settles through the external asset xrpl-testnet-account/0. An account without funds asks the testnet faucet for test XRP.

xrpl-testnet-dsusd

DSUSD on the XRP Ledger testnet: Dassie's own test dollar token, issued by rURgPoYNN7tGqBzGXFeCLmKYgpSjYgJP6M, booked as USD on ledger xrpl-testnet-dsusd+usd. It settles through xrpl-testnet-account/0 too, and pays its fees in that account's XRP. See Dollar tokens and the peg guard.

xrpl-xrp

XRP on the XRP Ledger mainnet, on ledger xrpl-xrp+xrp, through xrpl-account/0. Real money, in the live realm, which nodes refuse today. Mainnet has no faucet.

xrpl-rlusd

RLUSD on the XRP Ledger mainnet, issued by rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De, booked as USD on ledger xrpl-rlusd+usd, through xrpl-account/0. Real money, in the live realm, which nodes refuse today.

RLUSD on the testnet, xrpl-testnet-rlusd, is disabled: DSUSD stands in for it. A node that ran it before keeps its books as they were, but the scheme no longer starts and cannot be added.

The account's config

The external asset, your node's account on a network, has a config of its own, apart from its schemes. Set it with dassie setup --asset, or with SetAssetConfig in the owner's API. An account already running keeps its old config until the node restarts. The config is JSON, each field optional; empty takes the network's defaults:

server

The XRP Ledger server, a wss:// URL. By default the project's proof server of that network. A server on another network than the account's stops the account.

faucet

The faucet an account without funds asks, an https:// URL, or null to never ask. By default the testnet's. Mainnet takes only null.

publishers

The validator list publishers whose lists the node checks the ledger's proofs against. By default the network's own; a list you give replaces them.

$dassie setup --passphrase-file /root/phrase.txt \
  --asset 'xrpl-testnet-account/0={"server":"wss://xrpl.example.net"}'

Hub schemes

A hub scheme is your node's account in one settlement hub, and the way it settles with its peers. A node is in at most one hub per asset, and the scheme's ID names that account too. Deposits into the hub leave the owner book of its asset, and withdrawals reach it, so a node in a hub runs that owner book as well. A DSUSD hub needs the XRP book beside it, which pays its escrow's fees.

A hub scheme's config is the rules of its hub, {"rules":"<hex>"}, which the hub's founder gives out. Where the release has a default hub built in for the scheme, adding it without a config joins that hub, and the node stores the hub's rules as the config, so the scheme stays in that hub whatever a later release's default is. To see and move the funds in a hub, use the wallet's Hubs page or dassie hub.

hub-xrpl-testnet-xrp

XRP in a hub on the XRP Ledger testnet, on ledger hub-xrpl-testnet-xrp+xrp, funded from xrpl-testnet-xrp. This is the hub dassie setup joins by default in the test realm.

hub-xrpl-testnet-dsusd

DSUSD in a hub on the XRP Ledger testnet, booked as USD on ledger hub-xrpl-testnet-dsusd+usd, funded from xrpl-testnet-dsusd, with xrpl-testnet-xrp paying its escrow's fees.

hub-xrpl-xrp

XRP in a hub on the XRP Ledger mainnet, on ledger hub-xrpl-xrp+xrp, funded from xrpl-xrp. Real money, in the live realm, which nodes refuse today.

hub-xrpl-rlusd

RLUSD in a hub on the XRP Ledger mainnet, booked as USD on ledger hub-xrpl-rlusd+usd, funded from xrpl-rlusd, with xrpl-xrp paying its escrow's fees. Real money, in the live realm, which nodes refuse today.

Why peers settle only over hubs

Default hubs

A release can build in a default hub for each hub scheme, with that hub's rules. Where a scheme has one, the wallet offers it, and adding it without a config joins that hub. Where it has none, the wallet does not offer it, and you add it only with the rules of a hub as its config. dassie setup joins the testnet's XRP hub unless --hub says otherwise.

dassie hub status shows a hub's ID on its ID line. The testnet's two default hubs have these IDs, and their escrows these addresses on the XRP Ledger testnet:

hub-xrpl-testnet-xrp
  ID      5b4e3d7b99aa06f03642f872efd905f32a6183a09d2faf02327f49d6f3d2c308
  Escrow  rwLtDoCscTc6YWo82BefD27BPmQZVYprV

hub-xrpl-testnet-dsusd
  ID      8a33d0f5759f5411e1118b98adb1ab9f2831323ca01ab1287c372ccb72a11f3d
  Escrow  rDkVZmGMF5PEWnADsnqfTNr8WQDdrXpzS5

Mainnet's default hubs are not there yet: they come once the project's validators on mainnet found them. Until then, a mainnet hub scheme runs only with the rules of a hub as its config. What's next

To found a hub of your own, see Found a hub.

Why a scheme stays in the hub it was added with

For testing

stub

Test dollars with no ledger beneath them, on ledger stub+usd, for development and tests. Anyone peered over it can mint money, so only a build with debug assertions runs it: the local dev network, the tests and the simulations. A release neither offers nor runs it.

Its config picks its kind: {"trust":"unlimited"} or empty, whose peers never settle, or {"commitments":N}, which behaves like a hub's member without a hub.

Why the stub stays out of releases