Teku Documentation

Teku is an open-source Ethereum consensus client written in Java. It provides a full implementation of both a beacon node and a validator client.

For operational guidance, refer to the Teku user documentation. For technical details on the underlying protocol, see the Ethereum Beacon Chain specification.

Teku is implementing Enshrined Proposer-Builder Separation (ePBS) as defined by EIP-7732 and the Gloas consensus-specs. As of the latest snapshot, the implementation is approximately 78-84% complete.

Key Implementation Details:

• Spec Tracking: Teku tracks the consensus-specs/specs/gloas/ specification. It is currently adapting to v1.7.0-alpha.7 of the consensus-specs.
• Fork Choice: The fork-choice implementation for Gloas is complete. It utilizes ForkChoiceModelGloas and PtcVoteTracker. The system uses ForkChoiceModelFactory.forSlot to route Gloas slots to the appropriate model.
• Builder Role: Note that Teku does not currently include an in-protocol builder client. On the proposer side, Teku interacts with MEV-Boost or external builders only. The 'honest builder' guide is considered a separate conceptual deliverable.

This document tracks the implementation status of the ePBS (Enshrined Proposer-Builder Separation) features in Teku, following EIP-7732 / Gloas. The implementation is being rolled out across several functional areas including Fork Choice, State Transition, Validator/VC, Networking, REST API, Engine API, Builder Client, Storage, and Testing.

Key areas of active development include:

• REST API: Implementation of GET execution_payload_envelopes and GET /eth/v4/validator/blocks/{slot}.
• Engine API: Support for the engine_getBlobs envelope variant.
• Validator/VC: Managing block proposer bid thresholds via BUILDER_PAYMENT_THRESHOLD_* and handling Proposer Tip Commitments (PTC).
• Networking: Integration of proposer-prefs and gossip protocols.

The Kurtosis test network comes with several monitoring and debugging tools enabled by default:

• Dora: For network observability.
• el_forkmon: For monitoring execution layer forks.
• Prometheus/Grafana: For metrics and visualization.
• rpc-snooper: For inspecting RPC calls.

Teku uses a tiered community model to manage contributions and project governance. Roles range from public access to project leadership:

The Slashing Protection Database Interchange is a standardized format designed to allow different Ethereum clients to export and import slashing protection data. This enables interoperability when moving or sharing data related to slashing protection between different client implementations.

Teku's support for this format is as follows:

• Exporting: Teku stores sufficient data to generate a minimal export according to the specification.
• Importing: Teku supports loading the complete specification for slashing protection data.

If you want to test a local build of Teku instead of the official image, follow these steps:

1. Build the local Docker image from the Teku root directory:

   ./gradlew distDocker

2. Update your network_params.yaml file to use the local image by setting the cl_image key to consensys/teku:develop.

JMH (Java Microbenchmark Harness) benchmarks in the eth-benchmark-tests module can be executed using Gradle.

To run the benchmarks from the command line, execute the following command from the root of the eth-benchmark-tests directory:

./gradlew jmh

Alternatively, if you are using IntelliJ IDEA, you can run these benchmarks directly within the IDE by installing the JMH plugin.

Teku uses Google's Java coding conventions. To automatically reformat the source code to comply with these conventions, run the spotlessApply target:

./gradlew spotlessApply

To perform a standard build of the project, clone the repository and run the Gradle wrapper:

git clone https://github.com/Consensys/teku.git
cd teku && ./gradlew

Upon a successful build, the distribution packages will be located in build/distributions.