# Smart Contracts Deep-dive

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](https://github.com/abdk-consulting/abdk-libraries-solidity), 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.