BlockKeeperPreEpochContract.abi.json

Overview

BlockKeeperPreEpochContract.abi.json defines the Application Binary Interface (ABI) for the BlockKeeper Pre-Epoch smart contract. This contract is designed to manage the state and lifecycle of a "pre-epoch" phase in a blockchain consensus or staking system. It facilitates initialization, state maintenance, and controlled destruction of the contract instance, while also exposing functions to retrieve contract metadata such as public keys, version info, and ownership details.

The ABI specification includes definitions for the contract's constructor, state-changing functions, query functions, and storage fields. This file serves as a crucial interface layer, enabling interaction with the contract on-chain and integration with other components of the consensus or staking protocol ecosystem.

Contract Functions

constructor

• Purpose: Initializes the contract with essential parameters and configurations for the pre-epoch operation phase.

• Inputs:

  • waitStep (uint64): A timing parameter controlling waiting steps before state transitions.

  • epochDuration (uint64): Duration of an epoch in time units.

  • bls_pubkey (bytes): The BLS public key used for signature verification.

  • code (map(uint8,cell)): A map containing code cells indexed by uint8, potentially for upgrade or modular logic.

  • signerIndex (uint16): Index identifier for the signer in a multi-signer setup.

  • rep_coef (uint128): Reputation coefficient affecting consensus or stake weight.

  • licenses (tuple[]): An array of tuples, each representing a license with:

    • num (uint256): License number or identifier.

    • stake (uint128): Stake amount associated with the license.

  • virtualStake (optional(uint128)): Optional virtual stake amount, possibly adding to effective stake.

  • ProxyList (map(uint8,string)): Mapping of proxies by id to their string addresses or identifiers.

  • reward_sum (uint128): Accumulated reward sum starting value.

  • myIp (string): The node's IP address as a string.

  • epochCliff (uint64): A cliff period parameter for epochs, possibly for delayed effects.

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

• Outputs: None.

• Usage Example:

  constructor(
    10, 
    3600, 
    blsPubkeyBytes, 
    codeMap, 
    1, 
    5000, 
    licensesArray, 
    optionalVirtualStake, 
    proxyMap, 
    0, 
    "192.168.1.1", 
    5, 
    optionalNodeVersion
  );
  

destroy

• Purpose: Destroys the contract instance, optionally deleting proxy data.

• Inputs:

  • isProxyDelete (bool): Flag indicating whether to delete the proxy list on destruction.

• Outputs: None.

• Usage: Invoked when the contract lifecycle ends or is being forcefully terminated.

touch

• Purpose: Updates or refreshes the contract state; typically used to keep the contract active or update timestamps.

• Inputs: None.

• Outputs: None.

• Usage: Called periodically to maintain contract liveness or trigger state updates.

touchIn

• Purpose: Similar to touch, but may be invoked internally or via specific authorized messages.

• Inputs: None.

• Outputs: None.

cancelPreEpoch

• Purpose: Cancels the ongoing pre-epoch phase, likely reverting or halting state transitions related to epoch preparation.

• Inputs: None.

• Outputs: None.

getDetails

• Purpose: Retrieves key identifying details of the contract.

• Inputs: None.

• Outputs:

  • pubkey (uint256): The public key associated with the contract.

  • root (address): The root address related to the contract's deployment or ownership.

  • seqNoStart (uint64): Sequence number marking the start of the contract lifecycle.

  • owner (address): The owner address controlling the contract.

• Usage Example:

  (pubkey, root, seqNoStart, owner) = getDetails();
  

getVersion

• Purpose: Returns versioning information for the contract.

• Inputs: None.

• Outputs:

  • value0 (string): Primary version string.

  • value1 (string): Secondary version string or sub-version.

• Usage: Useful for compatibility checks or debugging.

Storage Fields

The contract maintains several internal state fields, which include:

• _pubkey (uint256, init): Public key initialized at deployment.

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

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

• _code (map(uint8,cell)): Stores code segments or modules.

• _owner_pubkey (uint256, init): Owner's public key.

• _root (address): Root address associated with the contract.

• _seqNoStart (uint64, init): Starting sequence number.

• _seqNoDestruct (uint64): Sequence number at destruction.

• _epochDuration (uint64): Duration of each epoch.

• _waitStep (uint64): Waiting step parameter.

• _bls_pubkey (bytes): BLS public key bytes.

• _stake (varuint32): Stake amount.

• _signerIndex (uint16): Signer index.

• _sumReputationCoef (uint128): Sum of reputation coefficients.

• _licenses (tuple[]): Array of license tuples (num, stake).

• _wallet (address): Wallet address for payouts or interactions.

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

• _reward_sum (uint128): Cumulative reward sum.

• _myIp (string): Node IP address.

• isDestroy (bool): Flag indicating if the contract is destroyed.

• _nodeVersion (optional(string)): Optional node version string.

Implementation Details

• The contract uses a modular code storage approach with a code map storing separate cell objects indexed by uint8. This design allows flexibility in upgrading or managing contract submodules.

• Licensing is managed as an array of tuples, each holding a license number and associated stake, enabling granular stake-based permissions or rights.

• Optional types (optional(uint128), optional(string)) are used for fields that may or may not be present, supporting flexible initialization and upgrades.

• The contract lifecycle is controlled via sequence numbers _seqNoStart and _seqNoDestruct, marking its active period on-chain.

• Reputation and stake coefficients are maintained in 128-bit unsigned integers, indicating high precision for reputation calculations.

• The destroy function supports conditional deletion of proxy data, which could be used for cleaning up delegated or proxied permissions upon contract termination.

Interaction with System Components

• This contract likely interacts with consensus or epoch management components by providing pre-epoch state and configuration.

• Public keys and licenses managed here are essential for validating signatures and stake weights in the broader staking or block production system.

• The map of proxies and associated IP address fields indicate interaction with network node management or proxy delegation layers.

• The versioning functions enable integration with upgrade and compatibility checking mechanisms throughout the system.

• Ownership and root address fields link this contract to wallet management and authorization modules.

Mermaid Diagram

classDiagram
class BlockKeeperPreEpochContract {
+constructor()
+destroy()
+touch()
+touchIn()
+cancelPreEpoch()
+getDetails()
+getVersion()
-_pubkey
-_timestamp
-_constructorFlag
-_code
-_owner_pubkey
-_root
-_seqNoStart
-_seqNoDestruct
-_epochDuration
-_waitStep
-_bls_pubkey
-_stake
-_signerIndex
-_sumReputationCoef
-_licenses
-_wallet
-_virtualStake
-_reward_sum
-_myIp
-isDestroy
-_nodeVersion
}

This diagram depicts the contract as a class with its public functions and private fields, illustrating the encapsulated structure of the contract ABI.