memento.rs

Overview

This file defines two primary data structures, BlockProducerMemento and ProducedBlock, which serve as state snapshots (mementos) related to block production within a blockchain or distributed ledger system. These structures encapsulate the information about blocks produced, their associated optimistic state, feedback, and block state, as well as timing metrics and attestation notifications.

The purpose of these mementos is to preserve and manage the state of produced blocks and related metadata, enabling the system to track and update block-related information efficiently during block production and validation processes.

Structures and Their Functionalities

BlockProducerMemento

BlockProducerMemento acts as a container for multiple produced blocks along with optional metadata about attestation notifications. It provides mutable access to the collection of produced blocks and setters for updating attestation-related state.

Fields

• produced_blocks: Vec<ProducedBlock>

  • A vector holding multiple ProducedBlock instances representing blocks produced over time.

• last_attestation_notification: Option<u32>

  • An optional field storing the identifier or index of the last attestation notification received or processed.

Methods

• produced_blocks_mut(&mut self) -> &mut Vec<ProducedBlock>

  • Returns a mutable reference to the vector of produced blocks, allowing for modifications such as adding or updating blocks.

• set_last_attestation_notification(&mut self, last_attestation_notification: u32)

  • Sets the last_attestation_notification field to the provided value, indicating the latest attestation notification processed.

Usage Example

let mut memento = BlockProducerMemento::builder()
    .produced_blocks(vec![])
    .build();

memento.produced_blocks_mut().push(produced_block_instance);
memento.set_last_attestation_notification(42);

ProducedBlock

ProducedBlock represents a single block created by the producer, along with its associated state and metadata necessary for tracking and validation.

Fields

• block: AckiNackiBlock

  • Represents the actual block data structure, likely containing the block's content, header, and other blockchain-specific information.

• optimistic_state: Arc<OptimisticStateImpl>

  • A thread-safe reference-counted pointer to an optimistic state instance, representing the tentative state after applying this block but before final confirmation.

• feedbacks: ExtMsgFeedbackList

  • A list of feedback messages or acknowledgments related to this block, possibly used for external message confirmations or network feedback.

• block_state: BlockState

  • The definitive state of the block, encapsulating validation results, status, or other block-specific state information.

• metrics_memento_init_time: Option<Instant>

  • An optional timestamp marking when metrics tracking for this block memento was initialized, useful for performance measurement or timeout handling.

Methods

• set_memento_init_time(&mut self, memento_init_time: Instant)

  • Assigns the initialization time for metrics tracking to the provided Instant value.

Usage Example

let mut produced_block = ProducedBlock::builder()
    .block(some_block)
    .optimistic_state(Arc::new(optimistic_state_instance))
    .feedbacks(feedback_list)
    .block_state(block_state_instance)
    .build();

produced_block.set_memento_init_time(Instant::now());

Implementation Details

• Both BlockProducerMemento and ProducedBlock utilize the TypedBuilder procedural macro for ergonomic and type-safe construction via builders.

• The Getters macro from derive_getters automatically generates getter methods for all fields, facilitating read-only access without exposing internal mutability.

• The usage of Arc (Atomic Reference Counting) for optimistic_state ensures safe concurrent sharing of the optimistic state across threads or asynchronous contexts.

• Optional fields such as last_attestation_notification and metrics_memento_init_time allow for flexible state tracking without requiring initialization upfront.

• The file imports several domain-specific types (AckiNackiBlock, OptimisticStateImpl, BlockState, ExtMsgFeedbackList) indicating tight integration with other components responsible for block data structure, optimistic state management, block validation state, and external messaging feedback.

Interaction with Other System Components

• Block State Management: The block_state field ties into the Block State submodule, indicating that each produced block maintains a reference to its validation or repository state.

• Optimistic State: The optimistic_state field connects with the optimistic state implementation (OptimisticStateImpl), representing pre-finalized block states possibly used in optimistic concurrency or speculative execution models.

• External Messaging Feedback: The feedbacks field integrates with HTTP server feedback mechanisms (http_server::ExtMsgFeedbackList), suggesting involvement in message passing or external communication confirmation.

• Attestation Notifications: The last_attestation_notification field supports tracking of attestation-related events, which likely interact with consensus or validation layers of the system.

• These mementos serve as snapshot points for the block producer component of the system, preserving the progression and metadata of blocks being produced and processed.

Mermaid Diagram

classDiagram
class BlockProducerMemento {
-produced_blocks: Vec<ProducedBlock>
-last_attestation_notification: Option<u32>
+produced_blocks_mut()
+set_last_attestation_notification()
}
class ProducedBlock {
-block: AckiNackiBlock
-optimistic_state: Arc<OptimisticStateImpl>
-feedbacks: ExtMsgFeedbackList
-block_state: BlockState
-metrics_memento_init_time: Option<Instant>
+set_memento_init_time()
}
BlockProducerMemento "1" o-- "*" ProducedBlock : contains

This diagram illustrates the composition relationship where BlockProducerMemento contains multiple ProducedBlock instances and the key methods each provides for interaction.