Skip to content

Fukuii Repository Structure

This document provides an overview of the Fukuii repository organization to help contributors and users understand the layout of the codebase.

Repository Organization

fukuii/
├── src/                    # Main application source code
├── bytes/                  # Vendored: Bytes manipulation library
├── crypto/                 # Vendored: Cryptographic utilities
├── rlp/                    # Vendored: RLP encoding/decoding
├── scalanet/               # Vendored: Networking library (from IOHK)
├── docker/                 # Docker configurations and compose files
├── docs/                   # Documentation (ADRs, runbooks, guides)
├── ets/                    # Ethereum Test Suite configuration
├── ops/                    # Operations configs (Grafana dashboards)
├── tls/                    # TLS certificates for testing
├── project/                # SBT build configuration
├── build.sbt               # Main SBT build definition
└── [config files]          # .scalafmt.conf, .scalafix.conf, etc.

Directory Details

Application Source Code

src/

The main Fukuii application source code, following standard SBT/Scala conventions:

  • src/main/ - Production code
  • scala/com/chipprbots/ethereum/ - Main application package
  • resources/ - Configuration files, genesis blocks, etc.

  • protobuf/ & protobuf_override/ - Protocol buffer definitions for external VM interface

  • src/test/ - Unit tests

  • src/it/ - Integration tests
  • src/rpcTest/ - RPC API-specific tests
  • src/evmTest/ - EVM execution tests
  • src/benchmark/ - Performance benchmarks
  • src/universal/ - Distribution files
  • bin/ - Launcher scripts
  • conf/ - Configuration templates

Vendored Libraries

These libraries were vendored (copied into the repository) to provide better control over dependencies and ensure Scala 3 compatibility:

bytes/

Simple bytes manipulation utilities. A foundational library used throughout the codebase.

crypto/

Cryptographic utilities for Ethereum operations (hashing, signing, key derivation).

rlp/

Recursive Length Prefix (RLP) encoding and decoding, the serialization format used in Ethereum.

scalanet/

Network layer implementation originally from IOHK. Provides peer-to-peer networking functionality.

Note: These libraries are defined as SBT subprojects in build.sbt and maintain their own src/main/ and src/test/ structure.

Testing & Integration

ets/

Ethereum Test Suite (ETS) integration: - ets/tests/ - Git submodule pointing to official Ethereum consensus tests - ets/config/fukuii/ - Retesteth configuration for Fukuii - ets/retesteth - Wrapper script for running tests - test-ets.sh - CI script for running the full test suite

See the Testing Documentation for details on running tests.

tls/

TLS certificates and scripts for secure RPC testing: - Self-signed certificates for development/testing - Certificate generation scripts

Operations & Deployment

docker/

Docker and Docker Compose configurations: - docker/fukuii/ - Fukuii-specific Docker Compose setup with Prometheus/Grafana - docker/besu/ - Besu client setup (for comparison testing) - docker/geth/ - Geth client setup (for comparison testing) - ops/barad-dur/ - Barad-dûr (Kong) API gateway integration - docker/scripts/ - Helper scripts - Dockerfile* - Various Dockerfile variants (prod, dev, distroless, etc.)

See Docker Documentation for comprehensive Docker documentation.

ops/

Operational configurations for production deployments: - ops/barad-dur/ - Barad-dûr (Kong API Gateway) - Production API gateway stack - ops/cirith-ungol/ - Cirith Ungol - ETC mainnet testing environment
- ops/gorgoroth/ - Gorgoroth - Internal private test network - ops/grafana/ - Pre-configured Grafana dashboards for monitoring Fukuii nodes - ops/prometheus/ - Prometheus configuration templates

See ops/README.md and Metrics and Monitoring for details.

docs/

Comprehensive documentation: - docs/adr/ - Architecture Decision Records (ADRs), organized by category (infrastructure, vm, consensus, testing, operations) - docs/runbooks/ - Operational runbooks for production - docs/operations/ - Metrics, monitoring, and operational guides - docs/images/ - Logo and other images

Key documents: - ../adr/README.md - Index of architecture decisions - ../runbooks/README.md - Index of operational runbooks - architecture-overview.md - System architecture

Build System

project/

SBT build configuration: - project/build.properties - SBT version - project/plugins.sbt - SBT plugins - project/Dependencies.scala - Dependency management

Root Build Files

  • build.sbt - Main build definition with subproject configuration
  • .jvmopts - JVM options for SBT
  • .scalafmt.conf - Code formatting rules (Scalafmt)
  • .scalafix.conf - Linting and refactoring rules (Scalafix)
  • version.sbt - Project version

Configuration Files

  • .gitignore - Git ignore patterns
  • .gitmodules - Git submodules (ETS tests)
  • .dockerignore - Docker ignore patterns
  • .devcontainer/ - VS Code Dev Container / GitHub Codespaces configuration

Build System Architecture

Fukuii uses a multi-module SBT build with the following structure:

  1. Core Application (node project in root)
  2. Depends on: bytes, crypto, rlp, scalanet, scalanetDiscovery

  3. Configurations: compile, test, it, evm, rpcTest, benchmark

  4. Vendored Libraries (independent SBT subprojects)

  5. Each has its own src/main/ and src/test/ structure
  6. Published as separate artifacts (though currently disabled)
  7. Can be built/tested independently

Conventions and Standards

Code Organization

  • Package structure: com.chipprbots.ethereum.*
  • Scala version: 3.3.4 (LTS)
  • JDK version: 21 (LTS)

Testing Conventions

  • Unit tests: src/test/scala/
  • Integration tests: src/it/scala/
  • Test configurations: Use ScalaTest framework
  • Ethereum tests: ETS submodule with retesteth

Documentation Conventions

  • Architecture decisions: ADRs in docs/adr/
  • Operational guides: Runbooks in docs/runbooks/
  • API documentation: ScalaDoc in source code
  • External docs: Markdown in docs/

Development Workflow

Quick Start

# Clone with submodules
git clone --recursive https://github.com/chippr-robotics/fukuii.git
cd fukuii

# Build
sbt compile

# Run tests
sbt test

# Format and check code
sbt pp  # "prepare PR" - formats, checks, and tests

# Build distribution
sbt dist

Testing

# Unit tests
sbt test

# Integration tests
sbt IntegrationTest/test

# RPC tests
sbt RpcTest/test

# EVM tests
sbt Evm/test

# Ethereum Test Suite
./test-ets.sh

Code Quality

# Format all code
sbt formatAll

# Check formatting
sbt formatCheck

# Run static analysis
sbt runScapegoat

# Coverage report
sbt testCoverage

Historical Context

This repository is a continuation of the Mantis Ethereum Classic client originally developed by Input Output (HK). Key changes:

  1. Rebranding (2024): Mantis → Fukuii
  2. Package: io.iohk.ethereum → com.chipprbots.ethereum

  3. Binary: mantis → fukuii

  4. Scala 3 Migration (October 2024)

  5. Scala 2.13 → Scala 3.3.4 (LTS)
  6. Akka → Apache Pekko
  7. Monix → Cats Effect 3

  8. See INF-001: Scala 3 Migration

  9. Vendored Dependencies

  10. scalanet: Networking library (needed for Scala 3 compatibility)
  11. bytes, crypto, rlp: Core utilities extracted as modules

Questions?

For questions about the repository structure or where to add new code:

  1. Check existing code for similar functionality
  2. Follow the package structure in src/main/scala/
  3. Refer to Contributing Guide
  4. Ask in GitHub Discussions or open an issue