BlockKeeperContractRoot.abi.json

Overview

This file defines the Application Binary Interface (ABI) for the BlockKeeperContractRoot smart contract. The contract primarily manages the root logic of block keepers within a blockchain network, including configuration management, stake handling, block keeper node deployment, reward calculation, and address/code retrieval for various related components.

The ABI version is 2, and the contract version is 2.4. The contract uses a header consisting of public key, time, and expire fields, which are common for transaction validation and security.

The contract encapsulates key functionalities to maintain the block keeper ecosystem, ensuring proper stake management, node registration, slashing mechanisms, and epoch-related operations.

Structure and Components

Fields

The contract maintains a set of persistent fields representing the state of the block keeper root. Key fields include:

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

• _timestamp (uint64): Tracks the last update time.

• _constructorFlag (bool): Flags if the constructor was executed.

• _notion (string): A string notion or description associated with the contract.

• _code (map(uint8,cell)): Stores different pieces of contract code indexed by an ID.

• _epochDuration, _epochCliff, _waitStep (uint64): Configuration parameters related to the epoch timing.

• _minBlockKeepers (uint128): Minimum number of block keepers required.

• _totalStake (uint256): Total stake managed by the contract.

• _licenseRoot (address): Address of the license root contract.

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

• _networkStart (uint32): Timestamp or block number marking network start.

• _numberOfActiveBlockKeepers (uint128): Current count of active block keepers.

• _block_seqno (uint32): Sequence number of the current block.

• _numberOfActiveBlockKeepersAtBlockStart (uint128): Count of active block keepers at block start.

• _needNumberOfActiveBlockKeepers (uint128): Required number of active block keepers.

• _isNeedNumberOfActiveBlockKeepers (bool): Flag indicating if a specific number of active block keepers is required.

• _reward_sum, _slash_sum (uint128): Summations for rewards and slashing.

• _nlinit, _mbkOld (uint128): Initialization and historical parameters.

• _is_close_owner (bool): Indicates if the owner has closed the root.

• _Gparam, _REMparam (uint256), _Bparam (uint32): Various parameters likely used in calculations and governance.

Functions

constructor(licenseRoot: address)

• Purpose: Initializes the contract with the license root address.

• Inputs:

  • licenseRoot: Address of the license root contract.

• Outputs: None

• Usage: Called once at deployment to set the license root.

closeRoot()

• Purpose: Closes the root contract, potentially restricting further operations.

• Inputs: None

• Outputs: None

setConfig(epochDuration: uint64, minBlockKeepers: uint128, isNeedNumberOfActiveBlockKeepers: bool, needNumberOfActiveBlockKeepers: uint128, walletTouch: uint8, nlinit: uint128)

• Purpose: Updates configuration parameters for the block keeper root.

• Inputs:

  • epochDuration: Duration of each epoch.

  • minBlockKeepers: Minimum block keepers required.

  • isNeedNumberOfActiveBlockKeepers: Flag to enforce minimum number of active block keepers.

  • needNumberOfActiveBlockKeepers: Required number of active block keepers.

  • walletTouch: Wallet interaction parameter.

  • nlinit: Initialization parameter.

• Outputs: None

setConfigNode(...)

• Same signature and purpose as setConfig, likely used for node-specific configuration updates.

deployAckiNackiBlockKeeperNodeWallet(pubkey: uint256, whiteListLicense: map(uint256,bool))

• Purpose: Deploys a block keeper node wallet with acknowledgment and negative acknowledgment mechanisms.

• Inputs:

  • pubkey: Public key for the node wallet.

  • whiteListLicense: Map of licenses whitelisted for the node.

• Outputs: None

coolerSlash(seqNoStart: uint64, pubkey: uint256)

• Purpose: Performs slashing on a block keeper starting from a sequence number.

• Inputs:

  • seqNoStart: Starting sequence number for slashing.

  • pubkey: Public key of the block keeper being slashed.

• Outputs: None

decreaseStakes(pubkey: uint256, seqNoStart: uint64, slash_stake: uint128, rep_coef: uint128)

• Purpose: Decreases the stake of a block keeper due to slashing or penalties.

• Inputs:

  • pubkey: Public key of the block keeper.

  • seqNoStart: Sequence number from which to start decreasing stakes.

  • slash_stake: Amount of stake to slash.

  • rep_coef: Reputation coefficient affecting stake decrease.

• Outputs: None

increaseActiveBlockKeeperNumber(pubkey: uint256, seqNoStart: uint64, stake: uint128, rep_coef: uint128, virtualStake: optional(uint128))

• Purpose: Increments the count of active block keepers, considering stakes and reputation.

• Inputs:

  • pubkey: Public key of the block keeper.

  • seqNoStart: Sequence number marking the start.

  • stake: Stake amount.

  • rep_coef: Reputation coefficient.

  • virtualStake: Optional virtual stake parameter.

• Outputs: None

receiveBlockKeeperRequestWithStakeFromWallet(pubkey: uint256, bls_pubkey: bytes, signerIndex: uint16, rep_coef: uint128, is_min: bool, ProxyList: map(uint8,string), myIp: string, nodeVersion: optional(string))

• Purpose: Handles incoming requests from wallets to register block keepers with stake.

• Inputs:

  • pubkey: Public key of the block keeper.

  • bls_pubkey: BLS public key bytes.

  • signerIndex: Index of the signer.

  • rep_coef: Reputation coefficient.

  • is_min: Flag indicating if this is a minimum stake.

  • ProxyList: Map of proxies.

  • myIp: IP address of the node.

  • nodeVersion: Optional version string of the node software.

• Outputs: None

isBLSAccepted(wallet: address, pubkey: uint256, bls_pubkey: bytes, stake: uint128, isNotOk: bool, signerIndex: uint16, rep_coef: uint128, virtualStake: optional(uint128), ProxyList: map(uint8,string), myIp: string, nodeVersion: optional(string))

• Purpose: Checks if a BLS key is accepted for a block keeper wallet.

• Inputs: As above, including wallet address and stake parameters.

• Outputs: None

isSignerIndexAccepted(...)

• Same signature and purpose as isBLSAccepted but focuses on signer index acceptance.

receiveBlockKeeperRequestWithStakeFromWalletContinue(pubkey: uint256, bls_pubkey: bytes, seqNoStartOld: uint64, signerIndex: uint16, is_min: bool, ProxyList: map(uint8,string), seqNoFinish: uint64, sumReputationCoef: uint128, nodeVersion: optional(string))

• Purpose: Continues processing block keeper stake requests from wallets.

• Inputs: Similar to receiveBlockKeeperRequestWithStakeFromWallet with additional parameters for sequence finishing and cumulative reputation.

• Outputs: None

isBLSAcceptedContinue(...)

• Continuation of the BLS acceptance check with additional sequence and reputation parameters.

isSignerIndexContinue(...)

• Continuation of signer index acceptance with additional parameters.

setNewCode(id: uint8, code: cell)

• Purpose: Updates or sets new code identified by an ID.

• Inputs:

  • id: Identifier for the code piece.

  • code: The new code cell.

• Outputs: None

decreaseActiveBlockKeeper(pubkey: uint256, rep_coef: uint128, seqNoStart: uint64, stake: uint128, virtualStake: optional(uint128), reward_sum: uint128, gparam: uint256, isSlash: bool)

• Purpose: Decreases active block keeper status, potentially due to penalties or stake reductions.

• Inputs:

  • pubkey: Public key of the block keeper.

  • rep_coef: Reputation coefficient.

  • seqNoStart: Sequence number start.

  • stake: Stake amount.

  • virtualStake: Optional virtual stake.

  • reward_sum: Sum of rewards.

  • gparam: Parameter likely used in calculations.

  • isSlash: Flag indicating if this is a slashing operation.

• Outputs: None

getBlockKeeperCoolerAddress(pubkey: uint256, seqNoStart: uint64) -> address

• Purpose: Retrieves the cooler address for a block keeper.

• Inputs:

  • pubkey: Public key of the block keeper.

  • seqNoStart: Sequence number start.

• Outputs:

  • value0: Address of the cooler contract.

getAckiNackiBlockKeeperNodeWalletAddress(pubkey: uint256) -> address

• Purpose: Retrieves the wallet address for the AckiNacki block keeper node.

• Inputs:

  • pubkey: Public key of the node.

• Outputs:

  • wallet: Address of the node wallet.

getAckiNackiBlockKeeperNodeWalletCode() -> cell

• Purpose: Returns the code associated with the AckiNacki block keeper node wallet.

• Inputs: None

• Outputs:

  • data: Code cell.

getBlockKeeperEpochCode() -> cell

• Purpose: Returns the code used for block keeper epochs.

• Inputs: None

• Outputs:

  • epochCode: Code cell for epoch.

getBlockKeeperEpochAddress(pubkey: uint256, seqNoStart: uint64) -> address

• Purpose: Gets the address of a block keeper epoch.

• Inputs:

  • pubkey: Public key.

  • seqNoStart: Sequence start.

• Outputs:

  • epochAddress: Epoch contract address.

getBlockKeeperPreEpochAddress(pubkey: uint256, seqNoStart: uint64) -> address

• Purpose: Gets the address of the pre-epoch block keeper contract.

• Inputs:

  • Same as above.

• Outputs:

  • preEpochAddress: Address of the pre-epoch contract.

getDetails() -> (minStake: uint128, numberOfActiveBlockKeepers: uint128)

• Purpose: Returns key details about the block keeper root.

• Inputs: None

• Outputs:

  • minStake: Minimum stake required.

  • numberOfActiveBlockKeepers: Current count.

getEpochCodeHash() -> uint256

• Purpose: Returns the hash of the epoch code.

• Inputs: None

• Outputs:

  • epochCodeHash: Hash value.

getPreEpochCodeHash() -> uint256

• Purpose: Returns the hash of the pre-epoch code.

• Inputs: None

• Outputs:

  • preEpochCodeHash: Hash value.

getRewardOut(reward_sum: uint128, rep_coef: uint128, gparam: uint256, stake: uint128) -> uint128

• Purpose: Calculates the reward output based on input parameters.

• Inputs:

  • reward_sum: Total rewards.

  • rep_coef: Reputation coefficient.

  • gparam: Parameter affecting reward.

  • stake: Stake amount.

• Outputs:

  • reward: Calculated reward.

getProxyListCode() -> cell

• Purpose: Provides the code cell representing the proxy list.

• Inputs: None

• Outputs:

  • code: Code cell of proxies.

getProxyListAddress(pubkey: uint256) -> address

• Purpose: Retrieves the proxy list address for a given public key.

• Inputs:

  • pubkey: Public key.

• Outputs:

  • proxyAddress: Address of proxy list.

getRewardNow(rep_coef: uint128, stake: uint128) -> uint128

• Purpose: Returns the immediate reward based on reputation and stake.

• Inputs:

  • rep_coef: Reputation coefficient.

  • stake: Stake amount.

• Outputs:

  • reward: Reward value.

getMinStakeNow() -> uint128

• Purpose: Returns the current minimum stake.

• Inputs: None

• Outputs:

  • minstake: Minimum stake.

getMaxStakeNow() -> uint128

• Purpose: Returns the current maximum stake.

• Inputs: None

• Outputs:

  • maxstake: Maximum stake.

getConfig() -> (epochDuration: uint64, epochCliff: uint64, waitStep: uint64)

• Purpose: Retrieves current configuration parameters.

• Inputs: None

• Outputs:

  • epochDuration, epochCliff, waitStep: Configuration values.

getSignerIndexAddress(index: uint16) -> address

• Purpose: Returns the address corresponding to a signer index.

• Inputs:

  • index: Signer index.

• Outputs:

  • signerIndex: Address of signer.

getMinStakeOut(reward_sum: uint128, timeEpochStart: uint128, numberOfActiveBlockKeepersAtBlockStart: uint128, needNumberOfActiveBlockKeepers: uint128) -> uint128

• Purpose: Calculates the minimum stake based on multiple parameters.

• Inputs:

  • reward_sum, timeEpochStart, numberOfActiveBlockKeepersAtBlockStart, needNumberOfActiveBlockKeepers

• Outputs:

  • minstake: Minimum stake value.

getBLSIndexAddress(bls_key: bytes) -> address

• Purpose: Retrieves the address associated with a BLS key.

• Inputs:

  • bls_key: BLS public key bytes.

• Outputs:

  • blsAddress: Address linked to the BLS key.

getCodes() -> map(uint8,cell)

• Purpose: Returns the map of all code cells indexed by their IDs.

• Inputs: None

• Outputs:

  • code: Map of codes.

getVersion() -> (string, string)

• Purpose: Returns the version info of the contract.

• Inputs: None

• Outputs:

  • Two string values representing version details.

_notion() -> string

• Purpose: Returns the notion string stored in the contract.

• Inputs: None

• Outputs:

  • _notion: The string notion.

Important Implementation Details

• The contract maintains a detailed ledger of block keeper states, including active counts, stakes, and reputation coefficients.

• Stake management functions handle both increases and decreases, reflecting changes due to slashing or reward calculations.

• The contract supports multi-stage requests for block keeper registration, with continuation functions helping to handle complex or asynchronous workflows.

• Code management is modular, with functions to update and retrieve different pieces of contract code (cells), enabling upgradability or multi-contract deployment.

• Reward calculation leverages parameters like stake, reputation coefficient, and configurable parameters (_Gparam, _REMparam, _Bparam) to compute incentives.

• Slashing mechanisms are integrated to penalize block keepers failing to meet criteria, ensuring network security and reliability.

Interaction with Other System Components

• License Root Contract: The contract references _licenseRoot for license validation or coordination.

• Block Keeper Node Wallets: Functions like deployAckiNackiBlockKeeperNodeWallet and retrievals of node wallet addresses indicate interaction with individual block keeper wallets.

• Epoch Contracts: Epoch-related methods manage different epochs (getBlockKeeperEpochAddress, getBlockKeeperPreEpochAddress) to track block keeper participation over time.

• Proxy Lists: Proxy list management is supported through code and address getters, indicating a layered network topology or proxy usage.

• BLS and Signer Index Management: Methods to validate and accept BLS keys and signer indices show integration with cryptographic identity components.

• Reward and Slashing Calculations: Reward-related inputs and outputs connect to incentive and penalty subsystems.

Visual Diagram: Function Structure Flowchart

flowchart TD
    constructor --> setConfig
    constructor --> setConfigNode

    setConfig --> deployAckiNackiBlockKeeperNodeWallet
    setConfigNode --> deployAckiNackiBlockKeeperNodeWallet

    deployAckiNackiBlockKeeperNodeWallet --> receiveBlockKeeperRequestWithStakeFromWallet
    receiveBlockKeeperRequestWithStakeFromWallet --> isBLSAccepted
    receiveBlockKeeperRequestWithStakeFromWallet --> isSignerIndexAccepted

    receiveBlockKeeperRequestWithStakeFromWallet --> receiveBlockKeeperRequestWithStakeFromWalletContinue
    receiveBlockKeeperRequestWithStakeFromWalletContinue --> isBLSAcceptedContinue
    receiveBlockKeeperRequestWithStakeFromWalletContinue --> isSignerIndexContinue

    coolerSlash --> decreaseStakes
    coolerSlash --> decreaseActiveBlockKeeper

    increaseActiveBlockKeeperNumber --> getDetails
    decreaseActiveBlockKeeper --> getDetails

    getBlockKeeperCoolerAddress --> getAckiNackiBlockKeeperNodeWalletAddress
    getAckiNackiBlockKeeperNodeWalletAddress --> getAckiNackiBlockKeeperNodeWalletCode

    getBlockKeeperEpochCode --> getBlockKeeperEpochAddress
    getBlockKeeperEpochCode --> getBlockKeeperPreEpochAddress

    getRewardOut --> getRewardNow
    getRewardNow --> getMinStake