# ssvlabs/ssv-network architecture

> Architecture diagram of the GitHub repository ssvlabs/ssv-network, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ssvlabs/ssv-network
- Repository: https://github.com/ssvlabs/ssv-network

## Overview

This repository implements the SSV Network v2.0.0 Solidity protocol. The principal user workflow is interaction with the network proxy to manage operator-backed clusters and validators; the protocol also supports ETH-based cluster accounting, effective-balance updates, SSV staking, and one-way migration of legacy SSV clusters. The README identifies the modular contract layout and capabilities, but no Solidity source excerpts were provided, so internal dispatch and call relationships are not asserted beyond that documentation.

Main entry points: [`contracts/SSVNetwork.sol`](https://github.com/ssvlabs/ssv-network/blob/main/contracts/SSVNetwork.sol) (Network core), [`contracts/modules/SSVClusters.sol`](https://github.com/ssvlabs/ssv-network/blob/main/contracts/modules/SSVClusters.sol) (Cluster accounting), [`contracts/modules/SSVValidators.sol`](https://github.com/ssvlabs/ssv-network/blob/main/contracts/modules/SSVValidators.sol) (Validator management), [`contracts/SSVProxy.sol`](https://github.com/ssvlabs/ssv-network/blob/main/contracts/SSVProxy.sol) (Network proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Network entry"]
  node_network_proxy["Network proxy<br/>[SSVProxy.sol]"]
  node_network_core["Network core<br/>[SSVNetwork.sol]"]
  node_network_views["Network views"]
end

subgraph group_protocol["Protocol modules"]
  node_cluster_logic["Cluster accounting<br/>[SSVClusters.sol]"]
  node_validator_logic["Validator management<br/>[SSVValidators.sol]"]
  node_operator_logic["Operator management<br/>[SSVOperators.sol]"]
  node_whitelist_logic["Operator whitelisting"]
  node_dao_logic["DAO governance<br/>[SSVDAO.sol]"]
  node_views_logic["Read views<br/>[SSVViews.sol]"]
end

subgraph group_assets["Staking and assets"]
  node_staking_logic["SSV staking<br/>[SSVStaking.sol]"]
  node_cssv_token["cSSV token<br/>[CSSVToken.sol]"]
  node_ssv_token["SSV token<br/>[SSVToken.sol]"]
  node_whitelisting_contract["Basic whitelist"]
end

subgraph group_internals["Shared internals"]
  node_protocol_storage[("Protocol storage<br/>[SSVStorage.sol]")]
  node_core_library["Core library<br/>[CoreLib.sol]"]
  node_cluster_library["Cluster library<br/>[ClusterLib.sol]"]
  node_validator_library["Validator library<br/>[ValidatorLib.sol]"]
end

node_cluster_owner(("Cluster owner"))

node_cluster_owner -->|"calls"| node_network_proxy
node_network_proxy -->|"routes through"| node_network_core
node_network_core -->|"modular logic"| node_cluster_logic
node_network_core -->|"modular logic"| node_validator_logic
node_network_core -->|"modular logic"| node_operator_logic
node_network_core -->|"modular logic"| node_whitelist_logic
node_network_core -->|"modular logic"| node_dao_logic
node_network_core -->|"modular logic"| node_views_logic
node_network_core -->|"modular logic"| node_staking_logic
node_cluster_owner -->|"manages clusters"| node_cluster_logic
node_cluster_owner -->|"manages validators"| node_validator_logic
node_staking_logic -->|"uses staking token"| node_cssv_token
node_cluster_logic -.->|"supports accounting"| node_cluster_library
node_validator_logic -.->|"supports validation"| node_validator_library

click node_network_proxy "https://github.com/ssvlabs/ssv-network/blob/main/contracts/SSVProxy.sol"
click node_network_core "https://github.com/ssvlabs/ssv-network/blob/main/contracts/SSVNetwork.sol"
click node_cluster_logic "https://github.com/ssvlabs/ssv-network/blob/main/contracts/modules/SSVClusters.sol"
click node_validator_logic "https://github.com/ssvlabs/ssv-network/blob/main/contracts/modules/SSVValidators.sol"
click node_operator_logic "https://github.com/ssvlabs/ssv-network/blob/main/contracts/modules/SSVOperators.sol"
click node_whitelist_logic "https://github.com/ssvlabs/ssv-network/blob/main/contracts/modules/SSVOperatorsWhitelist.sol"
click node_dao_logic "https://github.com/ssvlabs/ssv-network/blob/main/contracts/modules/SSVDAO.sol"
click node_views_logic "https://github.com/ssvlabs/ssv-network/blob/main/contracts/modules/SSVViews.sol"
click node_staking_logic "https://github.com/ssvlabs/ssv-network/blob/main/contracts/modules/SSVStaking.sol"
click node_cssv_token "https://github.com/ssvlabs/ssv-network/blob/main/contracts/token/CSSVToken.sol"
click node_ssv_token "https://github.com/ssvlabs/ssv-network/blob/main/contracts/token/SSVToken.sol"
click node_whitelisting_contract "https://github.com/ssvlabs/ssv-network/blob/main/contracts/whitelisting/BasicWhitelisting.sol"
click node_network_views "https://github.com/ssvlabs/ssv-network/blob/main/contracts/SSVNetworkViews.sol"
click node_protocol_storage "https://github.com/ssvlabs/ssv-network/blob/main/contracts/libraries/storage/SSVStorage.sol"
click node_core_library "https://github.com/ssvlabs/ssv-network/blob/main/contracts/libraries/CoreLib.sol"
click node_cluster_library "https://github.com/ssvlabs/ssv-network/blob/main/contracts/libraries/ClusterLib.sol"
click node_validator_library "https://github.com/ssvlabs/ssv-network/blob/main/contracts/libraries/ValidatorLib.sol"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_network_proxy,node_network_core,node_network_views toneBlue
class node_cluster_logic,node_validator_logic,node_operator_logic,node_whitelist_logic,node_dao_logic,node_views_logic toneAmber
class node_staking_logic,node_cssv_token,node_ssv_token,node_whitelisting_contract toneMint
class node_protocol_storage,node_core_library,node_cluster_library,node_validator_library toneRose
class node_cluster_owner toneIndigo
```

## Components

### Network entry

- [Network proxy](https://github.com/ssvlabs/ssv-network/blob/main/contracts/SSVProxy.sol): `contracts/SSVProxy.sol`
- [Network core](https://github.com/ssvlabs/ssv-network/blob/main/contracts/SSVNetwork.sol): `contracts/SSVNetwork.sol`
- [Network views](https://github.com/ssvlabs/ssv-network/blob/main/contracts/SSVNetworkViews.sol): `contracts/SSVNetworkViews.sol`

### Protocol modules

- [Cluster accounting](https://github.com/ssvlabs/ssv-network/blob/main/contracts/modules/SSVClusters.sol): `contracts/modules/SSVClusters.sol`
- [Validator management](https://github.com/ssvlabs/ssv-network/blob/main/contracts/modules/SSVValidators.sol): `contracts/modules/SSVValidators.sol`
- [Operator management](https://github.com/ssvlabs/ssv-network/blob/main/contracts/modules/SSVOperators.sol): `contracts/modules/SSVOperators.sol`
- [Operator whitelisting](https://github.com/ssvlabs/ssv-network/blob/main/contracts/modules/SSVOperatorsWhitelist.sol): `contracts/modules/SSVOperatorsWhitelist.sol`
- [DAO governance](https://github.com/ssvlabs/ssv-network/blob/main/contracts/modules/SSVDAO.sol): `contracts/modules/SSVDAO.sol`
- [Read views](https://github.com/ssvlabs/ssv-network/blob/main/contracts/modules/SSVViews.sol): `contracts/modules/SSVViews.sol`

### Staking and assets

- [SSV staking](https://github.com/ssvlabs/ssv-network/blob/main/contracts/modules/SSVStaking.sol): `contracts/modules/SSVStaking.sol`
- [cSSV token](https://github.com/ssvlabs/ssv-network/blob/main/contracts/token/CSSVToken.sol): `contracts/token/CSSVToken.sol`
- [SSV token](https://github.com/ssvlabs/ssv-network/blob/main/contracts/token/SSVToken.sol): `contracts/token/SSVToken.sol`
- [Basic whitelist](https://github.com/ssvlabs/ssv-network/blob/main/contracts/whitelisting/BasicWhitelisting.sol): `contracts/whitelisting/BasicWhitelisting.sol`

### Shared internals

- [Protocol storage](https://github.com/ssvlabs/ssv-network/blob/main/contracts/libraries/storage/SSVStorage.sol): `contracts/libraries/storage/SSVStorage.sol`
- [Core library](https://github.com/ssvlabs/ssv-network/blob/main/contracts/libraries/CoreLib.sol): `contracts/libraries/CoreLib.sol`
- [Cluster library](https://github.com/ssvlabs/ssv-network/blob/main/contracts/libraries/ClusterLib.sol): `contracts/libraries/ClusterLib.sol`
- [Validator library](https://github.com/ssvlabs/ssv-network/blob/main/contracts/libraries/ValidatorLib.sol): `contracts/libraries/ValidatorLib.sol`

### Other components

- **Cluster owner**

## Connections

- Cluster owner → Network proxy: calls (evidence: `README.md`)
- Network proxy → Network core: routes through (evidence: `README.md`)
- Network core → Cluster accounting: modular logic (evidence: `README.md`)
- Network core → Validator management: modular logic (evidence: `README.md`)
- Network core → Operator management: modular logic (evidence: `README.md`)
- Network core → Operator whitelisting: modular logic (evidence: `README.md`)
- Network core → DAO governance: modular logic (evidence: `README.md`)
- Network core → Read views: modular logic (evidence: `README.md`)
- Network core → SSV staking: modular logic (evidence: `README.md`)
- Cluster owner → Cluster accounting: manages clusters (evidence: `README.md`)
- Cluster owner → Validator management: manages validators (evidence: `README.md`)
- SSV staking → cSSV token: uses staking token (evidence: `README.md`)
- Cluster accounting → Cluster library: supports accounting
- Validator management → Validator library: supports validation
