BlockKeeperLib.sol

Overview

BlockKeeperLib.sol is a Solidity library designed to facilitate the creation and address calculation of various smart contract wallets and related entities within a blockchain system. It provides a collection of functions to compose and build state initialization cells (TvmCell) for different contracts, and to calculate their deterministic blockchain addresses based on the compiled contract code, initialization parameters, and cryptographic hashes.

The contracts involved include block keeper wallets, block manager wallets, epoch-related contracts, proxy lists, BLS key indexes, license contracts, and signer indexes. The library abstracts the encoding of state initialization and code salting logic, enabling standardized and reproducible contract deployment addresses.

Classes and Functions

This library contains only one Solidity library named BlockKeeperLib, which consists exclusively of public functions for calculating addresses, composing state initialization, and building contract code cells for various contract types.

Constant Variables

• versionLib (string): Defines the version of the library, "1.0.0".

Wallet Address Calculation and State Initialization

These functions generate state initialization cells and corresponding addresses for block keeper and block manager node wallets.

calculateBlockKeeperWalletAddress

function calculateBlockKeeperWalletAddress(TvmCell code, address root, uint256 pubkey) public returns(address)

• Purpose: Computes the blockchain address of a Block Keeper Wallet contract.

• Parameters:

  • code: The contract code as a TvmCell.

  • root: The root address of the system.

  • pubkey: The public key of the wallet owner.

• Returns: A deterministic contract address (address).

• Usage: Used when deploying or referencing Block Keeper Wallet contracts.

composeBlockKeeperWalletStateInit

function composeBlockKeeperWalletStateInit(TvmCell code, address root, uint256 pubkey) public returns(TvmCell)

• Purpose: Composes the state initialization cell for a Block Keeper Wallet contract.

• Parameters: Same as above.

• Returns: A TvmCell representing the state init for contract deployment.

• Details: Uses buildBlockKeeperWalletCode to generate salted contract code and initializes the _owner_pubkey variable.

buildBlockKeeperWalletCode

function buildBlockKeeperWalletCode(TvmCell originalCode, address root) public returns (TvmCell)

• Purpose: Builds the contract code cell with a salt containing library version and root address.

• Parameters:

  • originalCode: Original contract code.

  • root: Root address for salting.

• Returns: Salted contract code (TvmCell).

• Implementation: Uses abi.encode(versionLib, root) as salt data.

Block Manager Wallet Address and Initialization

Functions similar to block keeper wallets but for AckiNackiBlockManagerNodeWallet contracts:

• calculateBlockManagerWalletAddress

• composeBlockManagerWalletStateInit

• buildBlockManagerWalletCode

These follow the same contract address calculation and code salting pattern as the Block Keeper Wallet functions.

Block Keeper Pre-Epoch Contracts

These functions manage the pre-epoch contracts which are part of the block keeper system's epoch management.

• calculateBlockKeeperPreEpochAddress

• composeBlockKeeperPreEpochStateInit

• buildBlockKeeperPreEpochCode

Parameters:

• walletCode: The wallet contract code cell.

• seqNoStart: The starting sequence number for the epoch.

Implementation Details:

• Uses a hash of the wallet code as part of the code salt, combined with library version and root.

• Initializes contract variables _owner_pubkey and _seqNoStart.

Block Keeper Epoch Contracts

Functions related to epoch contracts that manage block keeper epochs:

• calculateBlockKeeperEpochAddress

• composeBlockKeeperEpochStateInit

• buildBlockKeeperEpochCode

Parameters:

• Adds preEpochCode to the code salt computation alongside walletCode.

• Uses two hashes (for wallet code and pre-epoch code) in code salting.

• Initializes _owner_pubkey and _seqNoStart.

Block Keeper Cooler Epoch Contracts

These functions handle cooler epoch contracts, which depend on epoch contracts and pre-epoch contracts.

• calculateBlockKeeperCoolerEpochAddress

• composeBlockKeeperCoolerEpochStateInit

• buildBlockKeeperCoolerEpochCode

Unique Aspects:

• Uses calculateBlockKeeperEpochAddress internally to compute the root address for code salting.

• Code salt includes version and root address.

• Initializes variables _owner_pubkey and _seqNoStart.

Block Keeper Epoch Proxy List Contracts

Functions to handle the proxy list contracts related to block keeper epochs:

• calculateBlockKeeperEpochProxyListAddress

• composeBlockKeeperEpochProxyListStateInit

• buildBlockKeeperEpochProxyListCode

Implementation Details:

• Code salt includes hashes of walletCode, epochCode, and preepochCode.

• Initializes _owner_pubkey.

BLS Key Index Contracts

Functions to calculate addresses and state init for BLS key index contracts:

• calculateBLSKeyAddress

• composeBLSKeyStateInit

• buildBLSKeyCode

Parameters:

• bls_key: The BLS key in bytes.

• root: Root address.

Details:

• buildBLSKeyCode returns original code without modification.

• Initializes _bls and _root.

License Contracts

Functions for license contracts:

• calculateLicenseAddress

• composeLicenseStateInit

• buildLicenseCode

Parameters:

• license_number: Unique license number.

• root: Root address.

Details:

• Code building returns original code.

• Initializes _license_number and _root.

License Block Manager Contracts

Similar to license contracts but for block manager license contracts:

• calculateLicenseBMAddress

• composeLicenseBMStateInit

• buildLicenseBMCode

Signer Index Contracts

Functions for signer index contracts:

• calculateSignerIndexAddress

• composeSignerIndexStateInit

• buildSignerIndexCode

Parameters:

• index: The signer index as a uint16.

• root: Root address.

Details:

• Code building returns original code.

• Initializes _signerIndex and _root.

Implementation Details and Algorithms

• State Initialization Encoding: Uses abi.encodeStateInit to assemble the contract code, contract type, and initial variables into a TvmCell that defines the contract state at deployment.

• Code Salting: For some contracts, the original contract code is salted by encoding extra information such as version, root address, and hashes of related code cells. This ensures unique and deterministic addresses.

• Address Calculation: Addresses are computed by hashing the state initialization cell (tvm.hash(s1)) and creating a standard address with workchain ID 0.

• Hashing: Uses tvm.hash on TvmCell or serialized data to generate consistent identifiers for code salting.

• Memory Management: Temporary builders (TvmBuilder) are cleared after use to ensure clean state.

Interaction with Other System Components

• This library interacts with multiple contract types imported at the beginning:

  • Wallet contracts: AckiNackiBlockKeeperNodeWallet, AckiNackiBlockManagerNodeWallet

  • Epoch contracts: BlockKeeperEpochContract, BlockKeeperPreEpochContract, BlockKeeperEpochProxyList

  • Index contracts: BLSKeyIndex, SignerIndex

  • License contracts: License

• It serves as a utility to generate deterministic contract addresses and initialization data, which is critical for contract deployment, lookup, and verification in the system.

• The use of root addresses and public keys ties contracts to their controlling entities and hierarchical system roots.

• The layered approach for epoch contracts (pre-epoch, epoch, cooler epoch) reflects a multi-stage consensus or coordination mechanism.

• The library supports the management of cryptographic keys and licenses, indicating integration with security and authorization subsystems.

Visual Diagram

classDiagram
class BlockKeeperLib {
+string versionLib
+calculateBlockKeeperWalletAddress()
+composeBlockKeeperWalletStateInit()
+buildBlockKeeperWalletCode()
+calculateBlockManagerWalletAddress()
+composeBlockManagerWalletStateInit()
+buildBlockManagerWalletCode()
+calculateBlockKeeperPreEpochAddress()
+composeBlockKeeperPreEpochStateInit()
+buildBlockKeeperPreEpochCode()
+calculateBlockKeeperEpochAddress()
+composeBlockKeeperEpochStateInit()
+buildBlockKeeperEpochCode()
+calculateBlockKeeperCoolerEpochAddress()
+composeBlockKeeperCoolerEpochStateInit()
+buildBlockKeeperCoolerEpochCode()
+calculateBlockKeeperEpochProxyListAddress()
+composeBlockKeeperEpochProxyListStateInit()
+buildBlockKeeperEpochProxyListCode()
+calculateBLSKeyAddress()
+composeBLSKeyStateInit()
+buildBLSKeyCode()
+calculateLicenseAddress()
+composeLicenseStateInit()
+buildLicenseCode()
+calculateLicenseBMAddress()
+composeLicenseBMStateInit()
+buildLicenseBMCode()
+calculateSignerIndexAddress()
+composeSignerIndexStateInit()
+buildSignerIndexCode()
}

References to Related Topics

• For encoding and state initialization concepts, see Smart Contract State Initialization.

• For address calculation methods and the use of tvm.hash, see Deterministic Contract Addressing.

• For cryptography and key management, see BLS Signatures and Key Indexing.

• For epoch management and consensus mechanisms, see Epoch and Pre-Epoch Contract Design.

• For license management in blockchain systems, see License Contracts and Access Control.