Skip to content

Commit

Permalink
Version 24.12.1
Browse files Browse the repository at this point in the history
  • Loading branch information
lucassaldanha committed Dec 18, 2024
1 parent 3c4d47b commit c181ce4
Show file tree
Hide file tree
Showing 72 changed files with 11,833 additions and 1 deletion.
8 changes: 8 additions & 0 deletions versioned_docs/version-24.12.1/chatbot.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
title: Chatbot
slug: chatbot
---

# Chatbot

<iframe src="https://docsbot-teku.prd.ai.consensys.io/?embed=true" height="800" width="100%" />
19 changes: 19 additions & 0 deletions versioned_docs/version-24.12.1/concepts/architecture.md
Original file line number Diff line number Diff line change
@@ -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).
29 changes: 29 additions & 0 deletions versioned_docs/version-24.12.1/concepts/builder-network.md
Original file line number Diff line number Diff line change
@@ -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).
45 changes: 45 additions & 0 deletions versioned_docs/version-24.12.1/concepts/node-types.md
Original file line number Diff line number Diff line change
@@ -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/development/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/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.

:::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)).

:::
19 changes: 19 additions & 0 deletions versioned_docs/version-24.12.1/concepts/p2p-private-key.md
Original file line number Diff line number Diff line change
@@ -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.

:::
36 changes: 36 additions & 0 deletions versioned_docs/version-24.12.1/concepts/proof-of-stake.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
---
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#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](node-types.md#execution-and-consensus-clients) processes the block and sends the execution payload to the [execution client](node-types.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.
46 changes: 46 additions & 0 deletions versioned_docs/version-24.12.1/concepts/proto-danksharding.md
Original file line number Diff line number Diff line change
@@ -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.
96 changes: 96 additions & 0 deletions versioned_docs/version-24.12.1/concepts/slashing-protection.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
---
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-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/#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:

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 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/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
63 changes: 63 additions & 0 deletions versioned_docs/version-24.12.1/concepts/weak-subjectivity.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
---
title: Weak subjectivity
description: Learn about the weak subjectivity period.
sidebar_position: 8
---

# 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.
:::

At a high-level, the weak subjectivity period is the period of time that a node can be behind the
chain and trust that it is following the correct chain.
In practice, the weak subjectivity mechanism tells Teku if the latest checkpoint is too old to
continue syncing from it (either when starting a new node or after your node has been offline for a while).


## Safely sync your node

Teku provides three methods to safely sync a node that is new to the network or has been offline for an extended period.

1. Use [`--checkpoint-sync-url`](../reference/cli/index.md#checkpoint-sync-url) to supply a URL of a
checkpoint state endpoint from which to sync.
2. Use [`--initial-state`](../reference/cli/index.md#initial-state) to supply an SSZ encoded state
file from which to sync.

We recommend using `--checkpoint-sync-url` on Mainnet.

:::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.

## Sync outside the weak subjectivity period

Originally, Teku's default behavior was to sync from any point in the chain without the weak
subjectivity check, including syncing all the way from the genesis of the chain.
However, this is considered unsafe.

If you want to allow Teku to sync outside the weak subjectivity period, you can use the
[`--ignore-weak-subjectivity-period-enabled`](../reference/cli/index.md#ignore-weak-subjectivity-period-enabled)
CLI option.

## Learn more

See the following resources to learn more about weak subjectivity:

- [Ethereum weak subjectivity documentation](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/weak-subjectivity/)
- [Proof of Stake: How I Learned to Love Weak Subjectivity](https://blog.ethereum.org/2014/11/25/proof-stake-learned-love-weak-subjectivity)
- [Exploring Ethereum 2: Weak Subjectivity Period](https://www.symphonious.net/2019/11/27/exploring-ethereum-2-weak-subjectivity-period/)
Loading

0 comments on commit c181ce4

Please sign in to comment.