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

spalmer25 · 2025-01-10T15:39:49Z

This PR adds an intermediate tutorial to present how to bake with a Ledger device.

It is presented all steps from the installation of the Ledger baking app of Tezos to security verifications.

Reference: Ledger maintainance announcement for Tezos Bakers

vercel · 2025-01-10T15:39:53Z

@spalmer25 is attempting to deploy a commit to the Trili Tech Team on Vercel.

A member of the Team first needs to authorize it.

ajinkyaraj-23

Will review once again when its complete.

ajinkyaraj-23 · 2025-01-13T10:35:26Z

docs/tutorials/bake-with-ledger/install-app.md

+
+:::note
+
+You won't need `Ledger Live` for the rest of the tutorial.


You dont need to mention this note.

ajinkyaraj-23 · 2025-01-13T10:36:20Z

docs/tutorials/bake-with-ledger/install-app.md

+
+## Download `Tezos Wallet (XTZ)`
+
+The `Tezos Baking` application does not allow you to sign some operations used in this tutorial. You will also need the `Tezos Wallet (XTZ)` application to sign them.


Rephrase it like , to sign operations to setup baking you need Tezos wallet app. No need to mention tezos baking does not allow ...

Yes, indeed. I'll change it.

ajinkyaraj-23 · 2025-01-13T10:37:34Z

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

+   ```
+
+A validation from your Ledger device will be required.
+


a series of screenshots might help here. Not sure.

I've added the screen flows.
The original document can be found here :
https://lucid.app/lucidchart/26df7357-40e6-4c1b-8ffe-0e4b8eebf707/edit?beaconFlowId=D98D3B908C0603CC&invitationId=inv_08b134b7-3e40-4429-af31-101e36489cc3&page=0_0#
Do you have access to it?

ajinkyaraj-23 · 2025-01-13T10:38:35Z

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

+In a new terminal, run:
+
+   ```bash
+   octez-client -R 'tcp://localhost:7732' config update


Does this end here? Need to complete the command and some text below

The command is complete.
I will add an explanatory text below.

ajinkyaraj-23 · 2025-01-13T10:41:00Z

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

+
+In the `Tezos Baking` application, in order to avoid signing blocks or operations that could lead to double-baking, double-attesting or double-preattesting, checks are carried out on the blocks and operations whose signature has been requested.
+These verifications require a High Watermark (HWM) to be stored in the RAM of your Ledger device. Saving information in RAM can be slow and can therefore slow down the performance of your device during baking.
+You can disable this by disabling the `High Watermark` option in the `Settings` section of the `Tezos Baking` application. However, when this option is no longer active, it becomes possible to sign operations that would lead to double-baking, double-attesting or double-preattesting. You are therefore strongly advised not to deactivate this option if your block and operations provider does not also prevent double-baking, double-attesting and double-preattesting.


Not a wording we want, also incorrect.
THe HWM is stored in NVRAM (non-volatile memory) .
Refer to the wording i have put in word document.

You're right, I will use the text of the reference doc.

ajinkyaraj-23 · 2025-01-14T10:11:12Z

docs/tutorials/bake-with-ledger.md

+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 launch a baker daemon by signing from your Ledger device using `octez-signer`


How to use an external signer (octez-signer) while running your baker for enhanced protection

docs/tutorials/bake-with-ledger.md

docs/tutorials/bake-with-ledger/install-app.md

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

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

ajinkyaraj-23 · 2025-01-14T12:34:54Z

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

+   ```
+
+A validation from your Ledger device will be required.
+


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

ajinkyaraj-23 · 2025-01-14T12:45:26Z

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

+
+:::note Warning
+
+This step is not necessary to be able to bake. However, if the HWM is not initialized, the first level encountered in an operation or block to be signed will be used as the initialization level. For this first operation or block, double baking, double-attesting or double pre-attesting will not be detected. It is therefore **strongly recommended** to at least initialize the HWM with the level of the block at the head of the chain.


Dont give extra information. make it compulsory for the user.

LIne 30 to 36 can be replaced by
"Always reset HWM to highest block value before starting to bake. The highest block can be obtained from Tzkt"

Co-authored-by: Ajinkya <[email protected]>

ajinkyaraj-23

LGTM.
Thanks

NicNomadic

As the page run-baker complements the existing tutorial written by Tim (run a node in 5 steps), @timothymcmackin will review this to make sure the content integrates well.

An orthogonal discussion is: these pages seem to belong to document the "Ledger support" product, so I assume you're committed to maintain them with every evolution of your code base, right? For that purpose, I wonder whether it would not be safer to keep all this doc in the repos of these products (https://github.com/trilitech/ledger-app-tezos-baking and https://github.com/trilitech/ledger-app-tezos-wallet), and only refer to them in docs.tezos.com?

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

ajinkyaraj-23 · 2025-01-15T18:35:04Z

As the page run-baker complements the existing tutorial written by Tim (run a node in 5 steps), @timothymcmackin will review this to make sure the content integrates well.

An orthogonal discussion is: these pages seem to belong to document the "Ledger support" product, so I assume you're committed to maintain them with every evolution of your code base, right? For that purpose, I wonder whether it would not be safer to keep all this doc in the repos of these products (https://github.com/trilitech/ledger-app-tezos-baking and https://github.com/trilitech/ledger-app-tezos-wallet), and only refer to them in docs.tezos.com?

I believe the baking app tutorial will not change much as the app is expected to be phased out after BLS signatures are introduced ( No timeline yet). Therefore its alright if they are here.

timothymcmackin

This may be a little tricky for people to follow because they have to switch between two tutorials to get it to work, but it may be doable. After we merge this I'll add a note to the other tutorial to remind you to set up your Ledger before you start that tutorial. A few other comments:

What do I do if I want to use a separate consensus key as in the baker tutorial?
In the intro, recommend that you add a section that explains the relationship between this tutorial and the main baker tutorial. Something like: Follow this tutorial before setting up your baker with the tutorial "Run a Tezos node in 5 steps." 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."

docs/tutorials.mdx

docs/tutorials/bake-with-ledger.md

timothymcmackin · 2025-01-15T19:38:34Z

docs/tutorials/bake-with-ledger.md

+
+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.


It may not be clear why this is relevant without mentioning that Tezos is one of the applications. Maybe something like "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."

docs/tutorials/bake-with-ledger.md

timothymcmackin · 2025-01-15T19:40:41Z

docs/tutorials/bake-with-ledger.md

+ - You need Ledger device.
+ - Baker program needs to run constantly, so you need a computer / cloud vm which can run without interruptions. 


Suggested change

- You need Ledger device.

- Baker program needs to run constantly, so you need a computer / cloud vm which can run without interruptions.

- A Ledger device

- 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

Do we need to list supported Ledger devices here?

All Ledgers support the 2 Tezos apps, but I think we should add the list of supported devices.
If future Ledgers are developed, which we have not supported in our applications, the reader should be informed.

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

timothymcmackin · 2025-01-15T19:55:12Z

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

+   octez-signer set ledger high watermark for my_ledger_key to <LEVEL>
+   ```
+
+On your Ledger device, you should see a screen sequence similar to:


Do I have to approve this with my Ledger or is this signed automatically?

You have to approve on your Ledger. I will also insert this information.

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

timothymcmackin · 2025-01-15T19:58:17Z

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

+           "highwatermark": { "round": 0, "level": 107096 } } ] }
+   ```
+
+


Maybe finish with a little summary here? "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."

spalmer25 · 2025-01-16T10:19:29Z

What do I do if I want to use a separate consensus key as in the baker tutorial?

If you want to use a consensus key, then unlike what is currently written in the tutorial, the baking key is not the ledger key. The Ledger key will be used as the consensus key. The only command line that changes in the tutorial is:

octez-client import secret key my_baker remote:tz...

And should be:

octez-client import secret key consensus_key remote:tz...

I will modify the section run-baker#set-up-a-baker-account to explain this.

NicNomadic · 2025-01-16T10:22:16Z

An orthogonal discussion is: these pages seem to belong to document the "Ledger support" product, so I assume you're committed to maintain them with every evolution of your code base, right? For that purpose, I wonder whether it would not be safer to keep all this doc in the repos of these products (https://github.com/trilitech/ledger-app-tezos-baking and https://github.com/trilitech/ledger-app-tezos-wallet), and only refer to them in docs.tezos.com?

I believe the baking app tutorial will not change much as the app is expected to be phased out after BLS signatures are introduced ( No timeline yet). Therefore its alright if they are here.

Still, if you want to place them here, can you commit testing all the tutorial at every major Octez release, at least the pages using Octez tools? We don't have enough resources in the doc squad to do that.

Also, on a more conceptual level, the architecture of the ecosystem documentation separates the Tezos-wide docs (on docs.tezos.com) from docs of each product, such as Octez, LIGO, etc. So conceptually, is this tutorial more than the doc of the Ledger apps?

Co-authored-by: NicNomadic <[email protected]> Co-authored-by: Tim McMackin <[email protected]>

Co-authored-by: Tim McMackin <[email protected]>

… steps

timothymcmackin · 2025-01-16T16:43:43Z

Maybe mention that you should use a UPS to keep your Ledger active and logged-in during power outages? That's mentioned here: https://opentezos.com/node-baking/baking/persistent-baker/#running-tezos-binaries-as-services

Add an intermediate tuto for baking using a Ledger device

0a30ea4

ajinkyaraj-23 reviewed Jan 13, 2025

View reviewed changes

spalmer25 added 2 commits January 13, 2025 14:42

fixup! Add an intermediate tuto for baking using a Ledger device

dd121a9

fixup! add record to install the baking app

cfd18d4

spalmer25 force-pushed the palmer@functori@tuto-running-baker-with-ledger branch from e91e9b9 to cfd18d4 Compare January 13, 2025 14:54

spalmer25 marked this pull request as ready for review January 13, 2025 15:39

spalmer25 requested a review from ajinkyaraj-23 January 13, 2025 15:39

ajinkyaraj-23 reviewed Jan 14, 2025

View reviewed changes

fixup! some wording

6d92a85

Co-authored-by: Ajinkya <[email protected]>

spalmer25 force-pushed the palmer@functori@tuto-running-baker-with-ledger branch from 9c9a8a9 to 6d92a85 Compare January 14, 2025 15:32

spalmer25 requested a review from ajinkyaraj-23 January 14, 2025 15:34

ajinkyaraj-23 approved these changes Jan 14, 2025

View reviewed changes

NicNomadic reviewed Jan 15, 2025

View reviewed changes

docs/tutorials/bake-with-ledger/run-baker.md Outdated Show resolved Hide resolved

NicNomadic requested a review from timothymcmackin January 15, 2025 16:54

timothymcmackin requested changes Jan 15, 2025

View reviewed changes

spalmer25 and others added 7 commits January 16, 2025 11:27

fixup! include NicNomadic and Tim McMackin suggestions

584ff6c

Co-authored-by: NicNomadic <[email protected]> Co-authored-by: Tim McMackin <[email protected]>

fixup! mention Ledger Tezos apps in the introduction of Ledger

66887fb

Co-authored-by: Tim McMackin <[email protected]>

fixup! update tutorial prerequisites

b7a5bff

Co-authored-by: Tim McMackin <[email protected]>

fixup! inform readers that they must approve their ledger

627311e

fixup! add a conclusion to the HWM checks

a55d0f8

Co-authored-by: Tim McMackin <[email protected]>

fixup! inform that this tuto is an extension of Run a Tezos node in 5…

9c3e932

… steps

Add a section if you want to use a consensus key

19ccfab

spalmer25 force-pushed the palmer@functori@tuto-running-baker-with-ledger branch from c192bdd to 19ccfab Compare January 16, 2025 11:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

spalmer25 commented Jan 10, 2025 •

edited

Loading

vercel bot commented Jan 10, 2025

ajinkyaraj-23 left a comment

ajinkyaraj-23 Jan 13, 2025

spalmer25 Jan 13, 2025

ajinkyaraj-23 Jan 13, 2025

spalmer25 Jan 13, 2025

ajinkyaraj-23 Jan 13, 2025

spalmer25 Jan 13, 2025

ajinkyaraj-23 Jan 14, 2025

ajinkyaraj-23 Jan 13, 2025

spalmer25 Jan 13, 2025

ajinkyaraj-23 Jan 13, 2025

spalmer25 Jan 13, 2025

ajinkyaraj-23 Jan 14, 2025

ajinkyaraj-23 Jan 14, 2025

ajinkyaraj-23 Jan 14, 2025

ajinkyaraj-23 left a comment

NicNomadic left a comment

ajinkyaraj-23 commented Jan 15, 2025

timothymcmackin left a comment

timothymcmackin Jan 15, 2025

timothymcmackin Jan 15, 2025

spalmer25 Jan 16, 2025

timothymcmackin Jan 15, 2025

spalmer25 Jan 16, 2025

timothymcmackin Jan 15, 2025

spalmer25 commented Jan 16, 2025

NicNomadic commented Jan 16, 2025

timothymcmackin commented Jan 16, 2025


		:::note

		You won't need `Ledger Live` for the rest of the tutorial.


		## Download `Tezos Wallet (XTZ)`

		The `Tezos Baking` application does not allow you to sign some operations used in this tutorial. You will also need the `Tezos Wallet (XTZ)` application to sign them.


		:::note Warning

		This step is not necessary to be able to bake. However, if the HWM is not initialized, the first level encountered in an operation or block to be signed will be used as the initialization level. For this first operation or block, double baking, double-attesting or double pre-attesting will not be detected. It is therefore strongly recommended to at least initialize the HWM with the level of the block at the head of the chain.


		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.

		- You need Ledger device.
		- Baker program needs to run constantly, so you need a computer / cloud vm which can run without interruptions.

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

Are you sure you want to change the base?

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

Conversation

spalmer25 commented Jan 10, 2025 • edited Loading

vercel bot commented Jan 10, 2025

ajinkyaraj-23 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ajinkyaraj-23 left a comment

Choose a reason for hiding this comment

NicNomadic left a comment

Choose a reason for hiding this comment

ajinkyaraj-23 commented Jan 15, 2025

timothymcmackin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

spalmer25 commented Jan 16, 2025

NicNomadic commented Jan 16, 2025

timothymcmackin commented Jan 16, 2025

spalmer25 commented Jan 10, 2025 •

edited

Loading