A server without a public IP

A server at home, behind a router, or on a network that lets nothing in can still run a node. Without a domain name, it joins as a periphery node: it connects out to a few core nodes and is reached through them.

How it works

A node with a domain name becomes a core node once its uplinks promote it: other nodes reach it at its address, and it forwards payments for them. A node without one is a periphery node for good:

• it peers only with core nodes, its uplinks, over connections it opens itself, so nothing needs to reach it from outside;
• its addresses lie beneath its uplinks', and payments reach it through them. It forwards nothing for others;
• wallets and apps that pay it with Open Payments reach it through a relay, a front door that it keeps a connection to.

A periphery node learns which core nodes there are from the bootstrap nodes. The test network's five bootstrap nodes are built into Dassie, so the node finds the network with nothing to set.

A relay is built in too: the front door at dassiepay.net. So wallets and apps reach the node at <node ID>.dassiepay.net, also with nothing to set. That front door is run by the Dassie project, and it learns when your node is online (below).

This is how the desktop app runs its node too, with the same defaults, so the same holds there (How others reach you). Core and periphery explains the two kinds of node.

What you need

• Linux with systemd, on x86-64 or arm64, as for any server node.
• A way out to the internet on UDP port 443. Where UDP is blocked, the node reaches core nodes over a WebSocket on TCP port 443 instead, by itself.
• TCP ports 80 and 443 and UDP port 443 free on the machine itself. The node listens on them as any node does, even though nothing from outside needs to reach them. It doesn't start while UDP port 443 is taken.
• A settlement hub that core nodes are in too. On the test network, that's the XRP hub (below).

You don't need a public address, a domain name, open ports on your router, a certificate, or a relay of your own.

Install and set up

1. Install Dassie as on any server:

   $curl --proto =https --tlsv1.2 -sSf https://sh.dassie.land | sh

   Don't run dassie init: it sets a domain name, and a node with one is a core node.

2. Set the node up with your recovery phrase. The setup page is on the server itself, so reach it through an SSH tunnel. On your own computer:

   $ssh -L 8443:localhost:443 you@your-server

   Then, in that SSH session, print the setup link:

   $sudo dassie setup-url
   https://localhost/setup/…

   Open it in your browser with the tunnel's port, https://localhost:8443/setup/…. The browser warns about the node's own certificate; that's expected for localhost. Follow Set up your wallet from there. Later, the same tunnel takes you to the wallet at https://localhost:8443/.

   For a node nobody logs in to, set it up from a phrase file on the server instead, with dassie setup (Headless setup). On the test network, dassie setup joins the XRP hub too, unless you name other hubs with --hub. Set up in the wallet, it joins no hub until you add one (Joining a hub).

3. Check on it:

   $dassie status

   A periphery node's status names its uplinks and its relay, and whether each is connected, and gives as its address its name for Open Payments:

     Address      https://<node ID>.dassiepay.net/ (Open Payments only)
     Network      a periphery node: it registers with no bootstrap node, and reaches the network through its uplinks
     Relay        orksjbmxvscmvfv3apa6xwencnxw2rt7t655esa at https://relay.dassiepay.net, connected

   While the relay is connected, wallets and apps reach the node at that name (below).

Why it works this way

Bootstrap nodes

The test network's five bootstrap nodes are built in, and a node uses them unless you name others. You only set them to join another network, such as one you run yourself. Name its bootstrap nodes in DASSIE_BOOTSTRAP_NODES, as a JSON list of entries, each with a node's ID, URL and two keys, the same form as a relay's entry (below). Whoever runs the network gives you the entries. Set it in a drop-in:

$sudo systemctl edit dassie.service

[Service]
Environment='DASSIE_BOOTSTRAP_NODES=[{"id":"<node ID>","url":"https://boot.example.com","publicKey":"…","slhDsaPublicKey":"…"}]'

$sudo systemctl restart dassie.service

An empty list, [], makes the node run alone, and its status says so:

  Network      no bootstrap nodes are set (DASSIE_BOOTSTRAP_NODES), so the node runs alone

Uplinks

Once set up, the node finds its uplinks itself: it asks core nodes that the bootstrap nodes list and that share a settlement hub with it, until a few have said yes. Each uplink is a peering like any other.

$dassie status
# …
  Uplinks      <node ID> at https://<core node>, connected

If it says none yet, no payment reaches the node. Check that the node is in a hub the core nodes are in too, such as the test network's XRP hub (Joining a hub), and that it can reach the internet on UDP or TCP port 443.

Pinning uplinks

To reach the network only through core nodes you choose, pin them by node ID in DASSIE_UPLINKS, separated by commas, at most 128. Set it in a drop-in:

$sudo systemctl edit dassie.service

[Service]
Environment=DASSIE_UPLINKS=<node ID>,<node ID>

$sudo systemctl restart dassie.service

The node then asks only those nodes, and looks for as many uplinks as you named. A pinned node it doesn't know yet, or can't reach, it waits for; it asks no other meanwhile. A peering it made before with another node stays until you end it in the wallet's Network page, and its payments may still go that way until you do.

A pinned node must share a hub with yours, as any uplink must. A node with a domain name ignores the list, and says so in its log. A market maker's node pins its uplinks so, to trade with the core nodes it names (Run a market maker).

The relay

Wallets and apps that pay with Open Payments find a node by its name, over HTTPS. A periphery node has no address they can reach, so it keeps a connection open to a front door, which passes their requests on.

By default, that is the front door at dassiepay.net, whose entry is built into Dassie. Once the node is set up, it connects there by itself, and its name, <node ID>.dassiepay.net, reaches it. That is the address its status gives, and the payment pointer the wallet shows. The front door reaches the node only over this connection; it never dials the node.

Here is what the default costs you. The front door is a machine the Dassie project runs. It learns when your node is online, from which address, and since when. It also reads the Open Payments requests it passes on to your node, as every front door does. While it is down, nobody reaches your node at its name there; payments over Interledger still reach the node through its uplinks, and it can send. If that doesn't suit you, name another relay, or none (below).

The wallet doesn't ask you about the relay yet. A step in the wallet that explains the choice, and what the default costs, is planned. What's next

Choosing a relay

To use another front door, such as one you run yourself (Run a front door), name it in DASSIE_RELAY, with the entry it prints, and add its name for your node to DASSIE_PUBLIC_NAMES:

[Service]
Environment='DASSIE_RELAY={"id":"<front door ID>","url":"https://relay.example.com","publicKey":"…","slhDsaPublicKey":"…"}'
Environment=DASSIE_PUBLIC_NAMES=<node ID>.example.com

The entry names the front door's node ID, its URL and its two keys, and the node's connection is pinned to those keys, so nobody else can stand in for it. A front door's operator finds the entry in its log. The single quotes keep systemd from reading the entry's double quotes.

Restart the node after each change. Its status then names the relay:

$dassie status
# …
  Relay        <front door ID> at https://relay.example.com, connected

connecting is normal for a few seconds after a start. If it says the relay isn't connected for longer, Open Payments clients can't reach the node through it; payments over Interledger still reach it through its uplinks.

A node keeps one relay. With another, the dassiepay.net front door no longer reaches it, so its name there reaches no one. The node still gives that name first, and the wallet warns you not to hand it out: give its name at your front door instead.

To keep no relay at all, set DASSIE_RELAY empty:

[Service]
Environment=DASSIE_RELAY=

Then no wallet or app reaches the node over Open Payments, and its status says so:

  Relay        none (DASSIE_RELAY names none), so Open Payments clients cannot reach the node

Payments over Interledger still reach it through its uplinks, and it can send. The variables are listed in Environment variables.

Why there is a default relay, and what it learns about your node.

Behind a proxy

Where UDP is blocked, the node carries its connections to core nodes and its relay over a WebSocket on their HTTPS port. On a network whose only way out is an HTTP proxy, it sends that WebSocket through the proxy named in https_proxy or HTTPS_PROXY, as other programs read it, and goes straight to the hosts in no_proxy or NO_PROXY. It takes only an http:// proxy. A setting it can't use doesn't stop it: it warns in its log at start and goes on without the proxy.

Set the proxy for the node in a drop-in, as above:

[Service]
Environment=https_proxy=http://proxy.example.internal:3128

Only a node without a domain name does this. A core node talks to other nodes over UDP alone.

What a periphery node doesn't do

• It forwards no payments for others, and earns no fees for that.
• It registers with no bootstrap node, and isn't in the node list.
• It offers its peers no swaps, and answers no request for its snapshot. It swaps with its uplinks only when you ask, or toward targets you set (Exchange-rate settings).
• It takes no peers of its own: no node can use it as an uplink.

If the server later gets a public address and a domain name, run sudo dassie init: the node becomes a core node. Its peerings as a periphery node end, and it peers again as a core node.

A node can't yet be reached under a domain of your own through a front door, and a node with a domain name doesn't yet start in the periphery and earn its place in the core. What's next