AECStakingLP.sol

Rewards liquidity providers in the protocol; incentivizes staking of AEC/Stablecoin LP tokens and ensures deep liquidity with a special, eternally-locked tier for the Perpetual Engine.

Quick Links

• View Contract on GitHub

• Contract Path: contracts/staking/AECStakingLP.sol

Inherits From

• ReentrancyGuard

• IAECStakingLP

Key State Variables

Public and immutable variables defining staking mechanics, tier structure, reward accounting, and historical stats.

Variable	Type	Description
aecToken	IERC20	The immutable address of the AEC reward token.
lpToken	IERC20	The immutable address of the LP token that can be staked.
perpetualEngine	address	The immutable address of the PerpetualEngine.
liquidityDeployer	address	The immutable address of the LiquidityDeployer, authorized for the genesis stake.
initialRewardAllocation	uint256	The immutable initial reward allocation for this pool (177,777,777 AEC).
deploymentTime	uint256	The immutable timestamp of the contract's deployment.
tiers	TierConfig[5]	An array of structs defining the 5 staking tiers (4 user, 1 Engine).
stakes	mapping(address => StakeInfo)	A mapping from a user's address to a struct containing all their staking information.
totalSupply	uint256	The total amount of (unweighted) LP tokens currently staked in the contract.
totalWeightedSupply	uint256	The total sum of all staked amounts multiplied by their tier multipliers, used for reward calculations.
remainingBaseRewards	uint256	The current balance of the initial reward allocation that decays over time.
lastBaseRewardUpdate	uint256	Timestamp of the last time the base reward pool was decayed.
rewardsDuration	uint256	The duration (in seconds) over which bonus rewards are distributed. Default is 7 days.
isEternalStaker	mapping(address => bool)	Returns true if an address (the Perpetual Engine) has staked in the eternal tier and cannot withdraw.
hasStaked	mapping(address => bool)	Tracks if a user has ever staked, for unique staker count.
poolStats	PoolStats	Struct containing historical pool statistics (totalDeposited, totalWithdrawn, totalRewardsPaid, uniqueStakers).
rewardPerTokenStored	uint256	The last calculated reward-per-token value.
lastUpdateTime	uint256	The timestamp of the last global reward calculation.
bonusRewardRate	uint256	The current rate of bonus rewards distributed per second.
baseRewardRate	uint256	The current rate of base rewards distributed per second from the decaying pool.
basePeriodFinish	uint256	Timestamp when the current base reward decay period ends.
bonusPeriodFinish	uint256	Timestamp when the current bonus reward distribution period ends.
userRewardPerTokenPaid	mapping(address => uint256)	Tracks the rewardPerTokenStored value for each user at their last interaction.
rewards	mapping(address => uint256)	Stores the accumulated, unclaimed rewards for each user.
totalBonusRewardsDistributed	uint256	Tracks the cumulative amount of bonus rewards distributed from the Engine.

Write Functions

Functions that modify staking state or rewards; access restricted where noted.

Function	Access	Description
stake(uint256 amount, uint8 tier)	Public	Stakes LP tokens into user-selectable tier (0-3); tier cannot be lower than current.
withdraw(uint256 amount)	Public	Withdraws LP tokens; reverts if lock period is not over.
claimReward()	Public	Claims all accumulated AEC rewards for caller.
exit()	Public	Withdraws all LP tokens and claims rewards in a single transaction.
upgradeTier(uint8 newTier)	Public	Upgrades staking tier without withdrawing/redepositing.
stakeForEngine(uint256 amount)	Engine-Only	Stakes LP tokens into eternal Tier 4; callable only by perpetualEngine or liquidityDeployer at genesis.
notifyRewardAmount(uint256 reward)	Engine-Only	Deposits new batch of rewards; automatically returns Engine’s share for compounding.
setRewardsDuration(uint256 _rewardsDuration)	Engine-Only	Adjusts duration over which bonus rewards are distributed.
emergencyRecoverToken(address token, uint256 amount)	Engine-Only	Recovers any non-protocol tokens mistakenly sent to contract.

View Functions

Read-only functions for monitoring staking, rewards, and pool analytics.

Function	Description
earned(address account)	Returns the total amount of claimable AEC rewards for a given account.
rewardPerToken()	Calculates the current reward-per-token value for use in earned() computation.
lastTimeRewardApplicable()	Returns the timestamp of the last moment bonus rewards are applicable.
totalBaseRewardsDistributed()	Returns the total amount of base rewards distributed since deployment.
getStakeInfo(address account)	Returns a detailed struct of an account's staking position (amount, tier, lock end, earned rewards).
getPoolStats()	Provides a high-level overview of the entire pool (total staked, remaining base rewards, bonus rate, Engine share).
getPoolMetrics()	Returns historical pool performance metrics (total deposited, withdrawn, rewards paid, etc.).
getProjectedAPY(uint8 tier)	Returns the projected Annual Percentage Yield (in basis points) for a given tier based on current reward rates.
getTierInfo(uint8 tier)	Returns the configuration of a specific tier (lock duration, multiplier, staker count, etc.).
verifySustainability(uint256 yearsToProject)	Models the long-term sustainability of the base rewards.
checkUpgradeability()	A view function to check if the contract is in a state safe for a potential future migration.
calculateRequiredStake(uint256 targetAPY, uint8 tier)	Calculates the stake amount needed to achieve a target APY in a specific tier.
validateRewardBalance()	Checks if the contract holds enough AEC to cover its current reward obligations.

Events

Events emitted for monitoring and off-chain tracking.

Event	Description
Staked(address indexed user, uint256 amount, uint8 tier, uint256 lockEnd, uint256 weightedAmount)	Emitted when a user successfully stakes LP tokens.
Withdrawn(address indexed user, uint256 amount)	Emitted when a user withdraws LP tokens.
RewardPaid(address indexed user, uint256 reward)	Emitted when a user claims their AEC rewards.
EngineStaked(uint256 amount, uint256 timestamp)	Emitted specifically when the Engine stakes its LP tokens.
EngineRewardReturned(uint256 amount)	Emitted when the Engine's share of rewards is returned to it for compounding.
BonusRewardAdded(uint256 reward)	Emitted when the Engine deposits new rewards into the contract.
BaseRewardsDecayed(uint256 decayAmount, uint256 remaining, uint256 newRate)	Emitted when the base reward pool decays, showing the amount released for the period.
RewardsDurationUpdated(uint256 newDuration)	Emitted when the rewards distribution duration is updated by the Engine.
TierMigration(address indexed user, uint8 fromTier, uint8 toTier)	Emitted when a user successfully upgrades their staking tier.
EmergencyRewardRecovery(address indexed token, uint256 amount)	Emitted when non-protocol tokens are recovered from the contract by the Engine.

Closing Note

This reference completes the overview for AECStakingLP.sol. All functions, state variables, and events are documented above for verification, integration, and developer usage.