hive runs the same integration suite against every Ethereum client, and finds real bugs

A shared integration suite, not a unit test framework

Hive is a system for running integration tests against Ethereum clients. That framing is the whole point, and it explains why the project exists separately from the test suites inside any single client.

An integration test here is not a unit test of an internal function. It is a scenario that spins up nodes, sends transactions, mines blocks, forks the chain and then asserts on the observable result through the client's public interfaces. The bug classes in the trophy list show what that catches: a data race between remote block import and local block mining in go-ethereum, a downloader that did not penalize incompatible forks harshly enough, a bug in the p2p bonding nodes algorithm in Nethermind, a Besu bug in estimating gas that treated a transaction as a FRONTIER transaction when no gas parameters were set and it should have been 1559, and a LogTopic case where an empty list was treated as a wildcard topic.

None of those are reachable by testing a function in isolation. They are protocol-level disagreements, and they only appear when two implementations of the same specification are driven through the same script and compared.

The list is also a reasonable proxy for who the tool is for. The entries name go-ethereum, Nethermind and Besu, and the project asks that client maintainers add their own finds to the list, on the reasoning that it could help prove that hive is a useful tool for validating Ethereum client implementations. So the audience is client implementers and protocol engineers, not application developers.

Two public instances keep clients honest about compatibility

The Ethereum Foundation maintains two public Hive instances, and their stated purpose is to check for consensus, p2p and blockchain compatibility.

The eth1 instance at hive.ethpandaops.io covers the eth1 consensus, the EngineAPI, RPC tests, graphql and p2p tests. Those categories are the compatibility surface between an execution client and the rest of the stack, and testing them in one place is what makes a fork transition tractable, because a client that passes the eth1 suite is at least speaking the same protocol as its peers.

The second instance is not named in the README, so what it covers is not stated there, but the existence of two instances alongside a separate eth2.go.work file in the tree suggests the second is oriented toward the eth2 side of the stack.

Running these publicly is a design decision with consequences. A client team gets continuous compatibility feedback without running the harness itself, which lowers the barrier to participation considerably. The cost is that a client that fails the public suite is publicly failing, and the trophy list means the failures get attributed by name and linked to a specific pull request.

For a protocol researcher, the instances also work as a comparison tool, since the same scenario run against several clients produces a table of where they disagree.

A Go core with a Rust simulator and a separate Lean simulator

The repository is a polyglot, and the structure says the simulation layer is being rewritten in more than one direction.

The main module is Go, github.com/ethereum/hive, requiring Go 1.24.0. The dependency list is instructive about what the harness does: the go-dockerclient library means every node runs in a container, gorilla/mux and golang.org/x/net carry the HTTP and websocket traffic, jwt/v4 is there for authenticated RPC calls, yaml.v3 for the test configuration files, esbuild for bundling the JavaScript sent to test nodes, uint256 for the large integer arithmetic the assertions need, and the pinned go-ethereum dependency is commented as a glamsterdam-devnet-8 build, which tells you the harness tracks a specific network fork.

Alongside the Go code there is a Rust component. The Cargo workspace has members hivesim-rs and simulators/lean, with simulators/lean as the default member, and the hiveproxy directory is a separate Go module pinned to a specific commit. The Makefile drives the Rust side with cargo fmt, cargo clippy with warnings denied, cargo check and cargo build across all targets.

The workspace also excludes simulators/portal, and the eth2.go.work file points at a second Go workspace. So the picture is a Go harness for eth1, a Rust rewrite of the simulation core, a Lean simulator, and a separate portal simulator that is deliberately kept out of the default build. That is a project in the middle of a migration, and it is the main structural risk for anyone adopting it.

Configuring a run is a Go workspace with a pinned fork build

The module declaration and the toolchain requirement are the entry point for anyone building Hive from source:

module github.com/ethereum/hive

go 1.24.0

The direct dependency set shows the shape of a run. The go-ethereum dependency is pinned to a pseudo-version with a trailing comment naming the fork build it tracks:

	github.com/ethereum/go-ethereum v1.17.6-0.20260813154252-aa1f2fcf5129 // glamsterdam-devnet-8
	github.com/ethereum/hive/hiveproxy v0.0.0-20240610172618-786a798a0cfe
	github.com/fsouza/go-dockerclient v1.12.2

Reading that pin correctly matters. Hive is not a neutral test runner; it is versioned against a particular network configuration, and the fork name in the comment is how you know which one. The hiveproxy module is a separate proxy the harness uses to sit between test nodes, which is the mechanism that lets a test observe and manipulate traffic that a real peer-to-peer network would not allow.

The Rust side is driven from the Makefile, with lint, fmt, check and build targets:

fmt:
	$(CARGO) fmt --all

lint-fix:
	$(CARGO) clippy $(RUST_WORKSPACE_FLAGS) $(CLIPPY_FIX_FLAGS) -- -D warnings

build:
	$(CARGO) build $(RUST_WORKSPACE_FLAGS)

The workspace flags default to --workspace --all-targets, and the clippy invocation turns warnings into errors, so a contribution that trips a lint will not pass. The README does not document a one-line install for the harness, and points to docs/overview.md for that material, so the tree-level build files are the concrete starting point.

The C4 contribution model optimistically merges patches that fix an issue

The contribution rules are unusual enough to be worth reading before you send a patch, and they are stated plainly rather than buried in a governance document.

The README says the project takes a different approach to code contributions than your usual FOSS project with well ingrained maintainers and relatively few external contributors, calls it an experiment, and says whether it will work out or not is for the future to decide. That is an unusually candid framing from a project inside the Ethereum Foundation.

The model is the Collective Code Construction Contract, C4, as expanded in The ZeroMQ Process. The core rule: any patch that successfully solves an issue, a bug or a feature, and does not break any existing code or contracts, must be optimistically merged by maintainers. Follow-up patches may be used for additional polish, and patches may even be outright reverted if they turn out to have a negative impact, but no change must be rejected based on personal values.

What this changes for a contributor is the review dynamic. You are not asking permission; you are proposing a patch that solves a stated issue and asking the maintainer to merge it unless it breaks something. The cost of that rule falls on the maintainers, who have to be willing to revert their own merges, and on reviewers, who have to do the checking that the merge gate no longer does.

For an engineer evaluating Hive as a dependency, the more relevant point is about maintenance. The GPL-3.0 licence and the C4 process both signal a project that optimises for throughput of fixes over gatekeeping, which for a compatibility harness is arguably the right trade, since the alternative is a client bug that ships.

Where Hive is the wrong tool

The first wrong-tool case is a project that wants ordinary unit testing. Hive orchestrates containers, networks and protocol interactions. It is the wrong tool for asserting that a function returns a value, and using it that way would be enormously slower than the alternative for no benefit.

The second case is a non-Ethereum client or a chain that Hive does not model. The fork pinning, the eth1 and eth2 split, the excluded portal simulator and the Lean simulator all exist because Ethereum's protocol surface is specific and versioned. A team building something adjacent to Ethereum but not on these networks would be adapting rather than adopting.

The third case is adoption during the ongoing migration. The Go harness, the Rust simulator rewrite, the Lean simulator in the Rust workspace and the separate eth2.go.work are not one settled system. A team that needs a stable, predictable test platform with a documented upgrade path is looking at something that is still moving, and the release history reinforces the point: the repository has no GitHub releases, so there is no tagged version series to pin against, and the last push was on 2026-10-20 with the go-ethereum dependency tracking a specific devnet build.

The alternative approach is not another harness but a different testing philosophy. Where Hive drives multiple real client implementations through a shared scenario and compares their observable behaviour, an in-house suite drives your own client only, over a network you control, with scenarios written by your team against the specification rather than a shared consensus. The difference in approach is the comparison axis: Hive's value comes precisely from the fact that several independent implementations are held to one script, so a private suite cannot tell you that your client disagrees with the others, only that it agrees with itself.

Editorial conclusion

Hive suits a client implementer who needs a shared, reproducible integration suite across geth, Nethermind, Besu and others, and a protocol researcher who wants to compare client behaviour on the same scenario. It does not suit a team looking for unit test tooling or a general CI harness, and the Rust simulator and Lean simulator pieces are separate efforts in different states. Before adopting, read docs/overview.md, run the public instance against your client on a scenario you already know the answer to, and confirm the GPL-3.0 licence is acceptable for your build infrastructure.

Frequently asked questions

Official sources

1. ethereum/hive on GitHub
2. Issues
3. License: GPL-3.0
4. README