How raul0ligma/smelter works
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.