BlockKeeperEpochProxyList.sol

Overview

BlockKeeperEpochProxyList.sol is a smart contract designed to manage and update a list of proxy nodes within an epoch in a blockchain-based system. Its primary function is to maintain the _ProxyList mapping, which holds proxy node identifiers keyed by uint8 indices. This contract ensures integrity and control over proxy list modifications, including additions and deletions, via owner permissions and inter-contract communication with epoch-related contracts.

The contract also enforces strict validation of code versions and addresses upon construction to prevent unauthorized deployment or interaction. It supports lifecycle operations such as closing the proxy list for further modifications and self-destruction triggered by authorized epoch contracts.

Contract: `BlockKeeperEpochProxyList`

Version

version: A constant string indicating the contract version "1.0.0".

State Variables

Variable	Type	Description
`_code`	`mapping(uint8 => TvmCell)`	Stores TvmCell code snippets indexed by code identifiers.
`_ProxyList`	`mapping(uint8 => string)`	The main proxy list, mapping proxy IDs to their string values.
`_owner`	`optional(address)`	Optional owner address for privileged modifications.
`_owner_pubkey`	`uint256 static`	Static public key used to verify ownership.
`_root`	`address`	Root contract address, used for self-destruct and validations.
`status`	`bool`	Indicates if a proxy list modification operation is in progress.
`_is_closed`	`bool`	Flag to mark the proxy list as closed for further changes.

Constructor

constructor (
    mapping(uint8 => TvmCell) code,
    uint64 seqNoStart,
    mapping(uint8 => string) ProxyList
) accept

Purpose: Initializes the contract with code mappings, an initial proxy list, validates code hashes and sender address.
Parameters:
- code: Mapping of code snippets (TvmCell) for various contract components.
- seqNoStart: Sequence number used to calculate legitimate caller addresses.
- ProxyList: Initial proxy list mapping.
Functionality:
- Decodes the contract's code salt to retrieve deployment parameters.
- Verifies the versions of critical libraries and contract code hashes to ensure consistency and security.
- Sets the _root address.
- Confirms the constructor caller matches the expected pre-epoch contract address.
- Sets the _ProxyList to the provided initial list.

Public Methods

`setNewProxyList`

function setNewProxyList(uint64 seqNoStart, mapping(uint8 => string) ProxyList) public senderIs(...) accept

Purpose: Updates the entire proxy list with a new mapping.
Parameters:
- seqNoStart: Sequence number for validating caller address.
- ProxyList: New proxy list mapping.
Access Control: Only callable by the epoch contract address calculated via BlockKeeperLib.
Behavior: Ensures sufficient balance, then replaces _ProxyList with the new list.

`toClose`

function toClose(uint64 seqNoStart) public senderIs(...) accept

Purpose: Closes the proxy list to prevent further modifications.
Parameters:
- seqNoStart: Sequence number for validating caller address.
Access Control: Only callable by the epoch contract.
Behavior: Ensures balance and sets _is_closed to true.

`destroy`

function destroy(uint64 seqNoStart) public senderIs(...) accept

Purpose: Self-destructs the contract, sending remaining funds to _root.
Parameters:
- seqNoStart: Sequence number for validating caller address.
Access Control: Only callable by the epoch contract.
Behavior: Executes selfdestruct(_root).

`destroyPreEpoch`

function destroyPreEpoch(uint64 seqNoStart) public senderIs(...) accept

Purpose: Self-destructs the contract when called by the pre-epoch contract.
Parameters:
- seqNoStart: Sequence number for validating caller address.
Access Control: Only callable by the pre-epoch contract.
Behavior: Executes selfdestruct(_root).

`setOwner`

function setOwner(optional(address) owner) public onlyOwnerWallet(_owner, _owner_pubkey) accept

Purpose: Updates the owner address.
Parameters:
- owner: Optional new owner address.
Access Control: Only callable by the current owner wallet.
Behavior: Ensures balance and sets _owner to the new owner.

`addProxyList`

function addProxyList(mapping(uint8 => string) data) public onlyOwnerWallet(_owner, _owner_pubkey) accept

Purpose: Adds entries to the proxy list.
Parameters:
- data: Partial proxy list entries to add.
Access Control: Only owner wallet allowed.
Preconditions:
- Proxy list is not closed.
- No other modification operation in progress (status == false).
- Input size does not exceed PROXY_LIST_CHANGE_SIZE.
Behavior:
- Sets status flag to true.
- Calls iterateProxyList to process additions asynchronously.

`deleteProxyList`

function deleteProxyList(mapping(uint8 => string) data) public onlyOwnerWallet(_owner, _owner_pubkey) accept

Purpose: Deletes entries from the proxy list.
Parameters:
- data: Partial proxy list entries to remove.
Access Control: Only owner wallet allowed.
Preconditions: Same as addProxyList.
Behavior: Similar to addProxyList, but removes entries by calling iterateProxyList with is_add = false.

`iterateProxyList`

function iterateProxyList(mapping(uint8 => string) data, optional(uint8, string) member, bool is_add) public senderIs(address(this)) accept

Purpose: Recursively processes proxy list entries for addition or deletion.
Parameters:
- data: Proxy list entries to process.
- member: Optional current key-value pair to process.
- is_add: Flag indicating addition (true) or deletion (false).
Access Control: Only callable by the contract itself.
Behavior:
- If no member to process, sets status to false (operation complete).
- Otherwise, adds or deletes the specified entry in _ProxyList.
- Calls itself recursively with the next entry in the mapping.
Implementation Detail:
- Uses asynchronous internal calls with a small value (0.1 vmshell) for each iteration.
- Ensures the operation continues over multiple transactions to avoid gas limits.

`ensureBalance`

function ensureBalance() private pure

Purpose: Ensures the contract has sufficient balance to operate.
Behavior:
- Checks if current balance exceeds FEE_DEPLOY_BLOCK_KEEPER_PROXY_LIST.
- If not, mints the required amount via gosh.mintshellq.
Note: This is a critical function for maintaining operational stability.

Fallback / Receive

receive() external

Empty receive function to accept incoming transfers without data.

Getters

`getDetails`

function getDetails() external view returns(
    uint256 pubkey,
    address root,
    mapping(uint8 => string) ProxyList,
    optional(address) owner
)

Returns important contract details:
- Owner public key.
- Root contract address.
- Current proxy list.
- Optional owner address.

`getVersion`

function getVersion() external pure returns(string, string)

Returns:
- Contract version string.
- Contract name "BlockKeeperEpochProxyList".

Important Implementation Details

Access Control: The contract relies heavily on sender address validation using senderIs modifier and public key checks to restrict access to critical functions.
Code Verification: The constructor validates the integrity of contract codes by hashing code snippets and comparing them against expected salts. This prevents unauthorized code injection.
Asynchronous Iteration: The iterateProxyList function uses asynchronous calls to process proxy list changes recursively, allowing large mappings to be handled without exceeding gas limits.
Balance Management: The ensureBalance function guards against insufficient funds, automatically minting required amounts to maintain contract operability.
Lifecycle Management: Functions toClose, destroy, and destroyPreEpoch provide lifecycle controls, enabling the proxy list to be closed or the contract to be destroyed by authorized contracts.

Interaction with Other Contracts

BlockKeeperLib Library: Used extensively for address calculations and version checks.
Epoch Contracts:
- BlockKeeperEpochContract - Authorized to update the proxy list and control lifecycle.
- BlockKeeperPreEpochContract - Authorized in initial construction and destruction phases.
Node Wallet Contract:
- AckiNackiBlockKeeperNodeWallet - Code related to node wallets is validated and referenced.
Root Contract: _root address is the ultimate recipient of self-destruct funds and a key part of deployment validation.

Visual Diagram: Class Structure of `BlockKeeperEpochProxyList`

classDiagram
class BlockKeeperEpochProxyList {
+string version
-mapping(uint8, TvmCell) _code
-mapping(uint8, string) _ProxyList
-optional(address) _owner
-uint256 _owner_pubkey
-address _root
-bool status
-bool _is_closed
+constructor(mapping, uint64, mapping)
+setNewProxyList(uint64, mapping)
+toClose(uint64)
+destroy(uint64)
+destroyPreEpoch(uint64)
+setOwner(optional(address))
+addProxyList(mapping)
+deleteProxyList(mapping)
+iterateProxyList(mapping, optional(uint8, string), bool)
+getDetails() returns (uint256, address, mapping, optional(address))
+getVersion() returns (string, string)
}

This diagram illustrates the contract’s core properties and its public methods, highlighting the state variables managing proxies and ownership, as well as its lifecycle and proxy list manipulation capabilities.

BlockKeeperEpochProxyList.sol

Overview

Contract: BlockKeeperEpochProxyList

Version

State Variables

Constructor

Public Methods

setNewProxyList

toClose

destroy

destroyPreEpoch

setOwner

addProxyList

deleteProxyList

iterateProxyList

ensureBalance