descendant_bk_set.rs

Overview

This file provides the implementation of the function set_descendant_bk_set, which is responsible for managing and updating the descendant block keeper sets associated with a given block state and a candidate block. The function checks the current status of the block state, retrieves the existing block keeper sets, and attempts to update them based on the candidate block's data by leveraging a common section update function. It ensures that the descendant block keeper sets are set only once and handles error cases gracefully with tracing logs.

Function: set_descendant_bk_set

pub fn set_descendant_bk_set(
    block_state: &BlockState,
    candidate_block: &Envelope<GoshBLS, AckiNackiBlock>,
)

Purpose

Updates the descendant block keeper sets for a block represented by block_state, using the information from a candidate_block. The function ensures that the descendant sets are only set if they have not been set previously and only if the block state is stored and valid.

Parameters

• block_state: &BlockState
  A reference to the BlockState instance representing the current state of the block, which holds guarded access to various block keeper sets and flags.

• candidate_block: &Envelope<GoshBLS, AckiNackiBlock>
  A reference to the candidate block wrapped in a cryptographically signed envelope, containing block data of type AckiNackiBlock.

Return Value

• None. This is a side-effect function that modifies the block_state by setting descendant block keeper sets if conditions are met.

Behavior and Workflow

1. Early Exit if Descendants Already Set:
   The function first checks if both descendant_bk_set and descendant_future_bk_set are already set in the block_state. If yes, it returns immediately to avoid redundant processing.

2. Retrieve Current BK Sets:
   Attempts to clone the current bk_set and future_bk_set from the guarded block_state. If either is not present, it exits early.

3. Check if Block is Stored:
   Only proceeds if the block is marked as stored (is_stored() returns true); otherwise, it returns early.

4. Update BK Sets from Common Section:
   Calls update_block_keeper_set_from_common_section with the candidate block's data and the cloned BK sets. This function attempts to produce updated BK sets based on the common section of the candidate block.

5. Handling Update Results:

   • If an error occurs, it logs a trace message with details.

   • If the update returns None, it sets the current BK sets as the descendant sets, but only if they have not been set yet.

   • If the update returns new BK sets, those are set as the descendant sets, again only if they have not been set yet.

Usage Example

use crate::block_keeper_system::bk_set::set_descendant_bk_set;
use crate::node::block_state::repository::BlockState;
use crate::bls::envelope::Envelope;
use crate::bls::GoshBLS;
use crate::types::AckiNackiBlock;

// Assume `state` is a BlockState instance and `candidate` is an Envelope<GoshBLS, AckiNackiBlock>
set_descendant_bk_set(&state, &candidate);

Important Implementation Details

• Uses guarded access (Guarded and GuardedMut) to safely read and write the internal state of BlockState.

• Clones the BK sets before passing them to the update function to avoid ownership issues and to maintain immutability of the original state during the update attempt.

• Relies on the external function update_block_keeper_set_from_common_section to compute the updated BK sets based on the candidate block's data.

• Uses detailed tracing for errors to facilitate debugging and monitoring.

Interaction with Other Parts of the System

• BlockState (block_state::repository):
  This is the primary data structure manipulated by this function. It stores the current and future block keeper sets, descendant block keeper sets, and block availability status. It uses internal guards to ensure thread-safe mutable and immutable access.

• Envelope and BLSSignedEnvelope (bls::envelope):
  The candidate_block parameter is wrapped in an envelope which includes cryptographic signatures for validation. The block data is extracted from this envelope for processing.

• update_block_keeper_set_from_common_section (block_keeper_system::bk_set):
  This external function is the core algorithm that attempts to derive updated BK sets by analyzing the common sections between the candidate block and existing BK sets.

• Tracing (tracing::trace!):
  Used for logging failures during the BK set update process, aiding diagnostics.

Data Flow and Control Flow Diagram

flowchart TD
A[Start: set_descendant_bk_set] --> B{Descendant BK Sets Set?}
B -- Yes --> C[Return Early]
B -- No --> D{BK Sets Available?}
D -- No --> C
D -- Yes --> E{Block Stored?}
E -- No --> C
E -- Yes --> F[Call update_block_keeper_set_from_common_section]
F --> G{Result}
G -- Error --> H[Log Trace & Return]
G -- None --> I[Set descendant BK sets with existing BK sets]
G -- Some --> J[Set descendant BK sets with updated BK sets]
I --> K[End]
J --> K
H --> K

Terms and Concepts Referenced

• For detailed information on block keeper sets and their role in block validation, see Block Keeper System.

• For the structure and usage of envelopes with BLS signatures, refer to BLS Envelope Handling.

• For concurrency and guarded access patterns, see Guarded Data Access.

• The update algorithm is elaborated in Update Block Keeper Set Algorithm.