Add an intermediate tuto for baking using a Ledger device (#506)

* Add an intermediate tuto for baking using a Ledger device * fixup! Add an intermediate tuto for baking using a Ledger device * fixup! add record to install the baking app * fixup! some wording Co-authored-by: Ajinkya <[email protected]> * fixup! include NicNomadic and Tim McMackin suggestions Co-authored-by: NicNomadic <[email protected]> Co-authored-by: Tim McMackin <[email protected]> * fixup! mention Ledger Tezos apps in the introduction of Ledger Co-authored-by: Tim McMackin <[email protected]> * fixup! update tutorial prerequisites Co-authored-by: Tim McMackin <[email protected]> * fixup! inform readers that they must approve their ledger * fixup! add a conclusion to the HWM checks Co-authored-by: Tim McMackin <[email protected]> * fixup! inform that this tuto is an extension of Run a Tezos node in 5 steps * Add a section if you want to use a consensus key * Encourage readers to use a UPS as suggested by `https://opentezos.com/node-baking/baking/persistent-baker/#running-tezos-binaries-as-services` * Precede this tutorial with the tutorial `Join the DAL as a baker in 5 steps` * fixup! the third step title --------- Co-authored-by: Ajinkya <[email protected]> Co-authored-by: NicNomadic <[email protected]> Co-authored-by: Tim McMackin <[email protected]>
trilitech · Jan 21, 2025 · c0150bb · c0150bb
1 parent c8a44e4
commit c0150bb
Show file tree

Hide file tree

Showing 11 changed files with 377 additions and 12 deletions.
diff --git a/docs/tutorials.mdx b/docs/tutorials.mdx
@@ -69,6 +69,14 @@ These tutorials contain multiple parts and are intended for developers with some
   link="Start tutorial"
 />
 
+<TutorialCard
+  title="Create NFTs from a web application"
+  emoji="🚀"
+  href="/tutorials/create-nfts"
+  description="Learn how to create a web application and smart contract so you can create your own NFTs"
+  link="Start tutorial"
+/>
+
 <TutorialCard
   title="Join the DAL as a baker in 5 steps"
   emoji="🍞"
@@ -78,10 +86,10 @@ These tutorials contain multiple parts and are intended for developers with some
 />
 
 <TutorialCard
-  title="Create NFTs from a web application"
-  emoji="🚀"
-  href="/tutorials/create-nfts"
-  description="Learn how to create a web application and smart contract so you can create your own NFTs"
+  title="Bake using a Ledger device"
+  emoji="🥖"
+  href="/tutorials/bake-with-ledger"
+  description="Set up a Ledger device to protect your private keys and start baking"
   link="Start tutorial"
 />
 

diff --git a/docs/tutorials/bake-with-ledger.md b/docs/tutorials/bake-with-ledger.md
@@ -0,0 +1,39 @@
+---
+title: Bake using a Ledger device
+authors: Sébastien Palmer
+last_update:
+  date: 10 January 2025
+---
+
+## What is a Ledger device?
+
+A Ledger device is a physical wallet provided by [Ledger](https://www.ledger.com). Its main purpose is to store the holder's private keys without ever disclosing them.
+
+Ledger devices support many blockchains by installing applications, such as an application to manage Tezos accounts and keys and an application to allow a Tezos baker to use keys on the Ledger.
+
+## Why use a Ledger device to bake?
+
+The baker daemon must have constant access to the baker's private key so that it can sign consensus operations and blocks.
+If a malicious entity manages to get access to this private key, it will also gain access to the baker's funds.
+Keeping your private key on a Ledger device and only interacting with an application dedicated to baking would prevent any direct access to your private key.
+
+## Setting up your Ledger to launch a baker signing with Ledger
+
+Follow this tutorial before setting up your baker with the tutorial [Run a Tezos node in 5 steps](/tutorials/join-dal-baker). This tutorial will tell you when to switch to that tutorial and what changes to make so the baker you set up will use the accounts on your Ledger device.
+
+In this tutorial, we'll look at:
+ - how to install the Tezos baking application on your Ledger device
+ - how to configure your Ledger device so that the [Ledger baking application of Tezos](https://github.com/trilitech/ledger-app-tezos-baking) works properly
+ - how to use an external signer (`octez-signer`) while running your baker for enhanced protection
+
+## Prerequisites
+
+ - A Ledger device: Nano S, Nano S+, Nano X, Stax or Flex
+ - A computer or cloud VM that can run without interruptions, because the baker program must run persistently
+ - The latest version of the Octez suite, including the `octez-signer` program
+
+:::note
+
+Note that a PIN input will be required after a power failure. To ensure a truly persistent system, please use a [UPS](https://wikipedia.org/wiki/Uninterruptible_power_supply).
+
+:::
diff --git a/docs/tutorials/bake-with-ledger/install-app.md b/docs/tutorials/bake-with-ledger/install-app.md
@@ -0,0 +1,35 @@
+---
+title: "Install the Ledger baking application of Tezos"
+authors: Sébastien Palmer
+last_update:
+  date: 10 January 2025
+---
+
+[`Tezos Baking`](https://github.com/trilitech/ledger-app-tezos-baking) is the application developed to bake on Tezos using your Ledger device.
+It allows you to sign block and consensus operations while keeping your private keys secure in the Ledger hardware. Some of its additional features are:
+ 1. HWM tracking to avoid double baking
+ 2. Restricted signing permission, i.e. it only allows signing baking related operations. You can not approve signing of funds transfer using baking app on Ledger. 
+
+## Download `Ledger Live`
+
+To download the Tezos baking application, you first need to download `Ledger Live`.
+[`Ledger Live`](https://www.ledger.com/ledger-live) is the application provided by Ledger to allow you to download the various applications compatible with your Ledger device.
+
+## Download `Tezos Baking`
+
+Once you have downloaded `Ledger Live`, launch it.
+
+The Tezos baking application is only available when developer mode is activated. To activate it, go to settings and, in the `Experimental features` tab, activate `Developer mode`. With developer mode enabled, the Tezos baking application is now accessible.
+
+Click on `My Ledger`. If you have not already done so, connect your Ledger device to the USB port and authorize the secure connection to `Ledger Live` on your Ledger device.
+
+Search for the `Tezos Baking` application and click on `Install`.
+
+![Install the Ledger `Tezos Baking` application from `Ledger Live`](/img/tutorials/bake-with-ledger/install-ledger-tezos-baking-app.gif)
+
+## Download `Tezos Wallet (XTZ)`
+
+To be able to sign the operations needed to set up your baker, you also need the `Tezos Wallet (XTZ)` application.
+[`Tezos Wallet (XTZ)`](https://github.com/trilitech/ledger-app-tezos-wallet) is the application developed to sign Tezos operations using your Ledger device.
+
+Find and install the `Tezos Wallet (XTZ)` application.
diff --git a/docs/tutorials/bake-with-ledger/run-baker.md b/docs/tutorials/bake-with-ledger/run-baker.md
@@ -0,0 +1,120 @@
+---
+title: "Running a baker signing using a Ledger baking key"
+authors: Sébastien Palmer
+last_update:
+  date: 10 January 2025
+---
+
+Now that the Ledger baking key is set up, you can follow the steps of [Run a Tezos node in 5 steps](/tutorials/join-dal-baker). However, some steps will differ.
+
+## Set up a baker account
+
+Complete the [Step 1: Run an Octez node](/tutorials/join-dal-baker/run-node) of the tutorial, and make following changes in [Step 2: Set up a baker account](/tutorials/join-dal-baker/prepare-account).
+
+ - If you **want to use a consensus key**, instead of generating it, use the Ledger key. To do so, import it from the `octez-signer` remote with the following command:
+
+    ```bash
+    octez-client import secret key consensus_key remote:tz...
+    ```
+
+    > Replace the `tz...` with the public key hash of your Ledger baking key.
+
+    You can then continue to set up your baker account.
+
+    By registering your baker as a delegate with the ledger key as the consensus key, the baker daemon will sign using the Ledger.
+
+ - If you **don't want to use a consensus key**, use your Ledger key directly as a baker. Import it from the `octez-signer` remote with the following command:
+
+    ```bash
+    octez-client import secret key my_baker remote:tz...
+    ```
+
+    > Replace the `tz...` with the public key hash of your Ledger baking key.
+
+    In that case, to be able to sign the operations required to set up your baker, you need to use the `Tezos Wallet (XTZ)` application.
+    Quit the `Tezos Baking` application and open the `Tezos Wallet (XTZ)` application.
+
+## Before running the Octez baking daemon
+
+Complete [Step 3: Run an Octez DAL node](/tutorials/join-dal-baker/run-dal-node). For the [Step 4: Run an Octez baking daemon](/tutorials/join-dal-baker/run-baker), make following changes to setup `octez-signer` and `Tezos Baking` application.
+
+### Setup the Ledger high watermark (HWM)
+
+For security reasons, always reset HWM to the highest possible block value before starting to bake. The highest block can be obtained from [Tzkt](https://www.tzkt.io/blocks?expand=1). Then, use that block value as the level in the following command.
+
+Go back to the `Tezos Baking` application and run:
+
+   ```bash
+   octez-signer set ledger high watermark for my_ledger_key to <LEVEL>
+   ```
+
+On your Ledger device, you should see a screen sequence similar to:
+![Ledger Setup Review](/img/tutorials/bake-with-ledger/set-hwm-review.png)
+<!-- https://lucid.app/lucidchart/26df7357-40e6-4c1b-8ffe-0e4b8eebf707/edit?beaconFlowId=D98D3B908C0603CC&invitationId=inv_08b134b7-3e40-4429-af31-101e36489cc3&page=0_0# -->
+
+Check that the HWM is the one you supplied, then you can approve.
+
+Output:
+
+   ```console
+   ledger://masculine-pig-stupendous-dugong/secp256k1/0h/0h has now high water mark: 42 (round: 0)
+   ```
+
+:::note
+
+Alternatively, the HWM can be set up from the setup command:
+
+   ```bash
+   octez-signer setup ledger to bake for my_ledger_key --main-hwm <LEVEL>
+   ```
+
+:::
+
+### Set up additional checks for `octez-signer`
+
+`octez-signer` also has the ability to enable various checks. Stop the previously launched `octez-signer` TCP socket and restart it with the following command:
+
+   ```bash
+   octez-signer launch socket signer -M 0x11,0x12,0x13 -W -a localhost
+   ```
+
+> The `-M 0x11,0x12,0x13` option is used to only request consensus operations and blocks to be signed.
+
+> The `-W` tag is used to activate the HWM check.
+
+:::note Warning
+
+The `-W` tag is required if you have chosen to disable the `High Watermark` option in the `Tezos Baking` application.
+
+:::
+
+## Security verifications
+
+Everything is ready, you can now finish the tutorial [Run a Tezos node in 5 steps](/tutorials/join-dal-baker). The baking daemon will send the data to be signed to `octez-signer` which will send it to your Ledger device, which will sign them.
+
+Once the baking daemon has started, you can check on your Ledger device that the HWM is evolving in accordance with the blocks signed by your Ledger baking key.
+
+The `octez-signer` also stores the HWM for the blocks it has signed. You can find them in a file named `Net..._highwatermarks` in the `.tezos-client` folder.
+
+> `Net...` being the chain-id of the chain in which you bake.
+
+Open the file and check that the HWMs evolve in accordance with the blocks signed by your Ledger baking key:
+
+   ```bash
+   cat .tezos-client/NetXnHfVqm9iesp_highwatermarks
+   ```
+
+   ```json
+   { "blocks":
+       [ { "delegate": "tz...",
+           "highwatermark": { "round": 0, "level": 107095 } } ],
+     "preattestations":
+       [ { "delegate": "tz...",
+           "highwatermark": { "round": 0, "level": 107096 } } ],
+     "attestations":
+       [ { "delegate": "tz...",
+           "highwatermark": { "round": 0, "level": 107096 } } ] }
+   ```
+
+Now the baking daemon is running and using the Ledger to sign consensus (baking) operations. You can leave the baker running and check on it by looking at the block numbers at the end of the `.tezos-client/NetXnHfVqm9iesp_highwatermarks` file.
+
diff --git a/docs/tutorials/bake-with-ledger/setup-baker.md b/docs/tutorials/bake-with-ledger/setup-baker.md
@@ -0,0 +1,109 @@
+---
+title: "Set up your Ledger baking key with octez-signer"
+authors: Sébastien Palmer
+last_update:
+  date: 10 January 2025
+---
+
+It’s recommended to use a separate machine to run the remote signer. For simplicity, in this tutorial, we assume a setup where the Ledger device is connected to the same machine running the baker binary. On the same machine, the following commands can be used to set up the baking key with `octez-signer`.
+
+## Import a key from your Ledger device to the `octez-signer` context
+
+Let's start by importing a key from your Ledger device for `octez-signer`.
+Connect your Ledger device with a USB cable and open the `Tezos Baking` application.
+To see the available keys, run:
+
+   ```bash
+   octez-signer list connected ledgers
+   ```
+
+Output:
+
+   ```console
+   ## Ledger `masculine-pig-stupendous-dugong`
+   Found a Tezos Baking 2.4.7 (git-description: "v2.4.7-70-g3195b4d2")
+   application running on Ledger Nano S Plus at [1-1.4.6:1.0].
+
+   To use keys at BIP32 path m/44'/1729'/0'/0' (default Tezos key path), use one
+   of:
+     octez-client import secret key ledger_username "ledger://masculine-pig-stupendous-dugong/ed25519/0h/0h"
+     octez-client import secret key ledger_username "ledger://masculine-pig-stupendous-dugong/secp256k1/0h/0h"
+     octez-client import secret key ledger_username "ledger://masculine-pig-stupendous-dugong/P-256/0h/0h"
+     octez-client import secret key ledger_username "ledger://masculine-pig-stupendous-dugong/bip25519/0h/0h"
+   ```
+
+Key's URIs are of the form `ledger://<animals>/<curve>[/<path>]` where:
+ - `<animals>` is the identifier of the ledger.
+ - `<curve>` is the signing curve
+ - `<path>` is a BIP32 path anchored at m/44h/1729h. The ledger does not yet support non-hardened paths, so each node of the path must be hardened.
+
+:::note Signing curve
+
+The `secp256k1` and `P-256` signature schemes (resp. `tz2` and `tz3`) have the best signature performance with the `Tezos Baking` application.
+
+:::
+
+Choose one of the URIs shown, modifying the BIP32 path as you like, then import it using `octez-signer`:
+
+   ```bash
+   octez-signer import secret key my_ledger_key "ledger://masculine-pig-stupendous-dugong/secp256k1/0h/0h"
+   ```
+
+On your Ledger device, you should see a screen sequence similar to:
+![Ledger Key Review](/img/tutorials/bake-with-ledger/pkh-review.png)
+<!-- https://lucid.app/lucidchart/26df7357-40e6-4c1b-8ffe-0e4b8eebf707/edit?beaconFlowId=D98D3B908C0603CC&invitationId=inv_08b134b7-3e40-4429-af31-101e36489cc3&page=0_0# -->
+
+If the public key hash displayed on your Ledger is equal to the address displayed in the command output, you can approve.
+
+Output:
+
+   ```console
+   Please validate (and write down) the public key hash displayed on the Ledger,
+   it should be equal
+   to `tz...`:
+   Tezos address added: tz...
+   ```
+
+## Authorise the baking key in the `Tezos Baking` application
+
+For your security, the `Tezos Baking` application only allows one key to be used for signing. So you need to specify which key you want to bake with:
+
+   ```bash
+   octez-signer setup ledger to bake for my_ledger_key
+   ```
+
+On your Ledger device, you should see a screen sequence similar to:
+![Ledger Setup Review](/img/tutorials/bake-with-ledger/setup-review.png)
+<!-- https://lucid.app/lucidchart/26df7357-40e6-4c1b-8ffe-0e4b8eebf707/edit?beaconFlowId=D98D3B908C0603CC&invitationId=inv_08b134b7-3e40-4429-af31-101e36489cc3&page=0_0# -->
+
+If the information displayed on your Ledger is similar to the information displayed in the command output, you can approve.
+
+Output:
+
+   ```console
+   Setting up the ledger:
+   * Main chain ID: 'Unspecified' -> NetXdQprcVkpaWU
+   * Main chain High Watermark: 0 (round: 0) -> 0 (round: 0)
+   * Test chain High Watermark: 0 (round: 0) -> 0 (round: 0)
+   Authorized baking for address: tz...
+   Corresponding full public key: ..pk...
+   ```
+
+## Link `octez-signer` to `octez-client`
+
+Now that your baking key on `octez-signer` is linked to your Ledger device, `octez-signer` will be in charge of signing using your Ledger device. Let's launch `octez-signer`:
+
+   ```bash
+   octez-signer launch socket signer -a localhost
+   ```
+
+> The default port is `7732`.
+
+To be able to sign from `octez-client` and from the baker binaries, you have to link your remote signer for `octez-client`.
+In a new terminal, run:
+
+   ```bash
+   octez-client -R 'tcp://localhost:7732' config update
+   ```
+
+This way, the key stored in the context of your `octez-signer` will be accessible by remote from the `octez-client` context.
diff --git a/docs/tutorials/bake-with-ledger/setup-ledger.md b/docs/tutorials/bake-with-ledger/setup-ledger.md
@@ -0,0 +1,40 @@
+---
+title: "Set up your ledger"
+authors: Sébastien Palmer
+last_update:
+  date: 10 January 2025
+---
+
+## Disable PIN lock
+
+The Tezos baking application allows you to bake securely without interruption. However, you will need to disable auto PIN lock feature in the Ledger to avoid getting locked out of the Ledger. Otherwise the Ledger device will lock itself and baking app will not work.
+
+:::note Warning
+
+Disabling the automatic lock on your Ledger device poses a risk that if any other app except baking-app is left open on your device, someone could get access to your funds by using that Ledger if left unattended.
+The Tezos baking application is extremely secure and it only allows you to sign baking-related transactions and requires a PIN code to exit the application. However, remember to **reactivate the automatic lock on your Ledger device if you stop using the Tezos baking application on this device**.
+
+:::
+
+Go to the settings of your Ledger device and search for the automatic PIN lock option, then deactivate it.
+ - For Nanos, Nanos+ and Nanox devices, go to `Settings` then `Security` and finally `PIN lock`.
+ - For Stax and Flex devices, go to `Settings` then `Lock screen` and then `Auto-lock`.
+
+## Screen saver
+
+In order to preserve the performance and integrity of your Ledger device, it is **strongly recommended** to activate the screen saver of your Ledger device. Go to the settings of your Ledger device and look for the screen saver option, then activate it for a value that suits you.
+ - For Nanos, Nanos+ and Nanox devices, go to `Settings` then `Security` and finally `Screen saver`.
+ - For Stax and Flex devices, there is no screen saver as of writing this article (Jan 25).
+
+## HWM option
+
+:::note Warning
+
+HWM (High Watermark) protection exists in the Ledger `Tezos Baking` application to avoid double-baking, double-attesting or double-preattesting at the level. The HWM is stored in NVRAM (Non-volatile Random Access Memory), after every signature, by the `Tezos Baking` application (that is on each pre-attestation, attestation, but also while signing blocks).
+
+The NVRAM on Ledger has limited read/write lifetime, thus frequent updates of NVRAM leads to NVRAM burn. To resolve this, an **optional** setting called HWM (ENABLE/DISABLE) is added to the Ledger `Tezos Baking` application (since v 2.4.7). When disabled, it allows storing HWM on RAM instead of NVRAM during the signature of operations. This increases the speed/performance of the Ledger `Tezos Baking` application and extends the lifetime of Ledger devices. The last HWM value on the Ledger’s RAM is written to NVRAM at the time of exiting the Ledger `Tezos Baking` application for persistent storage.
+In case of an abrupt interruption of the Ledger `Tezos Baking` application, e.g. caused by an abrupt power off of the Ledger device, the current HWM value may not be updated to the device’s NVRAM. Thus, it’s important to reset the value of the HWM on the Ledger device to the highest HWM value signed by the baker, before resuming baking. (See [Setup the Ledger high watermark (HWM)](/tutorials/bake-with-ledger/run-baker#setup-the-ledger-high-watermark-hwm) to setup the HWM)
+
+:::
+
+For additional protection from double-baking, this tutorial demonstrates the use of an external signer (`octez-signer`), which keeps track of HWM and prevents double baking. It's recommended to use this external signer when you disable the HWM feature on your Ledger device.