events.rs

Overview

This file defines event types related to changes in the blockchain's state, specifically focusing on the lifecycle of blocks within threads. The events represented here indicate key stages such as when a block is finalized, prefinalized, applied, or when a new thread starts processing with a collection of unfinalized block candidates. These events enable other parts of the system to react appropriately to changes in the blockchain state.

The primary components of this file are:

• Event structs representing distinct blockchain block-related events.

• An enum ChainPulseEvent that encapsulates all event variants, providing a unified interface.

• Associated functions on ChainPulseEvent for convenient construction of specific event instances.

Structs

BlockFinalizedEvent

Represents the event when a block is finalized on a particular thread.

Fields

• thread_identifier: ThreadIdentifier — Identifies the thread where the block is finalized.

• block_height: Option<BlockHeight> — The height of the finalized block, or None if not applicable.

Accessors

All fields have public getter methods generated by the derive_getters crate, allowing read-only access.

Usage Example

let event = BlockFinalizedEvent {
    thread_identifier: some_thread_id,
    block_height: Some(some_block_height),
};

let thread = event.thread_identifier();
let height = event.block_height();

BlockPrefinalizedEvent

Represents a block reaching the prefinalized state on a thread.

Fields

• thread_identifier: ThreadIdentifier — Thread where the block is prefinalized.

• block_height: Option<BlockHeight> — Height of the prefinalized block, optional.

Accessors

Public getter methods are available for both fields.

BlockAppliedEvent

Indicates that a block has been applied to the state of a thread.

Fields

• thread_identifier: ThreadIdentifier — Thread identifier for the applied block.

• block_height: Option<BlockHeight> — Optional block height applied.

Accessors

Getter methods provide read access to these fields.

Enum: ChainPulseEvent

A unified enum encapsulating all chain pulse events that can occur related to block processing and thread management.

Variants

• BlockFinalized(BlockFinalizedEvent) — Signals block finalization.

• BlockPrefinalized(BlockPrefinalizedEvent) — Signals block prefinalization.

• BlockApplied(BlockAppliedEvent) — Signals block application.

• StartThread — Indicates the start of a thread with a given collection of unfinalized candidate blocks.

StartThread Fields

• thread_id: ThreadIdentifier — Identifier of the thread being started.

• block_candidates: UnfinalizedCandidateBlockCollection — Collection of candidate blocks for the thread.

Associated Functions

Convenience constructors for creating instances of ChainPulseEvent with minimal boilerplate:

• block_finalized(thread_identifier: ThreadIdentifier, block_height: Option<BlockHeight>) -> Self

  Creates a BlockFinalized event.

• block_prefinalized(thread_identifier: ThreadIdentifier, block_height: Option<BlockHeight>) -> Self

  Creates a BlockPrefinalized event.

• block_applied(thread_identifier: ThreadIdentifier, block_height: Option<BlockHeight>) -> Self

  Creates a BlockApplied event.

• start_thread(thread_id: ThreadIdentifier, block_candidates: UnfinalizedCandidateBlockCollection) -> Self

  Creates a StartThread event.

Usage Example

let event = ChainPulseEvent::block_finalized(thread_id, Some(block_height));

Implementation Details

• The derive_getters procedural macro is used on the event structs to automatically generate getter methods for all private fields. This provides safe, read-only access to internal data.

• The use of Option<BlockHeight> accommodates cases where the block height may not be known or applicable at the time the event is created.

• StartThread is the only variant that contains multiple fields directly in the enum variant rather than wrapping a struct.

• The enum design favors extensibility by grouping all chain pulse events together, simplifying event handling logic elsewhere in the system.

Interactions with Other Modules

• Uses ThreadIdentifier and BlockHeight types from the crate::types module to uniquely identify threads and block heights.

• Uses UnfinalizedCandidateBlockCollection from crate::node::unprocessed_blocks_collection to represent collections of candidate blocks for thread startup.

• These events are likely consumed by components responsible for updating node state, triggering consensus operations, or notifying subsystems of blockchain state transitions.

Diagram

classDiagram
class BlockFinalizedEvent {
-thread_identifier
-block_height
+thread_identifier()
+block_height()
}
class BlockPrefinalizedEvent {
-thread_identifier
-block_height
+thread_identifier()
+block_height()
}
class BlockAppliedEvent {
-thread_identifier
-block_height
+thread_identifier()
+block_height()
}
class ChainPulseEvent {
+block_finalized()
+block_prefinalized()
+block_applied()
+start_thread()
}
ChainPulseEvent o-- BlockFinalizedEvent : contains
ChainPulseEvent o-- BlockPrefinalizedEvent : contains
ChainPulseEvent o-- BlockAppliedEvent : contains
ChainPulseEvent ..> UnfinalizedCandidateBlockCollection : uses in StartThread
ChainPulseEvent ..> ThreadIdentifier
BlockFinalizedEvent ..> ThreadIdentifier
BlockPrefinalizedEvent ..> ThreadIdentifier
BlockAppliedEvent ..> ThreadIdentifier

This diagram illustrates the relationship among the event structs and the ChainPulseEvent enum, showing composition and usage relations with key types.