MobileVerifiersContractRoot.sol

Overview

The MobileVerifiersContractRoot contract serves as the root and central management point for a set of verifier-related smart contracts within the system. It manages key code artifacts, epoch timing, reward calculations, and interactions with subordinate contracts such as PopCoinRoot, PopitGame, MvMultifactor, and Indexer. The contract maintains and adjusts the reward distribution mechanism over time, handles code upgrades, and facilitates the coordination and address calculation for its child contracts. It also emits events related to the lifecycle of PopCoinRoot contracts.

The contract implements reward tap functionality with time-based reward accrual and enforces access control through custom modifiers, ensuring only authorized senders can invoke sensitive methods.

Contract Structure and State Variables

• version (string constant): Defines the contract version "1.0.0".

• _code (mapping uint8 => TvmCell): Stores the compiled code cells for various child contracts identified by an ID.

• _networkStart, _epochStart, _epochEnd (uint32): Track network and epoch timing, essential for reward periods and epoch management.

• _prevEpochDuration, _reward_sum, _reward_adjustment, _reward_adjustment_prev_epoch (uint128): Variables related to reward calculation and adjustments across epochs.

• _reward_last_time, _min_reward_period, _reward_period (uint32): Timing variables for reward calculation intervals.

• _sum_coef (uint128): A coefficient used in reward calculations.

• _calc_reward_num (uint32): Counter tracking how often reward adjustments were calculated.

• _last_tap (uint32): Timestamp of the last reward tap.

• MBNLstPrev, MBNLstCur, GLstPrev, GLstCur, BCLst (arrays of uint64): Lists used for managing state related to rewards or verification processes.

Events

• PopCoinRootDestroyed(string name): Emitted when a PopCoinRoot contract is destroyed, with the contract's name.

Constructor

constructor(uint128 reward_adjustment)

• Initializes the contract state with the current block timestamp as network start, epoch start, and reward last time.

• Sets the _reward_adjustment and _reward_adjustment_prev_epoch from the input parameter.

• Initializes the arrays (MBNLstPrev, MBNLstCur, GLstPrev, GLstCur, BCLst) with a fixed size (vectorSize).

• Sets _epochEnd based on the configured reward period.

Methods

popCoinRootDestroyed

function popCoinRootDestroyed(string name) public senderIs(address) accept

• Emits the PopCoinRootDestroyed event when a PopCoinRoot contract is destroyed.

• Access restricted to the sender being the expected PopCoinRoot contract address calculated via VerifiersLib.calculatePopCoinRootAddress.

• Ensures contract balance is sufficient before proceeding.

setNewCode

function setNewCode(uint8 id, TvmCell code) public senderIs(address(this)) accept

• Updates the internal _code mapping with new compiled code for a given child contract ID.

• Restricted to calls originating from this contract itself (internal upgrade mechanism).

• Ensures sufficient contract balance.

destroyNode

function destroyNode() public senderIs(address(this)) accept

• Self-destructs the contract, restricted to calls from this contract only.

tapReward

function tapReward() private returns(uint128)

• Calculates the reward accrued since the last tap based on _reward_adjustment and time difference.

• Updates _reward_sum and _last_tap.

• Calls an external method gosh.mintecc to mint rewards in the form of a currency token.

• Returns the calculated reward amount.

sendTapRewards

function sendTapRewards(string name) public senderIs(address) accept

• Sends tap rewards to the sender, who must be the PopCoinRoot contract matching the given name.

• Calls tapReward to calculate the reward and transfers funds (including currencies) to the sender.

sendTapRewardsPopit

function sendTapRewardsPopit(string name, uint256 key, optional(string) media) public senderIs(address) accept

• Similar to sendTapRewards, but forwards the reward payment via a callback to the PopCoinRoot contract's getTapReward method.

• Includes additional parameters key and optional media.

calcRewardAdjustment

function calcRewardAdjustment() private returns (uint128)

• Recalculates the reward adjustment factor based on elapsed time and accumulated rewards.

• Updates _reward_period, _reward_last_time, _calc_reward_num, and _reward_adjustment.

• Calls an external calculation function gosh.calcbmmvrewardadj.

ensureBalance

function ensureBalance() private

• Checks if reward adjustment needs recalculation based on timing and number of calculations.

• Updates epoch timing if the current time exceeds _epochEnd.

• Ensures the contract balance is above a threshold (ROOT_BALANCE) by minting additional tokens if necessary.

Fallback / Receive

receive() external

• Empty receive function allowing the contract to accept plain transfers.

Getter Methods

• getPopitGameAddress(address owner): Returns the calculated address of a PopitGame contract for a given owner.

• getMvMultifactorAddress(uint256 pubkey): Returns the address of a multifactor verification contract for a given public key.

• getPopCoinRootAddress(string name): Returns the address of a PopCoinRoot contract by name.

• getIndexerAddress(string name): Returns the address of an Indexer contract by name.

• getIndexerCode(): Returns the compiled code cell for the Indexer contract.

• getCodes(): Returns all stored code cells.

• getEpoch(): Returns the current epoch start and end timestamps.

• getVersion(): Returns the version string and contract name.

• getReward(...): Pure function to calculate a reward based on provided inputs, delegating to gosh.calcmvreward.

Important Implementation Details and Algorithms

• Reward Calculation: The reward system is time-based, accruing rewards proportional to elapsed time since the last reward tap. The contract maintains sums and adjustment factors that are periodically recalculated to align incentives with network activity.

• Code Management: The contract holds compiled code for several child contracts and can update them internally, supporting upgradability and modular deployment.

• Access Control: The contract uses the senderIs modifier from Modifiers to restrict sensitive operations to specific known addresses, preventing unauthorized interactions.

• Inter-contract Address Derivation: Addresses of child contracts like PopCoinRoot, PopitGame, MvMultifactor, and Indexer are deterministically calculated using helper methods from VerifiersLib, ensuring consistent addressing without storing explicit mappings.

• Balance Management: The contract ensures it maintains a minimum balance (ROOT_BALANCE) by minting tokens as needed, enabling it to pay out rewards and cover operational costs.

Interactions with Other Contracts and Libraries

• Modifiers: Inherits custom modifiers from Modifiers.sol to enforce sender restrictions.

• VerifiersLib: Utilizes VerifiersLib.sol for address calculations and building code cells related to child contracts.

• PopitGame, PopCoinRoot, Mvmultifactor, Indexer: Interacts with these contracts by calculating their addresses and invoking methods, especially for reward distribution.

• External gosh Object: Calls functions like mintecc, calcbmmvrewardadj, calcmvreward, and mintshellq on the external gosh interface for minting tokens, calculating rewards, and adjusting reward parameters.

Visual Diagram

classDiagram
class MobileVerifiersContractRoot {
-string version
-mapping(uint8 => TvmCell) _code
-uint32 _networkStart
-uint32 _epochStart
-uint32 _epochEnd
-uint128 _prevEpochDuration
-uint128 _reward_sum
-uint128 _reward_adjustment
-uint128 _reward_adjustment_prev_epoch
-uint32 _reward_last_time
-uint32 _min_reward_period
-uint32 _reward_period
-uint128 _sum_coef
-uint32 _calc_reward_num
-uint32 _last_tap
-uint64[] MBNLstPrev
-uint64[] MBNLstCur
-uint64[] GLstPrev
-uint64[] GLstCur
-uint64[] BCLst
+constructor(uint128)
+popCoinRootDestroyed(string)
+setNewCode(uint8, TvmCell)
+destroyNode()
-tapReward() uint128
+sendTapRewards(string)
+sendTapRewardsPopit(string, uint256, optional(string))
-calcRewardAdjustment() uint128
-ensureBalance()
+getPopitGameAddress(address) address
+getMvMultifactorAddress(uint256) address
+getPopCoinRootAddress(string) address
+getIndexerAddress(string) address
+getIndexerCode() TvmCell
+getCodes() mapping(uint8 => TvmCell)
+getEpoch() (uint32, uint32)
+getVersion() (string, string)
+getReward(uint128, uint64[], uint64[], uint64, uint128) uint128
}
MobileVerifiersContractRoot --> Modifiers : inherits
MobileVerifiersContractRoot --> VerifiersLib : uses for address calculations
MobileVerifiersContractRoot --> PopCoinRoot : interacts for rewards
MobileVerifiersContractRoot --> PopitGame : address calculation
MobileVerifiersContractRoot --> Mvmultifactor : address calculation
MobileVerifiersContractRoot --> Indexer : address and code management
MobileVerifiersContractRoot --> gosh : external reward and mint calculations

This diagram summarizes the main properties and methods of the MobileVerifiersContractRoot contract, its inheritance, and its relationships with external contracts and libraries.