hyperledger/besu

Besu Ethereum Client

Download

Besu is an Apache 2.0 licensed, Mainnet compatible, Ethereum client written in Java.

Useful Links

• Besu User Documentation
• Besu Issues
• Besu Wiki
• How to Contribute to Besu

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:

• System requirements
• Troubleshoot peering
• Troubleshoot performance
• Configure ports
• Understand metrics
• Configure the JVM

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

• Contributing Guidelines
• Coding Conventions
• Command Line Interface (CLI) Style Guide
• Besu User Documentation for running and using Besu

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

• Checking Out and Building
• Logging or the Documentation's Logging section

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.