bk_set.rs

Overview

This file provides functionality to update the block keeper sets based on changes specified in a common section of a block. It mainly contains a single function that processes changes to the block keeper sets, applying removals, additions, and future additions as indicated in the block's common section. These updates are crucial for maintaining the current and future sets of block keepers, which likely represent entities responsible for specific roles in the system.

Functions

update_block_keeper_set_from_common_section

pub(crate) fn update_block_keeper_set_from_common_section(
    block: &AckiNackiBlock,
    current_bk_set: Arc<BlockKeeperSet>,
    current_future_bk_set: Arc<BlockKeeperSet>,
) -> anyhow::Result<Option<(Arc<BlockKeeperSet>, Arc<BlockKeeperSet>)>>

Parameters:

• block: A reference to an AckiNackiBlock instance which contains the data including the common section with block keeper set changes.

• current_bk_set: An Arc wrapped BlockKeeperSet representing the current block keeper set.

• current_future_bk_set: An Arc wrapped BlockKeeperSet representing the current future block keeper set.

Returns:

• anyhow::Result<Option<(Arc<BlockKeeperSet>, Arc<BlockKeeperSet>)>>:

  • On success, returns Ok(Some((new_bk_set, new_future_bk_set))) if there were changes applied.

  • Returns Ok(None) if there are no changes to apply.

  • Returns an error if any processing fails.

Description:

This function extracts block keeper set changes from the block's common section and applies them to clones of the current block keeper sets. The changes are processed in three phases:

1. Removal of block keepers: Removes specified signers from the current block keeper set.

2. Addition of block keepers: Adds specified signers to the current block keeper set and removes them from the future set if present.

3. Addition of future block keepers: Adds specified signers to the future block keeper set.

Each phase iterates over the block_keeper_set_changes and applies the relevant modifications accordingly.

Usage Example:

let updated_sets = update_block_keeper_set_from_common_section(
    &block, 
    current_bk_set.clone(), 
    current_future_bk_set.clone()
)?;

if let Some((new_bk_set, new_future_bk_set)) = updated_sets {
    // Use updated sets for subsequent processing
}

Implementation Details:

• Uses Arc to handle shared ownership of block keeper sets safely in concurrent contexts.

• Clones the current sets before applying changes to ensure immutability of inputs.

• Uses pattern matching on BlockKeeperSetChange enum variants to determine the type of change.

• Uses logging with the tracing crate at trace level to record detailed steps of the update process.

• The order of applying changes ensures that removals happen before additions, maintaining consistency of the sets.

Data Types and Interactions

• AckiNackiBlock: Represents a block containing a common section with possible block keeper set changes. The function uses its method get_common_section() to retrieve the changes, and identifier() to log the block's identity.

• BlockKeeperSet: Represents a set of block keepers. This type supports methods:

  • remove_signer(signer_index): Removes a signer by index.

  • insert(signer_index, block_keeper_data): Inserts a signer.

  • contains_signer(signer_index): Checks if a signer exists.

• BlockKeeperSetChange: An enum representing the types of changes to apply, including:

  • BlockKeeperRemoved

  • BlockKeeperAdded

  • FutureBlockKeeperAdded

The function uses these types to apply updates properly.

Interaction with Other System Components

• This file depends on the block_keeper_system module for types and data structures related to block keeper sets and their changes.

• It uses the types module for the AckiNackiBlock type.

• The function fits into a larger system that manages the lifecycle and membership of block keepers, updating sets as new blocks are processed.

• The updated sets returned by this function are likely used by other parts of the system to determine current and future block keeper responsibilities.

Visual Diagram

flowchart TD
A[AckiNackiBlock] -->|get_common_section| B[CommonSection]
B -->|block_keeper_set_changes| C{Iterate Changes}
C --> D[Remove BlockKeepers]
C --> E[Add BlockKeepers]
C --> F[Add Future BlockKeepers]
subgraph Update Process
D --> G[Clone current_bk_set]
E --> G
F --> H[Clone current_future_bk_set]
E --> H
F --> H
end
G --> I[Remove signers]
E --> J[Insert signers]
F --> K[Insert future signers]
I & J & K --> L[Return updated sets]

This flowchart illustrates the function's process: obtaining changes from a block, iterating through removal, addition, and future addition changes, applying them to clones of the current sets, and finally returning the updated sets.

References

• Arc Smart Pointer for thread-safe shared ownership.

• BlockKeeperSet for details on block keeper set structure and methods.

• BlockKeeperSetChange for enumeration of possible changes.

• AckiNackiBlock for block structure and common section access.