mod.rs

Overview

This file defines data structures and logic related to the management of "Block Keepers" within the system. Block Keepers appear to be entities responsible for certain roles in maintaining or validating blockchain-related data, tracked through their cryptographic keys, status, stakes, and identifiers.

The file provides:

Definitions of key enums and structs representing Block Keeper data.
A collection type BlockKeeperSet to manage multiple Block Keepers.
Serialization and deserialization implementations for API interoperability.
Conversion implementations between internal and API representations.

This module interacts heavily with cryptographic public keys (PubKey), node identifiers, and account addresses, integrating with external HTTP API types (ApiBk, ApiBkStatus, etc.) and cryptographic utilities from other parts of the codebase.

Enumerations

`BlockKeeperSetChange`

Represents state changes in the Block Keeper set.

Variants:

BlockKeeperAdded: A new Block Keeper added, containing a tuple (SignerIndex, BlockKeeperData).
BlockKeeperRemoved: A Block Keeper removed, containing a tuple (SignerIndex, BlockKeeperData).
FutureBlockKeeperAdded: A Block Keeper scheduled to be added in the future, containing a tuple (SignerIndex, BlockKeeperData).

`BlockKeeperStatus`

Represents the lifecycle status of a Block Keeper.

Variants:

PreEpoch: Before the epoch starts.
Active: Currently active.
CalledToFinish: Called to finish duties.
Expired: No longer active.

Structs and Their Details

`BlockKeeperData`

Holds comprehensive information about a Block Keeper.

Fields:

pubkey: PubKey — The public key associated with the Block Keeper.
epoch_finish_seq_no: Option<u64> — Optional sequence number marking the finish of an epoch.
wait_step: u64 — A waiting step counter.
status: BlockKeeperStatus — Current status of the Block Keeper.
address: String — String address identifier.
stake: BigUint — Stake amount held by the Block Keeper.
owner_address: AccountAddress — Account address of the Block Keeper owner; also serves as the NodeIdentifier.
signer_index: SignerIndex — Numeric index identifying the signer.
owner_pubkey: [u8; 32] — Owner's public key bytes.

Methods:

node_id(&self) -> NodeIdentifier
Returns the NodeIdentifier derived from the owner's account address.

Traits Implemented:

Clone, Serialize, Deserialize, Debug, Eq, PartialEq, Display

Usage example:

let bk_data = BlockKeeperData {
    pubkey: some_pubkey,
    epoch_finish_seq_no: Some(100),
    wait_step: 5,
    status: BlockKeeperStatus::Active,
    address: "0xabc...".to_string(),
    stake: BigUint::from(1000u32),
    owner_address: some_account_address,
    signer_index: 1,
    owner_pubkey: [0u8; 32],
};

println!("BlockKeeper Node ID: {:?}", bk_data.node_id());

`BlockKeeperSet`

A collection that manages multiple BlockKeeperData entries indexed by SignerIndex and NodeIdentifier.

Fields (private):

by_signer: HashMap<SignerIndex, BlockKeeperData> — Main storage keyed by signer index.
signer_to_pubkey: HashMap<SignerIndex, PubKey> — Maps signer indices to their public keys.
signer_by_node_id: BTreeMap<NodeIdentifier, SignerIndex> — Maps node identifiers to signer indices.

Key Methods:

new() -> Self
Creates an empty BlockKeeperSet.
len(&self) -> usize
Returns number of Block Keepers in the set.
is_empty(&self) -> bool
Checks if the set is empty.
insert(&mut self, signer_index: SignerIndex, keeper: BlockKeeperData)
Inserts or updates a Block Keeper record.
contains_signer(&self, signer_index: &SignerIndex) -> bool
Checks if a Block Keeper exists by signer index.
contains_node(&self, node_id: &NodeIdentifier) -> bool
Checks if a Block Keeper exists by node identifier.
get_by_signer(&self, signer_index: &SignerIndex) -> Option<&BlockKeeperData>
Retrieves a Block Keeper by signer index.
get_by_node_id(&self, node_id: &NodeIdentifier) -> Option<&BlockKeeperData>
Retrieves a Block Keeper by node identifier.
get_pubkeys_by_signers(&self) -> &HashMap<SignerIndex, PubKey>
Returns the mapping of signer indices to public keys.
get_undistributed_stake(&self, attested_signers: &HashSet<SignerIndex>) -> BigUint
Calculates the total stake of Block Keepers who are not in the attested signers set.
iter_node_ids(&self) -> impl Iterator<Item = &NodeIdentifier>
Returns an iterator over all node identifiers.
remove_signer(&mut self, signer_index: &SignerIndex) -> Option<BlockKeeperData>
Removes a Block Keeper by signer index, returning the removed data if it existed.

Traits Implemented:

Default — defaults to an empty set.
Serialize and Deserialize — serializes/deserializes the by_signer map.
Debug — custom debug output.

Usage example:

let mut bk_set = BlockKeeperSet::new();
bk_set.insert(1, bk_data.clone());
assert_eq!(bk_set.len(), 1);
if let Some(keeper) = bk_set.get_by_signer(&1) {
    println!("Found keeper with stake: {}", keeper.stake);
}

`BlockKeeperSlashData`

Represents slashing information for a Block Keeper, potentially used to penalize misbehavior.

Fields:

node_id: NodeIdentifier — Identifier of the node being slashed.
bls_pubkey: PubKey — BLS public key of the node.
addr: AccountAddress — Account address associated with the node.
slash_type: u8 — Numeric code representing the type or reason of the slashing.

Traits:

Clone, Debug

Conversion Implementations

These allow seamless transformation between internal types and API representations (ApiBk, ApiBkStatus, etc.).

From<ApiBk> for BlockKeeperData
Converts an API Block Keeper to internal representation.
From<BlockKeeperData> for ApiBk
Converts internal Block Keeper data to API type.
From<BlockKeeperStatus> for ApiBkStatus and vice versa
Converts between internal status and API status enums.
From<&BlockKeeperSet> for Vec<ApiBk>
Converts a set of Block Keepers into a vector of API Block Keepers.
From<Vec<ApiBk>> for BlockKeeperSet
Converts a vector of API Block Keepers into an internal set.

Important Implementation Details

The BlockKeeperSet maintains three synchronized data structures (HashMap and BTreeMap) for efficient lookup by signer index and node identifier, and to map signer indices to public keys. This ensures quick access for various queries.
Stake calculations in get_undistributed_stake sum the stakes of all Block Keepers not present in a provided attested set, useful for reward or penalty computations.
Serialization and deserialization focus on the by_signer map for compactness and simplicity, reconstructing other mappings during deserialization.
The Debug and Display implementations for BlockKeeperData provide concise yet informative output, showing key fields like node ID, public key, and stake.

Interactions with Other Modules

Uses cryptographic public keys from crate::bls::gosh_bls::PubKey.
Uses NodeIdentifier, SignerIndex, and AccountAddress from the node and types submodules.
Interacts with HTTP API types from the http_server module to allow serialization and deserialization of Block Keeper data for network communication.
The submodules abi, bk_set, epoch, and wallet_config are declared here, implying related functionality organized separately.

Visual Diagram

classDiagram
class BlockKeeperData {
+pubkey
+epoch_finish_seq_no
+wait_step
+status
+address
+stake
+owner_address
+signer_index
+owner_pubkey
+node_id()
}
class BlockKeeperSet {
-by_signer: HashMap
-signer_to_pubkey: HashMap
-signer_by_node_id: BTreeMap
+new()
+len()
+is_empty()
+insert()
+contains_signer()
+contains_node()
+get_by_signer()
+get_by_node_id()
+get_pubkeys_by_signers()
+get_undistributed_stake()
+iter_node_ids()
+remove_signer()
}
class BlockKeeperSetChange {
<<enumeration>>
+BlockKeeperAdded
+BlockKeeperRemoved
+FutureBlockKeeperAdded
}
class BlockKeeperStatus {
<<enumeration>>
+PreEpoch
+Active
+CalledToFinish
+Expired
}
class BlockKeeperSlashData {
+node_id
+bls_pubkey
+addr
+slash_type
}
BlockKeeperSet "1" o-- "many" BlockKeeperData : manages
BlockKeeperData ..> NodeIdentifier : uses
BlockKeeperData ..> PubKey : uses
BlockKeeperSetChange ..> BlockKeeperData : state changes with
BlockKeeperSlashData ..> NodeIdentifier : references
BlockKeeperSlashData ..> PubKey : references

Summary of Main Functions

Function	Description
BlockKeeperData::node_id()	Returns the node identifier derived from the owner address.
`BlockKeeperSet::new()`	Creates an empty Block Keeper set.
BlockKeeperSet::insert()	Inserts or updates a Block Keeper in the set.
BlockKeeperSet::get_by_signer()	Retrieves a Block Keeper by signer index.
BlockKeeperSet::get_by_node_id()	Retrieves a Block Keeper by node identifier.
BlockKeeperSet::get_undistributed_stake()	Computes stake not held by attested signers.
BlockKeeperSet::remove_signer()	Removes a Block Keeper by signer index.

Usage Context

This file plays a critical role in managing Block Keeper information, enabling the tracking of their states, statuses, and stakes, and facilitating communication with external API layers. It is essential for the parts of the system that require knowledge of active block validators or maintainers, their cryptographic identities, and their operational statuses. The presence of slashing data structures indicates integration with consensus or governance mechanisms that enforce penalties.

For more details on the cryptographic key types, node identifiers, and account addresses used here, see the respective topics:

For API interaction specifics, refer to:

HTTP API Types

For serialization and deserialization strategies, refer to:

Serde Serialization