Core and periphery

Not every node can be reached from the internet. Dassie has a place for both kinds: nodes with a public address form the core, and nodes without one join at the edge, as the periphery. This page explains how a periphery node connects, how others reach it, and what the machines in between can see.

Two kinds of node

A periphery node always dials out, so it works behind a home router or a firewall, with no port forwarding. It never connects to another periphery node. A server with a hostname starts in the periphery too, and its uplinks promote it into the core once they have watched it for an hour: it stayed reachable, answered at its domain name with a real certificate, settled with them and has room with them. Then it forwards payments for others, and is paid at its own address a couple of minutes later. Clearing the hostname makes it periphery again. The desktop app's node always stays periphery.

Why it works this way

Uplinks and child addresses

A periphery node finds core nodes in the node list and peers with a few of them that share a settlement hub with it. These are its uplinks. Each one gives it an address beneath its own: if an uplink is test.das. followed by the uplink's node ID, your node is reached at that address followed by a dot and your node ID. The uplink passes on whatever arrives for that address.

Dassie has the testnet's five bootstrap nodes built in, so a new node gets the node list from them and finds its uplinks on its own. Joining the network says more.

• Your node's payments go out through its uplinks, and reach whatever they reach.
• Payments to your node come in through the uplink its payment request names, one it is connected to at the time.
• Your uplinks never list your node as a neighbor, unless they promote it, and no route in the network leads to it directly: only its uplinks know it is there.

You can pin a periphery node to particular uplinks with DASSIE_UPLINKS, a comma-separated list of node IDs. A market maker's node does that: the core nodes it pins are the ones it swaps with. See Environment variables.

A periphery node does not need an account in a settlement hub before it can be paid. Its uplink pays it in once it owes it enough to open one, as Settlement hubs explains. On a core node, periphery nodes that have never paid it hold at most half of the places it keeps for periphery nodes, so new keys made for nothing cannot crowd out the ones that pay.

One kind of link: QUIC

Every link between two nodes is a QUIC connection, over UDP. Each side proves its node key in the handshake, and the other checks it against the node ID. Either side can open streams on a connection, so your uplink sends to your node over the connection your node opened. There is no other way to peer, so a node on a server does not start without its UDP port: dassie.service does not start while something else holds UDP 443.

Nodes speak version 2 of the peer protocol, dassie/2, so a node of the 0.2 releases cannot peer with one of 0.3.0 or later. Protocol versions says how versions change.

Some networks block UDP. There, a periphery node carries the same QUIC packets over a WebSocket to the core node's HTTPS port, at /quic. It tries UDP first and the WebSocket a moment later, and keeps whichever connects first. It goes through an HTTP proxy if HTTPS_PROXY names one, except to the hosts NO_PROXY lists. The QUIC inside still proves each node's key, so whatever sits between sees only ciphertext. A core node always uses UDP.

Why it works this way

Relays and front doors

Wallets and apps that want to pay your node speak Open Payments, over HTTPS. A periphery node has no address they can reach, so they reach it through someone else.

• A relay passes streams to the nodes connected to it. Every core node relays for its downlinks, and your node can keep a connection to one relay of its choice, even one it does not peer with. DASSIE_RELAY takes the relay's entry, as in the list of bootstrap nodes: its node ID, URL and keys, which a front door's operator finds in its log. The format is on Environment variables.
• A front door is a relay that also answers on the web. It takes Open Payments requests at a name under its domain and passes them through to the node. The project's front door answers for dassiepay.net, where a node without a hostname is reached at its node ID, such as https://<node ID>.dassiepay.net/pay/xrp. Anyone can run another: Run a front door.

Your node keeps one relay at a time. Dassie has the dassiepay.net front door built in, with its key, as the default relay. With DASSIE_RELAY unset, a node without a hostname, the desktop app's among them, dials it once it has its key, and is reached at <node ID>.dassiepay.net with nothing to set. A node with a hostname answers under that hostname alone, so it keeps no default relay: it closes the connection when you set a hostname, and dials again if you clear it.

• Another relay: put its entry in DASSIE_RELAY. Your node keeps that one, with a hostname or without.
• No relay: set DASSIE_RELAY empty. Your node still pays through its uplinks, but no Open Payments client can reach it, so other wallets and apps can't pay it.

The wallet and dassie status show which relay your node keeps and whether it is connected. The wallet also warns you when your dassiepay.net name does not reach your node.

The default has a cost. The dassiepay.net front door is a machine the project runs. While your node keeps it, that machine learns when your node is online, and reads the Open Payments requests it passes on. The next section says what it can and cannot see.

The wallet does not ask you about your relay yet. Choosing it during setup, with what each choice costs, is part of a guided setup that is not built. What's next

Why a node without a hostname has a default relay

What dassiepay.net can see

A front door answers on the web for your node, so it sees more than a relay does. Here is what the dassiepay.net front door, or any other, can and cannot see.

• It sees which nodes are online, from which address, and since when.
• It reads the Open Payments requests and answers it passes on, including the secret a payer uses to pay one of your payment requests. That is the nature of answering HTTPS for someone.
• It cannot answer for your node to anyone who checks. Your node signs every Open Payments answer with its node key. Dassie nodes that pay you at dassiepay.net check that signature against your node ID, so a front door cannot fake an answer to them. A client that does not check trusts the front door.
• It never sees your wallet. A front door passes on Open Payments and nothing else, and your wallet is never served through a relay or a front door.
• It cannot put anything of your node's in front of a browser: it passes on only JSON, sets no cookies, and the one page it serves at a name, which says whose node it is, is its own.

Your node uses a front door only while it keeps it as its relay: by default the dassiepay.net front door, while your node has no hostname. To stop, name another relay in DASSIE_RELAY, or set it empty for none.

What is not there yet

Finding a node's relays through records others keep, apps on your phone that reach your node through a relay, and your own domain in front of a front door are not there yet. What's next

To run a node on a server without a public IP, see A server without a public IP. For the desktop app, see How others reach you.