How euler-xyz/reward-streams works
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).