Skip to content

Contributing to Reth

Reth has docs specifically geared for developers and contributors, including documentation on the structure and architecture of reth, the general workflow we employ, and other useful tips.

Getting Help

Need support or have questions? Open a github issue and/or join the TG chat:

Repository and Project Structure

Reth is organized as a modular codebase with clear separation and a contributor friendly architecture, you can read about it in detail here. Here's the TL;DR:

Design

Reth follows a modular architecture where each component can be used independently:

  • Consensus: Block validation and consensus rules
  • Storage: Hybrid database with MDBX + static files
  • Networking: P2P networking stack
  • RPC: JSON-RPC server implementation
  • Engine: Consensus layer integration
  • EVM: Transaction execution
  • Node Builder: High-level orchestration

Crates

The repository is organized into focused crates under /crates/:

crates/
├── consensus/          # Consensus and validation logic
├── storage/           # Database and storage implementations
├── net/               # Networking components
├── rpc/               # JSON-RPC server and APIs
├── engine/            # Engine API and consensus integration
├── evm/               # EVM execution
├── node/              # Node building and orchestration
├── ethereum/          # Ethereum-specific implementations
├── optimism/          # Optimism L2 support
└── ...

Workflow: The Lifecycle of PRs

1. Before You Start

  • Check existing issues to avoid duplicate work
  • For large features, open an issue first to discuss the approach
  • Fork the repository and create a feature branch

2. Development Process

Setting Up Your Environment

# Clone your fork
git clone https://github.com/YOUR_USERNAME/reth.git
cd reth
 
# Install dependencies and tools
# Use nightly Rust for formatting
rustup install nightly
rustup component add rustfmt --toolchain nightly
 
# Run the validation suite
make pr

Code Style and Standards

  • Formatting: Use nightly rustfmt (cargo +nightly fmt)
  • Linting: All clippy warnings must be addressed
  • Documentation: Add doc comments for public APIs
  • Testing: Include appropriate tests for your changes

Recommended VS Code Settings

Install the rust-analyzer extension and use these settings for the best development experience:

{
    "rust-analyzer.rustfmt.overrideCommand": ["rustfmt", "+nightly"],
    "rust-analyzer.check.overrideCommand": [
        "cargo",
        "clippy",
        "--workspace",
        "--message-format=json",
        "--all-targets",
        "--all-features"
    ]
}

3. Testing Your Changes

Reth uses comprehensive testing at multiple levels:

Unit Tests

Test specific functions and components:

cargo test --package reth-ethereum-consensus

Integration Tests

Test component interactions:

cargo test --test integration_tests

Full Test Suite

Run all tests including Ethereum Foundation tests:

make test

Validation Suite

Before submitting, always run:

make pr

This runs:

  • Code formatting checks
  • Clippy linting
  • Documentation generation
  • Full test suite

4. Submitting Your PR

Draft PRs for Large Features

For substantial changes, open a draft PR early to get feedback on the approach.

PR Requirements

  • Clear, descriptive title and description
  • Tests for new functionality
  • Documentation updates if needed
  • All CI checks passing
  • Commit messages follow conventional format

Commit Message Format

type: brief description
 
More detailed explanation if needed.
 
- feat: new feature
- fix: bug fix
- docs: documentation changes
- refactor: code refactoring
- test: adding tests
- chore: maintenance tasks

5. Review Process

Who Can Review

Any community member can review PRs. We encourage participation from all skill levels.

What Reviewers Look For

  • Does the change improve Reth?
  • Are there clear bugs or issues?
  • Are commit messages clear and descriptive?
  • Is the code well-tested?
  • Is documentation updated appropriately?

Review Guidelines

  • Be constructive and respectful
  • Provide specific, actionable feedback
  • Focus on significant issues first
  • Acknowledge good work and improvements

Releases: How Reth is Released

Release Schedule

  • Regular releases: Following semantic versioning
  • Security releases: As needed for critical vulnerabilities
  • Pre-releases: For testing major changes

Release Process

  1. Version bump: Update version numbers across crates
  2. Changelog: Update CHANGELOG.md with notable changes
  3. Testing: Final validation on testnet and mainnet
  4. Tagging: Create release tags and GitHub releases
  5. Distribution: Update package registries and Docker images

Release Criteria

  • All CI checks passing
  • No known critical bugs
  • Documentation up to date
  • Backwards compatibility considerations addressed

Ways to Contribute

💡 Feature Requests

For feature requests, please include:

  • Detailed explanation: What should the feature do?
  • Context and motivation: Why is this feature needed?
  • Examples: How would it be used?
  • Similar tools: References to similar functionality elsewhere

📝 Documentation

Documentation improvements are always welcome:

  • Add missing documentation
  • Improve code examples
  • Create tutorials or guides

🔧 Code Contributions

Contributing code changes:

  • Fix bugs identified in issues
  • Implement requested features
  • Improve performance
  • Refactor for better maintainability

Code of Conduct

Reth follows the Rust Code of Conduct. We are committed to providing a welcoming and inclusive environment for all contributors.

Our Standards

  • Be respectful and constructive
  • Focus on what's best for the community
  • Show empathy towards other contributors
  • Accept constructive criticism gracefully

Reporting Issues

If you experience or witness behavior that violates our code of conduct, please report it to georgios@paradigm.xyz.