PerpetualEngine.sol

Core autonomous engine of AetherCycle; collects protocol revenue and executes 20/40/40 distribution via permissionless runCycle().

Quick Links

• View Contract on GitHub

• Contract Path: contracts/core/PerpetualEngine.sol

Inherits From

• ReentrancyGuard

• IPerpetualEngine

Key State Variables

These public and immutable variables provide a real-time snapshot of the Engine's configuration, core integrations, and operational state.

Variable	Type	Description
aecToken	IAECToken	The immutable address of the core AEC token contract.
stablecoinToken	IERC20	The immutable address of the stablecoin (e.g., USDC) used for liquidity pairing.
uniswapV2Router	IUniswapV2Router02	The immutable address of the official DEX router used for swaps and adding liquidity.
aecStablecoinPair	IUniswapV2Pair	The immutable address of the official AEC/Stablecoin liquidity pair.
perpetualEndowment	IPerpetualEndowment	The immutable address of the Perpetual Endowment contract.
stakingContractLP	address	The address of the AECStakingLP contract.
stakingContractToken	address	The address of the AECStakingToken contract.
stakingContractNFT	address	The address of the AECStakingNFT contract.
minAecToProcess	uint256	The minimum balance of AEC required in the contract before runCycle() can be executed.
publicProcessCooldown	uint256	The cooldown period (in seconds) between permissionless runCycle() calls.
lastPublicProcessTime	uint256	The timestamp of the last time runCycle() was successfully executed.
deployerPrivilegesActive	bool	Returns true if the deployer's one-time setup functions are still active.
totalEndowmentReceived	uint256	Tracks the cumulative amount of AEC received from the Perpetual Endowment.
lastEndowmentRelease	uint256	The timestamp of the last time funds were received from the Endowment.
deploymentTime	uint256	The immutable timestamp of the Engine's deployment.
slippageBasisPoints	uint16	The slippage tolerance in basis points (e.g., 500 = 5%) for swaps.

Write Functions

These functions modify the state of the contract and are subject to strict access controls.

Function	Access	Description
runCycle()	Public	Permissionless function that collects revenue and executes 20/40/40 distribution. Caller earns 0.1% reward.
notifyEndowmentRelease(uint256 amount)	Public	Called by the PerpetualEndowment to notify the Engine of new funds; may trigger runCycle().
setStakingContracts(address _stakingContractToken, address _stakingContractNFT)	Owner	Sets Token and NFT staking contracts. Callable once before deployer privileges are renounced.
renounceDeployerPrivileges()	Owner	Permanently renounces deployer privileges; disables all owner-only functions.
rescueForeignTokens(address tokenAddress, uint256 amount)	Owner	Withdraws non-protocol ERC20 tokens sent mistakenly (excluding AEC or official stablecoin).

View Functions

These functions are used to read data from the protocol without modifying state. They are essential for building analytics dashboards, monitoring tools, and integrated dApps.

Function	Description
getContractStatus()	Returns a struct with Engine status: balances, cooldown, and estimated caller reward.
calculateCycleOutcome()	Simulates runCycle() to preview burn, liquidity, rewards, and caller reward.
getConfiguration()	Returns core operational parameters: slippage, minimum AEC to process, public cooldown.
healthCheck()	Returns boolean diagnostics of key components: balances, LP pair, staking contracts, Endowment connection.
getPoolInfo()	Returns current reserve data and token addresses of the AEC/Stablecoin liquidity pair.
getEndowmentStats()	Returns analytics on Endowment performance: total received, last release timestamp, average release.
isOperational()	Returns true if the Engine is active.
version()	Returns the current contract version string.

Events

These events are crucial for monitoring the autonomous operations of the protocol. Subscribing to these events is the best way to build off-chain monitoring tools or dApps that react to the Engine's activity.

Event	Description
CycleProcessed(uint256 totalProcessed, uint256 burned, uint256 lpProcessed, uint256 rewardsDistributed, uint256 callerReward, address caller)	Emitted after each successful runCycle(); full breakdown of processed amounts.
AecBurnedInCycle(uint256 amount)	Emitted when AEC tokens are burned during a cycle.
AutoLiquidityAdded(uint256 aecAmount, uint256 stablecoinAmount, uint256 liquidityTokens)	Emitted when liquidity is added to the DEX.
RewardsDistributed(uint256 lpStakingAmount, uint256 tokenStakingAmount, uint256 nftStakingAmount)	Emitted when AEC rewards are sent to staking contracts.
EngineRewardsClaimed(uint256 amount)	Emitted when Engine claims its own staking rewards for compounding.
ProcessingSkipped(uint256 currentBalance, uint256 required)	Emitted if runCycle() is called without sufficient AEC.
SwapAttempt(uint256 aecAmount, bool successful, uint256 stablecoinObtained)	Logs each AEC-to-stablecoin swap attempt.
FlexibleStrategyAttempt(string strategyName, uint256 aecAmount, uint256 stablecoinAmount, uint256 aecMin, uint256 stablecoinMin, bool successful)	Logs flexible liquidity strategy attempts with parameters/outcome.
UnutilizedAecAccumulated(uint256 amount, string reason)	Emitted when unprocessed AEC is preserved for next cycle.
StakingContractsUpdated(address lpStaking, address tokenStaking, address nftStaking)	Emitted when staking contract addresses are updated.
DeployerPrivilegesRenounced()	Emitted when deployer renounces administrative privileges.
EndowmentReleaseNotified(uint256 amount, address indexed from)	Emitted when Endowment releases funds to Engine.
EndowmentReleased(uint256 amount, uint256 timestamp)	Confirms Endowment funds included in processing cycle.
EndowmentSkipped(string reason, uint256 potentialAmount)	Emitted when Endowment release conditions are not met.

Closing Note

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