ARCHITECTURE
Five-Layer Architecture
Flywheel Protocol is organized into five modular layers. Each layer has a single responsibility, a well-defined interface, and can be deployed, upgraded, or replaced independently. This architecture is blockchain-agnostic and token-agnostic — it works with any ERC-20 tokens, any EVM chain, and any revenue source.
L1Revenue Sources
The entry point for value. Revenue Sources capture on-chain value from any protocol activity — trading fees, creator royalties, yield from external protocols, or custom revenue streams.
Supported Sources
- • DEX swap fees
- • Creator / protocol royalties
- • Lending protocol yield
- • NFT marketplace fees
- • Custom revenue contracts
Interface
function collectRevenue(address token, uint256 amount) external;
Key Properties
Revenue Sources are passive collectors. They do not initiate conversions or make routing decisions. Their sole responsibility is to receive and forward value to the Collection Layer. This separation keeps revenue capture simple and auditable.
L2Collection Layer
Aggregates revenue from all L1 sources into a unified treasury. The Collection Layer normalizes multi-token revenue streams and prepares them for conversion. This is where the protocol decides when to route — not where.
Responsibilities
- • Aggregate revenue from all L1 sources
- • Track cumulative revenue per token
- • Trigger routing based on configurable thresholds
- • Gas-optimized batching of conversions
Interface
function depositRevenue(address token, uint256 amount) external;
function triggerRoute() external returns (uint256);
Routing Triggers
Conversions can be triggered by time (every N hours), by volume (every X tokens collected), or manually by a keeper. The trigger strategy is configurable per deployment and can be optimized for gas efficiency versus frequency.
L3Conversion Router
The engine of the protocol. The Conversion Router takes collected revenue tokens and swaps them for the reward asset through a DEX aggregator. Every conversion is validated by Chainlink oracles — if the effective price deviates beyond the configured slippage tolerance, the transaction reverts.
Conversion Flow
Interface
function convertRewards(
address revenueToken,
uint256 amount,
bytes calldata swapData
) external returns (uint256 rewardTokensOut);
Price Protection
Before executing the swap, the router queries the latest Chainlink round data. After the swap, it compares the effective exchange rate against the oracle price. If the deviation exceeds maxSlippageBPS, the entire transaction reverts. This prevents sandwich attacks and DEX manipulation.
L4Reward Accounting
Tracks per-second reward accrual for every depositor. Uses a gas-efficient checkpoint system — rewards are computed on-demand rather than updated every block. Each depositor earns proportionally to their share of the total deposited pool.
Accrual Formula
pendingRewards[user] = userShare × rewardPerToken - checkpoint[user]
Where rewardPerToken accumulates every time new rewards are deposited and userShareis the depositor's proportion of total active deposits.
Interface
function pendingRewards(address user) external view returns (uint256);
function deposit(address token, uint256 amount) external;
function requestWithdrawal(uint256 amount) external;
function claimRewards() external returns (uint256);
Key Properties
- • Per-second precision — no epoch boundaries
- • Gas-efficient checkpoint math — O(1) per user update
- • Proportional distribution — your share = your deposits / total
- • Activation delay — deposits must wait configurable N hours before earning
L5Settlement Vault
The final layer. Holds converted reward assets and processes claims, withdrawals, and penalties. The Settlement Vault is the user-facing layer — this is where depositors interact to claim rewards or exit their positions.
Responsibilities
- • Receive reward tokens from Conversion Router
- • Process user reward claims
- • Handle deposit withdrawals with cooldown periods
- • Enforce early withdrawal penalties
- • Support LP staking for bonus rewards
Penalty Model
Depositors who withdraw before the minimum deposit duration incur a configurable burn penalty (default: 5%). The penalty amount is permanently removed from supply, benefiting remaining depositors through increased proportional share. After the minimum duration, withdrawals are penalty-free.
Cooldown Period
Withdrawals require a configurable cooldown period (default: 48 hours) between requesting and completing the withdrawal. This prevents front-running and ensures fair reward distribution at the time of exit.