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"

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

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?

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

spalmer25 · 2025-01-17T09:50:13Z

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

We definitely need to inform readers of this information, thank you!

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

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

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

… steps

as suggested by `https://opentezos.com/node-baking/baking/persistent-baker/#running-tezos-binaries-as-services`

timothymcmackin

LGTM! Go ahead and merge when you are ready, or tell me and I'll merge.

spalmer25 · 2025-01-21T07:55:11Z

LGTM! Go ahead and merge when you are ready, or tell me and I'll merge.

I have no other changes to make.
@ajinkyaraj-23 , @NicNomadic do you also agree to merge this MR.
I don't have the required permissions to merge. If everyone agrees, you can merge.

NicNomadic · 2025-01-21T10:20:40Z

@timothymcmackin can you approve please the deployment on Vercel, to see the rendering of this tutorial? I don't have the rights for that.

NicNomadic · 2025-01-21T10:29:33Z

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?

OK, let's consider that most of the pages concern the interaction between the Ledger apps and the Octez suite, and thereby this tutorial belongs to the Tezos docs. Only two pages deviate from this: install_app and setup_ledger; but they are quite small and co-locating them in the same tutorial (here) can make some sense, even though they could as well live in the ledger-app repo. Up to you @ajinkyaraj-23 to decide on that.

ajinkyaraj-23 · 2025-01-21T10:37:03Z

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?

OK, let's consider that most of the pages concern the interaction between the Ledger apps and the Octez suite, and thereby this tutorial belongs to the Tezos docs. Only two pages deviate from this: install_app and setup_ledger; but they are quite small and co-locating them in the same tutorial (here) can make some sense, even though they could as well live in the ledger-app repo. Up to you @ajinkyaraj-23 to decide on that.

We can commit to testing this tutorial for every major octez-release, we will always have resource to maintain ledger apps because they are critical piece of Tezos ecosystem as long as ledger is in use.

Regarding the placement, the tutorial in its detailed form is already present in the Ledger-app repo, but it does not have visibility and is overly technical for a newbie. This tutorial will serve a wider audience by keeping things simple. Just like setup DAL as a baker tutorial does not have any thing which is not present in tezos gitlab docs but it makes things very simple and straighforward and easy to find. I would use the same logic here for using ledger baking app and octez-signer with ledger.

ajinkyaraj-23 · 2025-01-21T10:39:02Z

LGTM! Go ahead and merge when you are ready, or tell me and I'll merge.

I also second this approval. But i would request a Vercel deployment first to test how the rendering would look on preview website. Who has the rights to do that?

NicNomadic · 2025-01-21T10:46:01Z

We can commit to testing this tutorial for every major octez-release, we will always have resource to maintain ledger apps because they are critical piece of Tezos ecosystem as long as ledger is in use.

Thanks!

Regarding the placement, the tutorial in its detailed form is already present in the Ledger-app repo, but it does not have visibility and is overly technical for a newbie. This tutorial will serve a wider audience by keeping things simple. Just like setup DAL as a baker tutorial does not have any thing which is not present in tezos gitlab docs but it makes things very simple and straighforward and easy to find. I would use the same logic here for using ledger baking app and octez-signer with ledger.

I agree, distilling a more digest form is one valid reason to include this in the Tezos docs, so let's go for it.

NicNomadic · 2025-01-21T10:48:52Z

LGTM! Go ahead and merge when you are ready, or tell me and I'll merge.

I also second this approval. But i would request a Vercel deployment first to test how the rendering would look on preview website. Who has the rights to do that?

Tim does, see my message above
.
(Unfortunately github doesn't group conversations into threads, when they are not associated to a changed line 😞)

vercel · 2025-01-21T11:24:06Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
docs-staging	✅ Ready (Inspect)	Visit Preview	Jan 21, 2025 11:24am

timothymcmackin · 2025-01-21T11:35:07Z

I've approved the vercel deployment and run it a few times. It throws an error I don't understand:

I've run the tests and build locally and it's fine so I suggest we merge. I deployed a preview version manually here; it will not update automatically:
https://timothymcmackin.github.io/previews/docs/ledger/tutorials/bake-with-ledger

ajinkyaraj-23 · 2025-01-21T11:49:40Z

I just ran the vercel preview and it works for me

…

On Tue, Jan 21, 2025, 11:35 AM Tim McMackin ***@***.***> wrote: I've approved the vercel deployment and run it a few times. It throws an error I don't understand: Screenshot.2025-01-21.at.6.29.47.AM.png (view on web) <https://github.com/user-attachments/assets/b1697e55-a5b4-46b5-b440-db8660ac0b02> I've run the tests and build locally and it's fine so I suggest we merge. I deployed a preview version manually here; it will not update automatically: https://timothymcmackin.github.io/previews/docs/ledger/tutorials/bake-with-ledger — Reply to this email directly, view it on GitHub <#506 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BCZ3ZOBCDW2HUFWGM576SYD2LYWIDAVCNFSM6AAAAABU6UFESOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMMBUGQ3TSMJWHA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

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

sidebars.js

… steps`

NicNomadic

LGTM

timothymcmackin · 2025-01-21T16:16:03Z

LGTM. Go ahead and merge or ask me to.

ajinkyaraj-23 · 2025-01-21T16:18:00Z

@timothymcmackin could you please merge it?

ajinkyaraj-23 reviewed Jan 13, 2025

View reviewed changes

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

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 force-pushed the palmer@functori@tuto-running-baker-with-ledger branch from c192bdd to 19ccfab Compare January 16, 2025 11:19

spalmer25 and others added 12 commits January 20, 2025 09:31

Add an intermediate tuto for baking using a Ledger device

6f8513e

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

1f27123

fixup! add record to install the baking app

885ee99

fixup! some wording

da6bc7d

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

fixup! include NicNomadic and Tim McMackin suggestions

4cb3ca4

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

fixup! mention Ledger Tezos apps in the introduction of Ledger

82814be

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

fixup! update tutorial prerequisites

b73dffd

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

fixup! inform readers that they must approve their ledger

b555a2f

fixup! add a conclusion to the HWM checks

7eaa3aa

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

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

02d4bbb

… steps

Add a section if you want to use a consensus key

1aa2620

Encourage readers to use a UPS

4279b22

as suggested by `https://opentezos.com/node-baking/baking/persistent-baker/#running-tezos-binaries-as-services`

spalmer25 force-pushed the palmer@functori@tuto-running-baker-with-ledger branch from b4bca39 to 4279b22 Compare January 20, 2025 08:32

spalmer25 requested a review from timothymcmackin January 20, 2025 08:39

timothymcmackin approved these changes Jan 20, 2025

View reviewed changes

spalmer25 requested review from ajinkyaraj-23 and NicNomadic January 21, 2025 07:55

vercel bot deployed to Preview January 21, 2025 11:24 View deployment

NicNomadic reviewed Jan 21, 2025

View reviewed changes

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

NicNomadic reviewed Jan 21, 2025

View reviewed changes

sidebars.js Show resolved Hide resolved

spalmer25 added 2 commits January 21, 2025 15:57

Precede this tutorial with the tutorial `Join the DAL as a baker in 5…

f73be0f

… steps`

fixup! the third step title

f5c0c7a

spalmer25 requested a review from NicNomadic January 21, 2025 15:01

NicNomadic approved these changes Jan 21, 2025

View reviewed changes

timothymcmackin merged commit c0150bb into trilitech:main Jan 21, 2025
1 of 3 checks passed


		:::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

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

spalmer25 commented Jan 16, 2025

NicNomadic commented Jan 16, 2025

timothymcmackin commented Jan 16, 2025

spalmer25 commented Jan 17, 2025

timothymcmackin left a comment

Choose a reason for hiding this comment

spalmer25 commented Jan 21, 2025

NicNomadic commented Jan 21, 2025

NicNomadic commented Jan 21, 2025

ajinkyaraj-23 commented Jan 21, 2025

ajinkyaraj-23 commented Jan 21, 2025

NicNomadic commented Jan 21, 2025

NicNomadic commented Jan 21, 2025

vercel bot commented Jan 21, 2025 • edited Loading

timothymcmackin commented Jan 21, 2025

ajinkyaraj-23 commented Jan 21, 2025 via email

NicNomadic left a comment

Choose a reason for hiding this comment

timothymcmackin commented Jan 21, 2025

ajinkyaraj-23 commented Jan 21, 2025

spalmer25 commented Jan 10, 2025 •

edited

Loading

vercel bot commented Jan 21, 2025 •

edited

Loading