Merge branch 'main' into 7707-vc-slashing

docs/concepts/merge.md

@@ -12,7 +12,7 @@ The Merge was executed on **September 15, 2022**.
 
 :::
 
-[The Merge](https://ethereum.org/en/upgrades/merge/) was an Ethereum upgrade that merged the [Beacon Chain](https://ethereum.org/en/upgrades/beacon-chain/) into Ethereum Mainnet, turning Mainnet into a combination of an [execution layer and consensus layer](#execution-and-consensus-clients). The Merge transitioned Mainnet from proof of work to [proof of stake consensus](proof-of-stake.md).
+[The Merge](https://ethereum.org/en/upgrades/merge/) was an Ethereum upgrade that merged the [Beacon Chain](https://ethereum.org/en/upgrades/beacon-chain/) into Ethereum Mainnet, turning Mainnet into a combination of an [execution layer and consensus layer](#execution-and-consensus-clients). The Merge transitioned Mainnet from proof of work to [proof-of-stake consensus](proof-of-stake.md).
 
 You can run Teku as a consensus client with:
 
@@ -41,7 +41,7 @@ Consensus clients, such as Teku, contain beacon node and validator client implem
 
 Before The Merge, the execution and consensus clients' configurations were updated to listen for a certain total terminal difficulty (TTD) to be reached.
 
-The consensus layer enabled the Merge configuration (Bellatrix) before reaching the TTD. Once the execution layer blocks reached the TTD, the Beacon Chain merged into Ethereum Mainnet, and Ethereum transitioned to a proof of stake network.
+The consensus layer enabled the Merge configuration (Bellatrix) before reaching the TTD. Once the execution layer blocks reached the TTD, the Beacon Chain merged into Ethereum Mainnet, and Ethereum transitioned to a proof-of-stake network.
 
 :::tip
 

docs/concepts/slashing-protection.md

@@ -46,8 +46,8 @@ lastSignedAttestationTargetEpoch: 3247
 
 The following rules apply to the file:
 
-- A validator will not sign a block unless the slot is greater than `lastSignedBlockSlot`.
-- A validator will not sign an attestation unless the attestation source is greater than or equal to `lastSignedAttestationSourceEpoch`, and the attestation target epoch is greater than `lastSignedAttestationTargetEpoch`.
+- A validator signs a block only if the slot number is greater than `lastSignedBlockSlot`.
+- A validator signs an attestation when the source epoch of the attestation is equal to or exceeds `lastSignedAttestationSourceEpoch`, and the target epoch of the attestation is greater than `lastSignedAttestationTargetEpoch`.
 - `genesisValidatorsRoot` is a hash of the validators active at genesis, and is used to differentiate between different chains. Teku does not require this field to be present, but if it is present and differs from the required value, then Teku returns an error.
 
 :::info
@@ -60,19 +60,19 @@ These rules guarantee the validator does not sign anything that is slashable.
 
 ## Migrate the slashing protection file
 
-Use the Teku command line options to [import] or [export] the slashing protection file. Alternatively you can manually migrate or create the database.
+Use the Teku command line options to [import] or [export] the slashing protection file. Alternatively, you can manually migrate or create the database.
 
 ### Between Teku nodes
 
 If moving a validator from one Teku node to another, you can manually migrate the slashing protection file.
 
 For example, to manually move the file from node A to node B:
 
-- Stop Teku node A and confirm the process has fully exited and won't be restarted.
-- Remove the validator key from node A, for example from the [`--validator-keys`](../reference/cli/index.md#validator-keys) option.
-- Copy the file from `<nodeA-data-path>/validators/slashprotection/` to `<nodeB-data-path>/validators/slashprotection/`.
-- Start node B with the migrated validator key.
-- Restart node A if required.
+1. Stop Teku node A and confirm the process has fully exited and won't be restarted.
+1. Remove the validator key from node A, for example from the [`--validator-keys`](../reference/cli/index.md#validator-keys) option.
+1. Copy the file from `<nodeA-data-path>/validators/slashprotection/` to `<nodeB-data-path>/validators/slashprotection/`.
+1. Start node B with the migrated validator key.
+1. Restart node A if required.
 
 ### From a non-Teku node
 

docs/concepts/withdrawals.md

@@ -66,8 +66,10 @@ of Capella), there's no mechanism for recycling the validator ID that has been e
 From the first Capella slot, block proposers provide up to 16 withdrawals per
 proposed block.
 
-Proposers start from validator 1, and find validators that qualify: must have an
-Ethereum address as a withdrawal address, must have an excess balance, or have exited.
+Proposers start with validator 1, and find validators that have an Ethereum address as a withdrawal address, and meet one of these criteria:
+
+- They have an excess balance.
+- They have exited.
 
 Block proposers select the withdrawals that go into the block.
 In each block, up to 16 changes to withdrawal credentials are also allowed,

docs/get-started/start-teku.md

@@ -125,6 +125,36 @@ Content-Length: 0
  </TabItem>
 </Tabs>
 
+## Exit Codes
+
+**Exit Code 1**
+
+This code indicates a scenario where Teku has exited with a fatal error; however, restarting Teku without changes is a logical step in correcting it. This code represents the error is related to something external to Teku.
+
+Example: If the beacon chain controller has issues starting P2P services on a particular port, the system will exit with a fatal error code of 1. This could correct itself with a restart.
+
+Example 2: If the migrate database command does not successfully migrate the database, Teku will exit with a code 1 fatal error. Restarting the system could correct this.
+
+**Exit Code 2**
+
+This code indicates a scenario where Teku has exited with a fatal error. Restarting Teku will not correct this.
+
+Note that most user configuration errors fall into this category.
+
+Example: If you specify an invalid database version in the migrate database command, Teku will exit with a code 2 fatal error. To correct this, make the appropriate changes to the setup and then restart Teku.
+
+**Usages**
+
+The exit codes for Teku are important to understand so that you know how to approach a restart and mitigate the issue.
+
+The **service unit configuration** file is an example of how status codes can be used. `RestartPreventExitStatus=` and `RestartForceExitStatus=` can be used to automatically restart Teku or stop it in case of failure.
+
+[systemd.service](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html) File Example
+```
+RestartForceExitStatus=1
+RestartPreventExitStatus=2
+```
+
 <!-- links -->
 
 [validator clients]: #start-the-validator

docs/how-to/troubleshoot/network.md

@@ -16,10 +16,9 @@ finalized `BeaconState`. Any synchronized beacon node can provide this from the
 The [`--initial-state`](../../reference/cli/index.md#initial-state) option is only used when you first create a database. To
 restart an existing sync process with checkpoint sync, do the following:
 
-- Stop the current Teku sync process
-- Delete the `beacon` directory under your [data path](../../reference/cli/index.md#data-base-path-data-path)
-- Start teku with the [`--initial-state`](../../reference/cli/index.md#initial-state) option 
-
+1. Stop the current Teku sync process.
+1. Delete the `beacon` directory under your [data path](../../reference/cli/index.md#data-base-path-data-path).
+1. Start teku with the [`--initial-state`](../../reference/cli/index.md#initial-state) option .
 
 Teku will sync within a few minutes, and downloads historic blocks in the background, so it can
 help any peers that are syncing from genesis. Teku can run validators and attest while while historic blocks are being downloaded.
@@ -89,7 +88,7 @@ update the advertised port using the [`--p2p-advertised-port`](../../reference/c
 
 Troubleshooting poor attestation performance is complicated, and the solution requires you to identify the root cause.
 
-[This video](https://www.symphonious.net/2020/09/08/exploring-eth2-attestation-inclusion/) is a little old, but the general picture is still relevant.
+[This video](https://www.symphonious.net/2020/09/08/exploring-eth2-attestation-inclusion/), while slightly dated, still provides valuable and applicable insights.
 
 Common issues include:
 

docs/how-to/use-external-signer/use-web3signer.md

@@ -10,8 +10,8 @@ Teku supports the [Web3Signer] external signing client.
 
 **Prerequisites**:
 
-- Web3Signer installed and running.
-- [Signing key configuration files].
+- Web3Signer installed and running
+- [Signing key configuration files]
 
 ## Start Teku
 
@@ -24,10 +24,10 @@ teku --network=goerli \
 --validators-external-signer-url=http://localhost:9000
 ```
 
-The command line:
+The command line specifies the following:
 
-- Specifies the validator public keys for which Web3Signer signs attestations and blocks using [`--validators-external-signer-public-keys`](../../reference/cli/index.md#validators-external-signer-public-keys).
-- Specifies the URL of the Web3Signer client using [`--validators-external-signer-url`](../../reference/cli/index.md#validators-external-signer-url).
+- The validator public keys for which Web3Signer signs attestations and blocks using [`--validators-external-signer-public-keys`](../../reference/cli/index.md#validators-external-signer-public-keys).
+- The URL of the Web3Signer client using [`--validators-external-signer-url`](../../reference/cli/index.md#validators-external-signer-url).
 
 :::note
 
@@ -39,4 +39,4 @@ You need a [signing key configuration file] for each public key specified using
 
 [Web3Signer]: https://docs.web3signer.consensys.net/
 [Signing key configuration files]: https://docs.web3signer.consensys.net/HowTo/Use-Signing-Keys/
-[signing key configuration file]: https://docs.web3signer.consensys.net/en/latest/HowTo/Use-Signing-Keys/
+[signing key configuration file]: https://docs.web3signer.consensys.net/en/latest/HowTo/Use-Signing-Keys/

versioned_docs/version-24.1.0/concepts/architecture.md

@@ -0,0 +1,19 @@
+---
+title: Architecture
+description: Learn about the Teku high-level architecture.
+sidebar_position: 1
+---
+
+# Teku architecture
+
+The following diagram outlines the Teku high-level architecture.
+
+![Architecture](../images/architecture.png)
+
+Teku contains both a beacon node and validator client implementation.
+The beacon node is the primary link to the Beacon Chain.
+The validator client performs [validator duties](proof-of-stake.md).
+
+You can [run the beacon node only](../get-started/start-teku.md#start-the-beacon-node), or [run the beacon node and validator client](../get-started/start-teku.md#start-the-clients-in-a-single-process).
+
+Read more about the [Ethereum consensus client architecture](https://ethereum.org/en/developers/docs/nodes-and-clients/). For more information about the Teku architecture, contact us on [Teku Discord channel](https://discord.com/invite/consensys).

versioned_docs/version-24.1.0/concepts/builder-network.md

@@ -0,0 +1,29 @@
+---
+title: Builder network and MEV-Boost
+description: Learn about external builders and MEV-Boost.
+sidebar_position: 2
+---
+
+# Builder network and MEV-Boost
+
+[Consensus clients](merge.md#consensus-clients) are responsible for proposing
+blocks containing an execution payload obtained from their local
+[execution clients](merge.md#execution-clients) via the Engine API.
+
+A consensus client can optionally configure an external builder and delegate the
+execution payload construction to it, instead of using the execution client.
+
+## MEV-Boost
+
+The most common builder deployment is to run a specialized external software
+such as [MEV-Boost](https://github.com/flashbots/mev-boost).
+MEV-Boost works by requesting a payload proposal from several entities (called 
+relays), and selecting the best bid in order to improve validator rewards and
+increase the maximal extractable value (MEV).
+
+Teku allows you to
+[configure the beacon node to use a builder network](../how-to/configure/builder-network.md)
+to generate execution payloads.
+In case of failures or non-timely responses, Teku falls back to the payload
+produced by the local execution client specified using
+[`--ee-endpoint`](../reference/cli/index.md#ee-endpoint).

versioned_docs/version-24.1.0/concepts/merge.md

@@ -0,0 +1,52 @@
+---
+title: The Merge
+description: Learn about The Merge, and execution and consensus clients.
+sidebar_position: 4
+---
+
+# The Merge
+
+:::info
+
+The Merge was executed on **September 15, 2022**.
+
+:::
+
+[The Merge](https://ethereum.org/en/upgrades/merge/) was an Ethereum upgrade that merged the [Beacon Chain](https://ethereum.org/en/upgrades/beacon-chain/) into Ethereum Mainnet, turning Mainnet into a combination of an [execution layer and consensus layer](#execution-and-consensus-clients). The Merge transitioned Mainnet from proof of work to [proof of stake consensus](proof-of-stake.md).
+
+You can run Teku as a consensus client with:
+
+- Any execution client on Mainnet.
+- Any execution client on a testnet.
+- Besu on Mainnet.
+- Besu on a testnet.
+
+## Execution and consensus clients
+
+After The Merge, a full Ethereum Mainnet node is a combination of an execution client (previously called an [Ethereum 1.0](https://blog.ethereum.org/2022/01/24/the-great-eth2-renaming/) client) and a consensus client (previously called an [Ethereum 2.0](https://blog.ethereum.org/2022/01/24/the-great-eth2-renaming/) client).
+
+Execution and consensus clients communicate with each other using the [Engine API](https://besu.hyperledger.org/development/public-networks/how-to/use-engine-api).
+
+![Ethereum Merge node](../images/execution-consensus-clients.png)
+
+### Execution clients
+
+Execution clients, such as [Besu](https://besu.hyperledger.org/), manage the execution layer, including executing transactions and updating the world state. Execution clients serve [JSON-RPC API](https://besu.hyperledger.org/development/public-networks/reference/api) requests and communicate with each other in a peer-to-peer network.
+
+### Consensus clients
+
+Consensus clients, such as Teku, contain beacon node and validator client implementations. The beacon node is the primary link to the [Beacon Chain](https://ethereum.org/en/upgrades/beacon-chain/) (consensus layer). The validator client performs [validator duties](proof-of-stake.md) on the consensus layer. Consensus clients serve [REST API](../reference/rest.md) requests and communicate with each other in a peer-to-peer network.
+
+## What happened during The Merge
+
+Before The Merge, the execution and consensus clients' configurations were updated to listen for a certain total terminal difficulty (TTD) to be reached.
+
+The consensus layer enabled the Merge configuration (Bellatrix) before reaching the TTD. Once the execution layer blocks reached the TTD, the Beacon Chain merged into Ethereum Mainnet, and Ethereum transitioned to a proof of stake network.
+
+:::tip
+
+After The Merge, a Mainnet node operator must run both an execution client and a beacon node at the same time. To become a validator, you must also run a validator client (either [in the same process as the beacon node](../get-started/start-teku.md#start-the-clients-in-a-single-process) or [separately](../get-started/start-teku.md#run-the-clients-separately)).
+
+:::
+
+After The Merge, validators earn rewards for performing [validator duties](proof-of-stake.md), and fee recipients earn rewards for the inclusion of execution layer transactions.

versioned_docs/version-24.1.0/concepts/p2p-private-key.md

@@ -0,0 +1,19 @@
+---
+title: Peer-to-peer private key
+description: Learn about the peer-to-peer private key.
+sidebar_position: 5
+---
+
+# Peer-to-peer private key
+
+The peer-to-peer (P2P) private key is used to identify the beacon node on the network and secures the information channel between nodes.
+
+When starting Teku, if the [`--p2p-private-key-file`](../reference/cli/index.md#p2p-private-key-file) option is not specified, and the `generated-node-key.dat` file does not exist in the node's data directory, Teku generates a P2P private key and writes it to the `generated-node-key.dat` file.
+
+If the `generated-node-key.dat` file exists in the data directory when starting Teku, the node starts using the private stored in the file.
+
+:::info
+
+The `generated-node-key.dat` file is stored by default in the `<data-beacon-path>/kvstore` directory, where `<data-beacon-path>` is specified using the [`--data-beacon-path`](../reference/cli/index.md#data-beacon-path) option.
+
+:::

versioned_docs/version-24.1.0/concepts/proof-of-stake.md

@@ -0,0 +1,35 @@
+---
+title: Proof of stake
+description: Learn about Ethereum proof of stake consensus.
+sidebar_position: 3
+---
+
+# Proof of stake
+
+[The Merge](merge.md) transitioned Ethereum Mainnet to [proof of stake (PoS)](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/) consensus.
+
+In Ethereum's PoS, you must run a [full node](merge.md#execution-and-consensus-clients) and [stake 32 ETH](https://ethereum.org/en/staking/) to become a validator.
+
+:::note
+
+You must run a beacon node and an execution client to operate a node on Mainnet. To become a validator, you must also run a validator client (either [in the same process as the beacon node](../get-started/start-teku.md#start-the-clients-in-a-single-process) or [separately](../get-started/start-teku.md#run-the-clients-separately).
+
+:::
+
+The PoS mechanism randomly chooses validators to propose or validate blocks on the [Beacon Chain](https://ethereum.org/en/upgrades/beacon-chain/) in defined time frames.
+
+Proposers are responsible for proposing new consensus blocks, and non-proposing validators are responsible for validating (attesting to) proposed blocks. Validators are rewarded for proposing and attesting to consensus blocks eventually included in the Beacon Chain, and penalized for malicious behavior. Validators also receive transaction fees for included blocks.
+
+Each consensus block contains an execution payload, which contains a list of transactions and other data required to execute and validate the payload.
+
+When a node validates a consensus block, its [consensus client](merge.md#execution-and-consensus-clients) processes the block and sends the execution payload to the [execution client](merge.md#execution-and-consensus-clients), which:
+
+1. Assembles a block on the execution layer.
+1. Verifies pre-conditions.
+1. Executes transactions.
+1. Verifies post-conditions.
+1. Sends the validity result back to the consensus client.
+
+If the block is valid, the execution client includes it in the execution chain and stores the new state in execution state storage.
+
+If a consensus block receives attestations backed by enough staked ETH, the block is included in the Beacon Chain.