# eqlabs/pathfinder architecture

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

- Interactive diagram: https://gitdiagram.com/eqlabs/pathfinder
- Repository: https://github.com/eqlabs/pathfinder

## Overview

##### Project type and purpose
- Pathfinder is a Rust‐based full node implementation for the Starknet blockchain. It ingests and gossips blocks via a P2P network, runs a consensus protocol (“Malachite”), executes transactions to update state, persists everything to a database, and exposes a JSON-RPC/WebSocket API to clients.

##### Key architectural layers (from bottom to top)
a. Storage Layer
- Crate “storage”: handles database connections (SQLite or Postgres), schemas, migrations, and low-level CRUD for blocks, states, receipts, transactions, events, proofs, etc.
- Optional “fake” adapters and test fixtures under “crates/storage/src/fake.rs” and “crates/storage/src/test_utils.rs.”

b. Execution Layer
- Crate “executor”: applies transaction classes to state, tracks pending calls, caches contract classes, and simulates calls.
- Crate “block-hashes” and “class-hash”: helper crates for computing deterministic hash functions required by the Starknet VM.

c. Consensus Layer
- Crate “consensus”: implements the Malachite consensus protocol modules (proposals, rounds, votes, WAL).
- Crate “p2p” + “p2p_proto” + “p2p_stream”: networking transport, message codecs (protobuf), and high-level P2P behaviors for consensus gossip and sync.

d. Gateway / L1 Integration
- Crate “gateway-client”: pulls new L1 state updates and blocks from a Starknet gateway (HTTP/JSON), used during initial sync or state updates.
- Crate “gateway-types” and “gateway-test-fixtures” for modeling and testing gateway responses.

e. RPC / API Layer
- Crate “rpc”: exposes JSON-RPC and WebSocket endpoints, routes methods (get_block, get_state_update, simulate, subscribe_new_heads, etc.), embeds middleware (CORS, tracing), and dispatches to executor, storage, or pathfinder core.
- Specs under “specs/rpc” track OpenRPC definitions per version.

f. Orchestration / Binary
- Crate “pathfinder”: the main binary. It wires together all components, reads configuration (CLI + env), initializes the P2P network, starts consensus, triggers execution and storage subsystems, and launches the RPC server.
- “build/” & Docker assets for containerized builds and deployments.

##### External services and integrations
- Ethereum L1 node or Starknet sequencer (via gateway-client) for pulling blocks and L1 events
- Clients connecting via JSON-RPC / WebSockets
- Prometheus / metrics (see “metrics.rs” in gateway-client and “monitoring.rs” in pathfinder)
- Configuration / CLI inputs

- Main Orchestrator (pathfinder binary)

- P2P ↔ Consensus: block gossip, votes, sync messages
- Consensus → Orchestrator: new finalized block events
- Orchestrator → Executor: execute block transactions
- Executor → Storage: persist new state, receipts, block data
- Gateway Client → Orchestrator: push L1 updates for state sync
- RPC Server ↔ Orchestrator/Executor/Storage: client queries mapped to appropriate subsystem
- Monitoring → Metrics Endpoint: scrape metrics

- Blue: Networking components (P2P, Gateway Client)
- Green: Core computation (Consensus, Executor)
- Orange: Data persistence (Storage)
- Purple: External API (RPC Server)
- Grey: Orchestrator/CLI/Config

##### Architectural patterns and principles
- Modular crate-per-domain approach: each core domain (storage, execution, consensus, RPC) is isolated into its own crate.
- Layered architecture: clear separation of transport (P2P, HTTP) → business logic (consensus, execution) → persistence (storage).
- Pluggable transports and protocol versions: P2P stack uses protocol buffers and can evolve independent of business logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "Storage Layer"
        direction TB
        Storage["crates/storage (DB)"]:::storage
        FakeAdapter["fake adapter"]:::storage
        TestUtils["test utilities"]:::storage
    end

    subgraph "Execution Layer"
        direction TB
        Executor["crates/executor"]:::executor
        BlockHashes["crates/block-hashes"]:::executor
        ClassHash["crates/class-hash"]:::executor
    end

    subgraph "Consensus & P2P Layer"
        direction TB
        Consensus["crates/consensus"]:::consensus
        subgraph "P2P Networking"
            direction TB
            P2P["crates/p2p"]:::networking
            Proto["crates/p2p_proto"]:::networking
            Stream["crates/p2p_stream"]:::networking
        end
    end

    subgraph "Gateway & L1 Integration"
        direction TB
        GatewayClient["crates/gateway-client"]:::networking
        GatewayTypes["crates/gateway-types"]:::networking
        GatewayFixtures["crates/gateway-test-fixtures"]:::networking
    end

    subgraph "RPC / API Layer"
        direction TB
        RPC["crates/rpc"]:::api
        RPCSpecs["specs/rpc"]:::api
    end

    subgraph "Orchestration / Binary"
        direction TB
        Pathfinder["crates/pathfinder"]:::orchestrator
        Docker["build/, Dockerfile, nodes/docker-compose.yaml"]:::orchestrator
    end

    %% External Services
    Ethereum["Ethereum L1 node / Starknet sequencer"]:::external
    Clients["JSON-RPC/WebSocket clients"]:::external
    Prometheus["Prometheus (metrics)"]:::external

    %% Connections
    P2P <-->|"gossip blocks, votes, sync"| Consensus
    Consensus -->|"finalized block event"| Pathfinder
    Pathfinder -->|"execute block"| Executor
    Executor -->|"persist state, receipts, blocks"| Storage
    GatewayClient -->|"L1 updates for sync"| Pathfinder
    RPC -->|"client queries"| Pathfinder
    RPC -->|"client queries"| Executor
    RPC -->|"client queries"| Storage
    Prometheus -->|"scrape metrics"| GatewayClient
    Prometheus -->|"scrape metrics"| Pathfinder
    Ethereum -->|"blocks & events"| GatewayClient
    Clients -->|"RPC/WebSocket"| RPC

    %% Click Events
    click Storage "https://github.com/eqlabs/pathfinder/tree/main/crates/storage"
    click FakeAdapter "https://github.com/eqlabs/pathfinder/blob/main/crates/storage/src/fake.rs"
    click TestUtils "https://github.com/eqlabs/pathfinder/blob/main/crates/storage/src/test_utils.rs"
    click Executor "https://github.com/eqlabs/pathfinder/tree/main/crates/executor"
    click BlockHashes "https://github.com/eqlabs/pathfinder/tree/main/crates/block-hashes"
    click ClassHash "https://github.com/eqlabs/pathfinder/tree/main/crates/class-hash"
    click Consensus "https://github.com/eqlabs/pathfinder/tree/main/crates/consensus"
    click P2P "https://github.com/eqlabs/pathfinder/tree/main/crates/p2p"
    click Proto "https://github.com/eqlabs/pathfinder/tree/main/crates/p2p_proto"
    click Stream "https://github.com/eqlabs/pathfinder/tree/main/crates/p2p_stream"
    click GatewayClient "https://github.com/eqlabs/pathfinder/tree/main/crates/gateway-client"
    click GatewayTypes "https://github.com/eqlabs/pathfinder/tree/main/crates/gateway-types"
    click GatewayFixtures "https://github.com/eqlabs/pathfinder/tree/main/crates/gateway-test-fixtures"
    click RPC "https://github.com/eqlabs/pathfinder/tree/main/crates/rpc"
    click RPCSpecs "https://github.com/eqlabs/pathfinder/tree/main/specs/rpc"
    click Pathfinder "https://github.com/eqlabs/pathfinder/tree/main/crates/pathfinder"
    click Docker "https://github.com/eqlabs/pathfinder/tree/main/build/"
    click Prometheus "https://github.com/eqlabs/pathfinder/blob/main/crates/gateway-client/src/metrics.rs"
    click Prometheus "https://github.com/eqlabs/pathfinder/blob/main/crates/pathfinder/src/monitoring.rs"

    %% Styles
    classDef storage fill:#f39c12,color:#fff;
    classDef executor fill:#27ae60,color:#fff;
    classDef consensus fill:#27ae60,color:#fff;
    classDef networking fill:#3498db,color:#fff;
    classDef api fill:#8e44ad,color:#fff;
    classDef orchestrator fill:#95a5a6,color:#fff;
    classDef external fill:#7f8c8d,color:#fff;
```
