BlockManagerContractRoot.abi.json

Overview

This file defines the Application Binary Interface (ABI) for the BlockManagerContractRoot smart contract. The contract serves as a root manager for block managers within a distributed system, providing core functionalities such as configuration management, node wallet deployment, reward distribution, and lifecycle control. It maintains state variables related to epochs, reward adjustments, active block managers, and contract ownership.

The ABI specifies the contract's external interface including its functions, their inputs and outputs, and the storage fields representing the contract's state. This ABI is essential for interaction with the contract through transactions and calls, enabling other contracts or clients to invoke its methods and read its state.

Contract Structure and State Fields

The contract maintains several persistent state fields which track its configuration, operational parameters, and runtime statistics:

• _pubkey (uint256, init): The public key identifying the contract owner or main operator.

• _timestamp (uint64): Current timestamp tracked by the contract.

• _constructorFlag (bool): Flag indicating whether the constructor has been called.

• _code (map(uint8, cell)): Mapping storing various contract code cells indexed by identifiers.

• _licenseBMRoot (address): Address of the license BlockManager root contract, indicating a relationship or dependency.

• _numberOfActiveBlockManagers, _numberOfActiveBlockManagersAtEpochStart, _numberOfActiveBlockManagersAtPrevEpochStart (uint128): Counters tracking active block managers at different points in time.

• _owner_wallet (optional(address)): Optional field holding the owner's wallet address.

• _networkStart (uint32): Timestamp marking the start of the network or contract operation.

• _epochDuration, _waitStep (uint64): Configuration parameters defining the duration of epochs and waiting steps.

• _prevEpochDuration (uint32): Duration of the previous epoch for comparison or reference.

• _epochStart (uint32), _epochEnd (uint64): Epoch start and end times.

• _reward_adjustment, _reward_adjustment_prev_epoch (uint128): Reward adjustment factors for current and previous epochs.

• _reward_last_time (uint32): Timestamp of the last reward calculation.

• _min_reward_period, _reward_period (uint32): Parameters controlling reward period constraints.

• _calc_reward_num (uint32): Number of reward calculations to perform.

• _reward_sum, _reward_sum_prev_epoch (uint128): Aggregated reward amounts for current and previous epochs.

• _slash_sum (uint128): Sum of slashing penalties applied.

• _is_close_owner (bool): Flag indicating whether the owner has closed the contract.

• _walletTouch (uint8): Parameter related to wallet interaction frequency or control.

Functions

constructor

• Purpose: Initializes the contract with initial configuration parameters.

• Inputs:

  • licenseBMRoot (address): Address of the license BlockManager root.

  • epochDuration (uint64): Duration of an epoch.

  • waitStep (uint64): Waiting step duration.

  • reward_adjustment (uint128): Initial reward adjustment factor.

  • walletTouch (uint8): Wallet touch parameter.

• Outputs: None.

• Usage: Called once during deployment to set up initial contract state.

setConfig

• Purpose: Updates the contract's operational configuration parameters.

• Inputs:

  • epochDuration (uint64): New epoch duration.

  • waitStep (uint64): New wait step duration.

  • reward_period (uint32): Reward distribution period.

  • min_reward_period (uint32): Minimum allowable reward period.

  • calc_reward_num (uint32): Number of reward calculations.

  • walletTouch (uint8): Wallet interaction parameter.

• Outputs: None.

• Usage: Allows dynamic configuration updates to adapt contract behavior.

setConfigNode

• Purpose: Similar to setConfig, likely used for configuration at a node-specific level.

• Inputs: Same as setConfig.

• Outputs: None.

• Usage: Used to set or update configuration parameters potentially scoped to nodes.

closeRoot

• Purpose: Closes the root contract, likely disabling further operations or signaling contract termination.

• Inputs: None.

• Outputs: None.

• Usage: Called to safely close or deactivate the contract.

setNewCode

• Purpose: Updates or sets new contract code cells.

• Inputs:

  • id (uint8): Identifier for the code cell.

  • code (cell): The code cell data.

• Outputs: None.

• Usage: Enables upgrading or patching contract code components dynamically.

increaseBM

• Purpose: Registers or increments a block manager identified by a public key.

• Inputs:

  • pubkey (uint256): Public key of the block manager.

• Outputs: None.

• Usage: Adds or updates the count of active block managers.

deployAckiNackiBlockManagerNodeWallet

• Purpose: Deploys a node wallet contract associated with a block manager.

• Inputs:

  • pubkey (uint256): Public key of the block manager.

  • signerPubkey (uint256): Public key of the signer.

  • whiteListLicense (map(uint256,bool)): Whitelist of licenses.

• Outputs: None.

• Usage: Facilitates deployment of node wallets with license control and signer verification.

slashed

• Purpose: Records a slashing event for a block manager.

• Inputs:

  • pubkey (uint256): Public key of the block manager.

  • isWorking (bool): Indicates if the block manager was working during slashing.

• Outputs: None.

• Usage: Used to penalize or mark block managers for misbehavior or downtime.

getReward

• Purpose: Processes reward distribution to a block manager.

• Inputs:

  • pubkey (uint256): Block manager's public key.

  • sign_pubkey (uint256): Signer's public key.

  • wallet_address (address): Address of the recipient wallet.

  • rewarded (uint32): Amount rewarded so far.

  • startBM (uint32): Starting block manager index or count.

  • isEnd (bool): Indicates if this is the last reward distribution in the batch.

• Outputs: None.

• Usage: Manages reward allocation and accounting for block managers.

getAckiNackiBlockManagerNodeWalletAddress

• Purpose: Retrieves the wallet address for a block manager node wallet.

• Inputs:

  • pubkey (uint256): Public key of the block manager.

• Outputs:

  • wallet (address): The wallet address.

• Usage: Allows querying of deployed node wallet addresses.

getAckiNackiBlockManagerNodeWalletCode

• Purpose: Fetches the contract code cell related to node wallets.

• Inputs: None.

• Outputs:

  • data (cell): Code cell data.

• Usage: Provides access to the node wallet contract code.

getCodes

• Purpose: Retrieves the mapping of all code cells stored in the contract.

• Inputs: None.

• Outputs:

  • code (map(uint8,cell)): Mapping of code identifiers to code cells.

• Usage: Enables inspection or backup of contract code components.

getDetails

• Purpose: Returns summary statistics of the contract state.

• Inputs: None.

• Outputs:

  • reward_sum (uint128): Total rewards distributed.

  • slash_sum (uint128): Total slashing penalties.

  • numberOfActiveBlockManagers (uint128): Current count of active block managers.

  • numberOfActiveBlockManagersAtEpochStart (uint128): Count at epoch start.

• Usage: Used for monitoring and reporting contract state metrics.

getVersion

• Purpose: Returns the version information of the contract.

• Inputs: None.

• Outputs:

  • value0 (string): Version string part 1.

  • value1 (string): Version string part 2.

• Usage: Provides versioning information for compatibility and upgrade tracking.

Implementation Details and Algorithms

• The contract uses epoch-based time segmentation to manage reward calculations and block manager activity tracking. This allows for periodic reward adjustments and slashing enforcement based on epoch boundaries.

• Reward adjustments are maintained separately for current and previous epochs, facilitating smooth transition and calculation of rewards.

• Block manager nodes are dynamically deployed with individual wallets, enabled by the deployAckiNackiBlockManagerNodeWallet function. This deployment uses public keys and license whitelisting for secure and authorized creation.

• Slashing is implemented through the slashed function, allowing the contract to penalize block managers based on their operational status, impacting reward sums and active counts.

• The contract supports code upgrades by storing multiple code cells that can be updated via setNewCode. This modularity supports flexibility in contract logic evolution.

• Various configuration parameters can be adjusted on-chain using setConfig and setConfigNode, allowing for tuning of epoch durations, reward periods, and wallet interaction parameters without redeploying the contract.

Interactions with Other Components

• License BlockManager Root: The _licenseBMRoot field stores an address pointing to a licensing root contract, indicating dependency or interaction for licensing validation of block managers.

• Block Manager Node Wallets: The contract deploys and manages individual node wallets for block managers, facilitating decentralized management and reward distribution.

• External Wallets: Reward distribution functions interact with external wallet addresses provided by block managers or signers.

• Upgrade Mechanism: Through the code cell map and setNewCode function, the contract interacts with its own upgrade system, allowing replacement or modification of contract logic components.

• Epoch Timing and Reward Systems: The contract's timing and reward parameters are designed to integrate with broader system timekeeping and incentive mechanisms, coordinating with other contracts or off-chain components that track network epochs and block manager activity.

Mermaid Diagram: Contract Structure and Function Overview

classDiagram
class BlockManagerContractRoot {
+constructor()
+setConfig()
+setConfigNode()
+closeRoot()
+setNewCode()
+increaseBM()
+deployAckiNackiBlockManagerNodeWallet()
+slashed()
+getReward()
+getAckiNackiBlockManagerNodeWalletAddress()
+getAckiNackiBlockManagerNodeWalletCode()
+getCodes()
+getDetails()
+getVersion()
-_pubkey: uint256
-_timestamp: uint64
-_constructorFlag: bool
-_code: map(uint8,cell)
-_licenseBMRoot: address
-_numberOfActiveBlockManagers: uint128
-_owner_wallet: optional(address)
-_networkStart: uint32
-_epochDuration: uint64
-_waitStep: uint64
-_prevEpochDuration: uint32
-_epochStart: uint32
-_epochEnd: uint64
-_numberOfActiveBlockManagersAtEpochStart: uint128
-_numberOfActiveBlockManagersAtPrevEpochStart: uint128
-_reward_adjustment: uint128
-_reward_adjustment_prev_epoch: uint128
-_reward_last_time: uint32
-_min_reward_period: uint32
-_reward_period: uint32
-_calc_reward_num: uint32
-_reward_sum: uint128
-_slash_sum: uint128
-_reward_sum_prev_epoch: uint128
-_is_close_owner: bool
-_walletTouch: uint8
}