Version 9.9.9

versioned_docs/version-9.9.9/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-9.9.9/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-9.9.9/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-9.9.9/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-9.9.9/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.

versioned_docs/version-9.9.9/concepts/slashing-protection.md

@@ -0,0 +1,93 @@
+---
+title: Slashing protection
+description: Learn about Teku's slashing protection.
+sidebar_position: 6
+---
+
+# Slashing protection
+
+Teku implements slashing protection to prevent validators from signing blocks or attestations based on what it has already signed.
+
+By default, Teku also locks keystore files listed in the [`--validator-keys`](../reference/cli/index.md#validator-keys) option to prevent other processes from using it. You can enable and disable this functionality using the [`--validators-keystore-locking-enabled`](../reference/cli/index.md#validators-keystore-locking-enabled) option.
+
+:::warning
+
+Teku's slashing protection does not provide protection if the same validator key is being used by multiple nodes.
+
+:::
+
+To protect validators from slashable offenses, Teku stores a record of the most recently signed blocks for each validator in the `<data-path>/validator/slashprotection/` directory. One [YAML file is stored per validator] in the format `<validator-pubkey>.yml` (with no `0x` prefix).
+
+:::note
+
+Set `<data-path>` using the [`--data-path`](../reference/cli/index.md#data-path) command line option.
+
+:::
+
+Teku provides command line options to [import] or [export] the slashing protection file.
+
+:::tip
+
+Teku also supports [doppelganger detection](../how-to/enable-doppelganger-detection.md) to help prevent slashing. This is an early access feature.
+
+:::
+
+## Validator slashing protection file
+
+The slashing protection file records multiple values that protects the validator from incorrectly signing blocks or attestations.
+
+```yaml title="Example"
+---
+genesisValidatorsRoot: "0x9436e8a630e3162b7ed4f449b12b8a5a368a4b95bc46b941ae65c11613bfa4c1"
+lastSignedBlockSlot: 71090
+lastSignedAttestationSourceEpoch: 2290
+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`.
+- `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
+
+You can obtain the `genesisValidatorsRoot` value by using the [`/eth/v1/beacon/genesis`](https://consensys.github.io/teku/#operation/getEthV1BeaconGenesis) API.
+
+:::
+
+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.
+
+### 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.
+
+### From a non-Teku node
+
+If moving a validator from a different client to Teku, you can either:
+
+- Manually [create a new slashing protection file] by setting the values based on the validator's last signing details.
+- [Import] the slashing protection file.
+
+To manually create the file, stop the other client to ensure it isn't signing, then set `lastSignedBlockSlot` to the current chain head slot + 1, `lastSignedAttestationSourceEpoch` to the current justified checkpoint, and set `lastSignedAttestationTargetEpoch` to the current epoch + 1.
+
+Start the Teku node with the validator key.
+
+<!-- links -->
+
+[YAML file is stored per validator]: #validator-slashing-protection-file
+[create a new slashing protection file]: #validator-slashing-protection-file
+[import]: ../how-to/prevent-slashing.md#import-a-slashing-protection-file
+[export]: ../how-to/prevent-slashing.md#export-a-slashing-protection-file

versioned_docs/version-9.9.9/concepts/weak-subjectivity.md

@@ -0,0 +1,36 @@
+---
+title: Weak subjectivity
+description: Learn about the weak subjectivity period.
+sidebar_position: 7
+---
+
+# Weak subjectivity
+
+The weak subjectivity period refers to how far behind the chain head a node can be before 1/3 of validators may have exited since the node was last in sync.
+
+For example, if 1/3 of validators withdraw their stake and continue signing blocks and attestations, they can form a chain which conflicts with the finalized state. If your node is far enough behind the chain head not to be aware that they've withdrawn their funds, these validators can act dishonestly and continue feeding you blocks to lead you down the wrong chain.
+
+:::note
+
+If a node is aware that a validator has withdrawn its funds, the node will reject the validator's attestations.
+
+:::
+
+## Safely sync your node
+
+Teku provides two methods to safely sync a node that is new to the network or has been offline for an extended period.
+
+1. Use [`--initial-state`](../reference/cli/index.md#initial-state) to supply an SSZ encoded state file from which to sync.
+2. Use [`--ws-checkpoint`](../reference/cli/index.md#ws-checkpoint) to supply a weak subjectivity checkpoint by which a node can securely validate its view of the current state.
+
+We recommend using `--initial-state`. It provides the same security benefits as `--ws-checkpoint`, but syncs faster. The only exception is when syncing an archive node, in which case, use `--ws-checkpoint`.
+
+:::tip
+
+Use the [`/eth/v2/debug/beacon/states/<state_id>`](https://consensys.github.io/teku/#operation/getEthV2DebugBeaconStatesWithState_id) API on an updated node to download a recent finalized state as an SSZ encoded state file.
+
+:::
+
+Another option is to [reconstruct historical states](../how-to/reconstruct-historical-states.md).
+This allows the creation of a full archive node, ensuring that once the node is
+up-to-date, the concerns associated with weak subjectivity are cleared.

versioned_docs/version-9.9.9/concepts/withdrawals.md

@@ -0,0 +1,97 @@
+---
+title: Withdrawals
+description: Learn about validator reward withdrawals.
+sidebar_position: 8
+---
+
+# Withdrawals
+
+Validators staking ether on Mainnet after [The Merge](merge.md), accrue two
+forms of rewards:
+
+- Execution layer rewards paid directly to a withdrawal address (Ethereum address).
+- Consensus layer rewards for performing actions each epoch.
+
+The
+[Capella network upgrade](https://notes.ethereum.org/@launchpad/withdrawals-faq#Q-What-is-ShanghaiCapella)
+implements an automated process that allows a validator's rewards to be
+transferred from the consensus layer to an Ethereum address on the execution layer.
+Before the Capella upgrade, consensus layer rewards were locked, and couldn't be
+transferred to an Ethereum address.
+
+:::caution
+
+When you create a validator, you can set its withdrawal address to a
+[BLS address](https://en.wikipedia.org/wiki/BLS_digital_signature), or an
+Ethereum address.
+Withdrawal keys configured as BLS keys can't have automated withdrawals executed
+for them.
+
+You can
+[update your BLS withdrawal address to an Ethereum address](../how-to/update-withdrawal-keys.md)
+after the Capella upgrade.
+
+:::
+
+You don't pay gas fees for receiving reward payments.
+
+## Types of withdrawals
+
+Two types of automated withdrawals occur once the withdrawal key is set up as an
+Ethereum address: [partial withdrawals](#partial-withdrawals) and
+[full withdrawals](#full-withdrawals).
+
+### Partial withdrawals
+
+Partial withdrawals are for active validators that have a balance exceeding 32 ETH.
+The network periodically makes transfers to the associated Ethereum address for
+validators with a balance exceeding 32 ETH.
+This means that a validator's balance periodically reduces to 32 ETH once
+Capella becomes the active fork on the network.
+
+### Full withdrawals
+
+Full withdrawals are for validators that have exited the network, and have
+waited the necessary time to withdraw their funds.
+For these validators, their entire balance is returned to the Ethereum address
+associated with the validator key.
+The balance can't be transferred until the validator key is associated with an
+Ethereum address.
+
+An exited validator can't become active on the network again, and currently (as
+of Capella), there's no mechanism for recycling the validator ID that has been exited.
+
+## How it works
+
+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.
+
+Block proposers select the withdrawals that go into the block.
+In each block, up to 16 changes to withdrawal credentials are also allowed,
+where an owner of a validator key can
+[update their withdrawal key's Ethereum address](../how-to/update-withdrawal-keys.md).
+This update is retrieved from a pool, and the order isn't guaranteed.
+
+## Withdrawal keys
+
+Withdrawal keys configured as
+[BLS keys](https://en.wikipedia.org/wiki/BLS_digital_signature) can't have
+automated withdrawals executed for them.
+Users must alter their credentials to specify an Ethereum address for their
+withdrawal key.
+
+BLS withdrawal keys are prefixed with `0x00`, whereas Ethereum withdrawal keys
+are prefixed with `0x01`.
+
+To determine the type of withdrawal key your validator uses, you can
+[query your validator configuration onchain](../how-to/update-withdrawal-keys.md#determine-the-withdrawal-address-type).
+
+:::caution
+
+Don't store your [validator keys](../how-to/use-external-signer/manage-keys.md) and
+withdrawal keys in the same location.
+
+:::

versioned_docs/version-9.9.9/get-started/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Get started",
+  "position": 1,
+  "link": {
+    "type": "generated-index"
+  }
+}