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. When adding or updating dependencies, regenerate gradle/verification-metadata.xml with:

./gradlew --write-verification-metadata sha256 --refresh-dependencies resolveSourceArtifacts :plugin-api:checkAPICompatibility --rerun-tasks

The resolveSourceArtifacts task ensures source JARs are included in the metadata, which is required for IDE sync (e.g. IntelliJ automatically downloads sources). The :plugin-api:checkAPICompatibility task resolves the released Plugin API baseline so its artifacts are recorded as well. The --rerun-tasks and --refresh-dependencies flags make the regeneration behave like a clean checkout: without them, cached task results and cached dependency metadata can produce a silently incomplete file that passes locally but fails on a fresh clone.

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.