Update baker tutorial to use consensus keys (#498)

* Fix step numbering * Add messages for no attestation rights * Using a consensus key * Changing the consensus key * Not necessarily every level * typo * Unstake everything * Unstake delay * Typo * More about why you would or would not want to use a consensus key * DAL not required * sometimes called "manager" account Co-authored-by: NicNomadic <[email protected]> * typo * receive rights even if the baker daemon is not running Co-authored-by: NicNomadic <[email protected]> * optional step Co-authored-by: NicNomadic <[email protected]> * if you set one Co-authored-by: NicNomadic <[email protected]> * Handle error about empty data dir * Refactor setting up and funding accounts * Port accessible for layer 1 node * clean up the directory as the error message indicates. * Move installation for curl * This section is no longer helpful * COrrect default port --------- Co-authored-by: NicNomadic <[email protected]>
trilitech · Jan 13, 2025 · 3831686 · 3831686
1 parent 6aaab9a
commit 3831686
Show file tree

Hide file tree

Showing 6 changed files with 128 additions and 49 deletions.
diff --git a/docs/tutorials/join-dal-baker.md b/docs/tutorials/join-dal-baker.md
@@ -5,7 +5,7 @@ last_update:
   date: 18 December 2024
 ---
 
-As described in [Nodes](/architecutre/nodes), Tezos nodes are peer-to-peer programs that run the Tezos network.
+As described in [Nodes](/architecture/nodes), Tezos nodes are peer-to-peer programs that run the Tezos network.
 Anyone can run a node, and they might do so for many different reasons, including:
 
 - Running nodes makes the Tezos network resilient and secure

diff --git a/docs/tutorials/join-dal-baker/prepare-account.md b/docs/tutorials/join-dal-baker/prepare-account.md
@@ -1,65 +1,96 @@
 ---
-title: "Step 2: Set up a baker account"
+title: "Step 2: Set up baker accounts"
 authors: Tezos core developers, Tim McMackin
 last_update:
-  date: 19 August 2024
+  date: 9 January 2025
 ---
 
-The baker needs a user account that stakes tez.
-In this section, you use the Octez client to create an account, register it as a delegate, and stake tez with it.
+In this section you use the Octez client to set up two accounts for your baker:
 
-1. Create or import an account in the Octez client.
+- The baker key itself (also called the manager key) stakes tez and registers as a delegate
+- The consensus key is the key that the baker uses to sign attestations, which are generally referred to as _consensus operations_
+
+## Why set up a consensus key?
+
+Using a separate consensus key is not required but it is good security practice.
+Signing consensus operations incurs no fees, so you can set up a consensus key with no tez.
+You can generate and use this key on a remote machine that runs the baker and keep the baker key with your staked tez in a more secure location to reduce risk to your funds.
+This prevents you from having to move private keys between machines, which is inherently dangerous.
+
+If the consensus key is compromised or lost, you can create a new consensus key and switch the baker to it without changing how your tez is staked and delegated and without moving your delegators and stakers to a new account.
+In this way you can avoid transferring or backing up the consensus key or you can store it in a Key Management System (KMS) or Hardware Security Module (HSM) where no one has access to its private key.
+
+However, the consensus key can drain the liquid (unstaked) tez from the baker key, so you must keep the consensus key secure like all other keys.
+
+For more information about consensus keys, see [Consensus key](https://tezos.gitlab.io/user/key-management.html#consensus-key) in the Octez documentation.
+
+## Creating the accounts
+
+In this section, you use the Octez client to create these accounts and set them up for baking.
+
+1. Create or import an account in the Octez client to be the baker account (sometimes called the "manager" account).
 The simplest way to get an account is to use the Octez client to randomly generate an account.
 This command creates an account and associates it with the `my_baker` alias:
 
    ```bash
    octez-client gen keys my_baker
    ```
 
-   The address of the generated account can be obtained with the following command:
+   You can get the address of the generated account with this command:
 
    ```bash
    octez-client show address my_baker
    ```
 
-   At this point, the balance of the `my_baker` account is still zero, as you can see by running this command:
+   You can check the balance of the account with this command:
 
    ```bash
    octez-client get balance for my_baker
    ```
 
-1. Get at least 6,000 tez from the Ghostnet faucet.
+1. Stake at least 6,000 tez with the account, saving a small liquid amount for transaction fees.
+Staked tez is temporarily frozen and cannot be spent, so you need some unstaked tez to pay transaction fees.
 
-   The account must stake tez to get consensus and DAL rights.
-   To get tez, use the Ghostnet faucet linked from https://teztnets.com/ghostnet-about to send tez to the baker account.
+   You can check how much you have staked by running this command:
 
-   Running a baker requires staking at least 6,000 tez, but the more tez it stakes, the more rights it gets and the less time it has to wait to produce blocks and make attestations.
-   However, be aware that, for protecting abuses of the faucet, getting such amounts of tez from the faucet may take a long time (e.g. more than one hour). Consequently, some individual requests may occasionally time out or fail and need to be relaunched.
+   ```bash
+   octez-client get staked balance for my_baker
+   ```
 
-1. Verify that the faucet sent the tez to the account with the same `get balance` command:
+   If you need to stake more, pass the amount to the `stake` command, as in this example:
 
    ```bash
-   octez-client get balance for my_baker
+   octez-client stake 6000 for my_baker
    ```
 
-   If the balance still shows 0, the local node may not be ready yet.
-   In this case you can temporarily use the public RPC endpoint.
+   If you are using a testnet and need tez to stake, you can get tez from the testnet faucet.
+   For example, if you are using Ghostnet, use the Ghostnet faucet linked from https://teztnets.com/ghostnet-about to send tez to the baker account.
+
+   Running a baker requires staking at least 6,000 tez, but the more tez it stakes, the more rights it gets and the less time it has to wait to produce blocks and make attestations.
+   However, be aware that getting large amounts of tez from the faucet may take a long time (sometimes more than one hour) to prevent abuse of the faucet.
+   Consequently, some large requests may time out or fail and need to be resubmitted.
 
    When the account receives its tez, it owns enough stake to bake but has still no consensus or DAL rights because it has not declared its intention to become a baker.
 
-1. Register your account as a delegate by running the following command:
+1. (Optional) Set up a separate account to be the consensus key.
+This command creates an account and associates it with the `consensus_key` alias:
 
    ```bash
-   octez-client register key my_baker as delegate
+   octez-client gen keys consensus_key
    ```
 
-1. Stake at least 6,000 tez, saving a small amount for transaction fees, by running this command:
+   This account does not need any tez.
+
+1. Register the baker account as a delegate and set its consensus key (if you set one) by running the following command:
 
    ```bash
-   octez-client stake 6000 for my_baker
+   octez-client register key my_baker as delegate with consensus key consensus_key
    ```
 
-Now the account has staked enough tez to earn the right to make attestations, including attestations that data is available on the DAL.
-However, it does not receive these rights until the baking daemon is running and a certain amount of time has passed.
+   If you are not using a consensus key, omit the argument `with consensus key consensus_key`.
+
+Now the baker account has staked enough tez to earn the right to make attestations, including attestations that data is available on the DAL.
+If you set up a consensus key, that key is authorized to sign consensus operations on behalf of the baker account.
+However, the accounts do not receive these rights until a certain amount of time has passed.
 
 While you wait for attestation rights, continue to [Step 3: Run an Octez DAL node](/tutorials/join-dal-baker/run-dal-node).
diff --git a/docs/tutorials/join-dal-baker/run-baker.md b/docs/tutorials/join-dal-baker/run-baker.md
@@ -2,18 +2,25 @@
 title: "Step 4: Run an Octez baking daemon"
 authors: Tezos core developers, Tim McMackin
 last_update:
-  date: 19 December 2024
+  date: 31 December 2024
 ---
 
 Now that you have a layer 1 node and a DAL node, you can run a baking daemon that can create blocks and attests to DAL data.
 If you already have a baking daemon, you can restart it to connect to the DAL node.
 
 1. Optional: Set up a remote signer to secure the keys that the baker uses as described in [Signer](https://tezos.gitlab.io/user/key-management.html#signer) in the Octez documentation.
 
-1. To run a baking daemon that connects to the DAL, start it as usual and pass the URL to your DAL node to it with the `--dal-node` argument:
+1. Run a baking daemon with the following arguments:
+
+   - Use the consensus key, not the baker key, if you are using a consensus key
+   - Pass the URL to your DAL node with the `--dal-node` argument
+   - Pass the `--liquidity-baking-toggle-vote` argument; for more information, see [Liquidity baking](https://tezos.gitlab.io/active/liquidity_baking.html) in the Octez documentation
+   - Pass the `--adaptive-issuance-vote` argument; for more information, see [Adaptive Issuance and Staking](https://tezos.gitlab.io/active/adaptive_issuance.html) in the Octez documentation
+
+   For example:
 
    ```bash
-   octez-baker-PsParisC run with local node "$HOME/.tezos-node" my_baker --liquidity-baking-toggle-vote pass --adaptive-issuance-vote on --dal-node http://127.0.0.1:10732
+   octez-baker-PsParisC run with local node "$HOME/.tezos-node" consensus_key --liquidity-baking-toggle-vote pass --adaptive-issuance-vote on --dal-node http://127.0.0.1:10732
    ```
 
    Note that the command for the baker depends on the protocol version.
@@ -41,7 +48,7 @@ You can also refer to [Run a persistent baking node](https://opentezos.com/node-
    [Service]
    Type=simple
    User=tezos
-   ExecStart=octez-baker-PsParisC run with local node "$HOME/.tezos-node" my_baker --liquidity-baking-toggle-vote pass --adaptive-issuance-vote on --dal-node http://127.0.0.1:10732
+   ExecStart=octez-baker-PsParisC run with local node "$HOME/.tezos-node" consensus_key --liquidity-baking-toggle-vote pass --adaptive-issuance-vote on --dal-node http://127.0.0.1:10732
    WorkingDirectory=/opt/octez-baker
    Restart=on-failure
    RestartSec=5
@@ -56,8 +63,6 @@ You can also refer to [Run a persistent baking node](https://opentezos.com/node-
    curl http://localhost:10732/p2p/gossipsub/topics
    ```
 
-   You may need to install the `curl` program.
-
    DAL nodes share shards and information about them over a peer-to-peer pub/sub network built on the Gossipsub P2P protocol.
    As layer 1 assigns shards to the bakers, the Gossipsub network manages topics that DAL nodes can subscribe to.
    For example, if a user submits data to slot 1, the network has a list of topics: a topic to identify the slot 1 shards assigned to baker A, a topic to identify the slot 1 shards assigned to baker B, and so on for all the bakers that are assigned shards from slot 1.
@@ -116,20 +121,27 @@ For example, if the delay is 307,200 seconds, that time is about 3.5 days.
 
    The exact time depends on what time in the current cycle the account staked its tez.
 
-:::note
+   :::note
+
+   The amount of tez that the account stakes determines how often it is called on to make attestations, not how quickly it receives rights.
+   Therefore, staking more tez brings more rewards but does not reduce the attestation delay.
+
+   :::
+
+1. After the delay computed above has passed, **the baker log** (not the Octez node log, neither the DAL node log) should contain lines that look like this:
 
-The amount of tez that the account stakes determines how often it is called on to make attestations, not how quickly it receives rights.
-Therefore, staking more tez brings more rewards but does not reduce the attestation delay.
+   - Consensus pre-attestations: `injected preattestation ...`
+   - Consensus attestations: `injected attestation ...`
+   - Attach DAL attestations: `ready to attach DAL attestation ...`
 
-:::
+   These lines log the attestations that the baker makes.
 
-1. After the delay computed above has passed, **the baker log** (not the Octez node log, neither the DAL node log) should contain lines about:
+   If the baker does not have attestation rights, the log contains lines that start with `The following delegates have no attesting rights at level ...`.
 
-- Consensus pre-attestations: `injected preattestation ...`
-- Consensus attestations: `injected attestation ...`
-- Attach DAL attestations: `ready to attach DAL attestation ...`
+   Note that even though the baker daemon is using the consensus key, the attestations refer to the baker key.
+   The consensus key makes attestations on behalf of the baker key but the baking daemon does not need access to the baker key.
 
-Whether these messages appear or not after the attestation delay, proceed to [Step 5: Verifications](/tutorials/join-dal-baker/verify-rights).
+After the attestation delay, whether or not you have attestation rights, proceed to [Step 5: Verifications](/tutorials/join-dal-baker/verify-rights).
 
 ## Optional: Run an accuser
 

diff --git a/docs/tutorials/join-dal-baker/run-dal-node.md b/docs/tutorials/join-dal-baker/run-dal-node.md
@@ -2,13 +2,15 @@
 title: "Step 3: Run an Octez DAL node"
 authors: Tezos core developers, Tim McMackin
 last_update:
-  date: 19 December 2024
+  date: 9 January 2025
 ---
 
 The DAL node is responsible for temporarily storing data and providing it to bakers and Smart Rollups.
+As described in [Run a Tezos node in 5 steps](/tutorials/join-dal-baker), bakers are not currently required to run a DAL node but DAL nodes are important for the scalability and bandwidth of Tezos.
+
 Follow these steps to run the DAL node:
 
-1. Ensure that the port that the DAL node runs on (by default, 11732) is accessible from outside its system.
+1. Ensure that the port on which the DAL node listens for connections from peer nodes (by default, 11732) is accessible from outside its system.
 You may need to adapt your firewall rules or set up network address translation (NAT) to direct external traffic to the DAL node.
 For more information, see [Running a DAL attester node](https://tezos.gitlab.io/shell/dal_run.html) in the Octez documentation.
 
@@ -44,6 +46,8 @@ For example, this command initializes the DAL node with the address of a local `
    where `10732` is the default port on which the DAL node serves RPC calls.
    You can override it with the `--rpc-addr` argument.
 
+   You may need to install the `curl` program.
+
    The response lists the network connections that the DAL node has, as in this example:
 
    ```json

diff --git a/docs/tutorials/join-dal-baker/run-node.md b/docs/tutorials/join-dal-baker/run-node.md
@@ -2,7 +2,7 @@
 title: "Step 1: Run an Octez node"
 authors: Tezos core developers, Tim McMackin
 last_update:
-  date: 2 December 2024
+  date: 9 January 2025
 ---
 
 The first thing you need is a Tezos layer 1 node, which is an instance of the `octez-node` program and part of the Octez suite of programs.
@@ -36,6 +36,9 @@ If you build from source, you can use the `latest-release` branch to work with G
 
 ## Running the layer 1 node
 
+1. Ensure that the port on which the node listens for connections from peer nodes (by default, 9732) is accessible from outside its system.
+You may need to adapt your firewall rules or set up network address translation (NAT) to direct external traffic to the node.
+
 1. Initialize the Octez node for the network.
 For example, to initialize it for Ghostnet, run this command:
 
@@ -44,7 +47,6 @@ For example, to initialize it for Ghostnet, run this command:
    ```
 
    By default, the node stores its data in the folder `$HOME/.tezos-node`.
-   If this directory is not empty, you may have need to rename it (to keep its data) or remove it.
 
 1. Download a rolling snapshot of the network from https://snapshot.tzinit.org based on the instructions on that site.
 For example, the command to download a Ghostnet snapshot from the European servers might look like this:
@@ -53,6 +55,8 @@ For example, the command to download a Ghostnet snapshot from the European serve
    wget -O snapshot_file https://snapshots.eu.tzinit.org/ghostnet/rolling
    ```
 
+   If you get an error that says that the data directory is invalid, clean up the directory as the error message indicates.
+
 1. Load the snapshot in the node by running this command:
 
    ```bash
@@ -128,4 +132,4 @@ You can also refer to [Run a persistent baking node](https://opentezos.com/node-
 1. Optional: When the node has bootstrapped and caught up with the current head block, you can delete the snapshot file to save space.
 
 In the meantime, you can continue the baking infrastructure while the node is bootstrapping.
-Continue to [Step 2: Set up a baker account](/tutorials/join-dal-baker/prepare-account).
+Continue to [Step 2: Set up baker accounts](/tutorials/join-dal-baker/prepare-account).