Smart Contracts Deep-dive

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

AI Arena Smart Contracts Interactions.

Protocol Fee Model

Within the reward-distribution flow, the protocol applies a fee when users claim rewards denominated in FLOCK. This fee helps sustain ongoing network operations, security, and ecosystem development. The fee model distinguishes between two major participant groups to reflect their different roles in the protocol:

• Training Nodes & Validators: Claims incur an 8% protocol fee.

• Delegators: Claims incur a 14.5% protocol fee.

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.