# stader-labs/ethx architecture

> Architecture diagram of the GitHub repository stader-labs/ethx, 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/ethx
- Repository: https://github.com/stader-labs/ethx

## Overview

##### Project type and purpose
- This is a blockchain smart-contract system built with Solidity, managed by Hardhat and Foundry.
- Purpose: ETHx provides a multi-pool architecture (permissioned and permissionless pools) for Ethereum node operations, handling deposits, rewards, penalties, and withdrawals in a decentralized, upgradable manner.

##### File structure
- Top-level directories
- contracts: Solidity code organized into factory, interfaces, libraries
- scripts: TypeScript deployment, upgrade, verification, multisig helper scripts
- test: Foundry tests and mocks
- lib: external submodules (forge-std, OpenZeppelin upgrades)
- Config files
- hardhat.config.ts, foundry.toml for compilation and test frameworks
- .openzeppelin for proxy deployment data
- Dockerfile, .devcontainer for development environment
- CI/CD pipelines under .github/workflows for linting, testing, coverage, security

##### Key components from the README and code
- Core smart contracts (deployed on multiple networks):
- VaultFactory, Auction, ETHx (main token), OperatorRewardsCollector, Penalty
- PermissionedNodeRegistry & PermissionlessNodeRegistry
- PermissionedPool & PermissionlessPool
- PoolSelector, PoolUtils
- SD_Collateral, SD_UtilityPool, SD_IncentiveController, SD_RewardManager (for staked derivatives)
- Socializing pools, InsuranceFund, StaderOracle, StakePoolManager, UserWithdrawalManager, RewardVaults
- External integrations:
- Chainlink ETHx/ETH feed oracle
- Multisig Safe for upgrades (via safe-scripts)
- OpenZeppelin upgradeable proxy pattern

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% On-chain Modules
    subgraph "Core Protocol"
        direction TB
        VaultFactory["VaultFactory"]:::onchain
        PoolSelector["PoolSelector"]:::onchain
        PoolUtils["PoolUtils"]:::onchain
    end

    subgraph "Pools & Registries"
        direction TB
        PermissionedPool["PermissionedPool"]:::onchain
        PermissionlessPool["PermissionlessPool"]:::onchain
        PermissionedNodeRegistry["PermissionedNodeRegistry"]:::onchain
        PermissionlessNodeRegistry["PermissionlessNodeRegistry"]:::onchain
    end

    subgraph "Reward & Penalty"
        direction TB
        OperatorRewardsCollector["OperatorRewardsCollector"]:::onchain
        Penalty["Penalty"]:::onchain
        SD_RewardManager["SD_RewardManager"]:::onchain
        IncentiveController["SD_IncentiveController"]:::onchain
    end

    subgraph "Staking Derivatives"
        direction TB
        SD_Collateral["SD_Collateral"]:::onchain
        SD_UtilityPool["SD_UtilityPool"]:::onchain
    end

    subgraph "Oracle & External Services"
        direction TB
        StaderOracle["StaderOracle"]:::external
        Chainlink["Chainlink ETHx/ETH Feed"]:::external
    end

    subgraph "Governance & Upgrade"
        direction TB
        SafeMultisig["Gnosis Safe Multisig"]:::governance
        ProxyAdmin["OpenZeppelin ProxyAdmin"]:::governance
    end

    subgraph "Off-chain Scripts & CI"
        direction TB
        DeployScripts["Deployment & Upgrade Scripts"]:::offchain
        TestSuite["Foundry Tests"]:::offchain
        CI["CI/CD Pipelines"]:::offchain
    end

    User["User"]:::external

    %% Flows
    User -->|"deposit ETH"| VaultFactory
    VaultFactory -->|calls| PoolSelector
    PoolSelector -->|routes to| PermissionedPool
    PoolSelector -->|routes to| PermissionlessPool
    PermissionedPool -->|register| PermissionedNodeRegistry
    PermissionlessPool -->|register| PermissionlessNodeRegistry

    PermissionedPool -->|penalty events| Penalty
    PermissionlessPool -->|penalty events| Penalty

    OperatorRewardsCollector -->|collects rewards| SD_RewardManager
    SD_RewardManager -->|distribute via| IncentiveController

    SD_Collateral -->|backs| SD_UtilityPool
    SD_UtilityPool -->|incentives| IncentiveController
    StaderOracle -->|price feed| SD_UtilityPool
    Chainlink -->|feeds data| StaderOracle

    User -->|"withdraw request"| DeployScripts

    DeployScripts -->|invoke| UserWithdrawalManager["UserWithdrawalManager"]:::onchain
    UserWithdrawalManager -->|process withdrawal| PermissionedPool
    UserWithdrawalManager -->|process withdrawal| PermissionlessPool

    PermissionedPool -->|stake ops| StakePoolManager["StakePoolManager"]:::onchain
    PermissionlessPool -->|stake ops| StakePoolManager

    PoolSelector -->|util functions| PoolUtils

    SafeMultisig -->|submit tx| ProxyAdmin
    ProxyAdmin -->|upgrade impl| VaultFactory
    ProxyAdmin -->|upgrade impl| PoolSelector
    ProxyAdmin -->|upgrade impl| SD_UtilityPool
    ProxyAdmin -->|upgrade impl| SD_IncentiveController

    DeployScripts -->|deploy| VaultFactory
    DeployScripts -->|deploy| Auction["Auction"]:::onchain
    DeployScripts -->|deploy| ETHx["ETHx (Token)"]:::onchain
    DeployScripts -->|deploy| OperatorRewardsCollector
    DeployScripts -->|deploy| Penalty
    DeployScripts -->|deploy| PermissionedNodeRegistry
    DeployScripts -->|deploy| PermissionlessNodeRegistry
    DeployScripts -->|deploy| PermissionedPool
    DeployScripts -->|deploy| PermissionlessPool
    DeployScripts -->|deploy| PoolSelector
    DeployScripts -->|deploy| PoolUtils
    DeployScripts -->|deploy| SD_Collateral
    DeployScripts -->|deploy| SD_UtilityPool
    DeployScripts -->|deploy| IncentiveController
    DeployScripts -->|deploy| SD_RewardManager
    DeployScripts -->|deploy| SocializingPoolContract["SocializingPoolContract"]:::onchain
    DeployScripts -->|deploy| InsuranceFund["InsuranceFund"]:::onchain
    DeployScripts -->|deploy| StaderOracle
    DeployScripts -->|deploy| StakePoolManager
    DeployScripts -->|deploy| UserWithdrawalManager
    DeployScripts -->|deploy| RewardVaults["RewardVaults"]:::onchain

    TestSuite -->|tests| VaultFactory
    TestSuite -->|tests| PoolSelector
    CI -->|runs| TestSuite
    CI -->|coverage| VaultFactory

    %% Click Events
    click VaultFactory "https://github.com/stader-labs/ethx/blob/main/contracts/factory/VaultFactory.sol"
    click Auction "https://github.com/stader-labs/ethx/blob/main/contracts/factory/Auction.sol"
    click ETHx "https://github.com/stader-labs/ethx/blob/main/contracts/ETHx.sol"
    click OperatorRewardsCollector "https://github.com/stader-labs/ethx/blob/main/contracts/factory/OperatorRewardsCollector.sol"
    click Penalty "https://github.com/stader-labs/ethx/blob/main/contracts/factory/Penalty.sol"
    click PermissionedNodeRegistry "https://github.com/stader-labs/ethx/blob/main/contracts/factory/PermissionedNodeRegistry.sol"
    click PermissionlessNodeRegistry "https://github.com/stader-labs/ethx/blob/main/contracts/factory/PermissionlessNodeRegistry.sol"
    click PermissionedPool "https://github.com/stader-labs/ethx/blob/main/contracts/factory/PermissionedPool.sol"
    click PermissionlessPool "https://github.com/stader-labs/ethx/blob/main/contracts/factory/PermissionlessPool.sol"
    click PoolSelector "https://github.com/stader-labs/ethx/blob/main/contracts/factory/PoolSelector.sol"
    click PoolUtils "https://github.com/stader-labs/ethx/blob/main/contracts/library/PoolUtils.sol"
    click SD_Collateral "https://github.com/stader-labs/ethx/blob/main/contracts/interfaces/SDCollateral/SDCollateral.sol"
    click SD_UtilityPool "https://github.com/stader-labs/ethx/blob/main/contracts/factory/SDUtilityPool.sol"
    click IncentiveController "https://github.com/stader-labs/ethx/blob/main/contracts/factory/SDIncentiveController.sol"
    click SD_RewardManager "https://github.com/stader-labs/ethx/blob/main/contracts/factory/SDRewardManager.sol"
    click SocializingPoolContract "https://github.com/stader-labs/ethx/blob/main/contracts/factory/SocializingPoolContract.sol"
    click InsuranceFund "https://github.com/stader-labs/ethx/blob/main/contracts/factory/StaderInsuranceFund.sol"
    click StaderOracle "https://github.com/stader-labs/ethx/blob/main/contracts/factory/StaderOracle.sol"
    click StakePoolManager "https://github.com/stader-labs/ethx/blob/main/contracts/factory/StaderStakePoolManager.sol"
    click UserWithdrawalManager "https://github.com/stader-labs/ethx/blob/main/contracts/factory/UserWithdrawalManager.sol"
    click RewardVaults "https://github.com/stader-labs/ethx/blob/main/contracts/factory/RewardVaults.sol"
    click OpenZeppelin "https://github.com/stader-labs/ethx/tree/main/lib/openzeppelin-foundry-upgrades"
    click ForgeStd "https://github.com/stader-labs/ethx/tree/main/lib/forge-std"
    click SafeMultisig "https://github.com/stader-labs/ethx/tree/main/scripts/safe-scripts/helpers"
    click DeployScripts "https://github.com/stader-labs/ethx/tree/main/scripts/deploy"
    click TestSuite "https://github.com/stader-labs/ethx/tree/main/test"
    click CI "https://github.com/stader-labs/ethx/tree/main/ .github/workflows"

    %% Styles
    classDef onchain fill:#D0E6FF,stroke:#1E70BF,stroke-width:1.5px
    classDef offchain fill:#DFFFE0,stroke:#2E8B00,stroke-width:1.5px
    classDef external fill:#FFE6B0,stroke:#B35E00,stroke-width:1.5px
    classDef governance fill:#E5D0FF,stroke:#7350BF,stroke-width:1.5px
```
