Skip to content

Architectural Decision Records (ADR)

This directory contains Architectural Decision Records (ADRs) for the Fukuii Ethereum Client project.

What is an ADR?

An Architectural Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences. ADRs help teams:

  • Understand why certain decisions were made
  • Track the evolution of the architecture over time
  • Onboard new team members more effectively
  • Avoid revisiting already-settled discussions

ADR Format

Each ADR follows this structure:

  • Title: Short descriptive title
  • Status: Proposed, Accepted, Deprecated, Superseded
  • Context: The situation prompting the decision
  • Decision: The choice that was made
  • Consequences: The results of the decision (positive and negative)

ADR Organization by Category

To support parallel development and prevent naming collisions, ADRs are organized into categories:

Infrastructure (infrastructure/)

Platform, language, runtime, and build system decisions. - INF-001: Migration to Scala 3 and JDK 21 - Accepted - INF-001a: Netty Channel Lifecycle with Cats Effect IO - Accepted (Addendum) - INF-002: Actor System Architecture - Untyped vs Typed Actors - Accepted - INF-003: Apache HttpClient Transport for JupnP UPnP Port Forwarding - Accepted - INF-004: Actor IO Error Handling Pattern with Cats Effect - Accepted

View all Infrastructure ADRs →

VM (EVM) (vm/)

EVM implementations, EIPs, and VM-specific features. - VM-001: EIP-3541 Implementation - Accepted - VM-002: EIP-3529 Implementation - Accepted - VM-003: EIP-3651 Implementation - Accepted - VM-004: EIP-3855 Implementation - Accepted - VM-005: EIP-3860 Implementation - Accepted - VM-006: EIP-6049 Implementation - Accepted - VM-007: EIP-161 noEmptyAccounts Configuration Fix - Accepted

Related Specifications: - Ethereum Mainnet EVM Compatibility - Comprehensive analysis of EIPs and opcodes for Ethereum mainnet compatibility

View all VM ADRs →

Consensus (consensus/)

Consensus mechanisms, networking protocols, P2P communication, and blockchain synchronization. - CON-001: RLPx Protocol Deviations and Peer Bootstrap Challenge - Accepted - CON-002: Bootstrap Checkpoints for Improved Initial Sync - Accepted - CON-003: Block Sync Improvements - Enhanced Reliability and Performance - Accepted - CON-004: MESS (Modified Exponential Subjective Scoring) Implementation - Accepted - CON-005: ETH66 Protocol Aware Message Formatting - Accepted

View all Consensus ADRs →

Testing (testing/)

Testing infrastructure, strategies, test suites, and quality assurance. - TEST-001: Ethereum Tests Adapter - Accepted - TEST-002: Test Suite Strategy, KPIs, and Execution Benchmarks - Accepted

View all Testing ADRs →

Operations (operations/)

Operational features, administration, monitoring, user interfaces, and deployment. - OPS-001: Enhanced Console User Interface - Accepted - OPS-002: Logging Level Categorization Standards - Accepted

View all Operations ADRs →

Creating a New ADR

When creating a new ADR:

  1. Choose the appropriate category (infrastructure, vm, consensus, testing, operations)
  2. Use the next sequential number for that category (e.g., VM-008-title.md, CON-006-title.md)
  3. Follow the template structure
  4. Link it in both the category README and this main index
  5. Keep it concise but comprehensive
  6. Focus on the "why" not just the "what"

Category Naming Conventions

  • Infrastructure: INF-NNN-title.md
  • VM: VM-NNN-title.md
  • Consensus: CON-NNN-title.md
  • Testing: TEST-NNN-title.md
  • Operations: OPS-NNN-title.md

This categorization allows different teams to work on ADRs in parallel without naming conflicts.

References