Using a Ledger Nano S with Dune

Hardware wallets are secure devices used to store private keys in the blockchain world. They allow to keep users’ assets safe even in a poorly trusted environments.

To secure your Dune account, you should use a hardware wallet. Here, we show how to use the Ledger Nano S.

You will have to install the Dune application on the Ledger Nano S, once it has been setup. The Dune application will allow you to both sign manually some operations, and put the application in a baking-mode, where blocks and endorsements are automatically signed.

Prerequisites

You’ll need the following elements before you walk through this step-by-step tutorial:

  • An initialized Ledger Nano S with at least firmware 1.5.5;

  • A web browser;

  • Ledger Live application, if you want to install Dune Ledger app from it;

  • Dune Network binaries, if you are interested in setting up a baker, or in signing operations via command-line.

    Tip

    You may want to follow the steps below on this video.

Plug your Ledger Nano S and start Ledger Live to see if you have at least firware 1.5.5. If Ledger Live doesn’t show your Ledger device, it’s probably because it is not detected by the operating system, you may need to enable udev rules:

$ wget -q -O - https://raw.githubusercontent.com/LedgerHQ/udev-rules/master/add_udev_rules.sh | sudo bash

Installing the Dune Ledger app

To begin, connect you Ledger Nano S device and enter your PIN code.

Warning

As a precaution, make sure you only connected the Ledger on which you want to install Dune app to your computer.

Installation from Ledger Live

Note

Dune app is not available on Ledger Live yet. We are in the process of making the app available there.

Using Ledger Live is the easiest way to install the Dune app. We are in the process of making the app available there. In the meantime, you can either try to install it manually, or try to use the Tezos app already available on Ledger Live (see the last section).

Installation from binary

This is currently the easiest way to install Dune app. You will need a computer running Linux.

Go to https://dune.network/files/ledger-app-dune/nano-s/ and download the most recent version of Dune Network app.

Use the tar command to uncompress the files. For example:

$ tar zxvf ledger-app-dune-nano-s-bin-0.4.1-20190908.tar.gz

Inside the directory, follow the steps within the README.md file to install the dependencies and use the correct scripts. For instance, you will need to install the ledgerblue Python package (with the python-pip package on Debian):

$ sudo apt-get install python-pip
$ pip install --no-cache-dir ledgerblue

Then, still inside the directory, just run the install.sh script:

$ ./install.sh

You will be asked to enter your PIN. If a previous version of the app was installed, you will also be asked to confirm its removal.

Install Dune Ledger App from binaries

If you want to remove your Dune app, you can use the uninstall.sh script in the same way:

$ ./uninstall.sh

and you will be asked for your PIN and to confirm the removal of the app.

Installation from sources

You will need to install a fully configured Ledger SDK. The steps are described in the README file within the sources.

First, clone the GIT repository https://gitlab.com/dune-network/ledger-app-dune. Then, follow the steps given in the README to install needed dependencies. If everything is done correctly, you should now be able to build the app with make. Once built, use make load to install the app on your ledger. You can uninstall the app using make delete.

Using the Dune Ledger app

First, connect you Ledger Nano S device, enter your PIN code and start the Dune app.

Tip

If you want to test the steps below, we recommend you to use Dune Testnet with faucet accounts. See here for more details.

Wallet mode with Dune wallet

Wallet mode is the default configuration you are shown when you install the Dune Ledger app. With this mode, you can sign transactions, originate contracts, set or unset delegations, … If you manage to sign one of these operations with your Ledger Nano S, you should be able to do the other ones. Let’s see how this works in practice:

Dune web wallet provides simple way to interact with Dune testnet or mainnet. In fact, you don’t need to compile Dune Network on your machine. In addition, it works on any operating system (Windows, Linux, MaxOS, Android, …) with a (not too old) browser.

Dune web wallet interfaces with a Ledger Nano S in wallet mode. It allows to make transactions, originate contracts, update delegations, interact with smart contract, and much more.

To use Dune web wallet with a Ledger Nano S, visit https://wallet.dune.network, accept the terms and conditions, then click on ledger icon. In the next page, click on Link Dune Wallet. You will then be asked to verify the address on your Ledger Nano S device. Once you confirmed the operation on the Ledger, a popup with your address is shown. The last step asks you to provide a password to secure your web wallet.

Linking a ledger to Dune web wallet

Once all these steps are done, the main view of your web wallet is displayed. Here are the main information it contains:

  • The left panel shows your main address, the list of KT1 accounts you originated so far and a button add account to add a new KT1 account;

  • In the middle, the address and the balance of the selected account are shown. Then a list of tabs is displayed below. These tabs have titles: Transactions, Send, Delegate, Notarize, Options.

  • On the top right corner, the app indicates if you are on testnet or mainnet network. A setting button allows you to switch between these networks, or to add a custom one.

Dune web wallet's home page

Wallet mode with dune-client

In a terminal, use the dune-client binary to print the Ledgers that it can see:

$ ./dune-client list connected ledgers

## Ledger `previous-markhor-gleeful-ant`
Found a Wallet 0.4.1 (Dune) 20190908 v2.0.0-108-gc8c15b25* (git-description:
"v2.0.0-108-gc8c15b25*") application running on Ledger Nano S at
[0001:0008:00].

To use keys at BIP32 path m/44'/1729'/0'/0' (default Dune key path), use one
of:
  dune-client import secret key ledger_user "ledger://previous-markhor-gleeful-ant/ed25519/0'/0'"
  dune-client import secret key ledger_user "ledger://previous-markhor-gleeful-ant/secp256k1/0'/0'"
  dune-client import secret key ledger_user "ledger://previous-markhor-gleeful-ant/P-256/0'/0'"

If the Ledger is not found, it usually means that you didn’t start the Dune app on the Ledger device, or that your Ledger is not detected by the operating system.

The Dune client will extract the first key, and generate a uniq name for your Ledger. Here, it is previous-markhor-gleeful-ant. It can be very useful if you have several Ledgers, it makes it easy to verify that you are using the correct one.

You can have as many addresses as you want generated from the Ledger, by just changing the last two numbers from the BIP32 path /44'/1729'/0'/0'.

For now, let’s record only the keyhash associated with the 0'/0' derivation:

$ ./dune-client import secret key ledger_user "ledger://previous-markhor-gleeful-ant/ed25519/0'/0'"

Please validate (and write down) the public key hash displayed on the Ledger,
it should be equal
to `dn1RrJrx1y7hMYEJFWjZ3zDE5uS6CtEnnAS1`:

The client will wait for you to confirm on the Ledger that you can read the same key as displayed in the terminal. After confirmation, you get something like:

Dune address added: dn1RrJrx1y7hMYEJFWjZ3zDE5uS6CtEnnAS1
Key ledger_user registered

The key ledger_user is now recorded in your client. You will be able to use it for transfers and other operations. Each time you will need to sign an operation for that key, the client will automatically ask the Ledger and you will have confirm the operation.

For instance, assuming the address dn1RrJrx1y7hMYEJFWjZ3zDE5uS6CtEnnAS1 has some tokens on Dune’s testnet, you can make a transfer to an address dn1XHn8M1XvYfS3qsGDDwxRjW1HwbNxGpPbn as follows:

./dune-client -A testnet-node.dunscan.io -P 80 transfer 10 from ledger_user to \
  dn1XHn8M1XvYfS3qsGDDwxRjW1HwbNxGpPbn --burn-cap 0.257

You will then be asked to confirm the transaction or your Ledger device. After confirmation, the transaction will be injected in the node testnet-node.dunscan.io, which will forward it to others for inclusion in the next block.

Note that your private key never leaves your Ledger device. For instance, if you ask dune-client to print some information about ledger_user wallet with:

$ ./dune-client show address ledger_user -S

You’ll get something like:

Hash: dn1RrJrx1y7hMYEJFWjZ3zDE5uS6CtEnnAS1
Public Key: edpkuhqKnBR1nnVGcNLSqNKD9n4JdorZWXLpraJ1iDcYMjjiREfwQH
Secret Key: ledger://previous-markhor-gleeful-ant/ed25519/0'/0'

As you can see, secret key is not displayed: it is only calculated on the Ledger Nano S to sign operations. Remember to backup the 24 words that you used to initialize the Ledger, there is no other way to backup this secret key!

Baking mode with dune-client

For advanced users who want to become a validator, they should should switch the app to baking mode to be able to bake and endorse blocks. This should be done via command-line with dune-client. Here are the steps:

First, we assume that you imported your public key from the ledger with the command we have seen above:

$ ./dune-client list connected ledgers
...
$ ./dune-client import secret key ledger_user "ledger://previous-markhor-gleeful-ant/ed25519/0'/0'"
...

To switch the app to backing mode, you have just to run the following command, and confirm the operation on the Ledger when requested:

$ ./dune-client dune ledger becomes baking ledger_user

You have probably guessed that the command below allows to go back to wallet mode. There is a small difference: to exit baking mode, the Ledger will ask you to enter your PIN code:

$ ./dune-client dune ledger becomes wallet ledger_user

Assuming we are in baking mode, the next step is to configure the Ledger to bake for your key ledger_user. This is done with the command below, where <chain-ID> in the ID of the chain you would like to bake on:

./dune-client setup ledger to bake for ledger_user --main-chain-id <chain-ID>

Note that, you can ask the Ledger to bake for more than one address. For instance, if you have imported a second address ledger_user2 with a different derivation path:

$ ./dune-client import secret key ledger_user2 "ledger://previous-markhor-gleeful-ant/ed25519/0'/5'"

You can ask to Ledger to also bake for this key as follows:

./dune-client setup ledger to bake for ledger_user2 --main-chain-id <chain-ID> --more

Your can now start your baker and endorser. For instance, the baker is started with a command that looks as follows:

$ ./dune-baker-004-Pt24m4xi run with local node <path-to-node-dir> ledger_user

Warning

You should never start more than one baker or one endorser for the same public key hash. Indeed, you may double-bake or double-endorse, and thus, lose all your deposits of the corresponding cycle.

Note

For a more advanced and secure baking infrastructure, read this documentation.

Using the Tezos Ledger apps

Two Tezos apps for Ledger Nano S are available in Ledger Live, in the experimental section. The two modes of the Dune app are available by using two apps:

  • A Tezos Wallet app, for most operations, except baking

  • A Tezos Baking app, only for baking

Both should work with Dune as they do with Tezos, with the following differences:

  • the Tezos app will display the addresses as tzXXX addresses instead of dnXXX addresses. You may use dune-client dune print key hashes tzXXX to check the correspondence;

  • you can only setup one key for baking. This should not be a limitation for most people;

Tip

One could use Tezbox web wallet in combination with a Ledger Nano S having Tezos Wallet app installed to securely interact with Dune. For that, it suffices to edit Tezbox settings and put an RPC address of a Dune mainnet (for instance https://mainnet-node.dunscan.io) or testnet node (for instance https://mainnet-node.dunscan.io).