EmissionManagerV1

Overview

EmissionManagerV1 is a smart contract designed to manage and distribute weekly token emissions of the EYWA token. The contract determines how tokens are allocated among different reward categories—such as rebase rewards, gauge rewards, bond rewards, grants, and incentives—based on a weekly emission schedule. It also includes logic for dynamic emission adjustments depending on the amount of tokens locked in the associated escrow contracts.

The contract leverages the following key concepts and components:

  • Epoch-based Emissions: Emissions occur in discrete weekly epochs. Each epoch distributes a predetermined amount of EYWA tokens.

  • Emission Distribution: Emissions are split among various reward distributors and categories, with configurable percentage allocations.

  • Adjustment Factors: The amount of tokens locked in escrow influences the calculation of rebase rewards, applying different rates depending on whether the total locked tokens exceed a specified threshold.

  • Owner-Controlled Updates: Certain parameters, such as weekly emission amounts and distribution percentages, can only be updated by the contract owner, subject to cooldown periods and maximum allowed increases.

This contract implements the IEmissionManagerV1 interface and uses upgradeable patterns provided by OpenZeppelin libraries (UUPSUpgradeable, OwnableUpgradeable) for flexibility and future enhancements.

Inherited Contracts and Interfaces

  • UUPSUpgradeable: Manages upgrade logic for UUPS (Universal Upgradeable Proxy Standard) deployments.

  • OwnableUpgradeable: Provides access control, allowing only the owner to perform certain critical operations.

  • IEmissionManagerV1: Defines the required interface for emission manager contracts, including initialization and emission-related functions.

  • IEscrowVoteManagerV1, IEscrowManager: Interfaces that provide information about locked tokens and gauge voting logic.

  • IRebaseRewardsDistributorV1: Interface for distributing rebase rewards.

  • SafeERC20, IERC20: Used for safe and standard interactions with ERC20 tokens.

Constants

EPOCH_DURATION

  • Type: uint256

  • Value: 1 weeks

  • Description: The duration of each emission epoch. All emission-related calculations are based on discrete weekly intervals.

TOTAL_SUPPLY

  • Type: uint256

  • Value: 1_000_000_000e18 (1 billion EYWA tokens with 18 decimals)

  • Description: The total supply of the EYWA token, used in the rebase emission calculations.

MAXIMUM_EMISSION_INCREASE_PERCENTAGE

  • Type: uint256

  • Value: 125_000

  • Description: The maximum allowed percentage increase in weekly emissions compared to the historical average. Represented with the PRECISION factor (100,000 means 100%, so 125,000 means 125%).

PRECISION

  • Type: uint256

  • Value: 100_000

  • Description: Precision factor for percentage calculations. For example, a value of 70_000 means a 70% rate when scaled against PRECISION.

EPOCH_COOLDOWN_PERIOD

  • Type: uint256

  • Value: 12

  • Description: The minimum number of epochs that must pass before updateWeeklyEmissionState can be called again to alter the emission parameters.

State Variables

Emission Parameters

  • s_currentWeeklyEmission

    • Type: uint256

    • Description: The current weekly emission amount of EYWA tokens to be distributed each epoch.

  • s_totalDistributedEmission

    • Type: uint256

    • Description: Total amount of EYWA tokens distributed across all completed epochs.

Percentage Allocations

  • s_gaugeEmissionPercentage

    • Type: uint256

    • Description: The percentage of the weekly emission allocated to gauge rewards, scaled by PRECISION.

  • s_bondEmissionPercentage

    • Type: uint256

    • Description: The percentage of the weekly emission allocated to bond rewards, scaled by PRECISION.

  • s_grantEmissionPercentage

    • Type: uint256

    • Description: The percentage of the weekly emission allocated to grants, scaled by PRECISION.

  • s_incentiveEmissionPercentage

    • Type: uint256

    • Description: The percentage of the weekly emission allocated to incentives, scaled by PRECISION.

Thresholds and Rates

  • s_lockThreshold

    • Type: uint256

    • Description: Threshold of total locked tokens that determines which emission formula (above or below threshold) is used for calculating rebase emissions.

  • s_baseRateBelowThreshold

    • Type: uint256

    • Description: Base rate used in rebase emission calculations when the total locked tokens are below s_lockThreshold, scaled by PRECISION.

  • s_baseRateAboveThreshold

    • Type: uint256

    • Description: Base rate used in rebase emission calculations when the total locked tokens are above or equal to s_lockThreshold, scaled by PRECISION.

  • s_rateMultiplierBelowThreshold

    • Type: uint256

    • Description: Rate multiplier used in the rebase emission calculation when below the lock threshold, scaled by PRECISION.

  • s_rateMultiplierAboveThreshold

    • Type: uint256

    • Description: Rate multiplier used in the rebase emission calculation when above or equal to the lock threshold, scaled by PRECISION.

Epoch Management

  • s_currentEpochStart

    • Type: uint256

    • Description: The timestamp marking the start of the current epoch. Epoch boundaries are aligned to multiples of EPOCH_DURATION.

  • s_lastChangeEpochStart

    • Type: uint256

    • Description: The timestamp marking the start of the epoch during which the last state change to weekly emissions was made. Used to enforce cooldown periods.

  • s_epochCounter

    • Type: uint256

    • Description: The count of completed epochs. It increments once per epoch during updateEpoch() calls.

Addresses

  • s_treasury

    • Type: address

    • Description: The address of the treasury holding EYWA tokens to be distributed as emissions.

  • s_rebaseRewardsDistributor

    • Type: address

    • Description: The address of the contract that distributes rebase rewards.

  • s_bondEmissionDistributor

    • Type: address

    • Description: The address of the distributor for bond emissions.

  • s_grantEmissionDistributor

    • Type: address

    • Description: The address of the distributor for grant-related emissions.

  • s_incentiveEmissionDistributor

    • Type: address

    • Description: The address of the distributor for incentive-based emissions.

  • s_escrowVoteManager

    • Type: IEscrowVoteManagerV1

    • Description: The contract managing gauges and voting logic. Receives gauge emissions.

  • s_escrowManager

    • Type: IEscrowManager

    • Description: The contract managing escrowed token locking. Provides s_totalLocked() for rebase emission calculations.

  • s_eywa

    • Type: IERC20

    • Description: The EYWA token contract used for emissions and distributions.

Constructor

  • constructor()

    • Description: Disables initializers, ensuring the upgradeable contract cannot be re-initialized after deployment.

External Functions

initialize(...)

Signature:

function initialize(
    address owner_,
    address treasury_,
    address rebaseRewardsDistributor_,
    address bondEmissionDistributor_,
    address grantEmissionDistributor_,
    address incentiveEmissionDistributor_,
    IEscrowVoteManagerV1 escrowVoteManager_,
    IEscrowManager escrowManager_,
    IERC20 eywa_
) external initializer

Description: Initializes the contract state. Called once after the proxy is deployed. Sets initial parameters including owner, treasury, distributors, escrow references, and initial emission values.

Parameters:

  • owner_: Address of the contract owner.

  • treasury_: Address of the treasury.

  • rebaseRewardsDistributor_: Address of the rebase distributor contract.

  • bondEmissionDistributor_: Address of the bond emissions distributor.

  • grantEmissionDistributor_: Address of the grants distributor.

  • incentiveEmissionDistributor_: Address of the incentives distributor.

  • escrowVoteManager_: The escrow vote manager contract instance.

  • escrowManager_: The escrow manager contract instance.

  • eywa_: The EYWA token contract.

Effects:

  • Sets default emission values (e.g., s_currentWeeklyEmission = 7_500_000e18).

  • Sets default percentage allocations (70% gauge, 10% bond, 10% grant, 10% incentive).

  • Sets default threshold and rate parameters.

  • Initializes epoch timing and assigns references to external contracts.

  • Transfers ownership to owner_.

updateWeeklyEmissionState(...)

Signature:

function updateWeeklyEmissionState(
    uint256 newWeeklyEmission_,
    uint256 newGaugeEmissionPercentage_,
    uint256 newBondEmissionPercentage_,
    uint256 newGrantEmissionPercentage_,
    uint256 newIncentiveEmissionPercentage_
) external onlyOwner

Description: Updates the weekly emission parameters (total emission amount and distribution percentages among gauge, bond, grant, and incentive) after a cooldown period. Also enforces maximum emission increase rules.

Parameters:

  • newWeeklyEmission_: The new weekly emission in EYWA tokens.

  • newGaugeEmissionPercentage_: New percentage of emissions for gauge rewards.

  • newBondEmissionPercentage_: New percentage of emissions for bond rewards.

  • newGrantEmissionPercentage_: New percentage of emissions for grants.

  • newIncentiveEmissionPercentage_: New percentage of emissions for incentives.

Constraints & Checks:

  • s_epochCounter must be non-zero.

  • Must respect a cooldown period: can only update after EPOCH_COOLDOWN_PERIOD epochs have passed since the last change.

  • The new weekly emission must not exceed averageWeeklyEmissionOverTime() times MAXIMUM_EMISSION_INCREASE_PERCENTAGE / PRECISION.

  • The sum of the new distribution percentages must equal PRECISION (100%).

Effects:

  • Updates the weekly emission amount and percentages.

  • Records the epoch start as s_lastChangeEpochStart to enforce future cooldowns.

  • Emits WeeklyEmissionStateUpdated event.

updateAdjustmentFactorCalculation(...)

Signature:

function updateAdjustmentFactorCalculation(
    uint256 lockThreshold_,
    uint256 baseRateBelowThreshold_,
    uint256 rateMultiplierBelowThreshold_,
    uint256 baseRateAboveThreshold_,
    uint256 rateMultiplierAboveThreshold_
) external onlyOwner

Description: Updates the parameters that influence the calculation of rebase emissions based on locked tokens. These parameters determine how rebase rewards scale depending on whether total locked tokens are above or below s_lockThreshold.

Parameters:

  • lockThreshold_: New lock threshold value.

  • baseRateBelowThreshold_: New base rate for below-threshold scenario.

  • rateMultiplierBelowThreshold_: New rate multiplier for below-threshold scenario.

  • baseRateAboveThreshold_: New base rate for above-threshold scenario.

  • rateMultiplierAboveThreshold_: New rate multiplier for above-threshold scenario.

Effects:

  • Updates the respective state variables.

  • Emits AdjustmentFactorCalculationUpdated event.

updateEpoch()

Signature:

function updateEpoch() external

Description: If the current time has passed into a new epoch, this function updates the emission epoch, calculates and distributes the current week’s emissions, and increments the epoch counter.

Logic:

  1. Check if the current timestamp has passed at least one EPOCH_DURATION since s_currentEpochStart.

  2. If so, set s_currentEpochStart to the start of the new epoch.

  3. Calculate the rebase emission portion via _calculateRebaseEmission().

  4. Distribute emissions:

    • Transfer rebase portion to s_rebaseRewardsDistributor and trigger its checkpoint().

    • Distribute leftover emission among gauge, bond, grant, and incentive recipients based on percentages.

    • For gauge emissions, transfer directly to s_escrowVoteManager and call notifyRewardAmount().

  5. Update s_totalDistributedEmission and increment s_epochCounter.

  6. Emit EpochUpdated event with detailed emission breakdown.

averageWeeklyEmissionOverTime()

Signature:

function averageWeeklyEmissionOverTime() external view returns (uint256)

Description: Returns the average weekly emission calculated as s_totalDistributedEmission / s_epochCounter.

Return:

  • uint256: The average weekly emission amount over all completed epochs.

Internal Functions

_authorizeUpgrade(address)

Signature:

function _authorizeUpgrade(address) internal override onlyOwner

Description: Ensures that only the contract owner can authorize upgrades to the contract, as required by the UUPS proxy standard.

_calculateRebaseEmission(uint256 currentWeeklyEmission_)

Signature:

function _calculateRebaseEmission(uint256 currentWeeklyEmission_) private view returns (uint256)

Description: Calculates the portion of the weekly emission to be allocated as rebase rewards, based on the current weekly emission and the total amount of locked tokens in the escrow. The calculation applies different formulas depending on whether s_totalLocked() is above or below the s_lockThreshold.

Logic:

  1. Retrieve m_totalLocked from s_escrowManager.

  2. If m_totalLocked is zero, return zero (no rebase emission).

  3. If m_totalLocked >= s_lockThreshold, use s_baseRateAboveThreshold and s_rateMultiplierAboveThreshold in the formula.

  4. Otherwise, use s_baseRateBelowThreshold and s_rateMultiplierBelowThreshold.

  5. The formula computes an m_adjustmentFactor that scales based on total locked tokens and a base rate.

  6. Add a constant portion of the current emission to the calculated scaled value.

  7. Return the final rebaseEmission_ after dividing by 1e18 to maintain precision.

Return:

  • rebaseEmission_: The calculated portion of the weekly emission dedicated to rebase rewards.

Events

WeeklyEmissionStateUpdated

Emitted when the weekly emission configuration is updated.

Parameters:

  • newWeeklyEmission

  • newGaugeEmissionPercentage_

  • newBondEmissionPercentage_

  • newGrantEmissionPercentage_

  • newIncentiveEmissionPercentage_

AdjustmentFactorCalculationUpdated

Emitted when the rebase emission calculation parameters are updated.

Parameters:

  • lockThreshold

  • baseRateBelowThreshold

  • rateMultiplierBelowThreshold

  • baseRateAboveThreshold

  • rateMultiplierAboveThreshold

EpochUpdated

Emitted when the epoch transitions and emissions are distributed.

Parameters:

  • epochStartTimestamp

  • totalEmission

  • rebaseEmission

  • gaugeEmission

  • bondEmission

  • grantEmission

  • incentiveEmission

Errors

InvalidCallee()

Thrown if a function is called by an unauthorized entity (not used in current logic for this contract, but defined in the interface).

ZeroEpochCounter()

Thrown when attempting to update the emission state if no epochs have elapsed yet.

CooldownPeriodNotElapsed()

Thrown if attempting to update the weekly emission state before the required number of epochs (cooldown) have passed.

ExcessiveEmissionIncrease()

Thrown if the new weekly emission exceeds the allowed maximum percentage increase over the historical average.

InvalidPercentagesSum()

Thrown if the sum of new emission percentages does not equal PRECISION (i.e., not 100%).

Summary

The EmissionManagerV1 contract provides a sophisticated and flexible solution for managing weekly emissions of EYWA tokens. By using epoch-based logic, adjustable parameters, and strict owner-only modifications (with enforced cooldowns), the contract ensures a controlled and transparent distribution of tokens to various reward mechanisms. Additionally, the integration with escrow-related logic allows dynamic adjustments to rebase rewards based on ecosystem participation (locked tokens), fostering a balanced and incentive-aligned environment.

PreviousTechnical Documentation for EYWA DAO Smart ContractsNextEscrowManager

Last updated