# symbioticfi/rewards architecture

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

- Interactive diagram: https://gitdiagram.com/symbioticfi/rewards
- Repository: https://github.com/symbioticfi/rewards

## Overview

##### Main components
- On-Chain Core Modules:
- Reward Interfaces (src/interfaces/…)
- Default Implementations (src/contracts/defaultOperatorRewards, src/contracts/defaultStakerRewards)
- Core Symbiotic Protocol contracts (lib/core)
- External Libraries (lib/openzeppelin-contracts, lib/openzeppelin-contracts-upgradeable, lib/forge-std)
- Off-Chain Tooling:
- CLI Data Generators (cli/defaultOperatorRewards/*.js with distribution.json, trees.json, proofs, roots)
- Deployment Scripts (script/deploy, script/deploy/genesis)
- Tests & Mocks (test/…, test/integration, test/mocks)
- Build & CI:
- Foundry toolchain (foundry.toml, forge build/test/fmt/snapshot)
- GitHub Actions workflows (.github/workflows/lint.yml, test.yml)
- External Services:
- Ethereum RPC providers (ETH_RPC_URL, ETH_RPC_URL_HOLESKY)
- Etherscan API (ETHERSCAN_API_KEY)
- Documentation & Audit Links

##### Relationships and data flows
- Off-Chain → On-Chain:
- CLI scripts read distribution.json → generate Merkle trees, proofs, roots → these roots are passed as constructor/initializer params to reward contracts during deployment.
- Deployment scripts use RPC endpoint & forge to deploy reward modules.
- On-Chain:
- Reward contracts implement standard interfaces → interact with Core Symbiotic modules.
- Contracts rely on OpenZeppelin libraries for security (upgradeability, access control).
- Build & CI:
- GitHub Actions trigger forge build/test/lint → publish artifacts to out/ → ensure contracts pass audits and tests.
- External Services:
- Etherscan API used for contract verification after deployment.
- RPC endpoints serve as the blockchain node for deploy & tests.

##### Architectural patterns and design principles
- Modular Smart-Contract Design:
- Separation of Interface vs Implementation.
- Pluggable default modules (OperatorRewards, StakerRewards).
- Merkle-Tree Off-Chain Computation:
- Precompute reward distribution off-chain for gas efficiency.
- Standardized Build/Test Pipeline:
- Foundry for local development, CI for automated checks.
- Declarative Configuration:
- .env for environment-specific endpoints and keys.
- Documentation & Auditing:
- Specs/ folder for design docs; audits/ for security reviews.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: Off-Chain Tooling
    subgraph "Layer 1: Off-Chain Tooling"
        direction TB
        subgraph "CLI Data Generators" 
            direction TB
            D1["distribution.json.example"]:::offchain
            D2["trees.json.example"]:::offchain
            S1["distributionToProofs.js"]:::offchain
            S2["distributionToRoots.js"]:::offchain
            S3["distributionToTrees.js"]:::offchain
            S4["treesToDistribution.js"]:::offchain
            S5["treesToProofs.js"]:::offchain
            S6["treesToRoots.js"]:::offchain
        end
        subgraph "Deployment Scripts"
            direction TB
            DS1["script/deploy"]:::offchain
            DS2["script/deploy/genesis"]:::offchain
        end
        subgraph "Tests & Mocks"
            direction TB
            T1["test/defaultOperatorRewards"]:::offchain
            T2["test/defaultStakerRewards"]:::offchain
            T3["test/stakerRewards"]:::offchain
            T4["test/integration"]:::offchain
            T5["test/mocks"]:::offchain
        end
    end

    %% Layer 2: Build & CI
    subgraph "Layer 2: Build & CI"
        direction TB
        B1["foundry.toml"]:::ci
        B2["remappings.txt"]:::ci
        B3["package.json"]:::ci
        B4["out/"]:::ci
        subgraph "GitHub Actions"
            direction TB
            CI1[".github/workflows/lint.yml"]:::ci
            CI2[".github/workflows/test.yml"]:::ci
        end
    end

    %% Layer 3: On-Chain Contracts
    subgraph "Layer 3: On-Chain Contracts"
        direction TB
        subgraph "Interfaces"
            direction TB
            I1["src/interfaces/defaultOperatorRewards"]:::onchain
            I2["src/interfaces/defaultStakerRewards"]:::onchain
            I3["src/interfaces/stakerRewards"]:::onchain
        end
        subgraph "Default Implementations"
            direction TB
            C1["src/contracts/defaultOperatorRewards"]:::onchain
            C2["src/contracts/defaultStakerRewards"]:::onchain
        end
        subgraph "Core Symbiotic Protocol"
            direction TB
            Core["lib/core"]:::onchain
        end
        subgraph "Libraries"
            direction TB
            L1["lib/openzeppelin-contracts"]:::onchain
            L2["lib/openzeppelin-contracts-upgradeable"]:::onchain
            L3["lib/forge-std"]:::onchain
        end
    end

    %% Layer 4: External Services
    subgraph "Layer 4: External Services"
        direction TB
        E1["Ethereum RPC"]:::external
        E2["Etherscan API"]:::external
    end

    %% Data Flow Arrows
    D1 -->|reads| S1
    D1 -->|reads| S2
    D1 -->|reads| S3
    D2 -->|reads| S4
    D2 -->|reads| S5
    D2 -->|reads| S6

    S1 -->|outputs proofs| DS1
    S2 -->|outputs roots| DS1
    S3 -->|outputs trees| DS1
    S4 -->|outputs distribution| DS1
    S5 -->|outputs proofs| DS1
    S6 -->|outputs roots| DS1

    DS1 -->|deploys| C1
    DS1 -->|deploys| C2
    DS2 -->|genesis deploy| Core

    CI1 -->|runs lint| B1
    CI1 -->|runs lint| B3
    CI2 -->|runs tests| B4
    CI2 -->|runs tests| C1
    CI2 -->|runs tests| C2

    C1 -->|implements| I1
    C2 -->|implements| I2
    C1 -->|uses| Core
    C2 -->|uses| Core
    Core -->|imports| L1
    Core -->|imports| L2
    Core -->|imports| L3

    DS1 -->|uses RPC| E1
    DS1 -->|verifies| E2
    CI2 -->|publishes artifacts| B4

    %% Click Events
    click I1 "https://github.com/symbioticfi/rewards/tree/main/src/interfaces/defaultOperatorRewards"
    click I2 "https://github.com/symbioticfi/rewards/tree/main/src/interfaces/defaultStakerRewards"
    click I3 "https://github.com/symbioticfi/rewards/tree/main/src/interfaces/stakerRewards"
    click C1 "https://github.com/symbioticfi/rewards/tree/main/src/contracts/defaultOperatorRewards"
    click C2 "https://github.com/symbioticfi/rewards/tree/main/src/contracts/defaultStakerRewards"
    click Core "https://github.com/symbioticfi/rewards/tree/main/lib/core"
    click L1 "https://github.com/symbioticfi/rewards/tree/main/lib/openzeppelin-contracts"
    click L2 "https://github.com/symbioticfi/rewards/tree/main/lib/openzeppelin-contracts-upgradeable"
    click L3 "https://github.com/symbioticfi/rewards/tree/main/lib/forge-std"
    click S1 "https://github.com/symbioticfi/rewards/blob/main/cli/defaultOperatorRewards/distributionToProofs.js"
    click S2 "https://github.com/symbioticfi/rewards/blob/main/cli/defaultOperatorRewards/distributionToRoots.js"
    click S3 "https://github.com/symbioticfi/rewards/blob/main/cli/defaultOperatorRewards/distributionToTrees.js"
    click S4 "https://github.com/symbioticfi/rewards/blob/main/cli/defaultOperatorRewards/treesToDistribution.js"
    click S5 "https://github.com/symbioticfi/rewards/blob/main/cli/defaultOperatorRewards/treesToProofs.js"
    click S6 "https://github.com/symbioticfi/rewards/blob/main/cli/defaultOperatorRewards/treesToRoots.js"
    click D1 "https://github.com/symbioticfi/rewards/blob/main/cli/defaultOperatorRewards/data/distribution.json.example"
    click D2 "https://github.com/symbioticfi/rewards/blob/main/cli/defaultOperatorRewards/data/trees.json.example"
    click DS1 "https://github.com/symbioticfi/rewards/tree/main/script/deploy"
    click DS2 "https://github.com/symbioticfi/rewards/tree/main/script/deploy/genesis"
    click T1 "https://github.com/symbioticfi/rewards/tree/main/test/defaultOperatorRewards"
    click T2 "https://github.com/symbioticfi/rewards/tree/main/test/defaultStakerRewards"
    click T3 "https://github.com/symbioticfi/rewards/tree/main/test/stakerRewards"
    click T4 "https://github.com/symbioticfi/rewards/tree/main/test/integration"
    click T5 "https://github.com/symbioticfi/rewards/tree/main/test/mocks"
    click B1 "https://github.com/symbioticfi/rewards/blob/main/foundry.toml"
    click B2 "https://github.com/symbioticfi/rewards/blob/main/remappings.txt"
    click B3 "https://github.com/symbioticfi/rewards/blob/main/package.json"
    click B4 "https://github.com/symbioticfi/rewards/tree/main/out/"
    click CI1 "https://github.com/symbioticfi/rewards/blob/main/.github/workflows/lint.yml"
    click CI2 "https://github.com/symbioticfi/rewards/blob/main/.github/workflows/test.yml"

    %% Styles
    classDef onchain fill:#D6E4FF,stroke:#003366,color:#003366;
    classDef offchain fill:#D0F4DE,stroke:#145214,color:#145214;
    classDef ci fill:#FFE4B3,stroke:#996600,color:#996600;
    classDef external fill:#E2E2E2,stroke:#666666,color:#333333;
```
