MobileVerifiersContractRoot.abi.json

Overview

This file defines the Application Binary Interface (ABI) for the Mobile Verifiers Contract Root smart contract. The ABI version is 2, with contract version 2.4. It specifies the contract's external interface including constructors, callable functions, events, and stored fields. This contract manages key functionalities related to Mobile Verifiers, such as reward distribution, code management, and address resolution for subcontracts like PopCoinRoot, MV Multifactor, Popit Games, and Indexers.

The contract operates with a set of core state variables and exposes multiple utility functions for interacting with various Mobile Verifier components. It also includes mechanisms for controlling contract lifecycle events like destruction and code upgrades.

Structure and Components

Header

pubkey (public key)
time (timestamp)
expire (expiration time)

These headers define the transaction context for contract calls.

Fields

The contract maintains several fields representing its internal state:

Field Name	Type	Initialization	Description
_pubkey	uint256	true	Public key associated with the contract
_timestamp	`uint64`	false	Last recorded timestamp
_constructorFlag	`bool`	false	Flag indicating constructor execution
`_code`	`map(uint8,cell)`	false	Mapping of contract codes indexed by uint8 IDs
_networkStart	`uint32`	false	Network start time
_epochStart, _epochEnd	`uint32`	false	Start and end times of the current epoch
_prevEpochDuration	`uint128`	false	Duration of the previous epoch
`_reward_sum`	`uint128`	false	Sum of rewards
`_reward_adjustment`	`uint128`	false	Current reward adjustment factor
_reward_adjustment_prev_epoch	`uint128`	false	Reward adjustment factor from the previous epoch
`_reward_last_time`	`uint32`	false	Timestamp of the last reward calculation
`_min_reward_period`	`uint32`	false	Minimum period between rewards
`_reward_period`	`uint32`	false	Standard reward period
`_sum_coef`	`uint128`	false	Sum of coefficients used in reward calculations
`_calc_reward_num`	`uint32`	false	Counter for reward calculations
`_last_tap`	`uint32`	false	Timestamp of the last tapping event
`MBNLstPrev`, `MBNLstCur`	`uint64[]`	false	Lists for Mobile Verifier Nodes previous and current
`GLstPrev`, `GLstCur`	`uint64[]`	false	Lists for some groupings (possibly gamified elements)
BCLst	`uint64[]`	false	Another list related to contract state, exact purpose unspecified

Functions

constructor

Purpose: Initializes the contract with a reward adjustment value.
Parameters:
- reward_adjustment (uint128): Initial reward adjustment parameter.
Returns: None
Usage: Called once during contract deployment to set initial reward adjustment.

popCoinRootDestroyed

Purpose: Event handler to manage destruction of a PopCoinRoot by name.
Parameters:
- name (string): Identifier of the PopCoinRoot to mark destroyed.
Returns: None
Usage: Typically invoked to update contract state after a PopCoinRoot is destroyed.

setNewCode

Purpose: Updates the contract code for a specific code ID.
Parameters:
- id (uint8): Identifier for the code slot.
- code (cell): New contract code to set.
Returns: None
Usage: Enables upgrading or patching parts of the contract by replacing code cells.

destroyNode

Purpose: Destroys the current node or contract instance.
Parameters: None
Returns: None
Usage: Used for contract self-destruction, potentially for cleanup or upgrade procedures.

sendTapRewards

Purpose: Sends TAP rewards associated with a given name.
Parameters:
- name (string): Identifier for the reward recipient or category.
Returns: None
Usage: Distributes rewards based on TAP metrics.

sendTapRewardsPopit

Purpose: Sends TAP rewards for Popit games with optional media metadata.
Parameters:
- name (string): Identifier linked to the reward.
- key (uint256): Unique key for authorization or identification.
- media (optional(string)): Optional media information.
Returns: None
Usage: Extended reward distribution for Popit games, allowing media tagging.

getPopitGameAddress

Purpose: Resolves the address of a Popit game contract owned by a given address.
Parameters:
- owner (address): Owner address.
Returns:
- popitGameAddress (address): Address of the Popit game contract.
Usage: Helps in locating specific Popit game contracts.

getMvMultifactorAddress

Purpose: Retrieves the address of a Multifactor Mobile Verifier by public key.
Parameters:
- pubkey (uint256): Public key for the verifier.
Returns:
- mvMultifactorAddress (address): Address of the MV multifactor contract.
Usage: Used to query multifactor verifier contracts.

getPopCoinRootAddress

Purpose: Gets the address of a PopCoinRoot contract by its name.
Parameters:
- name (string): PopCoinRoot identifier.
Returns:
- popCoinRootAddress (address): Address of the PopCoinRoot contract.
Usage: Resolves contract addresses for PopCoinRoots.

getIndexerAddress

Purpose: Retrieves the address of an Indexer contract by name.
Parameters:
- name (string): Identifier for the Indexer.
Returns:
- indexerAddress (address): Address of the Indexer contract.
Usage: Used to find Indexer contracts.

getIndexerCode

Purpose: Retrieves the code cell of the Indexer contract.
Parameters: None
Returns:
- data (cell): Code of the Indexer contract.
Usage: Provides contract code for verification or upgrade.

getCodes

Purpose: Returns a map of all stored contract codes.
Parameters: None
Returns:
- code (map(uint8,cell)): Mapping of code IDs to code cells.
Usage: Useful for inspecting current stored codes.

getEpoch

Purpose: Returns the current epoch start and end timestamps.
Parameters: None
Returns:
- epochStart (uint32): Start of the current epoch.
- epochEnd (uint32): End of the current epoch.
Usage: Allows querying of epoch timing for reward calculations.

getVersion

Purpose: Returns the version information of the contract.
Parameters: None
Returns:
- value0 (string): Version major or identifier part 1.
- value1 (string): Version minor or identifier part 2.
Usage: Used for contract version tracking.

getReward

Purpose: Computes the reward amount based on various parameters.
Parameters:
- mbi (uint128): Mobile Verifier index or balance indicator.
- MBNLst (uint64[]): List of Mobile Verifier node values.
- TAPLst (uint64[]): List of TAP values.
- value (uint64): Base value for calculation.
- basicRewards (uint128): Basic reward amount.
Returns:
- value0 (uint128): Calculated reward.
Usage: Core method for reward calculation logic using provided metrics.

Events

PopCoinRootDestroyed

Parameters:
- name (string): The name of the PopCoinRoot that was destroyed.
Description: Emitted when a PopCoinRoot contract is destroyed to notify listeners and update state.

Implementation Details and Algorithms

Reward Calculation: The getReward function uses multiple lists (MBNLst, TAPLst) and input parameters to compute a reward value. This likely involves aggregating coefficients and applying adjustments based on epoch data and reward sums to determine precise payouts.
Code Management: Contract code is stored as a map from uint8 IDs to code cells, enabling modular code upgrades via setNewCode.
Epoch Management: The contract tracks epoch start and end times, which are essential for time-based reward distribution and network state transitions.
Address Resolution: Functions like getPopitGameAddress, getMvMultifactorAddress, and getPopCoinRootAddress provide dynamic resolution of related contracts, supporting composability and modular design.
Lifecycle Control: Functions such as destroyNode and event PopCoinRootDestroyed enable controlled destruction of contract components, ensuring clean state management.

Interaction with Other System Components

This contract serves as the root controller for Mobile Verifiers and coordinates with several other contract types:

PopCoinRoot Contracts: Managed via address resolution and destruction events.
MV Multifactor Contracts: Address lookup for multifactor verifiers by public key.
Popit Games: Address resolution and TAP reward sending for game-related contracts.
Indexers: Code and address management for indexing components.
Reward Distribution: Interfaces with reward pools and possibly external token contracts to distribute TAP rewards.

This contract is central to managing the lifecycle and reward mechanics of Mobile Verifier-related entities, making it a key integration point in the overall system.

Visual Diagram

flowchart TD
constructor -->|Init reward_adjustment| _reward_adjustment
setNewCode -->|Update code map| _code
popCoinRootDestroyed -->|Emit PopCoinRootDestroyed| EventPopCoinRootDestroyed
destroyNode -->|Contract self-destruct| NodeDestroyed
sendTapRewards -->|Send rewards by name| TAPRewardsSent
sendTapRewardsPopit -->|Send rewards with media| TAPRewardsPopitSent
getPopitGameAddress -->|Returns address| PopitGameAddress
getMvMultifactorAddress -->|Returns address| MVMultifactorAddress
getPopCoinRootAddress -->|Returns address| PopCoinRootAddress
getIndexerAddress -->|Returns address| IndexerAddress
getIndexerCode -->|Returns code cell| IndexerCode
getCodes -->|Returns code map| CodeMap
getEpoch -->|Returns epochStart & epochEnd| Epoch
getVersion -->|Returns version strings| Version
getReward -->|Computes reward| RewardValue
EventPopCoinRootDestroyed((PopCoinRootDestroyed))
NodeDestroyed((NodeDestroyed))
TAPRewardsSent((TAPRewardsSent))
TAPRewardsPopitSent((TAPRewardsPopitSent))

The diagram reflects main callable functions and their effect on contract state or outputs, emphasizing code management, reward distribution, and address resolution workflows.