Menu

Set up your wallet

A new node waits for its owner. You claim it once, in your browser, with a recovery phrase: a new one the wallet makes for you, or one you already have. Then you choose what your node holds, such as test XRP, and it joins the testnet's settlement hub of each, where it finds its peers.

On this page
  1. Open the setup page
  2. Make a new phrase
  3. Or bring your own phrase
  4. Choose what your node holds
  5. Without a browser
  6. When a step fails

Open the setup page

The desktop app opens the setup page by itself the first time it starts. On a server, print the setup link:

$sudo dassie setup-url

dassie init prints the same link when it finishes. The link holds a token, and whoever opens it first claims the node, so keep it to yourself until you have used it. It stays the same until setup is done, also when the node restarts.

Until your node has a domain name, the link names localhost, so it opens only on the server itself. To open it from your own computer, forward a port over SSH, and open the link with localhost:8443 in place of its host and port:

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

Your browser then warns you about the certificate: the node made it itself, since no certificate authority vouches for localhost. That is expected here.

If you open the node's address without the link, the wallet says the node is ready for setup and tells you to run sudo dassie setup-url.

Make a new phrase

Your recovery phrase is your wallet. It is 20 words, and every key your node has comes from it. Nobody can make it again for you.

  1. Choose Generate a new wallet.
  2. Write the 20 words down in order, with their numbers. The first four letters of each word, shown in bold, are enough: a metal plate made for 24 words holds them. Under the words, the wallet shows the day the phrase was made.
  3. Choose I have written it down.
  4. The wallet asks for one of the words by its number. Type it, or its first four letters, and choose Verify.
  5. The wallet sets your node up. Once it is done, it asks what your node holds.

The phrase never leaves your browser. The wallet works out your node's key from it and sends the node only that key. Read Back up your phrase before you put anything on the node.

Or bring your own phrase

To bring back a node you had before, use its phrase. Its node ID comes back with it, and so does everything the phrase holds the keys to.

  1. Choose Recover an existing wallet.
  2. Type your 20 words in order. The first four letters of each are enough. As you type, the wallet shows each word as it reads it, and flags a word that is not on the list.
  3. For a word you cannot read, type ? in its place, or tap the word to mark it unreadable.
  4. Choose Open wallet. If the wallet had to restore a word, it shows the phrase with the restored words marked. Compare them with your copy, and choose Use these words.

Bring your node back says what comes back with a phrase, and what you set up again.

A phrase from Dassie 0.2 or earlier doesn't work. The testnet was reset for 0.3.0, and those phrases were of an older kind, 12 or 24 words, that a node no longer reads. Make a new phrase instead.

Choose what your node holds

Until your node holds an asset, the wallet shows only Choose what your node holds, with the node you are signed in to and a Log out button. On the testnet, a note at the top says that nothing here is real money.

  1. Tick the assets you want. Test XRP is ticked to start with: XRP on the XRP Ledger testnet, which its faucet hands out for free. Test DSUSD is Dassie's test dollar token, and takes a little more to fund. Its ledger takes its fees in XRP, so ticking it ticks Test XRP too.
  2. Choose Continue →. For each asset, your node adds your own account on the XRP Ledger testnet and joins the testnet's settlement hub of the asset.

Peers settle with each other only through settlement hubs, so that is where your node finds its peers. The testnet's two hubs, one of XRP and one of DSUSD, are built into your release, and four of the testnet's bootstrap nodes keep them. There is no hub to join by hand.

The node starts on test XRP right away: while its account on the testnet does not exist yet, it asks the faucet itself, and then moves what the hub needs into it. Add and fund an asset shows how to follow that, and how to add more later. Your hubs shows your account in the hub.

Without a browser

A node that nobody sets up in a browser, such as a market maker's, can be set up on its own host with dassie setup, from a phrase in a file. It does what the wallet does and sends the node only the key. On the testnet it also joins the XRP hub, unless --hub names others, or none. Headless setup walks through it, and the command reference lists its options.

When a step fails

The wallet says What to do
This device's clock and your node's are more than a day apart. A phrase records when it was made, so the wallet makes one only while your computer's clock and the node's agree. Set the wrong one right, and try again.
That is a 12-word phrase (or 24). That is another wallet's phrase, or one from Dassie 0.2 or earlier. A Dassie phrase has 20 words, and older ones can no longer be read. Make a new phrase.
Too many words are wrong or unreadable. Check each word against your copy. Mark a word you cannot read rather than guess it. How much the phrase corrects
This phrase says it was made on a later date. Your computer's clock is behind, the words are not your phrase, or the clock of the computer that made it was ahead. In that last case, set this clock past the date it names.
The node could not be reached. Check that the node runs (dassie status) and that you can reach its address, then choose Back and try again.

If the wallet cannot ask your node for its state at all, it opens on Cannot reach your node instead of a setup step. Make the same checks, then choose Try again.

Once a node is set up, its setup link no longer works: the wallet asks for the phrase to sign in instead. Setup happens once, and a node never changes its phrase.

Why it works this way: how the token guards a new node, and why only the key reaches it.

A kopje of granite blocks against the sun, in veld grass; one dassie climbs its slab, one keeps lookout on top inside the sun, and one sleeps on the next rock; on a wide screen, a pair sits on a kopje to the left