# stader-labs/stader-node architecture

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

- Interactive diagram: https://gitdiagram.com/stader-labs/stader-node
- Repository: https://github.com/stader-labs/stader-node

## Overview

##### Project Type and Purpose
- This is a Go-based CLI and supporting library ecosystem for running and managing “ETHx” permissionless staking nodes on Ethereum.
- The stader-cli binary (user-facing) orchestrates node registration, reward claiming, config generation, and interactions with smart contracts.
- Underneath, a set of core libraries (shared/…), a service-oriented CLI app (stader/…), and a companion guardian module provide actual blockchain, state, wallet, and monitoring logic.

##### High-Level Architecture Overview
A. User Layer
- stader-cli (CLI): the entry point.
B. Application Layer
- CLI App (“stader-cli” package) uses:
– Shared Services (shared/services)
– Shared Types & Utils (shared/types, shared/utils)
- Main application binary (“stader” package) & “ec_migrate” scripts
- Guardian module (stader/guardian): metrics collector & exporter
C. Services Layer
- Config Manager (shared/services/config): reads/overrides YAML templates
- API Client (shared/services/stader): talks to Stader backend for pool data
- Blockchain Manager (shared/services/bc-manager & beacon client)
- Execution Client Manager (shared/services/ec-manager)
- Wallet Manager (shared/services/wallet): keystore per consensus client
- Gas Oracle (shared/services/gas): Etherchain & Etherscan
- State Manager (shared/services/state): tracks network & local node state
D. Infrastructure & External Systems
- Ethereum Consensus & Execution RPC Endpoints (e.g., Geth, Nethermind, Lighthouse, Prysm, Teku)
- Smart Contracts on Ethereum (abis/*.json + stader-lib/contracts)
- Monitoring & Metrics (Prometheus + Grafana + guardian exporter)
- Docker & Install Scripts (docker/, install/…): deployment artifacts

##### Component Relationships & Data Flows
- The CLI invokes the Application Layer, passing user commands.
- Configuration Manager loads templates, user overrides → passes config objects to Services.
- API Client retrieves pool/contract addresses & params from Stader backend.
- Blockchain Manager & EC Manager launch or talk to local Ethereum clients via JSON-RPC.
- Wallet Manager manages validator keys in consensus client format, feeds deposit data to smart contracts via RPC.
- Gas Oracle provides gas‐price suggestions before on-chain tx.
- State Manager tracks local node health & on-chain state.
- Guardian periodically pulls metrics from all Managers & Clients, exposes Prometheus endpoint.
- Monitoring stack scrapes Guardian + node exporters and displays on Grafana.

##### Important Patterns & Principles
- Layered architecture: CLI → Core Services → External Systems
- Dependency injection via “shared/services” interfaces—swapable clients (e.g., Lighthouse vs Prysm)
- Template-driven config generation for different client implementations
- Modularization: each blockchain service, gas oracle, wallet provider implemented as pluggable module

##### Essential Elements
- Sequence of interactions for a typical command (e.g., “deposit-sd”):
1) CLI reads config →
2) API Client fetches contract data →
3) Wallet Manager constructs deposit TX →
4) Gas Oracle suggests gas →
5) EC Manager submits TX to execution client →
6) State Manager confirms inclusion
- “stader-lib” usage as the in-process abstraction of smart-contract ABIs and proofs.

## Diagram (Mermaid)

```mermaid
graph TB
    %% User Layer
    subgraph "User Layer"
        style UserLayer fill:none,stroke:none
        User(["User"]):::external
        CLI(["stader-cli (CLI)"]):::cli
    end

    User -->|"executes"| CLI
    click CLI "https://github.com/stader-labs/stader-node/blob/main/stader-cli/stader-cli.go"

    %% Application Layer
    subgraph "Application Layer"
        style AppLayer fill:none,stroke:none
        AppBin(["stader (main binary)"]):::cli
        ECMigScripts(["ec_migrate scripts"]):::cli
        SharedTypes(["Shared Types"]):::common
        SharedUtils(["Common Utilities"]):::common
        SharedSvcsLib(["Shared Services Lib"]):::common
        GuardianMod(["Guardian Module"]):::cli
    end

    CLI -->|"orchestrates"| AppBin
    CLI -->|"uses"| SharedSvcsLib
    CLI -->|"uses"| SharedTypes
    CLI -->|"uses"| SharedUtils
    CLI -->|"invokes"| GuardianMod

    click AppBin "https://github.com/stader-labs/stader-node/blob/main/stader/stader.go"
    click ECMigScripts "https://github.com/stader-labs/stader-node/blob/main/stader/ec_migrate.sh"
    click ECMigScripts "https://github.com/stader-labs/stader-node/blob/main/stader/ec_migrate multi.sh"
    click SharedSvcsLib "https://github.com/stader-labs/stader-node/tree/main/shared/services/"
    click SharedTypes "https://github.com/stader-labs/stader-node/tree/main/shared/types/"
    click SharedUtils "https://github.com/stader-labs/stader-node/tree/main/shared/utils/"
    click GuardianMod "https://github.com/stader-labs/stader-node/blob/main/stader/guardian/guardian.go"

    %% Services Layer
    subgraph "Services Layer"
        style SvcsLayer fill:none,stroke:none
        ConfigMgr(["Config Manager"]):::svc
        APIClient(["API Client"]):::svc
        BCManager(["Blockchain Manager"]):::svc
        ECManager(["Execution Client Manager"]):::svc
        WalletMgr(["Wallet Manager"]):::svc
        GasOracle(["Gas Oracle"]):::svc
        StateMgr(["State Manager"]):::svc
    end

    AppBin -->|"loads config"| ConfigMgr
    ConfigMgr -->|"provides config"| APIClient
    ConfigMgr -->|"provides config"| BCManager
    ConfigMgr -->|"provides config"| ECManager
    ConfigMgr -->|"provides config"| WalletMgr
    ConfigMgr -->|"provides config"| GasOracle
    ConfigMgr -->|"provides config"| StateMgr

    click ConfigMgr "https://github.com/stader-labs/stader-node/tree/main/shared/services/config/"
    click APIClient "https://github.com/stader-labs/stader-node/tree/main/shared/services/stader/"
    click BCManager "https://github.com/stader-labs/stader-node/blob/main/shared/services/bc-manager.go"
    click ECManager "https://github.com/stader-labs/stader-node/blob/main/shared/services/ec-manager.go"
    click WalletMgr "https://github.com/stader-labs/stader-node/tree/main/shared/services/wallet/"
    click GasOracle "https://github.com/stader-labs/stader-node/tree/main/shared/services/gas/"
    click StateMgr "https://github.com/stader-labs/stader-node/tree/main/shared/services/state/"

    %% Service Interactions
    APIClient -->|"REST/gRPC"| StaderBackend["Stader Backend"]:::external
    BCManager -->|"JSON-RPC"| EthNodes["Ethereum Clients"]:::external
    ECManager -->|"JSON-RPC"| EthNodes
    WalletMgr -->|"ABI call"| SmartContracts["Smart Contracts"]:::external
    GasOracle -->|"REST/API"| EthData["Etherchain/Etherscan"]:::external
    StateMgr -->|"tracks state"| EthNodes

    %% Guardian & Monitoring
    subgraph "Guardian & Monitoring"
        style MonLayer fill:none,stroke:none
        Collector(["Metrics Collector"]):::cli
        Exporter(["Metrics Exporter"]):::cli
        Prometheus(["Prometheus"]):::external
        Grafana(["Grafana"]):::external
    end

    BCManager -->|"metrics"| Collector
    ECManager -->|"metrics"| Collector
    WalletMgr -->|"metrics"| Collector
    GasOracle -->|"metrics"| Collector
    StateMgr -->|"metrics"| Collector
    Collector --> Exporter
    Exporter -->|"Prometheus endpoint"| Prometheus
    Prometheus -->|"dashboarding"| Grafana

    click Collector "https://github.com/stader-labs/stader-node/tree/main/stader/guardian/collector/"
    click Exporter "https://github.com/stader-labs/stader-node/blob/main/stader/guardian/metrics-exporter.go"

    %% Infrastructure & External Systems
    subgraph "Infra & External Systems"
        style ExtLayer fill:none,stroke:none
        EthNodes
        SmartContracts
        EthData
        StaderBackend
    end

    click SmartContracts "https://github.com/stader-labs/stader-node/blob/main/abis/*.abi.json"
    click StaderBackend "https://github.com/stader-labs/stader-node/tree/main/stader-lib/contracts/"
    click EthNodes "https://github.com/stader-labs/stader-node/tree/main/docker/"
    click EthData "https://github.com/stader-labs/stader-node/tree/main/install/templates/"
    click Prometheus "https://github.com/stader-labs/stader-node/blob/main/install/templates/prometheus.tmpl"
    click Grafana "https://github.com/stader-labs/stader-node/blob/main/install/templates/grafana.tmpl"

    %% Classes
    classDef cli fill:#add8e6,stroke:#333,stroke-width:1px
    classDef svc fill:#90ee90,stroke:#333,stroke-width:1px
    classDef external fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef common fill:#d3d3d3,stroke:#333,stroke-width:1px
```
