Joining the network

A new node finds the network through a few bootstrap nodes, peers with neighbors it can settle with, and from then on takes part in routing like everyone else. This page walks through each step.

The journey in short

1. Your node registers with each bootstrap node. Each one checks that your node really answers at the address it gave, then lists it.
2. The other nodes read the bootstrap nodes' lists. Once most of the bootstrap nodes list your node, the others count it as a member.
3. They learn your node's link state: its signed statement of where it is, which hubs it settles over and who its neighbors are.
4. Your node looks for peers that share a settlement hub with it, and they look for it.
5. Once its peers list your node as a neighbor too, the rest of the network can route payments to it and through it.

This is the journey of a node with a public hostname, which its uplinks promote into the core. A node without one, such as the desktop app or a server behind a router, joins as a periphery node: it registers nowhere and reaches the network through the core nodes it peers with. See Core and periphery.

Wallets and apps reach a node without a hostname through a relay. Dassie has the dassiepay.net front door built in as the default one, so such a node is paid at <node ID>.dassiepay.net with nothing to set, the desktop app's node too. That front door is a machine the project runs: it learns when your node is online, and reads the Open Payments requests it passes on. Relays and front doors says how to choose another relay, or none.

Bootstrap nodes and the majority

Every node carries a list of bootstrap nodes, each named by its node ID, its URL and its two public keys. The node checks every entry against its ID when it starts, and refuses to start on a bad one. Bootstrap nodes take registrations and serve a list of the nodes registered with them.

• Registering. Your node registers with every bootstrap node by itself when it starts, and renews before its registration runs out a day later. Before it lists a new node, a bootstrap node asks that node for its own link state at the URL it gave, over a QUIC connection tied to its key, and fetches its discovery document there over HTTPS, which needs a certificate a public authority issued. That proves the URL really serves that node, both ways.
• The majority. Nodes check the bootstrap nodes' lists every minute. A node is a member once more than half of the bootstrap nodes in the configured list name it. It is half of all of them, not of those that happen to answer, so silencing a few bootstrap nodes cannot change who is a member.
• The freeze. When too many lists go stale, because bootstrap nodes are down or a node is cut off from them, membership freezes: nobody is dropped until most lists are fresh again, so a few bootstrap nodes going offline never empties the network. New members still join meanwhile.
• Free, so throttled. Registration costs nothing today. To keep it from being abused, bootstrap nodes limit how fast new nodes register and how many come from one network or one address.

Registration fees, which would let bootstrap nodes take registrations without throttling them, are not there yet. What's next

The project runs the public testnet's five bootstrap nodes, boot1 to boot5.dassie.xyz, in one cloud region and spread over its zones, so that two of them down leave three of five, still a majority. Their entries are built into dassie, so a new node finds the network by itself. Four of them, boot1 to boot4, also keep the testnet's two settlement hubs, one for XRP and one for DSUSD, as their validators.

You can replace the list with DASSIE_BOOTSTRAP_NODES, or set it to [] to run a node on its own. Its format is on Environment variables.

Why membership works this way, and why the testnet runs five bootstrap nodes.

Link states

Each core node signs a short statement about itself, its link state, and the network passes it around. It holds:

• the node's public keys, from which its node ID follows;
• its URL, where other nodes reach it;
• its neighbors, the peers it is ready to route through;
• its settlement offers: each hub it takes peers over, with its account there if it has one yet;
• the UDP port where it answers requests for its snapshot, if it offers swaps.

A node issues a new link state when it starts, when any of this changes, and every hour anyway. It sends the new one to its peers at once, and they pass it on to theirs. Peers also send each other their link state every few seconds as a heartbeat, and every node slowly sweeps through the nodes it knows, asking for anything it missed. A link state is fresh for a few hours; routing uses only fresh ones, so a node that goes away drops out by itself.

A node keeps only link states of nodes it has a reason to know: itself, its bootstrap nodes, its peers, members of the majority, and, on a bootstrap node, the nodes registered with it. Gossip alone cannot fill its tables.

Peering needs a shared hub

Peers settle only over settlement hubs, so two nodes peer only when they are in the same hub. One of them at least must already have an account there: a node without one is paid into the hub by its peer, once it is owed enough to open an account.

• How many. Your node looks for two peers by itself and holds at most eight. It accepts requests from others only up to a cap below that, so requests alone cannot fill every place.
• Whom it asks. Nodes it knows whose link states are fresh and offer a hub your node is in, one at a time. Nodes its routes cannot reach yet come first, so separate groups of nodes find each other.
• Not before the ledger is seen. A node takes no peers on a hub until it has synced with it at least once, so it can tell a peer's payment from its own deposit.
• Every shared hub counts. Two nodes in more than one hub together settle over each of them, within one peering. A hub they both join later is added; a hub that has failed for a day is dropped, and a peering left with no hub ends.
• When it fails. A refused or failed request waits longer before each new try. When two nodes ask each other at the same moment, the request of the lower node ID wins.

On the testnet, dassie setup joins the XRP hub unless --hub names other hubs, or none. In the wallet, your node joins a hub when you add it on Ledgers: XRP in a settlement hub on the XRP Ledger Testnet or DSUSD in a settlement hub on the XRP Ledger Testnet. Either way, it then looks for peers among the hub's other members, and Your hubs shows where it stands.

Mainnet hubs are not built in, and a node refuses the live realm anyway. What's next

Why every shared hub is part of one peering

Routing

Each node works out its own routes from the link states it holds. It searches outward from itself, breadth first, over links that both ends list. A node cannot claim a link to someone who does not list it back.

• For every node it can reach, your node keeps up to four first hops on the shortest paths there. Where more peers would do, it keeps its own few, chosen by a secret derived from its key.
• Each packet draws its next hop from those, weighted by what each peer earned your node. See Trust grows sideways.
• A packet never goes back to the peer it came from, and never takes a longer path than the shortest.
• Routes are worked out again whenever a link state changes, and as old ones go stale.
• A periphery node routes everything through its uplinks, and nobody routes to it directly: payments reach it at an address beneath one of its uplinks.

A peer that runs short of room or goes quiet is taken out of its neighbors' link states quickly, which takes it out of everyone's routes. Ending the peering takes much longer. See Withdraw readily, end reluctantly.

How routing works in full

Watching it happen

dassie status shows how many bootstrap nodes list your node and who its peers are. Only if you set DASSIE_BOOTSTRAP_NODES to [] does it say that the node runs alone. The wallet's Network and peers page shows each node your node knows, how far away it is and which hubs it settles over. If your node stays alone, start with Troubleshooting.