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 the first ledger it keeps your money on, and join the testnet's settlement hub so that your node has peers.
On this page
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.
- Choose Generate a new wallet.
- 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.
- Choose I have written it down.
- The wallet asks for one of the words by its number. Type it, or its first four letters, and choose Verify.
- The wallet sets your node up. Once it is done, it opens on the choice of your first ledger.
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.
- Choose Recover an existing wallet.
- 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.
- For a word you cannot read, type ? in its place, or tap the word to mark it unreadable.
- 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 your first ledger
A ledger is where your node keeps your money in one asset. Until you add one, the wallet shows only Choose a ledger type, with the node ID you are signed in to. A note at the top says that you are on the Dassie test network, and that none of the choices use real money.
- Pick XRP Ledger Testnet Settlement to start. It holds test XRP on the XRP Ledger testnet, which its faucet hands out for free. DSUSD on the XRP Ledger Testnet Settlement holds Dassie's test dollar token, and takes a little more to fund.
- Choose Select → next to it. The node adds the ledger, and the wallet opens on your ledgers.
The node starts on test XRP right away: while its account on the testnet does not exist yet, it asks the faucet itself. Add and fund a ledger shows how to follow that, and how to add more.
Join the testnet's hub
Your own ledger peers with no one. Peers settle with each other through settlement hubs, and the testnet's two hubs, one of XRP and one of DSUSD, are built into your release. Four of the testnet's bootstrap nodes keep them. The wallet joins none for you, so add the XRP hub yourself:
- Open Ledgers and choose + Add ledger.
- Choose Select → next to XRP in a settlement hub on the XRP Ledger Testnet Settlement.
The hub is funded from your XRP Ledger Testnet ledger, so pick that one first, as above. Your node then looks for peers in the hub by itself. Your hubs shows your account there.
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.
