# raul0ligma/smelter architecture

> Architecture diagram of the GitHub repository raul0ligma/smelter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raul0ligma/smelter
- Repository: https://github.com/raul0ligma/smelter

## Overview

##### Project type and purpose
- This is essentially a full-stack backend application that implements a local Ethereum node. It supports Ethereum JSON-RPC calls, custom RPC methods for state management and simulation (SMELTER namespace), and Otterscan RPC methods for block exploration.
- The purpose is to simulate Ethereum behavior (forking, executing transactions, handling state overrides, etc.) while also serving as an intermediary between external Ethereum nodes (via RPC) and end-user requests.

##### File structure to extract key architectural components
- Top-Level Entry Points:
- The main entry point is in cmd/main.go which initializes and starts the application.
- The app/app.go file likely contains application initialization logic.
- API / HTTP Server:
- Under pkg/server, you have modules (server.go and mw.go) that likely manage the HTTP server and middleware functions that process incoming JSON-RPC requests.
- The controller/router.go then handles request routing.
- Configuration:
- The config directory (e.g., config/config.go) holds configuration settings for the application.
- Business Logic and Domain Entities:
- The entity directory defines core data structures such as block, state, fork, transactions, and the entity tests ensure robust logic.
- Services and External Communication:
- The services directory contains handlers for different RPC behaviors (e.g., handling standard Ethereum RPC, Erigon-specific methods, and Otterscan RPC). These components abstract the communication with external Ethereum nodes.
- The provider folder (provider/rpc.go) further abstracts external Ethereum node interactions.
- Execution and Simulation:
- The executor and producer directories include logic to simulate blockchain behavior (e.g., block production and state transitions).
- The fork package indicates special logic to manage multiple fork states.
- Virtual Machine Execution:
- The vm directory is the heart of the EVM simulation. It includes the interpreter (vm/interpreter.go and related tests), contract handling, opcode implementations, gas calculations, and runtime environment.
- The tracer and statedb directories handle trace logging and state management during transaction execution.
- Utility and Logging:
- Under pkg/log, you have logging functionality to trace execution details.
- The utils directory provides CLI and conversion utilities, likely used for parsing arguments and formatting data.
- Testing:
- The tests directory (with various test_* files) ensures that the functionality is well covered with integration and unit tests.

a. Main Components:
- API Gateway / HTTP Server: Representing the entry point, including modules from cmd, controller, and pkg/server.
- Service Layer: Modules in services, producer, executor, provider, and fork. These handle RPC method dispatching, external Ethereum calls, state management, and simulation logic.
- Virtual Machine (VM) Layer: The vm package that simulates the Ethereum Virtual Machine, including the interpreter, opcodes, and runtime components.
- Logging & Utilities: Include the pkg/log and utils modules which support observability and command line interfaces.
- Configuration: The config module that supplies the settings for operation.
- External Dependencies: An external Ethereum node accessed via geth and external libraries (e.g., Otterscan) as per README references.

b. Relationships and Interactions:
- An incoming JSON-RPC request reaches the HTTP Server, which then passes it to the controller/router.
- The controller forwards requests to the appropriate service based on the RPC namespace (ETH, OTTERSCAN, or SMELTER).
- Within the service layer:
– Ethereum RPC calls are further dispatched to modules that communicate with external nodes (using provider/rpc.go and services/eth_rpc.go).
– The SMELTER-specific methods trigger execution paths that involve state management (statedb) and simulation of Ethereum operations using the VM layer.
- The virtual machine component processes transactions by executing contracts, consuming opcodes, implementing gas management, and maintaining runtime state.
- The fork and producer modules facilitate multi-fork support, managing isolated state contexts per key (as noted in the README with state TTL and cleanup interval).
- Logging and tracing components (pkg/log, tracer) capture detailed flow information that is invaluable for debugging and performance tracking.

c. Architectural Patterns and Design Principles:
- Layered Architecture: Clear separation between entry, business logic, and execution layers.
- Modularization: The project is divided into self-contained packages (e.g., services, vm, entity) that can be developed and tested in isolation.
- Abstraction: Provider and services layers abstract external Ethereum node interactions and internal simulation logic.
- Testability: Presence of a dedicated tests directory alongside test files in many modules indicates emphasis on unit and integration testing.

d. Relevant Technologies, Frameworks, or Libraries:
- Go language standard libraries and modules for network, logging, and concurrency.
- Specific RPC handling components (supporting Ethereum’s JSON-RPC spec and Otterscan extensions).
- EVM simulation components (interpreters, opcode handling) are custom-developed and are a core part of the architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CR("Client Request"):::api

    subgraph "Entry Layer"
        ME("Main Entry"):::entry
        AI("App Initialization"):::entry
    end

    subgraph "API Gateway Layer"
        HS("HTTP Server"):::api
        MW("Middleware"):::api
        RT("Router"):::api
    end

    CFG("Configuration"):::config

    ENT("Entities"):::business

    subgraph "Service Layer"
        ER("Eth RPC Service"):::service
        OT("Otterscan RPC Service"):::service
        ERG("Erigon RPC Service"):::service
        SM("Smelter RPC Service"):::service
        PR("Provider RPC"):::service
    end

    subgraph "Execution & Simulation"
        EXE("Executor"):::exec
        BP("Block Producer"):::exec
        FM("Fork Manager"):::exec
    end

    subgraph "VM & State"
        VM("VM Core"):::vm
        SDB("State DB"):::vm
        TR("Tracer"):::vm
    end

    subgraph "Utilities & Logging"
        LG("Logger"):::util
        CLI("CLI Utils"):::util
        CV("Convertors"):::util
    end

    subgraph "Testing"
        TST("Tests"):::test
    end

    EXT("External Ethereum Node"):::external

    %% Flow connections
    CR -->|"requests"| HS
    HS -->|"process"| MW
    MW -->|"forward"| RT
    RT -->|"dispatch"| ER
    RT -->|"dispatch"| OT
    RT -->|"dispatch"| ERG
    RT -->|"dispatch"| SM

    ER -->|"calls_provider"| PR
    PR -->|"external_call"| EXT

    SM -->|"triggers"| EXE
    EXE -->|"produces"| BP
    BP -->|"manages"| FM
    FM -->|"updates_state"| SDB
    FM -->|"engages"| VM

    ER -->|"interacts_with"| ENT
    OT -->|"interacts_with"| ENT
    ERG -->|"interacts_with"| ENT
    SM -->|"accesses"| ENT

    CFG -->|"configures"| HS
    CFG -->|"configures"| ER
    CFG -->|"configures"| SM
    CFG -->|"configures"| FM

    RT -->|"logs"| LG
    ER -->|"logs"| LG
    EXE -->|"logs"| LG
    VM -->|"logs"| LG

    ME -->|"initializes"| HS
    AI -->|"initializes"| HS

    %% Classes and styling
    classDef entry fill:#f9c,stroke:#333,stroke-width:2px,color:#000;
    classDef api fill:#bbf,stroke:#333,stroke-width:2px,color:#000;
    classDef config fill:#9f6,stroke:#333,stroke-width:2px,color:#000;
    classDef business fill:#cff,stroke:#333,stroke-width:2px,color:#000;
    classDef service fill:#fc9,stroke:#333,stroke-width:2px,color:#000;
    classDef exec fill:#ff9,stroke:#333,stroke-width:2px,color:#000;
    classDef vm fill:#cfc,stroke:#333,stroke-width:2px,color:#000;
    classDef util fill:#ccf,stroke:#333,stroke-width:2px,color:#000;
    classDef test fill:#f66,stroke:#333,stroke-width:2px,color:#fff;
    classDef external fill:#def,stroke:#333,stroke-width:2px,color:#000;

    %% Click Events
    click ME "https://github.com/raul0ligma/smelter/blob/master/cmd/main.go"
    click AI "https://github.com/raul0ligma/smelter/blob/master/app/app.go"
    click HS "https://github.com/raul0ligma/smelter/blob/master/pkg/server/server.go"
    click MW "https://github.com/raul0ligma/smelter/blob/master/pkg/server/mw.go"
    click RT "https://github.com/raul0ligma/smelter/blob/master/controller/router.go"
    click CFG "https://github.com/raul0ligma/smelter/blob/master/config/config.go"
    click ENT "https://github.com/raul0ligma/smelter/tree/master/entity/"
    click ER "https://github.com/raul0ligma/smelter/blob/master/services/eth_rpc.go"
    click OT "https://github.com/raul0ligma/smelter/blob/master/services/otterscan_rpc.go"
    click ERG "https://github.com/raul0ligma/smelter/blob/master/services/erigon_rpc.go"
    click SM "https://github.com/raul0ligma/smelter/blob/master/services/smelter_rpc.go"
    click PR "https://github.com/raul0ligma/smelter/blob/master/provider/rpc.go"
    click EXE "https://github.com/raul0ligma/smelter/blob/master/executor/executor.go"
    click BP "https://github.com/raul0ligma/smelter/blob/master/producer/block_producer.go"
    click FM "https://github.com/raul0ligma/smelter/blob/master/fork/fork.go"
    click VM "https://github.com/raul0ligma/smelter/tree/master/vm/"
    click SDB "https://github.com/raul0ligma/smelter/blob/master/statedb/statedb.go"
    click TR "https://github.com/raul0ligma/smelter/tree/master/tracer/"
    click LG "https://github.com/raul0ligma/smelter/blob/master/pkg/log/logger.go"
    click CLI "https://github.com/raul0ligma/smelter/blob/master/utils/cli.go"
    click CV "https://github.com/raul0ligma/smelter/blob/master/utils/convertors.go"
    click TST "https://github.com/raul0ligma/smelter/tree/master/tests/"
```
