# euler-xyz/reward-streams architecture

> Architecture diagram of the GitHub repository euler-xyz/reward-streams, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/euler-xyz/reward-streams
- Repository: https://github.com/euler-xyz/reward-streams

## Overview

##### Project Type & Purpose
- This isn’t a conventional full-stack web application but rather a smart contract library for on-chain reward distribution. Its goal is to enable efficient, proportional reward distribution for staking and balance tracking in Ethereum tokens.
- The README highlights two primary modes (staking and tracking rewards), and the file tree shows a clear separation of source contracts, interface definitions, testing infrastructure (both unit and invariant tests using Echidna), and external dependency libraries (e.g., OpenZeppelin, Forge-std).

##### Main Components
a. Core Contracts:
- BaseRewardStreams.sol – The base contract shared by both distribution modes.
- StakingRewardStreams.sol – Implements staking logic with stake/unstake functions.
- TrackingRewardStreams.sol – Implements balance-tracking reward logic via balanceTrackerHook.
- Interfaces (IBalanceTracker.sol and IRewardStreams.sol) – Define expected interaction points.

b. External Dependencies & Libraries:
- Libraries imported from “lib” (e.g., openzeppelin-contracts) that extend functionality and provide security primitives.
- External verification tools such as the Certora configurations, demonstrating formal analysis aspects.

c. Testing Infrastructure:
- Unit tests in the “test” directory.
- Invariant tests (using Echidna) under the “test/invariants” folder.
- Scripts for running tests and coverage (e.g., foundry.toml, test/scripts/echidna.sh).

d. Deployment/CI Components:
- GitHub workflows in the “.github/workflows” directory (like test.yml).
- Build and configuration files (e.g., foundry.toml, package.json).

##### Relationships and Interactions
- That the BaseRewardStreams contract is inherited by both the Staking and Tracking implementations.
- That external ERC20 tokens (both rewarded and reward tokens) interact with these contracts through:
- Methods for staking/unstaking,
- BalanceTracker hooks during transfers,
- Incentivization functions (enableReward/disableReward).
- Demonstrate how rewards accumulate over epochs, with interactions between multiple reward streams (including overlapping epochs).
- Testing and verification processes (unit tests, invariant testing using Echidna, and Certora proofs) which validate core logic.

##### Architectural Patterns and Design Principles
- Inheritance – The use of a common BaseRewardStreams for shared functionality.
- Permissionless interactions – No admin or owner controls exist for the distributor contracts.
- Modular design – Separation between staking and balance-tracking functionality.
- Iterative, epoch-based reward calculation – Represent the cycle that runs on each epoch to update reward distributions.
- Safety and gas optimization considerations (e.g., the use of parameters like forfeitRecentReward to optimize storage updates).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Smart Contracts
    subgraph "Smart Contracts"
        BR["BaseRewardStreams Contract"]:::contract
        SR["StakingRewardStreams Contract"]:::contract
        TR["TrackingRewardStreams Contract"]:::contract
    end

    %% Interfaces
    subgraph "Interfaces"
        IBT["IBalanceTracker Interface"]:::contract
        IRS["IRewardStreams Interface"]:::contract
    end

    %% External Dependencies & Libraries
    subgraph "External Dependencies"
        OZ["OpenZeppelin Contracts"]:::library
        FS["Forge-Std Library"]:::library
        EVC["Ethereum Vault Connector"]:::library
    end

    %% Testing Infrastructure
    subgraph "Testing Infrastructure"
        UT["Unit Tests"]:::testing
        IT["Invariant Tests (Echidna)"]:::testing
        TS["Testing Scripts"]:::testing
    end

    %% Deployment/CI Components
    subgraph "Deployment/CI"
        GW["GitHub Workflows"]:::ci
        FC["Foundry Configuration"]:::ci
        PC["Package Configuration"]:::ci
    end

    %% Verification & Formal Analysis
    subgraph "Verification & Formal Analysis"
        CERT["Certora Formal Verification"]:::verification
    end

    %% External Entities
    subgraph "External Entities"
        USER["User"]:::external
        TOKEN["ERC20 Token Contract"]:::external
    end

    %% Inheritance Relationships among Smart Contracts
    BR -->|"inherits"| SR
    BR -->|"inherits"| TR

    %% Contract Imports & Interface Usage
    SR -->|"imports"| OZ
    SR -->|"imports"| FS
    SR -->|"imports"| EVC
    TR -->|"imports"| OZ
    TR -->|"imports"| FS
    TR -->|"imports"| EVC

    SR -->|"uses"| IRS
    TR -->|"uses"| IBT
    TR -->|"uses"| IRS

    %% External Interactions
    USER -->|"stake_call"| SR
    USER -->|"balance_hook"| TR
    SR -->|"token_transfer"| TOKEN
    TR -->|"hook_call"| TOKEN

    %% Testing Interactions
    UT -->|"verifies"| BR
    UT -->|"verifies"| SR
    UT -->|"verifies"| TR
    IT -->|"verifies"| BR
    IT -->|"verifies"| SR
    IT -->|"verifies"| TR
    TS -->|"runs"| UT

    %% CI Components triggering tests
    GW -->|"triggers"| UT
    FC -->|"configures"| UT
    PC -->|"configures"| UT

    %% Formal Verification
    CERT -->|"verifies"| SR

    %% Click Events for Core Contracts
    click BR "https://github.com/euler-xyz/reward-streams/blob/master/src/BaseRewardStreams.sol"
    click SR "https://github.com/euler-xyz/reward-streams/blob/master/src/StakingRewardStreams.sol"
    click TR "https://github.com/euler-xyz/reward-streams/blob/master/src/TrackingRewardStreams.sol"

    %% Click Events for Interfaces
    click IBT "https://github.com/euler-xyz/reward-streams/blob/master/src/interfaces/IBalanceTracker.sol"
    click IRS "https://github.com/euler-xyz/reward-streams/blob/master/src/interfaces/IRewardStreams.sol"

    %% Click Events for External Dependencies
    click OZ "https://github.com/euler-xyz/reward-streams/tree/master/lib/openzeppelin-contracts"
    click FS "https://github.com/euler-xyz/reward-streams/tree/master/lib/forge-std"
    click EVC "https://github.com/euler-xyz/reward-streams/tree/master/lib/ethereum-vault-connector"

    %% Click Events for Testing Infrastructure
    click UT "https://github.com/euler-xyz/reward-streams/tree/master/test/unit"
    click IT "https://github.com/euler-xyz/reward-streams/tree/master/test/invariants"
    click TS "https://github.com/euler-xyz/reward-streams/blob/master/test/scripts/echidna.sh"

    %% Click Events for Deployment/CI Components
    click GW "https://github.com/euler-xyz/reward-streams/blob/master/.github/workflows/test.yml"
    click FC "https://github.com/euler-xyz/reward-streams/blob/master/foundry.toml"
    click PC "https://github.com/euler-xyz/reward-streams/blob/master/package.json"

    %% Click Event for Certora Verification
    click CERT "https://github.com/euler-xyz/reward-streams/blob/master/certora/conf/StakingRewardStream.conf"

    %% Class Definitions for Styling
    classDef contract fill:#a3d2f2,stroke:#1a73e8,stroke-width:2px;
    classDef library fill:#f9f6a7,stroke:#e8b71a,stroke-width:2px;
    classDef testing fill:#c8f7c5,stroke:#34a853,stroke-width:2px;
    classDef ci fill:#fbcfcf,stroke:#ea4335,stroke-width:2px;
    classDef verification fill:#ffebb2,stroke:#fbbc04,stroke-width:2px;
    classDef external fill:#ffd9ec,stroke:#d93025,stroke-width:2px;
```
