BlockKeeperEpochContract.abi.json

Overview

This file defines the Application Binary Interface (ABI) for the BlockKeeperEpochContract, a smart contract responsible for managing the lifecycle and state of block keepers within an epoch-based system. The contract facilitates operations such as initializing block keepers with stake and public keys, managing stake continuation, slashing penalties, lifecycle control (including destruction), and querying contract details. The ABI format describes the contract's functions, their inputs and outputs, and the state variables (fields) maintained by the contract.

The contract’s primary role is to handle stake management and reputation within a system where multiple block keepers operate over defined epochs, ensuring proper continuation, penalization, and destruction mechanisms align with the system’s epoch lifecycle.

Classes, Functions, and Methods

The file does not define traditional classes but instead specifies the contract interface with a set of functions and state fields. These functions represent the callable methods on the smart contract.

Functions

constructor

• Purpose: Initializes a new block keeper contract instance.

• Inputs:

  • waitStep (uint64): Waiting step duration parameter.

  • epochDuration (uint64): Duration of an epoch.

  • bls_pubkey (bytes): The BLS public key of the block keeper.

  • code (map(uint8,cell)): Code map for the contract.

  • sumReputationCoef (uint128): Aggregate reputation coefficient for the block keeper.

  • signerIndex (uint16): Index of the signer in the consensus group.

  • licenses (tuple[]): List of licenses, each with num (uint256) and stake (uint128).

  • virtualStake (optional(uint128)): Optional virtual stake value.

  • reward_sum (uint128): Sum of rewards accumulated.

  • myIp (string): IP address of the node.

  • isContinue (bool): Flag indicating if this stake is a continuation.

  • timeStart (optional(uint32)): Optional start time in UNIX time.

  • nodeVersion (optional(string)): Optional node software version.

• Outputs: None.

• Usage Example:

  constructor(
      waitStepValue,
      epochDurationValue,
      blsPublicKeyBytes,
      codeMap,
      reputationCoefficient,
      signerIndexValue,
      licensesArray,
      optionalVirtualStake,
      rewardSumValue,
      ipString,
      isContinuationFlag,
      optionalStartTime,
      optionalNodeVersion
  );
  

setStake

• Purpose: Sets or updates stake parameters for active block keepers.

• Inputs:

  • numberOfActiveBlockKeepers (uint128): Number of active block keepers.

  • gparam (uint256): General parameter used in stake calculation or consensus.

• Outputs: None.

• Usage Example:

  setStake(activeBlockKeepersCount, gparamValue);
  

continueStake

• Purpose: Continues stake for a block keeper, potentially extending their active participation.

• Inputs:

  • bls_pubkey (bytes): BLS public key for continuation.

  • signerIndex (uint16): Signer index for continuation.

  • licenses (tuple[]): Updated licenses for continuation.

  • virtualStake (optional(uint128)): Optional virtual stake for continuation.

  • ProxyList (map(uint8,string)): Proxy list mapping for continuation.

  • sumReputationCoef (uint128): Reputation coefficient for continuation.

  • nodeVersionContinue (optional(string)): Optional node version for continuation.

• Outputs: None.

• Usage Example:

  continueStake(blsPubkeyBytes, signerIdx, licensesList, optionalVirtualStake, proxyMap, reputationCoef, optionalNodeVersion);
  

cancelContinueStake

• Purpose: Cancels a previously initiated stake continuation.

• Inputs: None.

• Outputs: None.

• Usage Example:

  cancelContinueStake();
  

slash

• Purpose: Applies slashing penalties to the block keeper for misbehavior or protocol violations.

• Inputs:

  • slash_type (uint8): Type of slashing penalty to apply.

• Outputs: None.

• Usage Example:

  slash(slashTypeValue);
  

touch

• Purpose: Updates or refreshes contract state, likely to prevent timeout or maintain active status.

• Inputs: None.

• Outputs: None.

• Usage Example:

  touch();
  

cantDelete

• Purpose: Marks the contract or block keeper stake as non-deletable, preventing destruction.

• Inputs: None.

• Outputs: None.

• Usage Example:

  cantDelete();
  

canDelete

• Purpose: Evaluates whether the contract can be safely deleted based on reward and timing parameters.

• Inputs:

  • reward (uint256): Reward amount to consider.

  • epochDuration (uint64): Duration of the epoch.

  • waitStep (uint64): Waiting step duration.

  • reward_sum (uint128): Total accumulated rewards.

• Outputs: None.

• Usage Example:

  canDelete(rewardAmount, epochDurationValue, waitStepValue, totalRewardSum);
  

destroy

• Purpose: Destroys the contract instance, cleaning up resources and ending participation.

• Inputs:

  • epochDurationContinue (uint64): Epoch duration relevant to continuation.

  • waitStepContinue (uint64): Waiting step for continuation.

  • reward_sum_continue (uint128): Reward sum for continuation.

• Outputs: None.

• Usage Example:

  destroy(epochDurationContinue, waitStepContinue, rewardSumContinue);
  

destroy_full_slash

• Purpose: Performs a full slashing destruction of the contract, likely for severe misbehavior.

• Inputs: None.

• Outputs: None.

• Usage Example:

  destroy_full_slash();
  

getDetails

• Purpose: Retrieves comprehensive details about the contract and its current state.

• Inputs: None.

• Outputs:

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

  • root (address): Root address of the contract.

  • seqNoStart (uint64): Sequence number at start.

  • seqNoFinish (uint64): Sequence number at finish.

  • owner (address): Owner address.

  • continueStakes (uint256): Number of continuation stakes.

  • isContinue (bool): Continuation status flag.

  • signerIndex (uint16): Current signer index.

  • signerIndexContinue (uint16): Continuation signer index.

  • proxyListContinue (map(uint8,string)): Proxy list for continuation.

  • myIp (string): IP address of the node.

• Usage Example:

  (pubkey, root, seqStart, seqFinish, ownerAddr, contStakes, isCont, signerIdx, signerIdxCont, proxyListCont, ip) = getDetails();
  

getProxyListContinue

• Purpose: Returns the proxy list map used for stake continuation.

• Inputs: None.

• Outputs:

  • proxyListContinue (map(uint8,string)): Proxy mapping for continuation.

• Usage Example:

  proxyList = getProxyListContinue();
  

getEpochCoolerCodeHash

• Purpose: Retrieves the hash of the epoch cooler code, potentially for verification or upgrade purposes.

• Inputs: None.

• Outputs:

  • epochCoolerCodeHash (uint256): Hash value of the epoch cooler code.

• Usage Example:

  codeHash = getEpochCoolerCodeHash();
  

getVersion

• Purpose: Returns the version string(s) associated with the contract.

• Inputs: None.

• Outputs:

  • value0 (string): First version string.

  • value1 (string): Second version string.

• Usage Example:

  (ver0, ver1) = getVersion();
  

Fields (State Variables)

The contract maintains numerous state variables, which store configuration and state data:

• _pubkey (uint256): Public key of the block keeper; set at initialization.

• _timestamp (uint64): Timestamp of the last update or action.

• _constructorFlag (bool): Flag indicating if constructor has run.

• _code (map(uint8,cell)): Contract code mapping.

• _owner_pubkey (uint256): Public key of the owner.

• _root (address): Root contract address.

• _seqNoStart (uint64): Starting sequence number for epochs.

• _seqNoFinish (uint64): Ending sequence number.

• _bls_pubkey (bytes): BLS public key bytes.

• _isContinue (bool): Indicates stake continuation.

• _waitStep (uint64): Waiting step duration.

• _stake (uint128): Stake amount.

• _owner_address (address): Owner's blockchain address.

• _bls_pubkeyContinue (bytes): BLS public key for continuation.

• _stakeContinue (uint128): Stake amount for continuation.

• _numberOfActiveBlockKeepers (uint128): Number of active block keepers.

• _unixtimeStart (uint32): UNIX timestamp for start.

• _sumReputationCoef (uint128): Sum of reputation coefficients.

• _sumReputationCoefContinue (uint128): Reputation coefficient for continuation.

• _signerIndex (uint16): Signer index.

• _signerIndexContinue (uint16): Signer index for continuation.

• _proxyListContinue (map(uint8,string)): Proxy list for continuation.

• _myIp (string): IP address of node.

• _licenses (tuple[]): List of licenses with num and stake.

• _licensesContinue (tuple[]): Licenses for continuation.

• _virtualStake (optional(uint128)): Optional virtual stake.

• _virtualStakeContinue (optional(uint128)): Virtual stake continuation.

• _reward_sum (uint128): Sum of rewards.

• _busy_seqno (uint64): Busy sequence number for concurrency control.

• _is_full_slashing (bool): Flag for full slashing status.

• _is_touching (bool): Flag indicating if contract is being "touched" or refreshed.

• _slash_type (optional(uint8)): Optional slashing type.

• _gparam (uint256): General parameter used in staking or consensus.

• _nodeVersion (optional(string)): Node software version.

• _nodeVersionContinue (optional(string)): Node version for continuation.

Important Implementation Details

• Stake Continuation: The contract supports continuation of stakes through continueStake and related fields like _bls_pubkeyContinue, _stakeContinue, and _proxyListContinue. This enables block keepers to extend or modify their participation in the network epochs.

• Slashing Mechanism: Slashing is handled by slash and destroy_full_slash functions. The contract keeps track of slashing state (_is_full_slashing), types (_slash_type), and can fully destroy the contract in the case of severe faults.

• Lifecycle Management: Functions like touch, cantDelete, canDelete, and destroy manage the lifecycle, health, and cleanup of block keeper contracts.

• Licenses: The contract maintains a list of licenses associated with the block keeper, each with a unique number and stake, supporting complex stake structures.

• Versioning: The contract stores optional node version information and allows retrieval of version strings via getVersion.

• Proxy List: Proxy lists are maintained and can be updated or queried, facilitating delegation or proxying mechanisms for block keeper nodes.

• Epoch Parameters: Key parameters like waitStep, epochDuration, and reward_sum control timing and reward aspects aligned with the epoch-based operation model.

Interaction with Other Parts of the System

• The contract is designed to operate within an epoch-based blockchain system where block keepers participate in consensus and block production.

• It interacts with root contracts or managing entities via fields such as _root and _owner_address.

• The code field and getEpochCoolerCodeHash function suggest interaction with upgradeable or modular contract code components.

• Management of licenses and proxy lists indicates integration with reputation and delegation subsystems.

• Slashing and destruction functions tie into network security and penalty enforcement mechanisms.

• The stake continuation methods suggest coordination with stake management or epoch transition logic in the broader system.

Diagram: Contract Function and State Interaction Flow

flowchart TD
constructor --> setStake
setStake --> continueStake
continueStake --> cancelContinueStake
continueStake --> getProxyListContinue
continueStake --> getDetails
slash --> destroy_full_slash
canDelete --> destroy
touch --> cantDelete
getVersion --> getEpochCoolerCodeHash
subgraph State Variables
_pubkey
_bls_pubkey
_stake
_licenses
_proxyListContinue
_reward_sum
_signerIndex
_isContinue
_nodeVersion
_is_full_slashing
end
constructor -->|sets| _pubkey
constructor -->|sets| _bls_pubkey
constructor -->|sets| _licenses
setStake -->|updates| _stake
continueStake -->|updates| _proxyListContinue
slash -->|sets| _is_full_slashing
destroy -->|clears| _stake
getDetails -->|reads| State Variables
getProxyListContinue -->|reads| _proxyListContinue

This flowchart illustrates the primary function call relationships and their impact on key state variables within the contract. It highlights the lifecycle from construction through stake management, continuation, slashing, and potential destruction.