BlockKeeperEpochContract.sol

Overview

BlockKeeperEpochContract.sol implements the BlockKeeperEpoch contract, which manages the lifecycle, staking, and slashing mechanisms for a block keeper node during a specific epoch. It controls the node's stake, reputation, and operational parameters, and interacts with related contracts to coordinate epoch transitions, stake continuation, and penalties for misbehavior.

This contract maintains epoch state data, verifies caller permissions, manages stakes including continuation stakes, handles slashing (penalties), and coordinates the transition to a "cooler" contract after epoch completion. It is central to the block keeper node's participation in consensus during an epoch, providing methods to update stake, handle epoch lifecycle events, and enforce rules.

Contract Structure and State Variables

The contract stores crucial epoch-specific data such as public keys, stake amounts, reputation coefficients, IP addresses, licenses, and epoch timing parameters.

Constructor

constructor (
    uint64 waitStep,
    uint64 epochDuration,
    bytes bls_pubkey,
    mapping(uint8 => TvmCell) code,
    uint128 sumReputationCoef,
    uint16 signerIndex,
    LicenseStake[] licenses,
    optional(uint128) virtualStake,
    uint128 reward_sum,
    string myIp,
    bool isContinue,
    optional(uint32) timeStart,
    optional(string) nodeVersion
)

Description

Initializes a new BlockKeeperEpoch instance with epoch timing, stake, cryptographic keys, licenses, and other parameters. It verifies the contract code hashes for security, calculates the owner address, and ensures the caller is authorized based on whether this is a continuation epoch or not.

It also informs the root contract about the active block keeper and updates the node wallet with locking stake details.

Parameters

Usage Example

new BlockKeeperEpoch(
    waitStep,
    epochDuration,
    bls_pubkey,
    code,
    sumReputationCoef,
    signerIndex,
    licenses,
    virtualStake,
    reward_sum,
    myIp,
    false,          // isContinue flag
    optional.empty, // timeStart
    optional.empty  // nodeVersion
);

Key Functions

setStake

function setStake(uint128 numberOfActiveBlockKeepers, uint256 gparam) public senderIs(_root) accept

Updates the number of active block keepers and a general parameter. Only callable by the root contract.

continueStake

function continueStake(
    bytes bls_pubkey,
    uint16 signerIndex,
    LicenseStake[] licenses,
    optional(uint128) virtualStake,
    mapping(uint8 => string) ProxyList,
    uint128 sumReputationCoef,
    optional(string) nodeVersionContinue
) public senderIs(_owner_address) accept

Allows the owner to continue staking into the next epoch, setting continuation parameters.

cancelContinueStake

function cancelContinueStake() public senderIs(_owner_address) accept

Allows the owner to cancel a previously set continuation stake, reverting continuation state.

slash

function slash(uint8 slash_type) public senderIs(_owner_address) accept

Implements slashing (penalty) logic based on slash_type:

touch

function touch() public accept

Triggers epoch finalization actions if the epoch has ended:

cantDelete

function cantDelete() public senderIs(_root) accept

Called by root contract if deletion of the epoch contract is not permitted:

canDelete

function canDelete(uint256 reward, uint64 epochDuration, uint64 waitStep, uint128 reward_sum) public view senderIs(_root) accept

Initiates destruction of this epoch contract and transition to cooling phase.

destroy

function destroy(uint64 epochDurationContinue, uint64 waitStepContinue, uint128 reward_sum_continue) public view senderIs(address(this)) accept

Transitions the epoch to a "cooler" contract managing post-epoch cooldown and stake finalization.

destroy_full_slash

function destroy_full_slash() public view senderIs(address(this)) accept

Executes full stake slashing and destroys this epoch contract immediately.

part_slash

function part_slash(uint8 slash_type) private

Handles partial slashing by reducing stakes proportionally across licenses and virtual stake.

slashPartHelper

function slashPartHelper(uint i, uint8 slash_type, uint128 slash_stake) private returns(uint128)

Helper function to calculate and update the slashed amount for a specific license.

Private Utility Methods

ensureBalance

function ensureBalance() private pure

Ensures the contract has sufficient balance to cover deployment fees or operations. Mints currency if balance is below threshold.

Fallback Function

receive() external

Empty fallback function to accept incoming transfers.

Getters

Interactions with Other Contracts

This contract heavily relies on these contracts to delegate responsibilities and maintain the block keeper network's integrity and state consistency.

Important Implementation Details

Diagram: Contract Structure and Core Methods

classDiagram
class BlockKeeperEpoch {
-_owner_pubkey: uint256
-_root: address
-_seqNoStart: uint64
-_seqNoFinish: uint64
-_bls_pubkey: bytes
-_stake: uint128
-_licenses: LicenseStake[]
-_sumReputationCoef: uint128
-_signerIndex: uint16
-_isContinue: bool
-_stakeContinue: uint128
-_licensesContinue: LicenseStake[]
-_sumReputationCoefContinue: uint128
-_signerIndexContinue: uint16
-_proxyListContinue: mapping(uint8 => string)
-_myIp: string
-_reward_sum: uint128
-_is_full_slashing: bool
-_is_touching: bool
-_slash_type: optional(uint8)
+constructor()
+setStake()
+continueStake()
+cancelContinueStake()
+slash()
+touch()
+cantDelete()
+canDelete()
+destroy()
+destroy_full_slash()
+part_slash()
+slashPartHelper()
+getDetails()
+getProxyListContinue()
+getEpochCoolerCodeHash()
+getVersion()
}

This class diagram outlines the primary state variables and publicly accessible methods of the BlockKeeperEpoch contract.

For related concepts on staking, epoch management, and slashing algorithms, refer to Staking Mechanisms, Epoch Lifecycle, and Slashing Protocols. The contract’s interactions with node wallets and root contracts relate closely to Node Wallet Management and BlockKeeper Root Contract.