BLSKeyIndex.sol

Overview

BLSKeyIndex.sol defines the BLSKeyIndex smart contract, which manages the indexing and acceptance process of BLS (Boneh–Lynn–Shacham) public keys associated with wallets in a blockchain system. This contract facilitates communication with the root contract BlockKeeperContractRoot to verify and confirm BLS key acceptance statuses, maintains internal readiness state, and controls its lifecycle through destruction methods.

The contract enforces strict access control via the Modifiers contract, ensuring only authorized entities (notably the root contract or the wallet) can invoke sensitive functions. It also manages contract balance to ensure sufficient funds for operations.

Contract: BLSKeyIndex

State Variables

Variable	Type	Description
`version`	`string`	Constant string indicating the contract version ("1.0.0").
`_root`	`address`	Static address of the root contract that deploys this contract.
`_bls`	`bytes`	Static bytes representing the BLS public key associated with this contract.
`_wallet`	`address`	Address of the wallet associated with this BLS key.
`_ready`	`bool`	Internal flag indicating whether the BLS key is ready (accepted).

Constructor

constructor(address wallet) senderIs(_root) accept

Parameters:
- wallet: Address of the wallet this BLS key is associated with.
Modifiers:
- senderIs(_root): Ensures the caller is the root contract.
- accept: Accepts the inbound message.
Behavior:
- Initializes the _wallet variable.
- Sets _ready flag to false.
Usage: This constructor is called during deployment by the root contract, linking the BLS key index to a specific wallet.

Private Function: ensureBalance

function ensureBalance() private pure

Purpose: Ensures the contract has a minimum balance (FEE_DEPLOY_BLS_KEY) to perform operations.
Behavior:
- Checks the contract's balance.
- If insufficient, mints the required tokens using gosh.mintshellq.
Usage: Invoked internally before executing functions that require sufficient balance for message fees or deployment costs.

Public Functions

isBLSKeyAccept

function isBLSKeyAccept(
    address wallet,
    uint16 signerIndex,
    uint256 pubkey,
    uint128 rep_coef,
    uint128 stake,
    optional(uint128) virtualStake,
    mapping(uint8 => string) ProxyList,
    string myIp,
    optional(string) nodeVersion
) public senderIs(_root) accept

Parameters:
- wallet: Wallet address submitting the BLS key.
- signerIndex: Index of the signer in the validator set.
- pubkey: The public key value.
- rep_coef: Reputation coefficient.
- stake: Stake amount.
- virtualStake (optional): Optional virtual stake amount.
- ProxyList: Mapping of proxy indices to proxy identifiers.
- myIp: IP address string of the node.
- nodeVersion (optional): Optional string for the node software version.
Modifiers:
- senderIs(_root): Caller must be the root contract.
- accept: Accepts inbound message.
Behavior:
- Checks balance via ensureBalance.
- If the provided wallet matches _wallet, calls isBLSAccepted on the root contract with _ready state, then sets _ready to true.
- Otherwise, calls isBLSAccepted with _ready forced to true.

Usage Example:

blsKeyIndex.isBLSKeyAccept(wallet, signerIndex, pubkey, rep_coef, stake, virtualStake, proxyList, myIp, nodeVersion);

Notes: This function notifies the root contract whether the BLS key is accepted, with details about stake and reputation.

isBLSKeyAcceptContinue

function isBLSKeyAcceptContinue(
    address wallet,
    uint16 signerIndex,
    uint256 pubkey,
    uint64 seqNoStartOld,
    uint128 stake,
    optional(uint128) virtualStake,
    mapping(uint8 => string) ProxyList,
    uint128 sumReputationCoef,
    optional(string) nodeVersion
) public senderIs(_root) accept

Parameters:
- Same as isBLSKeyAccept with additional:
  - seqNoStartOld: Sequence number from old state.
  - sumReputationCoef: Summed reputation coefficient.
Modifiers:
- senderIs(_root), accept.
Behavior:
- Ensures balance.
- If wallet == _wallet, calls isBLSAcceptedContinue on root contract with _ready state, then sets _ready to true.
- Else calls isBLSAcceptedContinue with _ready forced to true.
Purpose: Used for continuing acceptance processes that involve sequence numbers and cumulative reputation.
Usage: Similar to isBLSKeyAccept, but used in continuation scenarios.

destroyRoot

function destroyRoot() public senderIs(_root) accept

Modifiers: senderIs(_root), accept.
Behavior:
- Ensures balance.
- Calls selfdestruct sending remaining balance to _root.
Usage: Allows root contract to destruct this contract and reclaim funds.

destroy

function destroy() public senderIs(_wallet) accept

Modifiers: senderIs(_wallet), accept.
Behavior:
- Ensures balance.
- Calls selfdestruct sending remaining balance to _root.
Usage: Allows the wallet owner to destruct this contract.

View Functions

getReadyStatus

function getReadyStatus() external view returns(bool ready)

Returns: Current readiness status _ready.
Usage: Can be called to check if the BLS key has been marked as ready/accepted.

getVersion

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

Returns:
- Contract version string ("1.0.0").
- Contract identifier string ("BLSKey").
Usage: Provides versioning information for external systems.

Implementation Details and Algorithms

The contract uses a readiness flag _ready to track whether the BLS key acceptance process has been completed locally.
Functions isBLSKeyAccept and isBLSKeyAcceptContinue serve as intermediaries to relay acceptance messages and associated metadata to the root contract, ensuring that acceptance follows a predefined protocol.
Balance management is conducted using ensureBalance() to avoid failures due to insufficient funds, minting tokens if necessary.
Access control is rigorously enforced via the Modifiers contract, restricting sensitive operations to the root contract or the associated wallet.
Destruction functions allow for cleanup and resource recovery, with funds forwarded to the root contract.

Interactions with Other Contracts

Modifiers: The contract inherits from Modifiers, which provides access control modifiers such as senderIs and accept to regulate function execution.
BlockKeeperContractRoot: The root contract at _root is the main recipient of acceptance messages (isBLSAccepted and isBLSAcceptedContinue) sent from this contract. This tight coupling allows the root contract to maintain consensus state and validator information.
gosh.mintshellq: Utilized in ensureBalance() to mint tokens when contract balance is below the required fee for deployment or operations.

Diagram: Contract Structure and Function Relationships

classDiagram
class BLSKeyIndex {
-string version = "1.0.0"
-address _root
-bytes _bls
-address _wallet
-bool _ready
+constructor(wallet)
-ensureBalance()
+isBLSKeyAccept()
+isBLSKeyAcceptContinue()
+destroyRoot()
+destroy()
+getReadyStatus() bool
+getVersion() (string, string)
}
BLSKeyIndex ..|> Modifiers
BLSKeyIndex --> BlockKeeperContractRoot : calls isBLSAccepted/isBLSAcceptedContinue
BLSKeyIndex --> gosh.mintshellq : calls for minting

This diagram summarizes the contract's internal properties, key functions, inheritance from Modifiers, and external contract interactions.