Version 25.12.0

Author: lucassaldanha

versioned_docs/version-25.12.0/chatbot.mdx

@@ -0,0 +1,8 @@
+---
+title: Chatbot
+slug: chatbot
+---
+
+# Chatbot
+
+<iframe src="https://teku.ai.protocols.consensys.io/?embed=true" height="800" width="100%" />

versioned_docs/version-25.12.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-25.12.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](./node-types.md#consensus-clients) are responsible for proposing
+blocks containing an execution payload obtained from their local
+[execution clients](./node-types.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-25.12.0/concepts/node-types.md

@@ -0,0 +1,45 @@
+---
+title: Consensus and execution clients
+description: Learn about execution and consensus clients.
+sidebar_position: 5
+---
+
+An Ethereum node is an instance of an Ethereum client, which consists of:
+
+- A consensus client (for example, Teku)
+- An execution client (for example, Besu)
+
+:::info
+
+Before The Merge, execution clients were known as
+[Eth1 clients](https://blog.ethereum.org/2022/01/24/the-great-eth2-renaming/), and consensus clients
+were called [Eth2 clients](https://blog.ethereum.org/2022/01/24/the-great-eth2-renaming/).
+
+The Merge, completed on **September 15, 2022**, transitioned Ethereum from
+proof of work to [proof of stake consensus](proof-of-stake.md).
+
+:::
+
+Execution and consensus clients communicate with each other using the [Engine API](https://besu.hyperledger.org/public-networks/how-to/use-engine-api).
+
+![Ethereum 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/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.
+
+:::info
+
+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)).
+
+:::

versioned_docs/version-25.12.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: 6
+---
+
+# 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-25.12.0/concepts/peer-das.md

@@ -0,0 +1,64 @@
+---
+description: Learn about the PeerDAS upgrade and its implications for node operators.
+sidebar_position: 4
+---
+
+# PeerDAS
+
+Peer Data Availability Sampling (PeerDAS), specified by [EIP-7594](https://eips.ethereum.org/EIPS/eip-7594), is the main feature of the next Ethereum upgrade, Fusaka.
+
+PeerDAS introduces enhanced capacity extension over [proto-danksharding](proto-danksharding.md).
+The goal of this enhancement is to significantly increase the average number of blobs in every slot while keeping moderate network and storage requirements for most node operators.
+
+This is achieved using multiple techniques:
+
+- **1D blob extension** - PeerDAS applies one-dimensional erasure coding extension to each blob, so its size doubles.
+  The extended blob can be split into 128 parts such that you can reconstruct the original blob from any 64 parts.
+
+- **Column splitting** - In danksharding, the base data unit is the blob.
+  Each node is required to download all blobs referenced in the block to verify its availability.
+  In PeerDAS, extended blobs are rows which stack one below another and are split into columns, creating DataColumnSidecars.
+  This is the base data unit in PeerDAS and consists of 1/128th of each extended blob from the block, with additional data like proofs and block header.
+
+- **Data availability sampling** - The last major change is easing node operator requirements for data availability checks.
+  By splitting blobs data into columns, so that every single node operator is required to get pieces of each blob, it's impossible to lose any whole blob; either all blobs are available or none are.
+  Security research has proven that it's enough to download 1/8 of the data (1/16 of the extended data) to prove data availability or confirm its non-availability.
+
+Decreasing the size of required download, store, and share data by 8 for most nodes compared to danksharding
+makes it possible to schedule a target number of blobs increase of almost 5x compared to the danksharding launch,
+with potential room to increase it by another 4x in the future.
+This change significantly increases the blob capacity of the Ethereum network and TPS of Layer 2.
+Moreover, [EIP-7892: Blob Parameters Only Hardforks](https://eips.ethereum.org/EIPS/eip-7892) allows for changing maximum number of blobs and blob target without a hard fork,
+making future blob capacity changes easier.
+
+## Expected implications for node operators
+
+Proto-danksharding was launched with increased network requirements over the previous fork and additional storage required for the data layer of about 50 GB for 3 blobs,
+which was later increased to about 100 GB for 6 blobs in the Pectra fork.
+
+With PeerDAS, consensus layer clients will use network and storage space for sidecar data according to their roles:
+
+- **Full nodes** - These are nodes without any validators.
+  Their requirements are to store 4 data columns in custody (which is permanent storage for a moving window of about 18 recent days) and sample another 4.
+  This means the data is downloaded, data availability is checked, but nothing is stored.
+  4 columns with a scheduled 14-blob target (which could be increased in the future) will occupy about 16 GB of space, which means significantly less storage consumption by non-validator nodes.
+
+- **Validator nodes** - Requirements for validator nodes are to custody at least 8 columns, with the number calculated based on the effective balance of active validators,
+  adding a requirement of 1 extra column per every 32 ETH.
+  So, 1 validator requires 8 columns, 8 validators require 8 columns, 20 validators require 20 columns, with a maximum of 128 columns for 128 validators or 4096 ETH in consolidated validators.
+  For 1-8 validators and 14 blobs, a node will take 32 GB of space, which is still less than current requirements.
+  But nodes with a lot of validators will basically become supernodes.
+
+- **Supernodes** - These are either nodes running in altruistic mode or those operated by big validator operators with 4096 or more ETH staked.
+  This type of node stores and shares all columns data.
+  An operator can enable this mode using the [`--p2p-subscribe-all-custody-subnets-enabled`](../reference/cli/index.md#p2p-subscribe-all-custody-subnets-enabled) command line option;
+  big operators run in this mode as a protocol requirement.
+  Storage consumption is increased, taking about 500 GB with 14 blobs of data layer space compared to 100 GB in Pectra.
+
+  :::warning important
+  If a node operator needs complete blob data through the REST API, they must run in supernode mode.
+  Other types of nodes store only partial blob data.
+  :::
+
+All node space requirements are subject to change proportionally to the target number of blobs, which is currently scheduled to be 14 starting from January 7, 2026 (about 1 month after the Fusaka fork).
+Further target changes may be applied later and do not require a hard fork, but require node operators to upgrade their clients in a timely manner.

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

@@ -0,0 +1,39 @@
+---
+title: Proof of stake
+description: Learn about Ethereum proof of stake consensus.
+sidebar_position: 3
+---
+
+# Proof of stake
+
+In Ethereum's [proof of stake (PoS)](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/), you
+must run a [full node](node-types.md) 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](node-types.md#consensus-clients) processes the block
+and sends the execution payload to the [execution client](node-types.md#execution-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-25.12.0/concepts/proto-danksharding.md

@@ -0,0 +1,46 @@
+---
+description: Learn about the proto-danksharding upgrade and its implications for node operators.
+sidebar_position: 4
+---
+
+# Proto-danksharding
+
+Proto-danksharding, specified by [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844), is part of
+the next Ethereum upgrade, the Dencun upgrade.
+
+Proto-danksharding introduces a new "blob-carrying" transaction type, which allows data to be posted
+to Ethereum Mainnet more cheaply than currently possible, thus improving scalability while
+preserving decentralization.
+
+## What are blobs?
+
+Blobs are "sidecars" of data that ride alongside blocks, and are primarily used by the sequencers of
+Ethereum Layer 2 rollups to contain batched transactions executed on those rollups.
+
+Blobs are made up of 4096 32-byte field elements.
+Blobs are designed to remain available for exactly 4096 epochs, or roughly 18 days.
+After a blob expires, a majority of consensus layer clients can no longer retrieve the specific
+data within the blob, but evidence of the blob's prior existence remains on the network.
+
+The blobs' fee market structure is designed to target an average of three blobs attached to each
+beacon block, with a maximum of six blobs.
+Each blob holds 128 KB of temporary data.
+This means that proto-danksharding might increase the data associated with a block by 384 KB on
+average (128 KB per blob times three blobs) with a maximum of 768 KB (six blobs per block).
+
+## What changes in consensus layer clients?
+
+With proto-danksharding, consensus layer clients will:
+
+- Use more network bandwidth in the peer-to-peer layer to receive and distribute the blobs.
+
+- Require roughly 48 GiB more storage space for blobs, with a maximum of 96 GiB.
+  This estimate comes from the following calculation:
+
+  - 3 blobs per block x 128 KB each = 384 KB per block
+  - 32 blocks per epoch x 4096 epochs for blob expiry = 131,072 blocks with blobs
+  - 384KB x 131,072 blocks = 48 GiB increase in storage
+
+See this article,
+[Ethereum Evolved: Dencun Upgrade Part 5, EIP-4844](https://consensys.io/blog/ethereum-evolved-dencun-upgrade-part-5-eip-4844),
+for more information about Dencun and proto-danksharding.

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

@@ -0,0 +1,103 @@
+---
+title: Slashing protection
+description: Learn about Teku's slashing protection.
+sidebar_position: 7
+---
+
+# 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-base-path-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/prevent-slashing/detect-doppelgangers.md)
+and [validator slashing detection](../how-to/prevent-slashing/detect-slashing.md) to help
+prevent slashing.
+These are early access features.
+
+:::
+
+## 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 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
+
+You can obtain the `genesisValidatorsRoot` value by using the [`/eth/v1/beacon/genesis`](https://consensys.github.io/teku/#tag/Beacon/operation/getGenesis) 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:
+
+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
+
+If moving a validator from a different client to Teku, you can do either of the following:
+
+- 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 the following:
+
+- Set `lastSignedBlockSlot` to the current chain head slot + 1.
+- Set `lastSignedAttestationSourceEpoch` to the current justified checkpoint.
+- 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/use-a-slashing-protection-file.md#import-a-slashing-protection-file
+[export]: ../how-to/prevent-slashing/use-a-slashing-protection-file.md#export-a-slashing-protection-file