BlockKeeperPreEpochContract.sol

Overview

The BlockKeeperPreEpochContract.sol file defines the BlockKeeperPreEpoch smart contract, which serves as a preparatory contract within a blockchain node management and epoch lifecycle system. Its primary function is to manage the pre-epoch phase, including initialization of node wallets, stake locking, and transitioning to the main epoch contract after a specified delay. This contract handles the configuration and setup necessary before an epoch begins, such as managing reputation coefficients, licenses, stakes, and proxy lists.

This contract interacts closely with other contracts and libraries like AckiNackiBlockKeeperNodeWallet, BlockKeeperEpoch, BlockKeeperEpochProxyList, and utility libraries such as BlockKeeperLib. It enforces strict authorization and consistency checks to ensure secure deployment and management of epochs.

Contract: BlockKeeperPreEpoch

Properties

• version: string
  Contract version identifier.

• _code: mapping(uint8 => TvmCell)
  Stores code cells for different related contracts (wallet, epoch, proxy, etc.).

• _owner_pubkey: uint256 (static)
  Owner's public key used for authorization.

• _root: address
  Address of the root contract or managing entity.

• _seqNoStart: uint64 (static)
  Sequence number marking the start of this pre-epoch contract.

• _seqNoDestruct: uint64
  Sequence number after which the contract self-destructs.

• _epochDuration: uint64
  Duration of the epoch to be launched after this pre-epoch.

• _waitStep: uint64
  Delay step before epoch activation.

• _bls_pubkey: bytes
  BLS public key used for cryptographic operations.

• _stake: varuint32
  Stake amount locked for this node.

• _signerIndex: uint16
  Index of the signer for identification in consensus.

• _sumReputationCoef: uint128
  Sum of reputation coefficients for the node.

• _licenses: LicenseStake[]
  List of license stakes associated with the node.

• _wallet: address
  Wallet address controlling this pre-epoch.

• _virtualStake: optional(uint128)
  Optional virtual stake used in reputation calculations.

• _reward_sum: uint128
  Total reward sum allocated for the node.

• _myIp: string
  IP address of the node.

• isDestroy: bool
  Flag indicating if the contract is in the process of destruction.

• _nodeVersion: optional(string)
  Optional version string of the node software.

Constructor

constructor (
    uint64 waitStep,
    uint64 epochDuration,
    bytes bls_pubkey,
    mapping(uint8 => TvmCell) code,
    uint16 signerIndex, 
    uint128 rep_coef,
    LicenseStake[] licenses,
    optional(uint128) virtualStake,
    mapping(uint8 => string) ProxyList,
    uint128 reward_sum,
    string myIp,
    uint64 epochCliff,
    optional(string) nodeVersion
)

• Purpose: Initializes the pre-epoch contract with all necessary parameters, validates the deploying entity, locks the stake, and deploys the proxy list contract.

• Parameters:

  • waitStep: Delay before epoch activation.

  • epochDuration: Duration of the epoch lifecycle.

  • bls_pubkey: BLS public key for cryptographic signing.

  • code: Mapping of contract codes (wallet, epoch, proxy).

  • signerIndex: Signer index within the consensus group.

  • rep_coef: Accumulated reputation coefficient.

  • licenses: Array of license stakes for the node.

  • virtualStake: Optional virtual stake.

  • ProxyList: Proxy list mapping with identifiers.

  • reward_sum: Total reward allocated.

  • myIp: Node's IP address.

  • epochCliff: Epoch cliff duration for destruction timing.

  • nodeVersion: Optional node version string.

• Functionality:

  • Validates the deploying wallet code hash and root address.

  • Ensures that the message sender is the expected wallet address.

  • Locks the stake with the AckiNackiBlockKeeperNodeWallet.

  • Calculates the destruction sequence number based on the epoch cliff.

  • Deploys the BlockKeeperEpochProxyList contract with the proxy list.

• Usage Example:

BlockKeeperPreEpoch preEpoch = new BlockKeeperPreEpoch(
    10, // waitStep
    1000, // epochDuration
    blsPubKeyBytes,
    codeMapping,
    2, // signerIndex
    12345, // rep_coef
    licensesArray,
    optionalVirtualStake,
    proxyListMapping,
    100000, // reward_sum
    "192.168.1.1", // myIp
    5, // epochCliff
    optionalNodeVersion
);

Functions

ensureBalance()

private pure

• Purpose: Checks if the contract balance exceeds a minimal threshold to cover deployment fees and mints tokens if necessary.

• Return: None.

• Implementation Details:
  Uses a fixed fee value constant FEE_DEPLOY_BLOCK_KEEPER_PRE_EPOCHE_WALLET and mints tokens if balance is insufficient.

destroy(bool isProxyDelete)

public view senderIs(address(this)) accept

• Purpose: Initiates the destruction process of the pre-epoch contract.

• Parameters:

  • isProxyDelete: If true, triggers deletion of the proxy list contract as well.

• Behavior:

  • If isProxyDelete is true, calls destroyPreEpoch on the BlockKeeperEpochProxyList contract.

  • Calls deleteLockStake on the associated node wallet to unlock the stake.

• Usage: Called internally when pre-epoch is canceled or expired.

touch()

public pure accept

• Purpose: A public function to trigger the internal touchIn method asynchronously, ensuring balance is maintained.

• Usage: External trigger to progress the pre-epoch lifecycle.

touchIn()

public senderIs(address(this)) accept

• Purpose: Handles the core transition logic from pre-epoch to epoch.

• Behavior:

  • Ensures contract balance.

  • Returns early if the current block sequence number is less than the start sequence number or if destruction is already initiated.

  • Marks the contract for destruction.

  • If the destruction sequence number has passed, calls destroy without proxy deletion.

  • Otherwise, deploys a new BlockKeeperEpoch contract with all relevant parameters to start the epoch.

• Important: Only callable internally via touch().

cancelPreEpoch()

public senderIs(_wallet) accept

• Purpose: Allows the wallet owner to cancel the pre-epoch contract.

• Behavior:

  • Ensures balance.

  • Marks contract for destruction.

  • Calls destroy with proxy deletion flag set to true.

receive() external

• Purpose: Fallback function to receive funds without any logic.

Getters

getDetails()

external view returns(
    uint256 pubkey,
    address root, 
    uint64 seqNoStart,
    address owner
)

• Purpose: Returns key details about the pre-epoch contract.

• Return values:

  • pubkey: Owner's public key.

  • root: Root contract address.

  • seqNoStart: Starting sequence number.

  • owner: Wallet address controlling this contract.

getVersion()

external pure returns(string, string)

• Purpose: Returns the contract version and contract type identifier.

• Returns:

  • Version string "1.0.0"

  • Contract name "BlockKeeperPreEpoch"

Important Implementation Details

• Authorization:
  The constructor enforces that only the correct wallet contract (calculated via BlockKeeperLib.calculateBlockKeeperWalletAddress) can deploy the pre-epoch contract. This prevents unauthorized deployment.

• Stake Locking:
  The contract locks the stake on the node wallet (AckiNackiBlockKeeperNodeWallet) during construction and deletes the lock upon destruction.

• Epoch Transition:
  The touchIn() method transitions the pre-epoch contract into an active epoch by deploying a new BlockKeeperEpoch contract instance. This is triggered after the start sequence number is reached and before the destruction sequence number.

• Self-Destruction Logic:
  The contract self-destructs after a defined epoch cliff period (_seqNoDestruct) to clean up resources and avoid stale pre-epoch contracts.

• Proxy List Management:
  The constructor deploys a BlockKeeperEpochProxyList contract with a proxy list mapping, which is used to manage epoch proxy contracts.

• Balance Management:
  The internal ensureBalance() function mints tokens to maintain minimum balance required for contract operations, preventing accidental failures due to insufficient funds.

• Use of TVM Features:
  Uses TVM-specific features like tvm.codeSalt, tvm.hash, and TvmBuilder for code verification and initialization.

Interactions with Other Contracts and Libraries

• AckiNackiBlockKeeperNodeWallet
  Used to lock and unlock stakes associated with the node during pre-epoch and destruction phases.

• BlockKeeperEpoch
  The target contract instantiated by this pre-epoch contract during transition to active epoch.

• BlockKeeperEpochProxyList
  Manages a list of proxy contracts related to the epoch, deployed during construction and optionally destroyed during pre-epoch destruction.

• BlockKeeperLib
  Provides utility functions for address calculation, version validation, and state initialization cell composition.

• Modifiers (Modifiers.sol)
  Likely contains reusable modifiers for access control such as senderIs() and accept.

Visual Diagram: Contract Structure and Workflow

classDiagram
class BlockKeeperPreEpoch {
-string version
-mapping _code
-uint256 _owner_pubkey
-address _root
-uint64 _seqNoStart
-uint64 _seqNoDestruct
-uint64 _epochDuration
-uint64 _waitStep
-bytes _bls_pubkey
-varuint32 _stake
-uint16 _signerIndex
-uint128 _sumReputationCoef
-LicenseStake[] _licenses
-address _wallet
-optional(uint128) _virtualStake
-uint128 _reward_sum
-string _myIp
-bool isDestroy
-optional(string) _nodeVersion
+constructor()
+ensureBalance()
+destroy(isProxyDelete)
+touch()
+touchIn()
+cancelPreEpoch()
+getDetails()
+getVersion()
+receive()
}
class AckiNackiBlockKeeperNodeWallet
class BlockKeeperEpoch
class BlockKeeperEpochProxyList
class BlockKeeperLib
BlockKeeperPreEpoch ..> AckiNackiBlockKeeperNodeWallet : interacts with
BlockKeeperPreEpoch ..> BlockKeeperEpoch : deploys
BlockKeeperPreEpoch ..> BlockKeeperEpochProxyList : deploys & destroys
BlockKeeperPreEpoch ..> BlockKeeperLib : uses utilities

Usage Scenario / Workflow

1. Deployment:
   BlockKeeperPreEpoch is deployed by the node's wallet contract, passing initialization parameters such as stake, keys, reputation, and proxy list.

2. Stake Locking:
   Upon deployment, the node's stake is locked via the wallet contract.

3. Proxy List Setup:
   A proxy list contract is deployed to manage proxy nodes for the upcoming epoch.

4. Waiting Period:
   The contract waits for the specified waitStep and epochDuration before transitioning.

5. Transition:
   The touch() function is called (externally or internally), which triggers touchIn(). This deploys the BlockKeeperEpoch contract, starting the active epoch.

6. Destruction:
   If the pre-epoch expires or is canceled, the contract calls destroy(), unlocking stakes and optionally deleting the proxy list.

7. Lifecycle Control:
   The wallet owner can cancel the pre-epoch at any time by calling cancelPreEpoch().

This contract is critical in orchestrating the node's lifecycle from initialization and stake locking to active epoch participation, ensuring secure and orderly transitions and resource management. For further details on related components, see the contracts and libraries referenced here.