mirror of
https://github.com/vacp2p/staking-reward-streamer.git
synced 2026-01-05 03:04:03 -05:00
1f9e9f678c
* MPMaximum Latex syntax fix * Update T_RATE to reflect block time on SN Sepolia * Pending Latex syntax fix * Global Reward Latex syntax fix * NewIndex Latex syntax fix * reward example value typo fix * format MathSpec table * explicitly state T_RATE is chain dependent value
Staking Protocol 
🧭 Overview
The Staking Reward Streamer Protocol enables secure token staking with dynamic reward calculation on Ethereum. Built with modularity and upgradability in mind, the system includes core components to manage stake deposits, reward calculations, time-based locking, and contract migration through user consent.
🧩 Core Contracts
🛠️ StakeManager
- Handles staking logic, tracks stakes and reward epochs.
- Calculates APY via Multiplier Points, which increase over time.
- Validates vaults using codehash verification for added safety.
- Upgradeable via proxy; users can opt out of migrations.
🔐 StakeVault
- A vault owned by the user, used to store and manage staked tokens.
- Interacts directly with
StakeManagerfor staking and unstaking operations. - Ensures only the owner can execute critical actions.
- Verifies contract code via codehash to ensure safety.
✨ Features
- Secure, user-owned staking vaults
- Dynamic APY via Multiplier Points
- Stake locking to boost rewards
- ERC20-compatible (via OpenZeppelin)
- Proxy upgradeability with opt-in/opt-out support
- Epoch-based reward streaming
🚀 Getting Started
📦 Install Dependencies
pnpm install
⚙️ Usage
📄 Deployment Flow
- Deploy
StakeManager - Deploy a sample
StakeVault(e.g., on a devnet or testnet) - Configure codehash in
StakeManager:
stakeManager.setTrustedCodehash(<vault_codehash>, true);
💰 Staking
- Approve the
StakeVaultto spend your tokens:
erc20.approve(stakeVaultAddress, amount);
- Stake your tokens:
stakeVault.stake(amount, secondsToLock);
⚠️ Do not transfer tokens directly to the
StakeVault. Always useapprove+stake.
Minimum stake amount and lock duration are enforced via contract settings. Epochs are automatically processed on stake actions.
🔓 Unstaking
stakeVault.unstake(amount);
- Only available for unlocked balances.
- Reduces stake proportionally based on amount and duration.
🔁 Migration (Opt-In/Out)
Users may opt-in to a new StakeManager implementation or leave:
stakeVault.acceptMigration(); // opt-in
stakeVault.leave(); // opt-out
Migration triggers automatic reward claiming. Locked balances can still opt out.
📬 Deployed Contracts
These are the official contract deployments on the Sepolia testnet (via Status Network Explorer):
| Contract | Address |
|---|---|
| StakeManagerProxy | 0x2C09141e66970A71862beAcCbDb816ec01D6B676 |
| StakeManager | 0xa2432fB545829f89E172ddE2DeD6D289c7ee125F |
| VaultFactory | 0xA6300Bd8aF26530D399a1b24B703EEf2c48a71Be |
| KarmaProxy | 0x486Ac0F5Eb7079075dE26739E1192D41F278a8db |
| Karma | 0xE9413C84eFF6B08E4F614Efe69EB7eb9a1Ca1180 |
| KarmaNFT | 0xdE5592e1001f52380f9EDE01aa6725F469A8e46F |
🧪 Development
🏗️ Build Contracts
forge build
🧹 Clean Build Artifacts
forge clean
🧪 Run Tests
forge test
🧮 Coverage
forge coverage
🚀 Deploy Locally (Anvil)
forge script script/Deploy.s.sol --broadcast --fork-url http://localhost:8545
Requires
MNEMONICenv variable.
📊 Gas & Linting
Gas Reports
pnpm gas-report
forge snapshot
Linting
pnpm lint
Formatting
forge fmt
Commit preparing command
pnpm adorno