Add an intermediate tuto for baking using a Ledger device

docs/tutorials.mdx

@@ -85,6 +85,14 @@ These tutorials contain multiple parts and are intended for developers with some
   link="Start tutorial"
 />
 
+<TutorialCard
+  title="Bake using a Ledger device"
+  emoji="🥖"
+  href="/tutorials/bake-with-ledger"
+  description="Setup a Ledger device and start baking"
+  link="Start tutorial"
+/>
+
 </TutorialCardContainer>
 
 ## Advanced

docs/tutorials/bake-with-ledger.md

@@ -0,0 +1,29 @@
+---
+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.
+
+Applications can be installed on your Ledger device so that you can take advantage of the many features of the blockchain without any entity having direct access to your private key.
+
+## Why using a Ledger device to bake?
+
+Baker involves, in particular, providing constant access to the baker's private key so that the baking daemon 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.
+
+
+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
+
+ - You need Ledger device.
+ - Baker program needs to run constantly, so you need a computer / cloud vm which can run without interruptions. 

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 operation needed to setup your baker, you will 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.

docs/tutorials/bake-with-ledger/run-baker.md

@@ -0,0 +1,104 @@
+---
+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 step](/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).
+For this step, you already have a baker! No need to regenerate it, just import it:
+
+   ```bash
+   octez-client import secret key my_baker remote:tz...
+   ```
+
+> Replace the `tz...` with the public key hash of your Ledger baking key.
+
+To be able to sign the operations you find in **Step 2**, 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 reason, always reset HWM to highest block value before starting to bake. The highest block can be obtained from [Tzkt](https://www.tzkt.io/blocks?expand=1)
+
+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# -->
+
+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>
+   ```
+
+:::
+
+### Setup additionnal 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 step](/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 } } ] }
+   ```
+
+

docs/tutorials/bake-with-ledger/setup-baker.md

@@ -0,0 +1,105 @@
+---
+title: "Setup 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# -->
+
+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# -->
+
+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.

docs/tutorials/bake-with-ledger/setup-ledger.md

@@ -0,0 +1,40 @@
+---
+title: "Setup 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, we will demonstrate use of external signer (`octez-signer`), which keeps track of HWM and prevents double baking. Its recommended to use this external signer, when you disable the HWM feature on your Ledger device.

sidebars.js

@@ -362,6 +362,20 @@ const sidebars = {
         'tutorials/join-dal-baker/conclusion',
       ],
     },
+    {
+      type: 'category',
+      label: 'Bake using a Ledger\'s device',
+      link: {
+        type: 'doc',
+        id: 'tutorials/bake-with-ledger',
+      },
+      items: [
+        'tutorials/bake-with-ledger/install-app',
+        'tutorials/bake-with-ledger/setup-ledger',
+        'tutorials/bake-with-ledger/setup-baker',
+        'tutorials/bake-with-ledger/run-baker',
+      ],
+    },
     {
       type: 'html',
       value: '<div>Advanced</div>',