From 38316867637fca3a62e7b5c253b0626965a8d3d1 Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Mon, 13 Jan 2025 13:11:34 -0500 Subject: [PATCH] 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 <148877430+NicNomadic@users.noreply.github.com> * typo * receive rights even if the baker daemon is not running Co-authored-by: NicNomadic <148877430+NicNomadic@users.noreply.github.com> * optional step Co-authored-by: NicNomadic <148877430+NicNomadic@users.noreply.github.com> * if you set one Co-authored-by: NicNomadic <148877430+NicNomadic@users.noreply.github.com> * 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 <148877430+NicNomadic@users.noreply.github.com> --- docs/tutorials/join-dal-baker.md | 2 +- .../join-dal-baker/prepare-account.md | 75 +++++++++++++------ docs/tutorials/join-dal-baker/run-baker.md | 42 +++++++---- docs/tutorials/join-dal-baker/run-dal-node.md | 8 +- docs/tutorials/join-dal-baker/run-node.md | 10 ++- .../tutorials/join-dal-baker/verify-rights.md | 40 ++++++++-- 6 files changed, 128 insertions(+), 49 deletions(-) diff --git a/docs/tutorials/join-dal-baker.md b/docs/tutorials/join-dal-baker.md index 1586f7c6a..1bc01bde3 100644 --- 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 index 93ace909b..869c50187 100644 --- a/docs/tutorials/join-dal-baker/prepare-account.md +++ b/docs/tutorials/join-dal-baker/prepare-account.md @@ -1,14 +1,34 @@ --- -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: @@ -16,50 +36,61 @@ This command creates an account and associates it with the `my_baker` alias: 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 index 2bc914393..c99f5bbe5 100644 --- a/docs/tutorials/join-dal-baker/run-baker.md +++ b/docs/tutorials/join-dal-baker/run-baker.md @@ -2,7 +2,7 @@ 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. @@ -10,10 +10,17 @@ If you already have a baking daemon, you can restart it to connect to the DAL no 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 index 1ad7fdd20..c46cfa319 100644 --- 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 index fb8a9ba08..451d9fa0d 100644 --- 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). diff --git a/docs/tutorials/join-dal-baker/verify-rights.md b/docs/tutorials/join-dal-baker/verify-rights.md index ec3134b51..2f0e7dc46 100644 --- a/docs/tutorials/join-dal-baker/verify-rights.md +++ b/docs/tutorials/join-dal-baker/verify-rights.md @@ -2,12 +2,12 @@ title: "Step 5: Verifications" authors: Tezos core developers, Tim McMackin last_update: - date: 2 December 2024 + date: 2 January 2025 --- After the delay that you calculated in [Step 4: Run an Octez baking daemon](/tutorials/join-dal-baker/run-baker), follow these instructions to verify the activity or diagnose and fix issues. -1. Record the address of your baker account in an environment variable so you can use it for commands that cannot get addresses by their Octez client aliases: +1. Record the address of your baker account (not the consensus account) in an environment variable so you can use it for commands that cannot get addresses by their Octez client aliases: ```bash MY_BAKER="$(octez-client show address my_baker | head -n 1 | cut -d ' ' -f 2)" @@ -50,7 +50,7 @@ After the delay that you calculated in [Step 4: Run an Octez baking daemon](/tut - Otherwise, make sure that your node and baker are running. - - Verify that the staked balance of your account is at least 6,000 tez by running the command `octez-client get staked balance for my_baker`. + - Verify that the staked balance of your baker account is at least 6,000 tez by running the command `octez-client get staked balance for my_baker`. If the response is less than 6,000 tez, you have not staked enough. Ensure that you are registered as a delegate and stake more tez, retaining a small amount for transaction fees. If necessary you can get more from the faucet. @@ -68,7 +68,7 @@ After the delay that you calculated in [Step 4: Run an Octez baking daemon](/tut 1. If the value for the `deactivated` field is `true`, re-register as a baker by running this command: ```bash - octez-client register key my_baker as delegate + octez-client register key my_baker as delegate with consensus key consensus_key ``` When the next cycle starts, Tezos calculates attestation rights for two cycles in the future and includes your baker. @@ -124,7 +124,9 @@ After the delay that you calculated in [Step 4: Run an Octez baking daemon](/tut l=; while true; echo $l; do octez-client rpc get "/chains/main/blocks/head/context/dal/shards?delegates=$MY_BAKER&level=$l"; l=$((l+1)); done ``` -1. Verify the baker's activity on the Explorus block explorer by going to the Consensus Ops page at https://explorus.io/consensus_ops, selecting Ghostnet, and searching for your address (only the first few characters). + If the DAL is active, you should see shards assigned for at least some levels but not necessarily every level. + +1. Verify the baker's activity on the Explorus block explorer by going to the Consensus Ops page at https://explorus.io/consensus_ops, selecting Ghostnet, and searching for your baker account address (only the first few characters). For example, this screenshot shows consensus operations that include DAL attestations, indicated by a number in the "DAL attestation bitset" column. @@ -140,6 +142,30 @@ If you don't see DAL attestation rights: - Verify that your DAL node is connected to the network by following the instructions in [Troubleshooting](https://tezos.gitlab.io/shell/dal_run.html#troubleshooting) in the Octez documentation. +## Optional: Changing the consensus key + +If you need to change the consensus key that the baker daemon uses, you can change it without changing the baker key. +The new key takes effect after the same attestation delay that you had to wait for your baker to receive attestation rights when you first set it up: + +``` +(consensus_rights_delay + 2) * blocks_per_cycle * minimal_block_delay +``` + +Follow these steps to change the consensus key: + +1. Generate a new consensus key with the `octez-client gen keys` command or import a private key into the instance of the Octez client on the same machine as the baking daemon. + +1. Use this new key as the consensus key for your baker account by running this command, with the address or alias of the new consensus key as the `` variable: + + ```bash + octez-client set consensus key for my_baker to + ``` + +1. Wait for the change to take effect. +During this time you can leave the baking daemon running with the old consensus key. + +1. When the new consensus key is active, stop the baking daemon and restart it with the new consensus key. + ## Optional: Unstaking your tez and receiving your baking rewards If you leave the baker running, you can see rewards accrue by running the command `octez-client get staked balance for my_baker`. @@ -152,7 +178,9 @@ For example, this command unstakes 6,000 tez: octez-client unstake 6000 for my_baker ``` -Then run this command to retrieve the tez: +You can substitute "everything" for the amount of tez to unstake everything. + +Then, after the same delay of `consensus_rights_delay + 2` cycles, run this command to retrieve the tez: ```bash octez-client finalize unstake for my_baker