README.md 34.2 KB
Newer Older
Alain Mebsout's avatar
Alain Mebsout committed
1
# Dune Ledger Nano S Application
Jimmy Hartzell's avatar
Jimmy Hartzell committed
2

Alain Mebsout's avatar
Alain Mebsout committed
3
## Acknowledgments
4

Alain Mebsout's avatar
Alain Mebsout committed
5 6 7 8 9
This application is developed by [Origin
Labs](https://origin-labs.com), based on [Obsidian Systems' Tezos
app](https://github.com/obsidiansystems/ledger-app-tezos), itself
based on [Ledger's SSH and PGP agent
app](https://github.com/LedgerHQ/ledger-app-ssh-agent).
10

Chris Martin's avatar
Chris Martin committed
11 12
## Overview

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
13 14 15 16 17 18
Whether you're baking or just trading DUN, you want to store your keys
securely.  This is what a "hardware wallet" like the [Ledger Nano
S](https://www.ledgerwallet.com/products/ledger-nano-s) is for.  Your
private keys never leave the device, and it performs the signing
operations. To use a Ledger Nano S with [Dune](https://dune.network/),
you need to load Dune-specific software onto it.
Chris Martin's avatar
Chris Martin committed
19 20 21

The term "hardware wallet" can refer to several devices that store your private
keys in a secure way. The term "wallet" refers to the fact that it stores your
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
22
"money" -- in the case of Dune, it stores your dun. Remember, storing your
Chris Martin's avatar
Chris Martin committed
23 24
tokens means storing the private keys that control your tokens. But the wallet
also has other uses, including an app that helps you securely and easily
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
25
interact with the network, including creating Dune transactions and baking
Chris Martin's avatar
Chris Martin committed
26 27
blocks.

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
28
This repository contains a Ledger Nano S application with two modes:
Chris Martin's avatar
Chris Martin committed
29

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
30
  1. The "Baking" mode is for baking: signing new blocks and
31
     endorsements. For more information about baking, see
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
32
     [*Benefits and Risks of Home Baking*](https://medium.com/@dune_91823/benefits-and-risks-of-home-baking-a631c9ca745).
Alain Mebsout's avatar
Alain Mebsout committed
33
  2. The "Wallet" mode is for making DUN transactions and contract calls, originating contracts, delegation, and voting. Basically
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
34
     everything you might want to use the Ledger Nano S for on Dune besides baking.
Chris Martin's avatar
Chris Martin committed
35 36

It is possible to do all of these things without a hardware wallet, but using a
Alain Mebsout's avatar
Alain Mebsout committed
37
hardware wallet provides greater security.
Chris Martin's avatar
Chris Martin committed
38

39
This documentation was originally written when there was no GUI support, so everything is
40 41 42 43 44
tailored towards the command line.  We recommend you read this entire
document to understand the commands available, and which commands are
most appropriate to your situation. This will require judgment on how
best to meet your needs, and this document will also provide context to
help you understand that.
Jimmy Hartzell's avatar
Jimmy Hartzell committed
45

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
46
This document is not a comprehensive guide to setting up Dune
Jimmy Hartzell's avatar
Jimmy Hartzell committed
47
software. While it covers some aspects of setting up and installing
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
48
Dune nodes and clients, especially as it interacts with the Ledger Nano S,
Alain Mebsout's avatar
Alain Mebsout committed
49
you should familiarize yourself with the [Dune Documentation](https://docs.dune.network).
Jimmy Hartzell's avatar
Jimmy Hartzell committed
50

Jimmy Hartzell's avatar
Jimmy Hartzell committed
51 52 53 54 55 56 57 58
This document is also not a guide on how to use Linux. It assumes you
know how to install and configure a Linux system to your general needs,
use the command line, or configure GitHub access. Occasionally, it will
recommend things like editing a script to match your configuration.
Learning how to run commands on Linux, edit scripts, or configure your
user accounts to enable groups, is outside the scope of this document,
but resources for all of those things are available on the Internet.

59 60 61 62 63
The commands in these instructions have only been tested on Linux. If
you use any form of virtualization, e.g. docker or VirtualBox, please
consult the documentation of that virtualization system to determine
how to access USB from inside the virtualization, as that can be a
complicated and difficult process.
64

Jimmy Hartzell's avatar
Jimmy Hartzell committed
65 66 67 68 69 70 71
The commands in this document have been tested as is, and have the correct
privileges. If you find yourself using `sudo` to run commands that are not
listed as requiring `sudo`, that likely indicates a problem with your
configuration, most often the `udev` configuration. Using `sudo` for commands
that should not require it can create security vulnerabilities and corrupt
your configuration.

Michael Reinhart's avatar
Michael Reinhart committed
72
## Set up your Ledger Nano S device
Chris Martin's avatar
Chris Martin committed
73

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
74
Dune recommends a hardware wallet called the Ledger Nano S. When you first get
Chris Martin's avatar
Chris Martin committed
75 76 77 78
it and set it up, part of the setup process is generating a keypair. The keypair
will be associated with a rather long seed phrase that you must write down and
keep securely. We'll discuss that seed phrase more below. You also set a PIN
code that allows you to unlock the device so that it will sign messages. You can
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
79 80
then install the Dune app to use the Ledger Nano S to interact directly with the
Dune network (see more about this in the app instructions, forthcoming).
Michael Reinhart's avatar
Michael Reinhart committed
81
However, your Ledger Nano S will ask for confirmation before it sends your keys to sign
Chris Martin's avatar
Chris Martin committed
82 83 84 85 86 87 88
transactions or blocks, and you must confirm by physically pushing a button on
the device, and that provides some security against an attacker taking control
over your keys.

### Protecting your key

The seed phrase is an encoding of your private key itself and can be used to
Michael Reinhart's avatar
Michael Reinhart committed
89
restore your key. If you lose your Ledger device or destroy it somehow, you can buy a
Chris Martin's avatar
Chris Martin committed
90 91 92
new one and set it up with the seed phrase from your old one, hence restoring
your tokens.

nhomesley's avatar
nhomesley committed
93
Consequently, it is extremely important that you keep your seed phrase written
Chris Martin's avatar
Chris Martin committed
94
down somewhere safe. Losing it can mean you lose control of your account should
Michael Reinhart's avatar
Michael Reinhart committed
95
you, for example, lose your Ledger device. Keeping it somewhere a hacker could find it
Chris Martin's avatar
Chris Martin committed
96 97 98 99 100 101
(such as in a file on your internet-connected computer) means your private key
can fall into the wrong hands.

You will write it down on paper, along with your PIN, and store it. If you will
have a large amount of money, consider putting your paper in a safe or safe
deposit box, but at the very least keep it away from places where children,
102
dogs, housekeepers, or obnoxious neighbors could inadvertently destroy it.
Chris Martin's avatar
Chris Martin committed
103

Jimmy Hartzell's avatar
Jimmy Hartzell committed
104 105
### Protecting Your Key -- Further Advanced Reading

106
More advanced techniques for those interested in even more layers of security
107
or plausible deniability features should look at
108 109
[Ledger's documentation on this](https://support.ledgerwallet.com/hc/en-us/articles/115005214529-Advanced-Passphrase-options).

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
110
Note that Ledger devices with different seeds will appear to `dune-client` to be
Michael Reinhart's avatar
Michael Reinhart committed
111
different hardware wallets. Note also that it can change what key is authorized in
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
112 113
Dune Baking. When using these features in a Ledger hardware wallet used for baking,
please exit and re-start Dune Baking right before baking is supposed to
Jimmy Hartzell's avatar
Jimmy Hartzell committed
114 115
happen, and manually verify that it displays the key you expect to bake for.

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
116
Dune does not require such extra steps, and so these extra
Jimmy Hartzell's avatar
Jimmy Hartzell committed
117 118
protections are more appropriate for keys used for transaction than
they are for keys used for baking. If you do use these features, one
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
119
technique is that your dun be stored in the passphrase-protected and
Jimmy Hartzell's avatar
Jimmy Hartzell committed
120
deniable account, and that you delegate them to a baking account. This
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
121
way, the baking account won't actually store the vast majority of the dun.
Jimmy Hartzell's avatar
Jimmy Hartzell committed
122

nhomesley's avatar
nhomesley committed
123
### Ledger device firmware update
Chris Martin's avatar
Chris Martin committed
124

Alain Mebsout's avatar
Alain Mebsout committed
125
To use this app, you must be sure to have [up-to-date
Jimmy Hartzell's avatar
Jimmy Hartzell committed
126
firmware](https://support.ledgerwallet.com/hc/en-us/articles/360002731113)
Michael Reinhart's avatar
Michael Reinhart committed
127
on the Ledger device. This code was tested with version
128
1.6.0. Please use [Ledger
Alain Mebsout's avatar
Alain Mebsout committed
129
Live](https://www.ledger.com/pages/ledger-live) to do this. 
Chris Martin's avatar
Chris Martin committed
130

Alain Mebsout's avatar
Alain Mebsout committed
131 132
<!--
## Installing the Application with Ledger Live
133

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
134 135
The easiest way to obtain and install the Dune Ledger Nano S apps is to download them
from [Ledger Live](https://www.ledger.com/pages/ledger-live). Dune is readily available
Alain Mebsout's avatar
Alain Mebsout committed
136
in Ledger Live's Manager.
137 138

If you've used Ledger Live for app installation, you can skip ahead to [Registering the Ledger Nano S with the node](#registering-the-ledger-nano-s-with-the-node).
Alain Mebsout's avatar
Alain Mebsout committed
139
-->
140

Alain Mebsout's avatar
Alain Mebsout committed
141
## Obtaining the Ledger Nano S app without Ledger Live
Jimmy Hartzell's avatar
Jimmy Hartzell committed
142

Alain Mebsout's avatar
Alain Mebsout committed
143 144
You should follow the instructions in [`BUILDING.md`](BUILDING.md), and
[`INSTALL_linux.md`](INSTALL_linux.md) or [`INSTALL_macosx.md`](INSTALL_macosx.md).
Chris Martin's avatar
Chris Martin committed
145

nhomesley's avatar
nhomesley committed
146
## Registering the Ledger device with the node
Jimmy Hartzell's avatar
Jimmy Hartzell committed
147

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
148 149
For the remainder of this document, we assume you have a Dune node running and
`dune-client` installed. Also, Docker has some issues working with the Ledger device,
Jimmy Hartzell's avatar
Jimmy Hartzell committed
150 151
so unless you're willing to troubleshoot them, we don't recommend it.

Jimmy Hartzell's avatar
Jimmy Hartzell committed
152 153 154
Depending on how you build it, you might need to prefix `./` to your commands, and the names
of some of the binaries might be different.

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
155
### What is dune-client
Jimmy Hartzell's avatar
Jimmy Hartzell committed
156

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
157
We can call the network at large "Dune." Dune consists of a bunch of nodes,
Chris Martin's avatar
Chris Martin committed
158 159 160
one of which is yours. Your node can be thought of as your gateway to the wider
network.

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
161
You can't do anything with the Ledger hardware wallet without using `dune-client`. Dune-client
Chris Martin's avatar
Chris Martin committed
162 163
is the program you use to access information about the network,
which you ultimately get through your node. See the
Alain Mebsout's avatar
Alain Mebsout committed
164
[client documentation](https://dune.network/docs/dune-dev-docs/introduction/howtouse.html#client)
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
165
for the full array of features that dune-client supports.
Chris Martin's avatar
Chris Martin committed
166 167 168

In summary:

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
169
* Dune is the network
Chris Martin's avatar
Chris Martin committed
170
* We connect to the network through a node
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
171
* We access that node through dune-client
Michael Reinhart's avatar
Michael Reinhart committed
172
* We store our client's keys on the Ledger device
Chris Martin's avatar
Chris Martin committed
173

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
174
Note that `dune-client` will not only not support certain commands unless the node is installed,
Jimmy Hartzell's avatar
Jimmy Hartzell committed
175 176 177 178
but the error messages for those commands will not even indicate that those commands are possible.
If a command documented here gives an `Unrecognized command` error, make sure you have a node
running.

Chris Martin's avatar
Chris Martin committed
179 180
### Side note about key generation

Michael Reinhart's avatar
Michael Reinhart committed
181
Every Ledger hardware wallet generates public and private keys for `ed25519`, `secp256k1`, or
Chris Martin's avatar
Chris Martin committed
182
`P-256` encryption systems based on a seed (represented by and encoded in
Michael Reinhart's avatar
Michael Reinhart committed
183
the words associated with that Ledger device) and a BIP32 ("hierarchical deterministic
Chris Martin's avatar
Chris Martin committed
184 185 186
wallet") path.

The same seed and BIP32 path will always result in the same key for the same
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
187
systems. This means that, to keep your Bitcoin app from knowing your Dune keys,
Michael Reinhart's avatar
Michael Reinhart committed
188 189
and vice versa, different BIP32 paths have to be used for the same Ledger device. This
also means that, in order to sync two Ledger devices, you can set them to the same
Chris Martin's avatar
Chris Martin committed
190 191
seed, represented as 24 or some other number of natural language words (English
by default).
Jimmy Hartzell's avatar
Jimmy Hartzell committed
192

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
193
All Dune BIP32 paths begin with `44'/1729'` (the `'` indicates it is
Michael Reinhart's avatar
Michael Reinhart committed
194
"hardened").  Which Ledger Nano S is intended to be used, as well as choice of
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
195
encryption system, is indicated by a root key hash, the Dune-specific base58
Michael Reinhart's avatar
Michael Reinhart committed
196
encoding of the hash of the public key at `44'/1729'` on that Ledger Nano S. Because
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
197
all Dune paths start with this, in `dune-client` commands it is implied.
Chris Martin's avatar
Chris Martin committed
198

199
Beginning in version 0.5.0, there is also support for a `ed25519-bip32` derivation
ApolloUnicorn's avatar
ApolloUnicorn committed
200 201 202 203 204 205
method, which was made available in V1.5.5 of the Nano firmware. The existing `ed25519`
operation was purposefully not changed to preserve backwards compatibility. If you do
nothing, expect no changes. However, it is recommended that all new accounts use the `bip25519`
command instead of the legacy `ed25519`. After it is imported, the address can be treated
the same as any other.

nhomesley's avatar
nhomesley committed
206
### Importing the key from the Ledger device
Chris Martin's avatar
Chris Martin committed
207 208

This section must be done regardless of whether you're going to be baking or
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
209
only using the Dune Wallet application.
Chris Martin's avatar
Chris Martin committed
210

211
Please run, with a Dune app open on your device, in whatever mode.
212

Chris Martin's avatar
Chris Martin committed
213
```
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
214
$ dune-client list connected ledgers
Chris Martin's avatar
Chris Martin committed
215 216
```

217
The output of this command includes four Dune addresses derived from the secret
Chris Martin's avatar
Chris Martin committed
218 219 220
stored on the device, via different signing curves and BIP32 paths.

```
Alain Mebsout's avatar
Alain Mebsout committed
221 222 223
## Ledger `major-squirrel-thick-hedgehog`
Found a Wallet 1.0.0 (Dune) 20190904  (git-description: "") application
running on Ledger Nano S at [0003:000b:00].
Chris Martin's avatar
Chris Martin committed
224

Alain Mebsout's avatar
Alain Mebsout committed
225 226
To use keys at BIP32 path m/44'/1729'/0'/0' (default Dune key path), use one
of:
227 228 229 230
  dune-client import secret key my_ledger "ledger://major-squirrel-thick-hedgehog/bip25519/0h/0h"
  dune-client import secret key my_ledger "ledger://major-squirrel-thick-hedgehog/ed25519/0h/0h"
  dune-client import secret key my_ledger "ledger://major-squirrel-thick-hedgehog/secp256k1/0h/0h"
  dune-client import secret key my_ledger "ledger://major-squirrel-thick-hedgehog/P-256/0h/0h"
Chris Martin's avatar
Chris Martin committed
231 232
```

ApolloUnicorn's avatar
ApolloUnicorn committed
233
These show you how to import keys with a specific signing curve (e.g. `bip25519`) and derivation path (e.g. `/0'/0'`). The
Jimmy Hartzell's avatar
Jimmy Hartzell committed
234
animal-based name (e.g. `major-squirrel-thick-hedgehog`) is a unique identifier for your
235
Ledger device enabling the client to distinguish different Ledger devices. This is combined with
ApolloUnicorn's avatar
ApolloUnicorn committed
236
a derivation path (e.g. `/0'/0'`) to indicate one of the possible keys on the Ledger device. Your *root* key is the full identifier without the derivation path (e.g. `major-squirrel-thick-hedgehog/bip25519` by itself) but you should not use the root key directly\*.
237

Alain Mebsout's avatar
Alain Mebsout committed
238
\* *NOTE:* If you have used your root key in the past and need to import it, you can do so by simply running one of the commands but without the last derivation portion. From the example above, you would import your root key by running `dune-client import secret key my_ledger "ledger://major-squirrel-thick-hedgehog/ed25519"`. You should avoid using your root key.
Chris Martin's avatar
Chris Martin committed
239

nhomesley's avatar
nhomesley committed
240
The Ledger device does not currently support non-hardened path components. All
Chris Martin's avatar
Chris Martin committed
241 242 243 244
components of all paths must be hardened, which is indicated by following them
with a `'` character. This character may need to be escaped from the shell
through backslashes `\` or double-quotes `"`.

Jimmy Hartzell's avatar
Jimmy Hartzell committed
245
You'll need to choose one of the three commands starting with
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
246
`dune-client import secret key ...` to run. `ed25519` is the standard recommended curve.
Chris Martin's avatar
Chris Martin committed
247

Jimmy Hartzell's avatar
Jimmy Hartzell committed
248 249
The BIP32 path is the part that in the example commands read `0'/0'`. You
can change it, but if you do (and even if you don't), be sure to write
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
250
down. You need the full address to use your dun. This means that if you
Jimmy Hartzell's avatar
Jimmy Hartzell committed
251 252
lose all your devices and need to set everything up again, you will need
three things:
Chris Martin's avatar
Chris Martin committed
253

Jimmy Hartzell's avatar
Jimmy Hartzell committed
254
  1. The mnemonic phrase -- this is the phrase from your Ledger device itself when you set it up, not the animal mnemonic you see on the command line. They are different.
Chris Martin's avatar
Chris Martin committed
255 256 257
  2. Which signing curve you chose
  3. The BIP32 path, if you used one

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
258
The `dune-client import secret key` operation copies only the public key; it
Michael Reinhart's avatar
Michael Reinhart committed
259
says "import secret key" to indicate that the Ledger hardware wallet's secret key will be
nhomesley's avatar
nhomesley committed
260
considered available for signing from them on, but it does not leave the Ledger device.
Chris Martin's avatar
Chris Martin committed
261

Michael Reinhart's avatar
Michael Reinhart committed
262
This sends a BIP32 path to the device. You then need to click a button on the
nhomesley's avatar
nhomesley committed
263
Ledger device and it sends the public key back to the computer.
Chris Martin's avatar
Chris Martin committed
264 265 266 267 268

After you perform this step, if you run the `list known addresses` command, you
should see the key you chose in the list:

```
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
269
$ dune-client list known addresses
Alain Mebsout's avatar
Alain Mebsout committed
270
ledger_<...>_ed_0_0: dn1ccbGmKKwucwfCr846deZxGeDhiaTykGgK (ledger sk known)
Chris Martin's avatar
Chris Martin committed
271 272
```

Jimmy Hartzell's avatar
Jimmy Hartzell committed
273 274 275
We recommend reading as much as possible about BIP32 to ensure you fully understand
this.

276
## Using the application in Wallet mode
Chris Martin's avatar
Chris Martin committed
277

Alain Mebsout's avatar
Alain Mebsout committed
278 279 280 281
This application can be used in two modes, _i.e_ **Wallet Mode** and
**Baking Mode**. The Wallet Mode rejects any baking related signature
requests (such as endorsements or blocks) and the Baking Mode cannot
sign any operation.
Chris Martin's avatar
Chris Martin committed
282

Alain Mebsout's avatar
Alain Mebsout committed
283
The "provide address" command on the Dune Wallet Mode shows the address
Chris Martin's avatar
Chris Martin committed
284 285
the first time the command is run for any given session. Subsequently, it
provides the address without prompting. To display addresses again, exit the
Alain Mebsout's avatar
Alain Mebsout committed
286
Dune Application and restart it. This is again provided for testing/initial
Chris Martin's avatar
Chris Martin committed
287 288
set up purposes.

Alain Mebsout's avatar
Alain Mebsout committed
289
The sign command for the Wallet Mode prompts every time for transactions
Chris Martin's avatar
Chris Martin committed
290 291
and other "unsafe" operations, with the generic prompt saying "Sign?" We hope to
eventually display more transaction details along with this. When block headers
nhomesley's avatar
nhomesley committed
292
and endorsements are sent to the Ledger device, they are rejected silently as if the
Chris Martin's avatar
Chris Martin committed
293 294
user rejected them.

295
### Faucet (testnet only)
Chris Martin's avatar
Chris Martin committed
296

Alain Mebsout's avatar
Alain Mebsout committed
297 298
On testnet, you will need to use the [Dune Faucet](https://faucet.dune.network/)
to obtain some DUN. Tell them you're not a robot, then click "Get testnet dune."
Chris Martin's avatar
Chris Martin committed
299 300 301
It works on zeronet (even though the URL says alphanet).

Run the following command, where `<your-name>` is some alias you want to use for
Alain Mebsout's avatar
Alain Mebsout committed
302
this wallet, and `dn1<...>.json` is the name of the file you just downloaded
Chris Martin's avatar
Chris Martin committed
303 304 305
from the faucet.

```
Alain Mebsout's avatar
Alain Mebsout committed
306
$ dune-client activate account <your-name> with ~/downloads/dn1<...>.json
Chris Martin's avatar
Chris Martin committed
307 308 309 310 311 312 313
Node is bootstrapped, ready for injecting operations.
Operation successfully injected in the node.
Operation hash is 'onxJStKxK1oMPgGskkzc2gDBDyKeQ7CbBYTrcK4TMMySvKZq6vF'.
Waiting for the operation to be included...
Operation found in block: BMRjW94ge499sCPAMUTvrp3ku2UjWy9kB2LsjtuJhL1bkcQ85Ny (pass: 2, offset: 0)
This sequence of operations was run:
  Genesis account activation:
Alain Mebsout's avatar
Alain Mebsout committed
314
    Account: dn1Vntj2aVpqcQEeHq2CEmNrSGw8finvbFcX
Chris Martin's avatar
Chris Martin committed
315
    Balance updates:
Alain Mebsout's avatar
Alain Mebsout committed
316
      dn1Vntj2aVpqcQEeHq2CEmNrSGw8finvbFcX ... +ꜩ66835.212314
Chris Martin's avatar
Chris Martin committed
317

Alain Mebsout's avatar
Alain Mebsout committed
318
Account <your-name> (dn1Vntj2aVpqcQEeHq2CEmNrSGw8finvbFcX) activated with ꜩ66835.212314.
Chris Martin's avatar
Chris Martin committed
319 320 321 322 323
```

You can then check your account balance like this:

```
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
324
$ dune-client get balance for <your-name>
325
66835.212314 đ
Chris Martin's avatar
Chris Martin committed
326 327 328 329
```

### Transfer

nhomesley's avatar
nhomesley committed
330
Now transfer the balance to the account whose key resides on your Ledger device:
Chris Martin's avatar
Chris Martin committed
331 332

```
Alain Mebsout's avatar
Alain Mebsout committed
333
$ dune-client transfer 66000 from <your-name> to ledger_<...>_ed_0_0
Chris Martin's avatar
Chris Martin committed
334 335 336 337
```

### Further transaction details

Alain Mebsout's avatar
Alain Mebsout committed
338
In general, to send DUN, you'll need to:
Chris Martin's avatar
Chris Martin committed
339 340

  * Have a node running
341
  * Open the Dune app on your hardware wallet
Chris Martin's avatar
Chris Martin committed
342
  * Know the alias of your account or its public key hash
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
343
  * Know the public key hash of the account you are sending dun to
Chris Martin's avatar
Chris Martin committed
344 345 346 347

The command you run has the form:

```
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
348
dune-client transfer QTY from SRC to DST
Chris Martin's avatar
Chris Martin committed
349 350
```

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
351
  * `QTY` is the amount of dun. It's best to not include commas and to include 6
Jimmy Hartzell's avatar
Jimmy Hartzell committed
352 353
    decimal points (ie. 1000000.000000). If you'd prefer to include commas, you can:
    `1,000,000.000,000`.
Chris Martin's avatar
Chris Martin committed
354 355 356 357 358 359 360 361
  * `SRC` is the source, or where the money is coming from. This should be your
    alias or public key has.
  * `DST` is the destination, or where the money is going. You should use the
    public key hash, as your computer likely doesn't know any aliases for that
    account.

Some options which you can consider:

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
362
  * `--fee <amount>` - The fee defaults to 0.05 dun. If you'd like to select
Chris Martin's avatar
Chris Martin committed
363 364 365 366 367 368 369 370 371
    another amount, either because you think that's too high or the network is
    crowded and a higher fee is needed to ensure it goes through, you can
    include this with the amount of fee you want to pay (ie. `--fee 0.05` for
    the default).
  * `-D` or `--dry-run` - Use this if you just want to display what would happen
    and not actually do the transaction.
  * `-G` or `--gas-limit` - This sets the gas limit of the transaction instead.

There are other options which you can read up about more in the docs, but these
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
372
are the main ones you'd potentially want to use when just sending dun to
Chris Martin's avatar
Chris Martin committed
373 374
someone.

Jimmy Hartzell's avatar
Jimmy Hartzell committed
375 376
### Delegation

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
377
If you want to delegate dun controlled by a Ledger Nano S account to another account to
Michael Reinhart's avatar
Michael Reinhart committed
378
bake, that requires the Wallet App. This is distinct from registering the Ledger Nano S
Jimmy Hartzell's avatar
Jimmy Hartzell committed
379
account itself to bake, which is also called "delegation," and which is covered
nhomesley's avatar
nhomesley committed
380
in the section on the baking application below.
Jimmy Hartzell's avatar
Jimmy Hartzell committed
381

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
382
To delegate dun controlled by a Ledger device to someone else,
Jimmy Hartzell's avatar
Jimmy Hartzell committed
383
you must first originate an account. Please read more
Alain Mebsout's avatar
Alain Mebsout committed
384
about this in the Dune Node documentation, [How to use Dune](https://dune.network/docs/dune-dev-docs/introduction/howtouse.html), to
Jimmy Hartzell's avatar
Jimmy Hartzell committed
385 386 387 388
understand why this is necessary and the semantics of delegation.

To originate an account, the command is:
```
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
389
$ dune-client originate account <NEW> for <MGR> transferring <QTY> from <SRC> --delegatable
Jimmy Hartzell's avatar
Jimmy Hartzell committed
390 391
```

Alexandre Esteves's avatar
Alexandre Esteves committed
392
  * `NEW` is the alias you will now give to the originated account. Only originated accounts can
Jimmy Hartzell's avatar
Jimmy Hartzell committed
393 394
     be delegated, and even then only if originated with this `--delegatable` flag.
  * `MGR` is the name of the key you will use to manage the account. If you want to manage it
Michael Reinhart's avatar
Michael Reinhart committed
395
    with a Ledger device, it should be an existing imported key from the Ledger hardware wallet.
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
396 397
  * `QTY` is the initial amount of dun to give to the originated account.
  * `SRC` is the account where you'll be getting the dun from.
Chris Martin's avatar
Chris Martin committed
398

nhomesley's avatar
nhomesley committed
399
Subsequently, every transaction made with `<NEW>` will require the Ledger hardware wallet mentioned in `<MGR>`
Jimmy Hartzell's avatar
Jimmy Hartzell committed
400 401 402
to sign it. This is done with the wallet application, and includes setting a delegate with:

```
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
403
$ dune-client set delegate for <NEW> to <DELEGATE>
Jimmy Hartzell's avatar
Jimmy Hartzell committed
404 405
```

406
Originated accounts have names beginning with `KT1` rather than `dn1`, `tz2` or `tz3`.
407

408 409
### Manually Confirming Operation Hashes

410 411 412 413 414 415 416 417 418 419 420
Many operations are too large or complex for the Dune app to show you
enough detail on the device that you could safely confirm it. For
example, it is possible to create an operation that includes hundreds
of transactions. It is not feasible to confirm all of them on a tiny
device screen. For any operation that the Dune app can't easily
confirm via screen prompts, it will instead show you the "Sign Hash"
prompt. This shows you a *hash* of the entire operation that you
should cross-check with another source. `dune-client` will show you
this hash if you ask it to run the operation with
`--verbose-signing`. This will include additional output like the
following:
421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437

```
Pre-signature information (verbose signing):
  * Branch: BMRELbkCkHvCAr2vZfavjYUKXLbKrGvX6oN3qNEDKPjp8aJHqRm
  * Watermark: `Generic-operation` (0x03)
  * Operation bytes:
    e0ac9e16f0005865f71bcf039d10ec2bb8d604210c9139968949f64ea5c9d1320500aed01
    1841ffbb0bcc3b51c80f2b6c333a1be3df00000000000000040ab22e46e7872aa13e366e4
    55bb4f5dbede856ab0864e1da7e122554579ee71f876cd995a324193bbe09ac2d5c53f69f
    93778f8d608f1fea885f9b53e0abdb6e4
  * Blake 2B Hash (raw): Hnw7wQsfv8fvMUejXNJ31NauapEtzLZg859JwqNUEDEE
  * Blake 2B Hash (ledger-style, with operation watermark):
    C5Qkk9tTwaUbhnrN29JpXSmsYCEi1uhM8rSsentBwmbN
  * JSON encoding:
    { "branch": "BMRELbkCkHvCAr2vZfavjYUKXLbKrGvX6oN3qNEDKPjp8aJHqRm",
      "contents":
        [ { "kind": "proposals",
438
            "source": "dn1baMXLyDZ7nx7v96P2mEwM9U5Rhj5xJUnJ", "period": 0,
439 440 441 442 443
            "proposals":
              [ "Pt24m4xiPbLDhVgVfABUjirbmda3yohdN82Sp9FeuAXJ4eV9otd",
                "Psd1ynUBhMZAeajwcZJAeq5NrxorM6UCU4GJqxZ7Bx2e9vUWB6z" ] } ] }
```

444 445 446
Here, the hash under `Blake 2B Hash (ledger-style, with operation
watermark)` is `C5Qkk9tTwaUbhnrN29JpXSmsYCEi1uhM8rSsentBwmbN` and
should match the hash on the Ledger screen.
447

448 449 450 451 452
To be truly confident in the correctness of this operation, run the
same operation multiple times from different places. `dune-client`
has two options to help with this: `--dry-run` which skips the last
step of injecting the operation into the chain, and `--block
<block-hash>` to pin an operation to a specific block.
Jimmy Hartzell's avatar
Jimmy Hartzell committed
453

Alain Mebsout's avatar
Alain Mebsout committed
454
## Using the application in Baking Mode
Jimmy Hartzell's avatar
Jimmy Hartzell committed
455

Alain Mebsout's avatar
Alain Mebsout committed
456
The Dune Baking Mode supports the following operations:
Chris Martin's avatar
Chris Martin committed
457

458 459 460 461 462
  1. Get public key
  2. Setup ledger for baking
  3. Reset high watermark
  4. Get high watermark
  5. Sign (blocks and endorsements)
Chris Martin's avatar
Chris Martin committed
463 464 465

It will only sign block headers and endorsements, as the purpose of the baking
app is that it cannot be co-opted to perform other types of operations (like
466
transferring DUN). If a Ledger Nano S is running in Baking mode, it
Chris Martin's avatar
Chris Martin committed
467
is the expectation of its owner that no transactions will need to be signed with
468
it. To sign transactions with that Ledger Nano S, you will need to switch it to 
Alain Mebsout's avatar
Alain Mebsout committed
469
the Wallet Mode (with a PIN confirmation).
470 471 472 473 474 475 476

### Switching between wallet and baking modes

To switch to baking mode:
```
dune-client dune ledger becomes baking <account-alias-or-ledger-uri>
```
Chris Martin's avatar
Chris Martin committed
477

478 479 480 481 482 483 484 485 486 487 488 489
You can add the options `--always` to prevent the app from ever going
back to wallet mode, and `--volatile` to store high water marks in
memory instead of nvram (nvram erasure cycles are limited to about
500,000 on a Ledger Nano S).

To switch to wallet mode:
```
dune-client dune ledger becomes wallet <account-alias-or-ledger-uri>
```

The app will ask your PIN to verify that you are legitimate for this
operation.
Chris Martin's avatar
Chris Martin committed
490 491 492 493

### Start the baking daemon

```
Alain Mebsout's avatar
Alain Mebsout committed
494
$ dune-baker-004-Pt24m4xi run with local node ~/.dune-node ledger_<...>_ed_0_0
Chris Martin's avatar
Chris Martin committed
495 496
```

nhomesley's avatar
nhomesley committed
497
This won't actually be able to bake successfully yet until you run the rest of
Jimmy Hartzell's avatar
Jimmy Hartzell committed
498 499 500 501 502 503
these setup steps. This will run indefinitely, so you might want to do it in
a dedicated terminal or in a `tmux` or `screen` session.

You will also want to start the endorser and accuser daemons:

```
Alain Mebsout's avatar
Alain Mebsout committed
504 505
$ dune-endorser-004-Pt24m4xi run ledger_<...>_ed_0_0
$ dune-accuser-004-Pt24m4xi run
Jimmy Hartzell's avatar
Jimmy Hartzell committed
506 507 508 509
```

Again, each of these will run indefinitely, and each should be in its own terminal
`tmux`, or `screen` window.
Chris Martin's avatar
Chris Martin committed
510

Alain Mebsout's avatar
Alain Mebsout committed
511
*Note*: The binaries shown above all correspond to current Dune mainnet protocol. When the Dune protocol upgrades, the binaries shown above will update to, for instance, `dune-baker-005-********`.
512

513
### Setup ledger device to bake and endorse
Chris Martin's avatar
Chris Martin committed
514 515 516 517 518

You need to run a specific command to authorize a key for baking. Once a key is
authorized for baking, the user will not have to approve this command again. If
a key is not authorized for baking, signing endorsements and block headers with
that key will be rejected. This authorization data is persisted across runs of
nhomesley's avatar
nhomesley committed
519
the application, but not across application installations. Only one key can be authorized for baking per Ledger hardware wallet at a
Chris Martin's avatar
Chris Martin committed
520 521
time.

522
In order to authorize a public key for baking, use the APDU for setting up the ledger device to bake:
Jimmy Hartzell's avatar
Jimmy Hartzell committed
523 524

    ```
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
525
    $ dune-client setup ledger to bake for <ALIAS>
Jimmy Hartzell's avatar
Jimmy Hartzell committed
526 527
    ```

nhomesley's avatar
nhomesley committed
528
    This only authorizes the key for baking on the Ledger device, but does
Jimmy Hartzell's avatar
Jimmy Hartzell committed
529
    not inform the blockchain of your intention to bake. This might
nhomesley's avatar
nhomesley committed
530
    be necessary if you reinstall the app, or if you have a different
Michael Reinhart's avatar
Michael Reinhart committed
531
    paired Ledger device that you are using to bake for the first time.
Jimmy Hartzell's avatar
Jimmy Hartzell committed
532 533

### Registering as a Delegate
Jimmy Hartzell's avatar
Jimmy Hartzell committed
534

535 536
*Note: The ledger device will not sign this operation unless you have already setup the device to bake using the command in the previous section.*

nhomesley's avatar
nhomesley committed
537
In order to bake from the Ledger device account you need to register the key as a
Jimmy Hartzell's avatar
Jimmy Hartzell committed
538
delegate. This is formally done by delegating the account to itself. As a
Michael Reinhart's avatar
Michael Reinhart committed
539
non-originated account, an account directly stored on the Ledger device can only
Jimmy Hartzell's avatar
Jimmy Hartzell committed
540
delegate to itself.
Jimmy Hartzell's avatar
Jimmy Hartzell committed
541

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
542
Open the Dune Baking Application on the device, and then run this:
Jimmy Hartzell's avatar
Jimmy Hartzell committed
543 544

```
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
545
$ dune-client register key <ALIAS> as delegate
Jimmy Hartzell's avatar
Jimmy Hartzell committed
546 547
```

Jimmy Hartzell's avatar
Jimmy Hartzell committed
548
This command is intended to inform the blockchain itself of your intention to
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
549 550
bake with this key. It can be signed with either Dune Wallet or Dune Baking, however
Dune Baking can only sign self-delegations.
Jimmy Hartzell's avatar
Jimmy Hartzell committed
551 552 553

### Sign

Jimmy Hartzell's avatar
Jimmy Hartzell committed
554 555
The sign operation is for signing block headers and endorsements.

556
Block headers must have monotonically increasing levels; that is, each
Michael Reinhart's avatar
Michael Reinhart committed
557
block must have a higher level than all previous blocks signed with the Ledger device.
558
This is intended to prevent double baking and double endorsing at the device level, as a security
Chris Martin's avatar
Chris Martin committed
559 560
measure against potential vulnerabilities where the computer might be tricked
into double baking. This feature will hopefully be a redundant precaution, but
Michael Reinhart's avatar
Michael Reinhart committed
561
it's implemented at the device level because the point of the Ledger hardware wallet is to not
562
trust the computer. The current High Watermark (HWM) -- the highest level to
Michael Reinhart's avatar
Michael Reinhart committed
563
have been baked so far -- is displayed on the device's screen, and is also
Chris Martin's avatar
Chris Martin committed
564
persisted between runs of the device.
Jimmy Hartzell's avatar
Jimmy Hartzell committed
565

Michael Reinhart's avatar
Michael Reinhart committed
566
The sign operation will be sent to the hardware wallet by the baking daemon when
nhomesley's avatar
nhomesley committed
567
configured to bake with a Ledger device key. The Ledger device uses the first byte of the
Chris Martin's avatar
Chris Martin committed
568
information to be signed -- the magic number -- to tell whether it is a block
569
header (which is verified with the High Watermark), an endorsement (which is
Chris Martin's avatar
Chris Martin committed
570 571 572 573
not), or some other operation (which it will reject, unless it is a
self-delegation).

With the exception of self-delegations, as long as the key is configured and the
574
high watermark constraint is followed, there is no user prompting required for
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
575
signing. Dune Baking will only ever sign without prompting or reject an
576 577
attempt at signing; this operation is designed to be used unsupervised. As mentioned,
 the only exception to this is self-delegation.
Jimmy Hartzell's avatar
Jimmy Hartzell committed
578

579
### Reset High Watermark
Jimmy Hartzell's avatar
Jimmy Hartzell committed
580

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
581
When updating the version of Dune Baking you are using or if you are switching baking to
582 583 584
 a new ledger device, we recommend setting the HWM to the current head block level of the blockchain.
This can be accomplished with the reset command. The following command requires an explicit
confirmation from the user:
Jimmy Hartzell's avatar
Jimmy Hartzell committed
585

586
```
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
587
$ dune-client set ledger high watermark for "ledger://<tz...>/" to <HWM>
588
```
Jimmy Hartzell's avatar
Jimmy Hartzell committed
589

590
`<HWM>` indicates the new high watermark to reset to. Both the main and test chain HWMs will be
591
simultaneously changed to this value.
Jimmy Hartzell's avatar
Jimmy Hartzell committed
592

593
If you would like to know the current high watermark of the ledger device, you can run:
Jimmy Hartzell's avatar
Jimmy Hartzell committed
594

595
```
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
596
$ dune-client get ledger high watermark for "ledger://<tz...>/"
597
```
Jimmy Hartzell's avatar
Jimmy Hartzell committed
598

599
While the ledger device's UI displays the HWM of the main chain it is signing on, it will not
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
600
display the HWM of a test chain it may be signing on during the 3rd period of the Dune Amendment Process.
601
Running this command will return both HWMs as well as the chain ID of the main chain.
Jimmy Hartzell's avatar
Jimmy Hartzell committed
602

Jimmy Hartzell's avatar
Jimmy Hartzell committed
603 604 605 606
## Upgrading

When you want to upgrade to a new version, whether you built it yourself from source
or whether it's a new release of the `app.hex` files, use the same commands as you did
Michael Reinhart's avatar
Michael Reinhart committed
607
to originally install it. As the keys are generated from the device's seeds and the
608
derivation paths, you will have the same keys with every version of this Ledger hardware wallet app,
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
609
so there is no need to re-import the keys with `dune-client`.
Jimmy Hartzell's avatar
Jimmy Hartzell committed
610 611 612

### Special Upgrading Considerations for Bakers

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
613
If you've already been baking on an old version of Dune Baking, the new version will
614
not remember which key you are baking with nor the High Watermark. You will have to re-run
615 616
this command to remind the hardware wallet what key you intend to authorize for baking. As shown, it can
also set the HWM:
Jimmy Hartzell's avatar
Jimmy Hartzell committed
617 618

```
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
619
$ dune-client setup ledger to bake for <ALIAS> --main-hwm <HWM>
Jimmy Hartzell's avatar
Jimmy Hartzell committed
620 621
```

622
Alternatively, you can also set the High Watermark to the level of the most recently baked block with a separate command:
Jimmy Hartzell's avatar
Jimmy Hartzell committed
623 624

```
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
625
$ dune-client set ledger high watermark for "ledger://<tz...>/" to <HWM>
Jimmy Hartzell's avatar
Jimmy Hartzell committed
626 627
```

nhomesley's avatar
nhomesley committed
628
The latter will require the correct URL for the Ledger device acquired from:
Jimmy Hartzell's avatar
Jimmy Hartzell committed
629 630

```
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
631
$ dune-client list connected ledgers
Jimmy Hartzell's avatar
Jimmy Hartzell committed
632 633
```

Chris Martin's avatar
Chris Martin committed
634
## Troubleshooting
Jimmy Hartzell's avatar
Jimmy Hartzell committed
635

636 637 638
### Display Debug Logs

If you are worried about bugs, you should configure your system to display debug logs. Add the
nhomesley's avatar
nhomesley committed
639
following line to `~/.bashrc` and to `~/.bash_profile`, or set the equivalent environment
640
variable in whatever system you use to launch your daemons:
641 642

```
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
643
export DUNE_LOG="client.signer.ledger -> debug"
644 645
```

646 647
If you have a bug report, it is far more likely we'll be able to fix it if you include the
entire output of the transaction, including debug messages enabled by that command above.
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
648
Please copy and paste the entire run of the command (for `dune-client`) or everything
649 650 651 652 653 654 655 656
involving the failed block level and the previous one (for baking); if you need to anonymize
the PKH then please do so by using `XXX` or similar rather than by removing those entire lines.
We need as much context as possible to help troubleshoot.

`script` is also a useful command for logging all the output of a long-running process.
If you run `script <file-name>` it opens a new shell where everything output and typed
is also output to that file, giving you a transcript of your terminal session.

657 658
### Importing a Fundraiser Account to a Ledger Device

Alain Mebsout's avatar
Alain Mebsout committed
659 660 661 662 663 664
You currently cannot directly import a fundraiser account to the
Ledger device. Instead, you'll first need to import your fundraiser
account to a non-hardware wallet address from which you can send the
funds to an address on the ledger. You can do so with software wallets
such as [Dune Wallet](https://wallet.dune.network) or the [Metal
extension](https://metal.dune.network).
665

666 667 668
### Two Ledger Devices at the Same Time

Two Ledger devices with the same seed should not ever be plugged in at the same time. This confuses
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
669
`dune-client` and other client programs. Instead, you should plug only one of a set of paired
670 671 672 673
ledgers at a time. Two Ledger devices of different seeds are fine and are fully supported,
and the computer will automatically determine which one to send information to.

If you have one running the baking app, it is bad for security to also have the wallet app
nhomesley's avatar
nhomesley committed
674
plugged in simultaneously. Plug the wallet application in as-needed, removing the baking app, at a time
675 676 677
when you are not going to be needed for endorsement or baking. Alternatively, use a different
computer for wallet transactions.

Chris Martin's avatar
Chris Martin committed
678
### unexpected seq num
Jimmy Hartzell's avatar
Jimmy Hartzell committed
679

Chris Martin's avatar
Chris Martin committed
680
```
681
$ dune-client list connected ledgers
Chris Martin's avatar
Chris Martin committed
682 683
Fatal error:                                                                                                                                        Header.check: unexpected seq num
```
Jimmy Hartzell's avatar
Jimmy Hartzell committed
684

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
685
This means you do not have the Dune app open on your device.
Jimmy Hartzell's avatar
Jimmy Hartzell committed
686

Chris Martin's avatar
Chris Martin committed
687 688 689
### No device found

```
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
690
$ dune-client list connected ledgers
Chris Martin's avatar
Chris Martin committed
691
No device found.
Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
692
Make sure a Ledger Nano S is connected and in the Dune Wallet app.
Chris Martin's avatar
Chris Martin committed
693 694 695 696
```

In addition to the possibilities listed in the error message, this could also
mean that your udev rules are not set up correctly.
Jimmy Hartzell's avatar
Jimmy Hartzell committed
697 698 699

### Unrecognized command

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
700 701
If you see an `Unrecognized command` error, it might be because there is no node for `dune-client`
to connect to. Please ensure that you are running a node. `ps aux | grep dune-node` should display
Jimmy Hartzell's avatar
Jimmy Hartzell committed
702 703
the process information for the current node. If it displays nothing, or just displays a `grep`
command, then there is no node running on your machine.
704

nhomesley's avatar
nhomesley committed
705
### Ledger Application Crashes
706

nhomesley's avatar
nhomesley committed
707
If the Ledger application crashes when you load it, there are two primary causes:
708

Fabrice Le Fessant's avatar
Fabrice Le Fessant committed
709
  * Quitting the `dune-client` process before the device responds. Even if you meant to cancel
Michael Reinhart's avatar
Michael Reinhart committed
710
    the operation in question, cancel it from the device before pressing Ctrl-C, otherwise you
nhomesley's avatar
nhomesley committed
711 712
    might have to restart the Ledger device.
  * Out of date firmware: If the Ledger application doesn't work at all, make sure you are running firmware
713
    version 1.5.5.
714

715
### Error "Unexpected sequence number (expected 0, got 191)" on macOS
716

717
If `dune-client` on macOS intermittently fails with an error that looks like
718 719 720 721 722

```
client.signer.ledger: APDU level error: Unexpected sequence number (expected 0, got 191)
```

723
then your installation of `dune-client` was built with an older version of HIDAPI that doesn't work well with macOS (see [#30](https://github.com/obsidiansystems/ledger-app-tezos/issues/30)).
724

Elliot Cameron's avatar
Elliot Cameron committed
725
To fix this you need to get the yet-unreleased fixes from the [HIDAPI library](https://github.com/signal11/hidapi) and rebuild `tezos-client`.
726 727 728 729 730 731 732

If you got HIDAPI from Homebrew, you can update to the `master` branch of HIDAPI like this:

```shell
$ brew install hidapi --HEAD
```

733
Then start a full rebuild of `dune-client` with HIDAPI's `master` branch:
734 735 736

```shell
$ brew unlink hidapi   # remove the current one
Alexandre Esteves's avatar
Alexandre Esteves committed
737
$ brew install autoconf automake libtool  # Just keep installing stuff until the following command succeeds:
738 739 740
$ brew install hidapi --HEAD
```

741
Finally, rebuild `ocaml-hidapi` with Tezos. In the `tezos` repository:
742 743 744 745 746 747 748

```shell
$ opam reinstall hidapi
$ make all build-test
$ ./tezos-client list connected ledgers  # should now work consistently
```

749 750
Note that you may still see warnings similar to `Unexpected sequence number (expected 0, got 191)` even after this update. The reason is that there is a separate, more cosmetic, issue in `tezos-client` itself which has already been fixed but may not be in your branch yet (see the [merge request](https://gitlab.com/tezos/tezos/merge_requests/600)).

Michael Reinhart's avatar
Michael Reinhart committed
751
### Contact Us
752 753

You can email us at [email protected] and come to our channel on Discord.