# Dune Ledger Nano S Application ## Acknowledgments 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). ## Overview 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. 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 "money" -- in the case of Dune, it stores your dun. Remember, storing your 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 interact with the network, including creating Dune transactions and baking blocks. This repository contains a Ledger Nano S application with two modes: 1. The "Baking" mode is for baking: signing new blocks and endorsements. For more information about baking, see [*Benefits and Risks of Home Baking*](https://medium.com/@dune_91823/benefits-and-risks-of-home-baking-a631c9ca745). 2. The "Wallet" mode is for making DUN transactions and contract calls, originating contracts, delegation, and voting. Basically everything you might want to use the Ledger Nano S for on Dune besides baking. It is possible to do all of these things without a hardware wallet, but using a hardware wallet provides greater security. This documentation was originally written when there was no GUI support, so everything is 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. This document is not a comprehensive guide to setting up Dune software. While it covers some aspects of setting up and installing Dune nodes and clients, especially as it interacts with the Ledger Nano S, you should familiarize yourself with the [Dune Documentation](https://docs.dune.network). 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. 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. 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. ## Set up your Ledger Nano S device Dune recommends a hardware wallet called the Ledger Nano S. When you first get 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 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). However, your Ledger Nano S will ask for confirmation before it sends your keys to sign 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 restore your key. If you lose your Ledger device or destroy it somehow, you can buy a new one and set it up with the seed phrase from your old one, hence restoring your tokens. Consequently, it is extremely important that you keep your seed phrase written down somewhere safe. Losing it can mean you lose control of your account should you, for example, lose your Ledger device. Keeping it somewhere a hacker could find it (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, dogs, housekeepers, or obnoxious neighbors could inadvertently destroy it. ### Protecting Your Key -- Further Advanced Reading More advanced techniques for those interested in even more layers of security or plausible deniability features should look at [Ledger's documentation on this](https://support.ledgerwallet.com/hc/en-us/articles/115005214529-Advanced-Passphrase-options). Note that Ledger devices with different seeds will appear to `dune-client` to be different hardware wallets. Note also that it can change what key is authorized in 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 happen, and manually verify that it displays the key you expect to bake for. Dune does not require such extra steps, and so these extra protections are more appropriate for keys used for transaction than they are for keys used for baking. If you do use these features, one technique is that your dun be stored in the passphrase-protected and deniable account, and that you delegate them to a baking account. This way, the baking account won't actually store the vast majority of the dun. ### Ledger device firmware update To use this app, you must be sure to have [up-to-date firmware](https://support.ledgerwallet.com/hc/en-us/articles/360002731113) on the Ledger device. This code was tested with version 1.6.0. Please use [Ledger Live](https://www.ledger.com/pages/ledger-live) to do this. ## Obtaining the Ledger Nano S app without Ledger Live You should follow the instructions in [`BUILDING.md`](BUILDING.md), and [`INSTALL_linux.md`](INSTALL_linux.md) or [`INSTALL_macosx.md`](INSTALL_macosx.md). ## Registering the Ledger device with the node 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, so unless you're willing to troubleshoot them, we don't recommend it. 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. ### What is dune-client We can call the network at large "Dune." Dune consists of a bunch of nodes, one of which is yours. Your node can be thought of as your gateway to the wider network. You can't do anything with the Ledger hardware wallet without using `dune-client`. Dune-client is the program you use to access information about the network, which you ultimately get through your node. See the [client documentation](https://dune.network/docs/dune-dev-docs/introduction/howtouse.html#client) for the full array of features that dune-client supports. In summary: * Dune is the network * We connect to the network through a node * We access that node through dune-client * We store our client's keys on the Ledger device Note that `dune-client` will not only not support certain commands unless the node is installed, 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. ### Side note about key generation Every Ledger hardware wallet generates public and private keys for `ed25519`, `secp256k1`, or `P-256` encryption systems based on a seed (represented by and encoded in the words associated with that Ledger device) and a BIP32 ("hierarchical deterministic wallet") path. The same seed and BIP32 path will always result in the same key for the same systems. This means that, to keep your Bitcoin app from knowing your Dune keys, 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 seed, represented as 24 or some other number of natural language words (English by default). All Dune BIP32 paths begin with `44'/1729'` (the `'` indicates it is "hardened"). Which Ledger Nano S is intended to be used, as well as choice of encryption system, is indicated by a root key hash, the Dune-specific base58 encoding of the hash of the public key at `44'/1729'` on that Ledger Nano S. Because all Dune paths start with this, in `dune-client` commands it is implied. Beginning in version 0.5.0, there is also support for a `ed25519-bip32` derivation 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. ### Importing the key from the Ledger device This section must be done regardless of whether you're going to be baking or only using the Dune Wallet application. Please run, with a Dune app open on your device, in whatever mode. ``` $ dune-client list connected ledgers ``` The output of this command includes four Dune addresses derived from the secret stored on the device, via different signing curves and BIP32 paths. ``` ## 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]. To use keys at BIP32 path m/44'/1729'/0'/0' (default Dune key path), use one of: 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" ``` These show you how to import keys with a specific signing curve (e.g. `bip25519`) and derivation path (e.g. `/0'/0'`). The animal-based name (e.g. `major-squirrel-thick-hedgehog`) is a unique identifier for your Ledger device enabling the client to distinguish different Ledger devices. This is combined with 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\*. \* *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. The Ledger device does not currently support non-hardened path components. All 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 `"`. You'll need to choose one of the three commands starting with `dune-client import secret key ...` to run. `ed25519` is the standard recommended curve. 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 down. You need the full address to use your dun. This means that if you lose all your devices and need to set everything up again, you will need three things: 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. 2. Which signing curve you chose 3. The BIP32 path, if you used one The `dune-client import secret key` operation copies only the public key; it says "import secret key" to indicate that the Ledger hardware wallet's secret key will be considered available for signing from them on, but it does not leave the Ledger device. This sends a BIP32 path to the device. You then need to click a button on the Ledger device and it sends the public key back to the computer. After you perform this step, if you run the `list known addresses` command, you should see the key you chose in the list: ``` $ dune-client list known addresses ledger_<...>_ed_0_0: dn1ccbGmKKwucwfCr846deZxGeDhiaTykGgK (ledger sk known) ``` We recommend reading as much as possible about BIP32 to ensure you fully understand this. ## Using the application in Wallet mode 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. The "provide address" command on the Dune Wallet Mode shows the address the first time the command is run for any given session. Subsequently, it provides the address without prompting. To display addresses again, exit the Dune Application and restart it. This is again provided for testing/initial set up purposes. The sign command for the Wallet Mode prompts every time for transactions and other "unsafe" operations, with the generic prompt saying "Sign?" We hope to eventually display more transaction details along with this. When block headers and endorsements are sent to the Ledger device, they are rejected silently as if the user rejected them. ### Faucet (testnet only) 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." It works on zeronet (even though the URL says alphanet). Run the following command, where `` is some alias you want to use for this wallet, and `dn1<...>.json` is the name of the file you just downloaded from the faucet. ``` $ dune-client activate account with ~/downloads/dn1<...>.json 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: Account: dn1Vntj2aVpqcQEeHq2CEmNrSGw8finvbFcX Balance updates: dn1Vntj2aVpqcQEeHq2CEmNrSGw8finvbFcX ... +ꜩ66835.212314 Account (dn1Vntj2aVpqcQEeHq2CEmNrSGw8finvbFcX) activated with ꜩ66835.212314. ``` You can then check your account balance like this: ``` $ dune-client get balance for 66835.212314 đ ``` ### Transfer Now transfer the balance to the account whose key resides on your Ledger device: ``` $ dune-client transfer 66000 from to ledger_<...>_ed_0_0 ``` ### Further transaction details In general, to send DUN, you'll need to: * Have a node running * Open the Dune app on your hardware wallet * Know the alias of your account or its public key hash * Know the public key hash of the account you are sending dun to The command you run has the form: ``` dune-client transfer QTY from SRC to DST ``` * `QTY` is the amount of dun. It's best to not include commas and to include 6 decimal points (ie. 1000000.000000). If you'd prefer to include commas, you can: `1,000,000.000,000`. * `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: * `--fee ` - The fee defaults to 0.05 dun. If you'd like to select 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 are the main ones you'd potentially want to use when just sending dun to someone. ### Delegation If you want to delegate dun controlled by a Ledger Nano S account to another account to bake, that requires the Wallet App. This is distinct from registering the Ledger Nano S account itself to bake, which is also called "delegation," and which is covered in the section on the baking application below. To delegate dun controlled by a Ledger device to someone else, you must first originate an account. Please read more about this in the Dune Node documentation, [How to use Dune](https://dune.network/docs/dune-dev-docs/introduction/howtouse.html), to understand why this is necessary and the semantics of delegation. To originate an account, the command is: ``` $ dune-client originate account for transferring from --delegatable ``` * `NEW` is the alias you will now give to the originated account. Only originated accounts can 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 with a Ledger device, it should be an existing imported key from the Ledger hardware wallet. * `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. Subsequently, every transaction made with `` will require the Ledger hardware wallet mentioned in `` to sign it. This is done with the wallet application, and includes setting a delegate with: ``` $ dune-client set delegate for to ``` Originated accounts have names beginning with `KT1` rather than `dn1`, `tz2` or `tz3`. ### Manually Confirming Operation Hashes 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: ``` 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", "source": "dn1baMXLyDZ7nx7v96P2mEwM9U5Rhj5xJUnJ", "period": 0, "proposals": [ "Pt24m4xiPbLDhVgVfABUjirbmda3yohdN82Sp9FeuAXJ4eV9otd", "Psd1ynUBhMZAeajwcZJAeq5NrxorM6UCU4GJqxZ7Bx2e9vUWB6z" ] } ] } ``` Here, the hash under `Blake 2B Hash (ledger-style, with operation watermark)` is `C5Qkk9tTwaUbhnrN29JpXSmsYCEi1uhM8rSsentBwmbN` and should match the hash on the Ledger screen. 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 ` to pin an operation to a specific block. ## Using the application in Baking Mode The Dune Baking Mode supports the following operations: 1. Get public key 2. Setup ledger for baking 3. Reset high watermark 4. Get high watermark 5. Sign (blocks and endorsements) 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 transferring DUN). If a Ledger Nano S is running in Baking mode, it is the expectation of its owner that no transactions will need to be signed with it. To sign transactions with that Ledger Nano S, you will need to switch it to the Wallet Mode (with a PIN confirmation). ### Switching between wallet and baking modes To switch to baking mode: ``` dune-client dune ledger becomes baking ``` 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 ``` The app will ask your PIN to verify that you are legitimate for this operation. ### Start the baking daemon ``` $ dune-baker-004-Pt24m4xi run with local node ~/.dune-node ledger_<...>_ed_0_0 ``` This won't actually be able to bake successfully yet until you run the rest of 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: ``` $ dune-endorser-004-Pt24m4xi run ledger_<...>_ed_0_0 $ dune-accuser-004-Pt24m4xi run ``` Again, each of these will run indefinitely, and each should be in its own terminal `tmux`, or `screen` window. *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-********`. ### Setup ledger device to bake and endorse 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 the application, but not across application installations. Only one key can be authorized for baking per Ledger hardware wallet at a time. In order to authorize a public key for baking, use the APDU for setting up the ledger device to bake: ``` $ dune-client setup ledger to bake for ``` This only authorizes the key for baking on the Ledger device, but does not inform the blockchain of your intention to bake. This might be necessary if you reinstall the app, or if you have a different paired Ledger device that you are using to bake for the first time. ### Registering as a Delegate *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.* In order to bake from the Ledger device account you need to register the key as a delegate. This is formally done by delegating the account to itself. As a non-originated account, an account directly stored on the Ledger device can only delegate to itself. Open the Dune Baking Application on the device, and then run this: ``` $ dune-client register key as delegate ``` This command is intended to inform the blockchain itself of your intention to bake with this key. It can be signed with either Dune Wallet or Dune Baking, however Dune Baking can only sign self-delegations. ### Sign The sign operation is for signing block headers and endorsements. Block headers must have monotonically increasing levels; that is, each block must have a higher level than all previous blocks signed with the Ledger device. This is intended to prevent double baking and double endorsing at the device level, as a security measure against potential vulnerabilities where the computer might be tricked into double baking. This feature will hopefully be a redundant precaution, but it's implemented at the device level because the point of the Ledger hardware wallet is to not trust the computer. The current High Watermark (HWM) -- the highest level to have been baked so far -- is displayed on the device's screen, and is also persisted between runs of the device. The sign operation will be sent to the hardware wallet by the baking daemon when configured to bake with a Ledger device key. The Ledger device uses the first byte of the information to be signed -- the magic number -- to tell whether it is a block header (which is verified with the High Watermark), an endorsement (which is 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 high watermark constraint is followed, there is no user prompting required for signing. Dune Baking will only ever sign without prompting or reject an attempt at signing; this operation is designed to be used unsupervised. As mentioned, the only exception to this is self-delegation. ### Reset High Watermark When updating the version of Dune Baking you are using or if you are switching baking to 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: ``` $ dune-client set ledger high watermark for "ledger:///" to ``` `` indicates the new high watermark to reset to. Both the main and test chain HWMs will be simultaneously changed to this value. If you would like to know the current high watermark of the ledger device, you can run: ``` $ dune-client get ledger high watermark for "ledger:///" ``` While the ledger device's UI displays the HWM of the main chain it is signing on, it will not display the HWM of a test chain it may be signing on during the 3rd period of the Dune Amendment Process. Running this command will return both HWMs as well as the chain ID of the main chain. ## 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 to originally install it. As the keys are generated from the device's seeds and the derivation paths, you will have the same keys with every version of this Ledger hardware wallet app, so there is no need to re-import the keys with `dune-client`. ### Special Upgrading Considerations for Bakers If you've already been baking on an old version of Dune Baking, the new version will not remember which key you are baking with nor the High Watermark. You will have to re-run this command to remind the hardware wallet what key you intend to authorize for baking. As shown, it can also set the HWM: ``` $ dune-client setup ledger to bake for --main-hwm ``` Alternatively, you can also set the High Watermark to the level of the most recently baked block with a separate command: ``` $ dune-client set ledger high watermark for "ledger:///" to ``` The latter will require the correct URL for the Ledger device acquired from: ``` $ dune-client list connected ledgers ``` ## Troubleshooting ### Display Debug Logs If you are worried about bugs, you should configure your system to display debug logs. Add the following line to `~/.bashrc` and to `~/.bash_profile`, or set the equivalent environment variable in whatever system you use to launch your daemons: ``` export DUNE_LOG="client.signer.ledger -> debug" ``` 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. Please copy and paste the entire run of the command (for `dune-client`) or everything 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 ` it opens a new shell where everything output and typed is also output to that file, giving you a transcript of your terminal session. ### Importing a Fundraiser Account to a Ledger Device 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). ### 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 `dune-client` and other client programs. Instead, you should plug only one of a set of paired 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 plugged in simultaneously. Plug the wallet application in as-needed, removing the baking app, at a time when you are not going to be needed for endorsement or baking. Alternatively, use a different computer for wallet transactions. ### unexpected seq num ``` $ dune-client list connected ledgers Fatal error: Header.check: unexpected seq num ``` This means you do not have the Dune app open on your device. ### No device found ``` $ dune-client list connected ledgers No device found. Make sure a Ledger Nano S is connected and in the Dune Wallet app. ``` In addition to the possibilities listed in the error message, this could also mean that your udev rules are not set up correctly. ### Unrecognized command 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 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. ### Ledger Application Crashes If the Ledger application crashes when you load it, there are two primary causes: * Quitting the `dune-client` process before the device responds. Even if you meant to cancel the operation in question, cancel it from the device before pressing Ctrl-C, otherwise you 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 version 1.5.5. ### Error "Unexpected sequence number (expected 0, got 191)" on macOS If `dune-client` on macOS intermittently fails with an error that looks like ``` client.signer.ledger: APDU level error: Unexpected sequence number (expected 0, got 191) ``` 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)). To fix this you need to get the yet-unreleased fixes from the [HIDAPI library](https://github.com/signal11/hidapi) and rebuild `tezos-client`. If you got HIDAPI from Homebrew, you can update to the `master` branch of HIDAPI like this: ```shell $ brew install hidapi --HEAD ``` Then start a full rebuild of `dune-client` with HIDAPI's `master` branch: ```shell $ brew unlink hidapi # remove the current one $ brew install autoconf automake libtool # Just keep installing stuff until the following command succeeds: $ brew install hidapi --HEAD ``` Finally, rebuild `ocaml-hidapi` with Tezos. In the `tezos` repository: ```shell $ opam reinstall hidapi $ make all build-test $ ./tezos-client list connected ledgers # should now work consistently ``` 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)). ### Contact Us You can email us at dune@dune.network and come to our channel on Discord.