Smart Contracts Deep-dive

This page gives detailed explanation of AI Arena's smart contracts.

AI Arena Smart Contracts Interactions.

Core Contracts

AdminUpgradeable.sol

Role: Base class that provides admin rights and other access-related methods.

• Inherits AccessControlUpgradeable from OpenZeppelin.

• Exposes onlyAdmin modifier and isAdmin checks.

• Allows flexible role management for upgradeable contracts.

FlockMiniPool.sol

Role: Represents a “mini pool” that supports user delegation, tracks delegations, calculates claimable rewards, and interacts with the protocol’s managers.

• Uses mappings to track each delegator’s stake, claims, temporal stakes, etc.

• Integrates with FlockConfig for config references, calls back into FlockPoolManager and FlockMainManager.

FlockPoolManagerUpgradeable.sol

Role: Manages the creation and configuration of FlockMiniPool instances.

• Tracks all active pools in sets, plus each user’s associated mini pool.

• Maintains system-wide parameters (e.g., min/max Sigma, protocol fees).

• Acts as a factory for creating new mini pools: createMiniPool(...).

• Handles callbacks to update delegations in a user’s mini pool.

FlockStakeInfoUpgradeable.sol

Role: Central ledger for all stakes across tasks.

• Maintains stake amounts, weights, and distribution logic for nodes, validators, and delegators.

• Relies on FlockConfig references to connect to other managers (e.g. main manager, pool manager).

• Example responsibilities include:

  • addStakes() / removeStakes(): Called by the main manager to adjust totals.

  • taskStakes[], taskWeights[]: Summaries for each task’s stake distribution.

  • “Re-tallying” delegations to keep stake info up to date.

FlockTaskManagerUpgradeable.sol

Role: Orchestrates tasks in the system.

• Maintains references to each task (node stakes, validator stakes, distributions).

• Aggregates daily minted rewards from FlockToken, then calculates how to distribute among nodes, validators, and delegators.

• Offers hooks like afterDelegationUpdate(...) so that the pool manager can re-tally the user’s delegation.

FlockTokenUpgradeable.sol

Role: The upgradeable ERC20 for the entire protocol.

• Allows “mint” and “burn” operations.

• Implements a blacklist mechanism to restrict malicious actors.

• Has “admin” only calls for minting, daily mint limits, etc.

• Used as the currency for all staking, delegation, and reward flows.

Libraries

LibABDKMathQuad.sol

Role: Quadruple-precision (128-bit) floating-point math.

• Based on the ABDK Consulting library, enabling IEEE 754-compatible operations with 16-byte bytes16 floats.
• Key functionalities include:

  • Converting between int256/uint256 and quad precision.

  • Arithmetic ops (add, sub, mul, div).

  • Logarithms, exponentiation, square roots.

• Used when standard fixed-point or 256-bit integer math is insufficient for advanced computations (such as extremely precise reward calculations).

LibFlockTask.sol

Role: Utility library for certain math and pseudo-randomness within tasks.

• Wraps LibABDKMathQuad logic for simpler usage in multiplication/division scenarios.

• Provides a “random” function (rand()), which generates a random number using block/transaction properties.

LibMath.sol

Role: Additional numeric utilities, focusing on n-th root calculations.

• Provides the function nthRoot() which approximates the n-th root of a given number.

• Useful for advanced arithmetic or reward distribution models needing, for example, “square root” or other root-based weighting logic.