BlockManagerContractRoot.sol

Overview

BlockManagerContractRoot.sol defines the BlockManagerContractRoot smart contract, which acts as the central root contract managing Block Manager Node Wallets within a blockchain network. This contract maintains the lifecycle, configuration, and reward management of block managers, overseeing their deployment, activity tracking, and reward/slashing mechanisms. It also handles the storage and updating of code for various block manager wallet types and interacts closely with AckiNackiBlockManagerNodeWallet contracts and utility libraries like BlockKeeperLib.

Contract: BlockManagerContractRoot

Version

version: "1.0.0" (constant string)

State Variables

Variable	Type	Description
`_code`	`mapping(uint8 => TvmCell)`	Stores contract code cells indexed by an ID, used for wallet deployment and upgrades.
`_licenseBMRoot`	`address`	Address of the License Block Manager Root contract.
`_numberOfActiveBlockManagers`	`uint128`	Current count of active block managers.
`_owner_wallet`	`optional(address)`	Optional owner wallet address.
`_networkStart`	`uint32`	Timestamp marking the network start time.
`_epochDuration`	`uint64`	Duration of an epoch in seconds or blocks (context-dependent).
`_waitStep`	`uint64`	Wait step duration used in timing controls.
`_prevEpochDuration`	`uint32`	Duration of the previous epoch.
`_epochStart`	`uint32`	Timestamp when the current epoch started.
`_epochEnd`	`uint64`	Sequence number indicating the epoch end block.
`_numberOfActiveBlockManagersAtEpochStart`	`uint128`	Number of active block managers at the start of the current epoch.
`_numberOfActiveBlockManagersAtPrevEpochStart`	`uint128`	Number of active block managers at the start of the previous epoch.
`_reward_adjustment`	`uint128`	Current reward adjustment factor.
`_reward_adjustment_prev_epoch`	`uint128`	Reward adjustment factor from the previous epoch.
`_reward_last_time`	`uint32`	Timestamp of the last reward calculation.
`_min_reward_period`	`uint32`	Minimum period between reward calculations (default 432000).
`_reward_period`	`uint32`	Current reward calculation period.
`_calc_reward_num`	`uint32`	Number of reward calculations performed.
`_reward_sum`	`uint128`	Sum of all rewards issued.
`_slash_sum`	`uint128`	Sum of all slashes applied.
`_reward_sum_prev_epoch`	`uint128`	Sum of rewards from the previous epoch.
`_is_close_owner`	`bool`	Flag indicating if owner operations are closed.
`_walletTouch`	`uint8`	Configuration parameter likely controlling wallet interaction frequency or mode.

Constructor

constructor (
    address licenseBMRoot,
    uint64 epochDuration,
    uint64 waitStep,
    uint128 reward_adjustment,
    uint8 walletTouch
)

Purpose: Initializes the contract with initial network and epoch parameters, reward adjustment, and wallet interaction settings.

Parameters:

licenseBMRoot: Address of the license block manager root.
epochDuration: Duration of a block epoch.
waitStep: Wait step duration controlling timing.
reward_adjustment: Initial reward adjustment factor.
walletTouch: Wallet interaction parameter.

Behavior:

Sets network start and epoch start timestamps to current block time.
Sets epoch end as current block sequence number plus epoch duration.
Initializes reward and wallet interaction variables.

Functions

`setConfig`

function setConfig(
    uint64 epochDuration, 
    uint64 waitStep,
    uint32 reward_period, 
    uint32 min_reward_period, 
    uint32 calc_reward_num, 
    uint8 walletTouch
) public onlyOwner accept

Description: Updates the contract configuration parameters related to epoch duration, wait steps, reward periods, and wallet interaction. Callable only by the owner.

Parameters:

epochDuration: New epoch duration.
waitStep: New wait step duration.
reward_period: Reward calculation period.
min_reward_period: Minimum period before rewards can be recalculated.
calc_reward_num: Number of reward calculations to average over.
walletTouch: Wallet interaction parameter.

Implementation Details:

Checks if owner operations are not closed.
Calls ensureBalance to update state and mint tokens if necessary.
Updates reward adjustment by calling a calculation function from the external gosh contract.

`setConfigNode`

function setConfigNode(
    uint64 epochDuration,
    uint64 waitStep,
    uint32 reward_period,
    uint32 min_reward_period,
    uint32 calc_reward_num,
    uint8 walletTouch
) public senderIs(address(this)) accept

Description: Similar to setConfig but callable only by the contract itself (internal calls).

`closeRoot`

function closeRoot() public onlyOwner accept

Description: Marks the root owner as closed, preventing further owner-only configuration changes.

`setNewCode`

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

Description: Updates a code cell in the _code mapping, enabling upgrades or changes in wallet contract code.

Parameters:

id: Identifier of the code cell.
code: New compiled contract code as TvmCell.

`calcRewardAdjustment`

function calcRewardAdjustment() private returns (uint128)

Description: Calculates and updates the reward adjustment factor based on elapsed time, past rewards, and configured parameters.

Implementation Details:

Updates _reward_period as a moving average.
Updates _reward_last_time to current timestamp.
Calls external gosh.calcbmmvrewardadj for adjustment calculation.

`ensureBalance`

function ensureBalance() private

Description: Ensures the contract's balance and state are consistent with epoch timing. Handles epoch transitions, reward adjustment recalculation, and triggers minting tokens if balance is low.

Implementation Details:

Checks if current block sequence number passed epoch end to update epoch timing variables.
Calls calcRewardAdjustment if minimum reward period elapsed.
Calls gosh.mintshellq if contract balance is below a predefined threshold ROOT_BALANCE.

`increaseBM`

function increaseBM(uint256 pubkey) public senderIs(BlockKeeperLib.calculateBlockManagerWalletAddress(_code[m_AckiNackiBlockManagerNodeWalletCode], address(this), pubkey)) accept

Description: Increments the number of active block managers. Only callable by a valid block manager wallet identified by its public key.

`deployAckiNackiBlockManagerNodeWallet`

function deployAckiNackiBlockManagerNodeWallet(
    uint256 pubkey,
    uint256 signerPubkey,
    mapping(uint256 => bool) whiteListLicense
) public accept

Description: Deploys a new AckiNackiBlockManagerNodeWallet contract instance initialized with the provided public keys and license whitelist.

Parameters:

pubkey: Public key of the block manager.
signerPubkey: Public key of the signer authorized for actions.
whiteListLicense: Mapping for license whitelist validation.

Implementation Details:

Ensures the whitelist size does not exceed MAX_LICENSE_NUMBER_WHITELIST_BM.
Uses BlockKeeperLib.composeBlockManagerWalletStateInit to prepare wallet state initialization.
Deploys the wallet with specified gas fee and initial parameters.

`slashed`

function slashed(uint256 pubkey, bool isWorking) public senderIs(BlockKeeperLib.calculateBlockManagerWalletAddress(_code[m_AckiNackiBlockManagerNodeWalletCode], address(this), pubkey)) accept

Description: Called by block manager wallets to register a slashing event, reducing active block manager count if applicable and updating total slashed sum.

Parameters:

pubkey: Public key of the block manager.
isWorking: Indicates if the block manager was active (true) or not (false).

`getReward`

function getReward(
    uint256 pubkey,
    uint256 sign_pubkey,
    address wallet_address,
    uint32 rewarded,
    uint32 startBM,
    bool isEnd
) public senderIs(BlockKeeperLib.calculateBlockManagerWalletAddress(_code[m_AckiNackiBlockManagerNodeWalletCode], address(this), pubkey)) accept

Description: Processes reward distribution to block managers based on activity, epoch timing, and reward sums.

Parameters:

pubkey: Block manager's public key.
sign_pubkey: Signer public key.
wallet_address: Wallet address receiving the reward.
rewarded: Timestamp of last reward.
startBM: Start time of block manager activity.
isEnd: Flag indicating if the block manager is ending activity.

Implementation Details:

Decreases active block manager count if isEnd is true.
Checks if reward conditions are met; if not, calls noRewards on the wallet.
Calculates reward using external gosh.calcbmreward.
Mints the reward tokens using gosh.mintecc.
Calls wallet's takeReward method with updated parameters.

Fallback and Receive Functions

receive() external {}

Accepts incoming plain value transfers without executing code.

Getters

getAckiNackiBlockManagerNodeWalletAddress(pubkey): Returns the wallet address for a given block manager public key, computed via BlockKeeperLib.
getAckiNackiBlockManagerNodeWalletCode(): Returns the compiled code cell for the AckiNackiBlockManagerNodeWallet.
getCodes(): Returns the _code mapping containing deployed contract codes.
getDetails(): Returns key state information including total rewards, slashes, and active block manager counts.
getVersion(): Returns the version string and contract name.

Important Implementation Details and Algorithms

Epoch Management: The contract manages epochs based on block sequence numbers and timestamps. Epoch start and end times are updated, and various metrics are tracked per epoch.
Reward Calculation: Uses an external calculation function gosh.calcbmmvrewardadj for reward adjustments and gosh.calcbmreward for computing individual rewards, ensuring dynamic adaptation based on total rewards, periods, and adjustments.
Wallet Deployment: Block manager wallets are deployed dynamically using state initialization cells composed via BlockKeeperLib, enabling upgradeable wallet code and configuration.
Balance Assurance: The contract maintains a minimum balance ROOT_BALANCE and mints tokens when below threshold via gosh.mintshellq.
Access Control: Functions use modifiers like onlyOwner, senderIs, and accept for security and message handling, ensuring calls originate from authorized entities.

Interaction with Other Components

BlockKeeperLib: Provides utility functions for calculating wallet addresses and composing state initialization cells.
AckiNackiBlockManagerNodeWallet: The deployed wallet contracts for block managers interact with this root contract for registration, slashing, and rewards.
LicenseBMRoot Contract: Referenced by address _licenseBMRoot, likely responsible for license management related to block managers.
gosh External Contract: Provides reward calculation (calcbmmvrewardadj, calcbmreward), minting (mintshellq, mintecc), and other financial operations related to token economics.

Visual Structure Diagram

classDiagram
class BlockManagerContractRoot {
-mapping(uint8 => TvmCell) _code
-address _licenseBMRoot
-uint128 _numberOfActiveBlockManagers
-optional(address) _owner_wallet
-uint32 _networkStart
-uint64 _epochDuration
-uint64 _waitStep
-uint32 _prevEpochDuration
-uint32 _epochStart
-uint64 _epochEnd
-uint128 _numberOfActiveBlockManagersAtEpochStart
-uint128 _numberOfActiveBlockManagersAtPrevEpochStart
-uint128 _reward_adjustment
-uint128 _reward_adjustment_prev_epoch
-uint32 _reward_last_time
-uint32 _min_reward_period
-uint32 _reward_period
-uint32 _calc_reward_num
-uint128 _reward_sum
-uint128 _slash_sum
-uint128 _reward_sum_prev_epoch
-bool _is_close_owner
-uint8 _walletTouch
+BlockManagerContractRoot()
+setConfig()
+setConfigNode()
+closeRoot()
+setNewCode()
+calcRewardAdjustment()
+ensureBalance()
+increaseBM()
+deployAckiNackiBlockManagerNodeWallet()
+slashed()
+getReward()
+receive()
+getAckiNackiBlockManagerNodeWalletAddress()
+getAckiNackiBlockManagerNodeWalletCode()
+getCodes()
+getDetails()
+getVersion()
}
class AckiNackiBlockManagerNodeWallet
class BlockKeeperLib
BlockManagerContractRoot --> AckiNackiBlockManagerNodeWallet : deploys, interacts
BlockManagerContractRoot ..> BlockKeeperLib : uses utilities
BlockManagerContractRoot --> gosh : calls reward & mint functions

Usage Examples

Deploying a New Block Manager Wallet

// Example call to deploy a new block manager wallet
deployAckiNackiBlockManagerNodeWallet(pubkey, signerPubkey, whiteListLicense);

Deploys a new wallet with public keys and license whitelist.

Updating Contract Configuration

// Owner updates configuration parameters
setConfig(
    86400,       // epochDuration (e.g., 1 day)
    300,         // waitStep (e.g., 5 minutes)
    432000,      // reward_period
    432000,      // min_reward_period
    10,          // calc_reward_num
    200          // walletTouch parameter
);

Adjusts timing and reward parameters.

Requesting Reward

// Called by a block manager wallet to claim rewards
getReward(pubkey, sign_pubkey, wallet_address, rewarded, startBM, isEnd);

Calculates and transfers reward tokens based on activity and epoch.

Notes on Constants and External Dependencies

Constants like ROOT_BALANCE, FEE_DEPLOY_BLOCK_MANAGER_WALLET, MAX_LICENSE_NUMBER_WHITELIST_BM, CURRENCIES_ID are assumed defined elsewhere or imported.
External contract gosh provides core financial logic functions.
Modifiers like onlyOwner, senderIs, accept control access and message acceptance, defined in imported modifiers.sol.

This contract is central to the block management system, coordinating wallet deployments, managing epoch-based reward distributions, and maintaining system state with strict access controls and inter-contract communication patterns. For detailed understanding of utility functions and wallet interactions, refer to BlockKeeperLib and AckiNackiBlockManagerNodeWallet subtopics.