The dassie command

One binary, dassie, runs your node and talks to it. This page lists every subcommand and option it has, in the order you are likely to meet them.

Usage

$dassie <command> [options]

-h, --help

Prints the list of commands and options, and exits.

-V, --version

Prints dassie and the version, such as dassie 0.3.0, and exits.

Most commands talk to the running node over its IPC socket. Using that socket is administering the node, so only root and members of the group dassie-users may. The installer adds you to the group; log in again afterwards for it to take effect. The command looks for the socket at DASSIE_IPC_SOCKET_PATH if you set it, and otherwise at /run/dassie.sock, then $XDG_RUNTIME_DIR/dassie.sock. See Files, ports and sockets.

The commands that talk to the node are init, status, setup-url, setup, pair and hub. If nothing answers on the socket, they say the daemon is not running and how to start it.

Exit codes

dassie daemon

Runs the node in the foreground, for a process manager such as systemd. The installer's dassie.service runs dassie daemon --runtime=systemd. It reads its settings from the environment, and stops at once, naming the variable, if one has a value it cannot use. SIGTERM or SIGINT stops it cleanly.

--runtime standalone|systemd

Where the sockets come from. systemd takes them from the socket units, by name, and reports readiness to systemd. standalone binds them itself. Without this option the node uses systemd when systemd passed it sockets, and standalone otherwise.

--http-port <port>, --https-port <port>

Standalone only: listen for HTTP and HTTPS on these TCP ports instead of 80 and 443. The two go together. QUIC listens on UDP at the HTTPS port, since peers dial QUIC at the port in the node's URL.

--listen <address>

Standalone only: listen on this one IP address instead of every address.

--feed-listen <address:port>

Standalone only: the UDP socket that answers requests for the node's snapshot. By default it is the HTTPS listener's address on port 7768. If the node cannot bind it, it runs, answers no request for its snapshot, and says so in its log.

It exits with 1 if it could not start: a bad variable, a socket it could not bind, a database it cannot open, or an engine that fails to start. A node does not run without its UDP socket for QUIC.

How the runtimes differ

dassie init

Gives a server node its public name and a certificate. It sets the hostname, asks the node to order a certificate from Let's Encrypt over ACME, shows how the order goes, and prints the link that finishes setup in your browser, or, once the node is set up, its address. The node runs the order itself; init only shows it. For the order to work, the name must point at this host and TCP port 80 must be reachable from the internet.

In a terminal it asks for what you did not give as an option. Without a terminal, --hostname is required, and so is --agree-tos when it orders a certificate. If the node already has a certificate from a CA, it asks whether to skip ordering one; without a terminal it skips.

A node with a hostname answers under it alone. So once init sets one, the node closes its connection to the default relay, relay.dassiepay.net. A relay you named in DASSIE_RELAY stays.

--hostname <name>

The node's public DNS name.

--email <address>

A contact for the ACME account, which the CA may write to about your certificate. Optional.

--agree-tos

Agree to the CA's terms of service without being asked.

--acme-directory <url>

Order from this ACME directory. Once an order from it succeeds, the node keeps it, for renewals and for every later init that names none. Without this option, the node orders from the directory it keeps, Let's Encrypt's at first.

--acme-staging

The same as --acme-directory with Let's Encrypt's staging directory, whose certificates browsers do not trust. Useful for a trial run. Once it succeeds, the node keeps staging too. To go back, run sudo dassie init in a terminal with --acme-directory https://acme-v02.api.letsencrypt.org/directory, and answer No when it asks whether to skip ordering.

--skip-acme

Keep the certificate the node has now, whatever it is.

More on certificates in Certificates. A node without a public IP needs no init: see A server without a public IP.

dassie setup

Sets the node up from your recovery phrase, on the node's own host, without a browser. It does what the wallet does: it derives the node key from the phrase and hands the node only the key, never the phrase. Then it waits for the node's engine, sets the config of the external assets you name, adds the settlement schemes you name, and joins settlement hubs. Each step prints one line. A walk-through is in Headless setup.

The phrase names its realm, so no option does. A phrase of the live realm is refused, and the node stays as it was. The realm is fixed once the node is set up.

Running it again changes nothing that is already in place, so a unit can run it at every boot. A node already set up with another phrase is refused, and nothing is changed: with exit code 1 if the node runs another realm than the phrase's, which it checks first, and with 3 otherwise. A phrase that needs correcting is refused, since no one is there to confirm the correction, and so is one made more than a day after the host's clock.

--passphrase-file <file>

Required. The file that holds your recovery phrase, and nothing else. It is read once; no line the command prints names it. Keep the file readable by root alone.

--asset <id>=<config>

The JSON config of an external asset, set before any scheme is added, such as the XRP Ledger server of xrpl-testnet-account/0: --asset 'xrpl-testnet-account/0={"server":"wss://…"}'. Repeatable, at most 8.

--scheme <id>[=<config>]

A settlement scheme to add if the node does not run it yet, with its JSON config if it takes one. Repeatable, at most 16. The ids are in Schemes and hubs.

--hub <scheme>|none

Join the default hub of this hub scheme's asset, such as hub-xrpl-testnet-dsusd. For each hub, it first adds the owner books the hub is funded from, which peer with nobody, then the hub's scheme. Repeatable. none joins no hub, and goes with no other --hub.

Without --hub, setup joins the testnet's XRP hub, hub-xrpl-testnet-xrp. This release has two default hubs built in, the testnet's XRP hub and its DSUSD hub, both kept by four of the bootstrap nodes, boot1 to boot4. A --hub of another realm than the phrase's is refused before anything changes.

To join a hub other than the default, add the owner books it is funded from, then its scheme with the hub's rules as the config: --scheme <hub scheme>='{"rules":"<hex>"}'. Schemes are added before hubs are joined, so setup then leaves that hub's scheme as it is.

--no-hub is refused, with a pointer to --hub none.

Why it works this way

dassie setup-url

Prints the link that finishes setup in a browser. The link holds the setup token, so treat it as a secret until setup is done. Once the node is set up, it says so and exits with 1: log in to the wallet with your phrase instead. It takes no options.

dassie status

Shows how the node is doing, in a few lines: its version, address and certificate, whether it is set up, the network (and, for a node without a public IP, its uplinks), the relay it keeps and whether it is connected (a node without a public IP that keeps none says so), its settlement hubs, whether it answers requests for its snapshot (the line labeled Rate feed), the hubs it validates or founds, the last update, what its engine counted since it started, its peers and its ledgers. It gives a hint only where something is wrong.

It names no secret, so you can paste its output where you ask for help. If the node is not running, it says so, still shows how the last update went, and exits with 1. It takes no options. How to read it is in Check on your node.

dassie pair

Prints a code that pairs an owner app with the node. Enter it in the app within five minutes. It works once, and running dassie pair again replaces it. It takes no options.

The owner apps that take this code are not there yet. What's next

dassie hub

Your node's account in each settlement hub it is in, and moving your funds between a hub and your own XRP Ledger account. Every command that acts on one hub names it first by the scheme over it, such as hub-xrpl-testnet-xrp, exactly as dassie hub status shows it. That way a script means the same hub once the node is in more than one.

Amounts are in the hub's asset, XRP or DSUSD, with up to nine decimals, such as 2.5. They must be more than zero.

dassie hub status

Also plain dassie hub. For each hub whose scheme runs: the hub's ID, the account's number and balance, whether it is in step with the hub, how many validators answer, what was deposited and withdrawn, the target the node keeps the account near, yours or the default, the floor and ceiling either side of it, whether the node moves funds by itself, a move on its way, the pool against the peerings over the hub with the newcomers it refuses (As many peers as your funds cover), and the holds toward and from each peer, each of the node's own with that peer's share of the hub's funds. A move the other side still has not shown ten minutes after it was made, or after the XRP Ledger applied it, is marked late.

$dassie hub status

dassie hub deposit <scheme> <amount>

Moves the hub's asset from the node's XRP Ledger account into the hub. If the node has no account in the hub yet, this deposit opens one. Moving funds by hand pauses the node's own moves for that hub for an hour, so they do not undo yours.

$dassie hub deposit hub-xrpl-testnet-xrp 2.5

dassie hub withdraw <scheme> <amount>

Moves the hub's asset from the hub back to the node's XRP Ledger account. From a DSUSD hub, the node first checks that the hub's escrow has the XRP it pays its fees with, and tops it up if not; if it asks you to, try again shortly. This pauses the node's own moves for an hour too.

dassie hub auto <scheme> on|off

Lets the node move funds to and from the hub by itself, or not. With it on, the node deposits when the account falls below its floor, and withdraws to your own account what goes beyond the ceiling.

dassie hub target <scheme> <amount>|default

Sets how much the node keeps in the hub: what it put in, its balance, its reserves and its holds for peers. The floor and the ceiling follow, a tenth below and above it. default goes back to the default, a thousand of the largest packets: 100 XRP, or 100 dollars in a DSUSD hub. The node remembers the target, and refuses one below ten of the largest packets, or so low that the account's reserve alone would fill it; the message says the least.

$dassie hub target hub-xrpl-testnet-xrp 10
$dassie hub target hub-xrpl-testnet-xrp default

dassie hub give-up <scheme>

Gives up a move that is late: the hub has not shown it for a while. The node forgets the move and books nothing; if the other side shows it later, it is booked then. Its own moves for that hub then wait until you turn them on again with dassie hub auto, or move funds yourself.

dassie hub found <node ID>@<host:port>…

Founds a new settlement hub with these nodes as its validators, with your node as its sponsor, on the XRP Ledger network of your node's realm: the testnet, since nodes refuse the live realm. Name 4 to 16 validators, each once, as <node ID>@<host:port>. Every validator must accept. The node pays the hub's escrow from its XRP account on that network. It prints the founding's nonce; dassie hub foundings shows how far it is. The full steps are in Found a hub.

--terms <file>

A JSON file, at most 8 KiB, of the terms that differ from the starting ones.

--escrow-funding <XRP>

How much XRP funds the escrow: its reserves and the fees of its setup and of the hub's own transactions. By default 2. You may give more, never less than the ledger's reserves and the setup's fees.

--xrpl <url>

The XRP Ledger server to set the escrow up on. By default, the server of the node's own XRP Ledger account on that network.

dassie hub foundings

Shows each hub the node is founding or founded: its stage, which validators accepted, signed the genesis and run the hub, the escrow and how many validators checked it, any problem, and, once they are fixed, the hub's rules.

dassie hub drop <nonce>

Drops a founding, named by the nonce dassie hub foundings shows.

dassie hub payout <scheme>

Shows the payout bundles the node kept of the hub over that scheme: which validators signed the payout of which block. Once a quorum signed the same set, it prints the transactions to submit to the XRP Ledger, in order. Validators sign a payout once a hub ended or stalled, and anyone may submit it, so you are paid out whether or not a validator is still up. While the hub runs there is nothing to show.

dassie update

Updates Dassie to the newest release on the mirror, once the release's signature and sums check out. It installs the new version beside the old one in /opt/dassie, switches to it, restarts the node, and goes back to the version before if the new one does not come up. The installer's timer runs it once a day; you can run it yourself as root. See Updates and rollback.

It only moves forward on its own, and it does not try again a version that failed to start here until the mirror offers a newer one. It runs only from an installer's layout, /opt/dassie/<version>/bin/dassie; on NixOS your flake decides the version instead.

-f, --force

Install even if the version is not newer, or is the one that was rolled back.

-t, --target-version <version>

Install this version instead of the newest, older ones included. Stop dassie-update.timer if you want to stay there, or it moves the node forward again.

--mirror <url>

Another mirror, https:// only. By default DASSIE_MIRROR_URL, or else https://get.dassie.land.

--no-restart

Install and switch, but leave systemd and the node alone.

--unit <name>.service=<dir>

Restart this unit, whose node keeps its data in <dir>, instead of dassie.service, and install none of the release's units. For a host that runs its nodes under units of its own. On a rollback it puts back each node's database. Repeatable, at most 8; not together with --no-restart.

It exits with 1 if the update failed or was rolled back, and records how it went in /opt/dassie/last-update, which dassie status shows.

Why it works this way

dassie verify-install

Checks that this binary works on this host: SQLite, TLS, the wallet built into it, and a version the updater can read. Then it names the release key it trusts for updates. The installer and the updater run it before they switch to a new binary. It takes no options.

$dassie verify-install
Verifying that SQLite is working...
Verifying that TLS is working...
Verifying that the wallet is built in...
Verifying the version...
Updates are verified with release key 5D960652FE941432.
Success! Dassie appears to be installed correctly.

dassie front-door

Runs a front door, which is not a node. It serves Open Payments at <node ID>.<domain> for the nodes that keep it as their relay, and at <name>.<domain> for whoever holds a name, as the registrars among the bootstrap nodes list it. The project runs the one at dassiepay.net, which a node without a hostname keeps by default; a node keeps yours when its DASSIE_RELAY names it. Each option overrides its DASSIE_FRONT_DOOR_* variable. Setting one up is in Run a front door.

--domain <name>

The domain it serves nodes under, of at least two labels. By default dassiepay.net.

--https-listen <address:port>

HTTPS, on TCP. By default [::]:443.

--quic-listen <address:port>

QUIC, on UDP. By default [::]:443.

--certificate <file>

The PEM certificate chain for *.<domain>, leaf first.

--certificate-key <file>

The certificate's PEM key.

--key-file <file>

The front door's own key. By default front-door.key in systemd's state directory.

--relay-url <url>

Where nodes dial it, as https://host[:port]. By default https://relay.<domain>.

--make-key

Make the key file if there is none, print the entry that names this front door for DASSIE_RELAY, and exit.

dassie market-maker

Trades through core nodes when what their snapshots quote and an AMM pool on the XRP Ledger leave a margin, and moves your funds back on the ledger. It is not a node: it drives one node of your own, a node without a public IP in the settlement hubs of both of the pool's assets, over that node's IPC socket. The core nodes it trades through are that node's uplinks, which DASSIE_UPLINKS pins. It reads their snapshots from its node, and swaps with the one that pays best, over their peering. Its node must swap with its peers, as a new node does: the market maker doesn't start while the node's owner has turned Swapping with peers off. It runs until SIGTERM or SIGINT. See Run a market maker.

--config <file>

Required. Its JSON config, at most 64 KiB, checked whole before anything connects: socket, its node's IPC socket; passphraseFile, the file with that node's recovery phrase; xrpl, the XRP Ledger server and the token the pool pairs with XRP; for xrp and token each, the hub's ledger it swaps on, the ownerBook that funds the hub, a tradeSize and a band; marginPpm and slippagePpm; and, if the host needs them, caFile, roots to trust the XRP Ledger server by. A config in the format before 0.3.0 is refused.

The command in the spec