ethereum-hive

Ethereum Hive Simulators Python Library

Write ethereum/hive simulators using Python.

This library provides a Python API for creating and running Ethereum Hive simulation tests, allowing you to test Ethereum clients against various scenarios and network conditions.

Installation

pip install ethereum-hive

Features

• Client Management: Start, stop, and manage Ethereum clients.
• Network Configuration: Configure custom networks and genesis configuration.
• Test Simulation: Run comprehensive test suites against Ethereum clients.

Quick Start

Start a Hive Development Server

./hive --dev --client go-ethereum

Basic Example

Here's a basic example of how to use the Hive Python API with Hive running in developer mode. It requires a genesis file; please modify the path as required.

from pathlib import Path

from hive.simulation import Simulation
from hive.testing import HiveTestResult

# Create a simulation on a development hive server
simulator = Simulation(url="http://127.0.0.1:3000")

# Get information about the hive instance cli args and clients
hive_info = simulator.hive_instance()

# Start a test suite
suite = simulator.start_suite("my_test_suite", "my test suite description")

# Start a test
test = suite.start_test("my_test", "my test description")

# Start a client for the test
all_clients = simulator.client_types()
print(all_clients[0].version)

# Specify the genesis file; here we use the genesis from the unit test
files = {"genesis.json": Path("src/hive/tests/genesis.json").as_posix()}
env = {"HIVE_CHAIN_ID": "1"}
client = test.start_client(client_type=all_clients[0], environment=env, files=files)

# Run your test logic
# ...

# Stop the test and the suite (will clean-up clients)
test.end(result=HiveTestResult(test_pass=True, details="test details"))
suite.end()

For more detailed examples, check out the unit tests or explore the simulators in the execution-spec-tests repository.

Development

Setup

• Install uv:

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

• Clone and setup the project:

  git clone https://github.com/marioevz/hive.py.git
  cd hive.py
  uv sync --all-extras
  

Running Tests

Prerequisites

• Fetch and build hive:

  git clone https://github.com/ethereum/hive.git
  cd hive
  go build -v .
  

• Run hive in dev mode:

  ./hive --dev --client go-ethereum,lighthouse-bn,lighthouse-vc
  

• Run the test suite:

  uv run pytest
  

Code Quality

• Linting: uv run black src/
• Type checking: uv run mypy src/
• Import sorting: uv run isort src/

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Related Projects

• ethereum/hive - The main Hive testing framework.
• ethereum/execution-spec-tests - Contains implementations of several Hive simulators.