Smart Contracts

High Level Architecture

1. VoteEscrow (VoteEscrow.sol):

   • Core Function: The foundation of the system. Users lock the primary governance/reward token (voteEscrowToken) for a chosen duration (up to 4 years).

   • Output: In return, users receive an NFT (veNFT) representing their lock. This NFT holds voting power that decays linearly over the lock's duration.

   • Features: Manages NFT minting, transfers, approvals, lock extensions, amount increases, merging of locks, and withdrawals (including conditional early unlocks potentially governed by the IncentivesManager). Calculates voting power at current or past times/blocks.

2. IncentivesManager (IncentivesManager.sol):

   • Core Function: Acts as the central treasury and time-release mechanism for the base reward token (rewardToken) emissions.

   • Process: Holds the total rewards allocated for a distribution period. Periodically (weekly), it calculates the amount to release, potentially adjusting for dilution based on the total veNFT supply (_ve.totalSupply()) relative to a configurable poolCap.

   • Interaction: Sends the calculated weekly reward amount to the Voter contract. Crucially, it interacts with VoteEscrowDistribution before sending rewards to ensure distributions are based on accurate snapshots.

3. VoteEscrowDistribution (VoteEscrowDistribution.sol):

   • Core Function: Works alongside VoteEscrow and IncentivesManager. It tracks the historical total supply of veNFT voting power and the distribution rate per week.

   • Purpose: Enables accurate calculation of rewards per veNFT holder based on historical data, even though the IncentivesManager sends rewards in bulk to the Voter. The IncentivesManager calls its checkpoint functions before distributing.

4. Voter (Voter.sol):

   • Core Function: The central hub for directing emissions and claiming bribes/fees.

   • Process: Receives weekly reward tokens from the IncentivesManager. veNFT holders interact with the Voter to allocate their voting power (vote function) towards different Gauge contracts. The Voter calculates the total weight for each gauge.

   • Distribution: Periodically (distribute function), the Voter pushes the accrued rewards out to the individual Gauge contracts based on their relative vote weight.

   • Bribe Interaction: When users vote, the Voter also deposits their calculated weight into the corresponding Bribe contract for that gauge. It provides functions (claimBribes, claimFees) for users to claim from these associated Bribe contracts.

5. Gauge (Gauge.sol):

   • Core Function: A staking contract for a specific asset (stake).

   • Reward Mechanism: Receives base reward tokens from the Voter (based on votes) and potentially other reward tokens via notifyRewardAmount. Users deposit their tokens (deposit) to earn these rewards.

   • Boosting: Implements a boost mechanism (derivedBalance) where a user's reward share is calculated based on both their staked token amount and the voting power of an associated veNFT they can link to their stake. This interaction (attaching/detaching the veNFT) is mediated via calls to the Voter.

   • Claiming: Users claim their accrued rewards using getReward.

6. Bribe (Bribe.sol):

   • Core Function: An external incentive mechanism associated with a specific Gauge.

   • Process: Third parties can deposit any ERC20 token (notifyRewardAmount) as a bribe to incentivize users to vote for the associated gauge. When users vote via the Voter, their voting weight is simultaneously recorded in the Bribe contract (_deposit).

   • Claiming: Users who voted for the gauge can claim their proportional share of the deposited bribe tokens (getReward).

7. Factories (VoteEscrowFactory, VoterFactory, GaugeFactory, BribeFactory, IncentivesManagerFactory, VoteEscrowDistributionFactory, BaseGaugeFactory, BaseBribeFactory, Factory):

   • Core Function: These contracts manage the deployment process. The Base*Factory contracts deploy the specific functional factories (GaugeFactory, BribeFactory). The top-level Factory contract orchestrates the deployment of a complete set of the core functional contracts (Voter, VoteEscrow, Gauge, Bribe, IncentivesManager, VoteEscrowDistribution) using the underlying factories, wires them together correctly, and can configure initial gauges/projects, often interacting with external registries (DappRegistry, ProjectRegistry).

In essence, the system creates a flywheel: locking tokens gives voting power, voting directs rewards to desired pools (gauges), staking in those pools earns rewards (boosted by voting power), and voting itself can be incentivized via bribes. The factories streamline the complex deployment and setup of this interconnected system.