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:
- GitHub Issues: Open an issue for bugs or feature requests
- Telegram Chat: Join our Telegram for real-time support and discussions
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
- Version bump: Update version numbers across crates
- Changelog: Update
CHANGELOG.md
with notable changes - Testing: Final validation on testnet and mainnet
- Tagging: Create release tags and GitHub releases
- 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.