SignerIndex.sol

Overview

The SignerIndex.sol file defines the SignerIndex smart contract, which serves as a component in a blockchain-based system responsible for managing and verifying signer identities and their associated metadata. It acts as a proxy or intermediary that interacts with a root contract (BlockKeeperContractRoot) to confirm acceptance or continuation of signer status. The contract maintains signer-specific state, including readiness status and wallet association, and enforces strict access control via sender verification modifiers.

This contract primarily facilitates:

Verification of signer acceptance and continuation requests.
Management of signer readiness state.
Secure interaction with the root contract for updating signer acceptance.
Controlled self-destruction initiated by the authorized wallet.

Contract: SignerIndex

State Variables

Variable	Type	Description
`version`	`string constant`	Version identifier for the contract (`"1.0.0"`).
`_signerIndex`	`uint16 static`	Immutable index identifier for the signer, set at contract deployment.
`_root`	`address static`	Immutable address of the root contract (`BlockKeeperContractRoot`) managing signer indices.
`_wallet`	`address`	Address of the wallet associated with this signer index.
`_ready`	`bool`	Boolean flag indicating whether this signer index is ready (accepted).

Constructor

constructor(address wallet) senderIs(_root) accept

Parameters:
- wallet: The wallet address associated with this signer index.
Functionality:
- Initializes the _wallet with the given address.
- Sets _ready to false.
- Ensures the caller is the _root contract via the senderIs(_root) modifier.
Usage:
- Called once at deployment by the root contract to instantiate a new signer index mapped to a wallet.

Private Function: `ensureBalance`

function ensureBalance() private pure

Purpose:
- Ensures the contract has sufficient balance to cover deployment or execution fees.
Implementation Detail:
- Checks if the contract's balance exceeds a predefined constant FEE_DEPLOY_SIGNER_INDEX.
- If balance is insufficient, it triggers a minting call gosh.mintshellq to top up the required amount.
Note:
- The actual minting mechanism and fee constant are external to this contract.
- This function is called internally before making calls that require gas.

Public Function: `isSignerIndexAccept`

function isSignerIndexAccept(
    address wallet, 
    bytes blsKey, 
    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: The wallet address requesting acceptance.
- blsKey: The BLS signature key (bytes).
- pubkey: Public key identifier (uint256).
- rep_coef: Reputation coefficient (uint128).
- stake: Amount staked by the signer (uint128).
- virtualStake: Optional virtual stake (uint128).
- ProxyList: Mapping of proxy IDs to proxy addresses (mapping from uint8 to string).
- myIp: IP address of the node (string).
- nodeVersion: Optional node software version (string).
Functionality:
- Ensures the contract has enough balance via ensureBalance().
- If the caller's wallet matches _wallet:
  - Calls BlockKeeperContractRoot.isSignerIndexAccepted with _ready status and other parameters.
  - Sets _ready to true.
- If the wallet differs from _wallet, invokes the root contract call with _ready set to true.
Access Control:
- Restricted to calls from _root only, enforced by senderIs(_root).

Usage Example:

signerIndex.isSignerIndexAccept(
  walletAddress,
  blsKeyBytes,
  publicKey,
  reputationCoefficient,
  stakeValue,
  optionalVirtualStake,
  proxyListMapping,
  ipString,
  optionalNodeVersionString
);

Notes:
- Calls to the root contract include attached value of 0.1 vmshell and flag 1, indicating a specific gas or message flag.

Public Function: `isSignerIndexAcceptContinue`

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

Parameters:
- Similar to isSignerIndexAccept with additional parameters:
  - seqNoStartOld: Sequence number indicating the start of the old state (uint64).
  - sumReputationCoef: Summed reputation coefficient (uint128).
Functionality:
- Ensures balance before proceeding.
- If the wallet matches _wallet:
  - Calls BlockKeeperContractRoot.isSignerIndexContinue with _ready status and other parameters.
  - Sets _ready to true.
- Otherwise, calls the root contract with _ready set to true.
Access Control:
- Restricted to _root caller.
Usage:
- Used to continue or update the acceptance process of a signer index after initial acceptance.

Public Function: `destroy`

function destroy() public senderIs(_wallet) accept

Functionality:
- Ensures sufficient balance for contract self-destruction.
- Calls selfdestruct to delete the contract and send remaining balance to _root.
Access Control:
- Can only be called by the wallet associated with this signer index.
Usage:
- Allows controlled removal of the signer index contract instance.

External View Function: `getReadyStatus`

function getReadyStatus() external view returns(bool ready)

Returns:
- The boolean _ready indicating if the signer index is marked ready.

Usage Example:

bool isReady = signerIndex.getReadyStatus();

External Pure Function: `getVersion`

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

Returns:
- Tuple (version, "SignerIndex") indicating the contract version and contract name.

Usage:

(string ver, string name) = signerIndex.getVersion();

Implementation Details

Modifiers:
- senderIs(address): Ensures that the function caller matches the specified address.
- accept: Likely a modifier that accepts inbound messages or transactions, details in modifiers.sol.
Gas and Fees:
- The contract ensures it holds sufficient gas tokens (vmshell) for operations that require external calls or self-destruction.
Inter-contract Communication:
- Interacts primarily with BlockKeeperContractRoot for updating signer acceptance status.
- Uses low-level call syntax with attached value and flags for message passing.
State Immutability:
- _signerIndex and _root are declared static, meaning they are immutable and set at contract deployment.
Data Structures:
- Uses optional types and mappings as parameters for flexible signer metadata and proxy lists.

Interaction with Other System Components

BlockKeeperContractRoot:
- Acts as the root contract managing all signer indices.
- SignerIndex calls methods on it to report acceptance and continuation states.
Modifiers and Libraries:
- Uses imported Modifiers for access control.
- Imports BlockKeeperLib though unused directly in this contract; may be relevant to related contracts.
Wallets:
- Each SignerIndex instance is tied to a single wallet address, which controls destruction and state readiness.

Diagram: Contract Structure and Interaction Flow

classDiagram
class SignerIndex {
+string version
+uint16 static _signerIndex
+address static _root
-address _wallet
-bool _ready
+constructor(address)
-ensureBalance()
+isSignerIndexAccept(...)
+isSignerIndexAcceptContinue(...)
+destroy()
+getReadyStatus() bool
+getVersion() (string, string)
}
class BlockKeeperContractRoot {
+isSignerIndexAccepted(...)
+isSignerIndexContinue(...)
}
SignerIndex --> BlockKeeperContractRoot : calls

This class diagram illustrates the SignerIndex contract with its key properties and methods, and its interaction with the BlockKeeperContractRoot contract through external calls. The private method ensureBalance() supports other public functions internally. The destroy() method allows the wallet to self-destruct the contract.