Besu Ethereum Client
Download
Besu is an Apache 2.0 licensed, Mainnet compatible, Ethereum client written in Java.
Useful Links
Community and support
If you have a question, need help, or want to engage with the Besu community, the following resources are available.
Documentation
The Besu documentation answers many common questions. Some useful starting points:
Chat
- Join the Besu Discord:
#besu to interact with the dev team and get support, and #besu-contributors if you are interested in contributing to the client.
- Besu is an execution client and must be paired with a consensus client. If you are also running the Teku consensus client, the Teku Discord is useful too.
GitHub
The Besu GitHub repository tracks recent releases, patch notes, and known issues with up-to-date status on fixes and mitigations. If Discord can't resolve your problem, search the existing issues and, if needed, open a new issue with relevant logs and context.
Announcements
Version announcements are posted in the Discord announcements channel. Occasionally, the team also posts emergency alerts and support information on Discord and X.
Issues
Besu issues are tracked in the github issues tab.
See our contributing guidelines for more details on searching and creating issues.
If you have any questions, queries or comments, Besu channel on Discord is the place to find us.
Besu Users
To install the Besu binary, follow these instructions.
Besu Developers
Development
Instructions for how to get started with developing on the Besu codebase. Please also read the
contributing guidelines for more details on how to submit a pull request (PR).
Dependency Verification
This project uses Gradle dependency verification. Whenever you add or update a dependency or a Gradle plugin (including the apiBaselineVersion bump), regenerate gradle/verification-metadata.xml with:
./gradlew --write-verification-metadata sha256 --refresh-dependencies --rerun-tasks --no-parallel updateVerificationMetadata
and commit the updated file. The updateVerificationMetadata task resolves everything the build and the IDE need, so that their checksums get recorded:
- the binary and source JARs of every project's dependencies; the source JARs are required for IDE sync, since IntelliJ automatically downloads sources and fails the sync on missing checksums;
- the
.pom of every dependency, resolved via generateLicenseReport; normal resolution prefers Gradle Module Metadata (.module) over the .pom, so without the license report those POM checksums are never recorded and checkLicense fails verification on a fresh clone;
- the binary and source JARs of every project's Gradle plugins, including the ones declared in subproject
plugins {} blocks;
- the released Plugin API baseline and the tooling used by
:plugin-api:checkAPICompatibility.
All four flags are required, and the task fails fast if any of them is missing. --refresh-dependencies and --rerun-tasks make the regeneration behave like a clean checkout: without them, cached dependency metadata and cached task results can produce a silently incomplete file that passes locally but fails on a fresh clone. --no-parallel is required because generateLicenseReport resolves cross-project configurations under an exclusive lock that only serial execution provides.
To check that the metadata is complete without modifying it (this is what CI runs), use:
./gradlew verifySourceArtifacts
Profiling Besu
Besu supports performance profiling using Async Profiler, a low-overhead sampling profiler.
You can find setup and usage instructions in the Profiling Guide.
Profiling can help identify performance bottlenecks in block processing, transaction validation, and EVM execution.
Please ensure the profiler is run as the same user that started the Besu process.
Release Notes
Release Notes
Reference Tests and JSON Tracing
Besu includes support for running Ethereum reference tests and generating detailed EVM execution traces.
To learn how to run the tests and enable opcode-level JSON tracing for debugging and correctness verification, see the Reference Test Execution and Tracing Guide.
