# chainsafe/forest architecture

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

- Interactive diagram: https://gitdiagram.com/chainsafe/forest
- Repository: https://github.com/chainsafe/forest

## Overview

##### Main System Components
- Forest Daemon – the primary binary (“forest”) that launches the node. This is where chain syncing, state management, consensus, and database interaction occur.
- Forest CLI – “forest-cli” which wraps the JSON-RPC API for user-friendly interactions.
- Forest Tool – “forest-tool” handling tasks that are not part of the main chain node (e.g., snapshots, backups).
- F3 Sidecar – a Go module providing additional functionality (like certificate handling, network messaging); it interfaces with the main system.
- RPC & API Modules – located in the “src/rpc” folder, handling command routing, filtering, and JSON-RPC methods.
- Network & P2P Modules – in “src/libp2p” and “src/libp2p_bitswap”, which deal with the underlying networking (peer discovery, chain exchange, bitswap protocols).
- Chain Sync and Consensus – implemented under “src/chain_sync”, “src/chain”, “src/blocks”, and “src/beacon” to manage blockchain validation, chain following, block production, and consensus protocols.
- Storage & DB Modules – found in “src/db”, “src/chain/store”, and “src/state_manager” for persistent data (e.g., chain state, blocks, messages).
- State Migration – many files under “src/state_migration” show that this node has intricate logic to handle upgrading or migrating its internal state.
- Keystore & Security – contained in “src/auth”, “src/key_management”, along with configuration settings via environmental variables and config files.
- Additional Domains – modules such as “src/eth”, “src/lotus_json”, “src/ipld”, “src/message”, and “src/shim” which handle cross-chain data structures, serialization (CBOR/IPLD), and interfacing with Filecoin’s actor model.

##### Relationships and Interactions
- The Forest Daemon is at the center. It:
– Listens for network connections using libp2p.
– Manages chain synchronization and state updates via the chain sync, consensus, and blocks modules.
– Interacts with persistent storage (databases) as well as with the keystore for cryptographic operations.
– Exposes a JSON-RPC API (through the “rpc” modules) which is accessed by the Forest CLI.
- The CLI and Tool binaries interact with the daemon via its RPC endpoints, sending commands such as “snapshots”, “info”, “wallet”, and “sync” commands.
- The F3 sidecar module, written in Go, interacts with the main node (or might run as a side process) for certain protocol-specific functions.
- Configuration management is supported by multiple files (TOML, YAML) and environment variables to allow dynamic setting of network points, bootnodes, and logging.
- External dependencies in Dockerfiles and scripts indicate that deployments are containerized and support multiple OS builds.

##### Architectural Patterns and Design Principles
- Modular design – the code is separated into modules for networking, consensus, state management, message handling, and migration.
- Layered architecture – with high-level RPC and CLI layers on top of core daemon functionality (networking, chain sync, DB).
- Separation of concerns – the daemon is isolated from command-line tools, and external-facing components (like RPC) are managed separately.
- Use of asynchronous programming paradigms – inherent when dealing with network communications and multi-threaded state management in Rust.
- Extensibility – plenty of configuration and migration modules indicate the system is built for iterative improvements.

##### Relevant Technologies & Frameworks
- Rust as the prime programming language
- Go (for the f3-sidecar)
- Libp2p for P2P networking and bitswap protocols
- JSON-RPC for API interactions
- Docker for containerized deployments
- Tooling such as Clippy, rustfmt, and Nextest for testing & linting
- TOML, YAML, and configuration management strategies for flexible deployments

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        CLI["Forest CLI"]:::ui
        TOOL["Forest Tool"]:::ui
        RPC["RPC & API Modules"]:::ui
    end

    %% Core Processing Layer
    subgraph "Core Processing Layer"
        FD["Forest Daemon"]:::core
        CS["Chain Sync & Consensus"]:::core
        SM["State Migration"]:::core
        KS["Keystore & Security"]:::core
    end

    %% Additional Domains
    subgraph "Additional Domains"
        ETH["Ethereum Modules"]:::aux
        LOTUS["Lotus JSON Handling"]:::aux
        IPLD["IPLD Serialization"]:::aux
        MSG["Message Handling"]:::aux
        SHIM["Shim Interfaces"]:::aux
    end

    %% Networking & Storage Layer
    subgraph "Networking & Storage Layer"
        NET["Network & P2P Modules"]:::network
        DB["Storage & DB Modules"]:::storage
        F3["F3 Sidecar"]:::network
    end

    %% Connections within layers and across layers
    CLI -->|"calls"| RPC
    RPC -->|"forward"| FD
    TOOL -->|"commands"| FD

    FD -->|"chain_sync"| CS
    FD -->|"state_update"| SM
    FD -->|"key_ops"| KS
    FD -->|"network_ops"| NET
    FD -->|"persist"| DB
    FD -->|"side_integ"| F3

    FD -->|"integrates"| ETH
    FD -->|"integrates"| LOTUS
    FD -->|"integrates"| IPLD
    FD -->|"integrates"| MSG
    FD -->|"integrates"| SHIM

    %% Styles
    classDef ui fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef core fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef aux fill:#f94144,stroke:#333,stroke-width:2px;
    classDef network fill:#577590,stroke:#333,stroke-width:2px;
    classDef storage fill:#277da1,stroke:#333,stroke-width:2px;

    %% Click Events
    click CLI "https://github.com/chainsafe/forest/blob/main/src/bin/forest-cli.rs"
    click TOOL "https://github.com/chainsafe/forest/blob/main/src/bin/forest-tool.rs"
    click TOOL "https://github.com/chainsafe/forest/blob/main/src/tool/main.rs"
    click FD "https://github.com/chainsafe/forest/blob/main/src/bin/forest.rs"
    click FD "https://github.com/chainsafe/forest/blob/main/src/daemon/main.rs"
    click RPC "https://github.com/chainsafe/forest/tree/main/src/rpc/"
    click NET "https://github.com/chainsafe/forest/tree/main/src/libp2p/"
    click NET "https://github.com/chainsafe/forest/tree/main/src/libp2p_bitswap/"
    click CS "https://github.com/chainsafe/forest/tree/main/src/chain_sync/"
    click CS "https://github.com/chainsafe/forest/tree/main/src/chain/"
    click DB "https://github.com/chainsafe/forest/tree/main/src/db/"
    click SM "https://github.com/chainsafe/forest/tree/main/src/state_migration/"
    click KS "https://github.com/chainsafe/forest/tree/main/src/auth/"
    click KS "https://github.com/chainsafe/forest/tree/main/src/key_management/"
    click ETH "https://github.com/chainsafe/forest/tree/main/src/eth/"
    click LOTUS "https://github.com/chainsafe/forest/tree/main/src/lotus_json/"
    click IPLD "https://github.com/chainsafe/forest/tree/main/src/ipld/"
    click MSG "https://github.com/chainsafe/forest/tree/main/src/message/"
    click MSG "https://github.com/chainsafe/forest/tree/main/src/message_pool/"
    click SHIM "https://github.com/chainsafe/forest/tree/main/src/shim/"
    click F3 "https://github.com/chainsafe/forest/tree/main/f3-sidecar/"
```
