mod.rs

Overview

This file defines the ThreadState struct and its associated methods, which manage the state transitions of blockchain blocks in a thread. The struct handles two types of checkpoints: a finalized block that is immutable and a prefinalized block that can be reverted if necessary. The implementation enforces non-clonability of ThreadState to prevent unintended duplication and state inconsistencies.

The primary functionality is to move forward the finalized and prefinalized states by applying new blocks wrapped in cryptographic envelopes (Envelope<GoshBLS, AckiNackiBlock>). This ensures that state progression is cryptographically verified and consistent with the consensus rules.

Structs and Methods

ThreadState

pub struct ThreadState {
    last_finalized: Checkpoint,
    last_prefinalized: Checkpoint,
}

• Description:
  Represents the state of a single thread in the blockchain processing pipeline.

  • last_finalized: The last block that has been finalized and cannot be rolled back.

  • last_prefinalized: The last block that is prefinalized and may be rolled back upon receiving a negative acknowledgment (NACK).

• Non-Clonability:
  The ThreadState is intentionally not clonable to ensure that no unintended inner clones of its state occur, preserving correct state management semantics.

Methods

move_finalized

pub fn move_finalized(self, next_finalized_block: Envelope<GoshBLS, AckiNackiBlock>) -> Self

• Purpose:
  Transitions the ThreadState to a new finalized block by applying the given next_finalized_block. This operation is designed to never fail, ensuring that all necessary validation and application logic succeeds before the state is updated.

• Parameters:

  • self: The current ThreadState instance, consumed to produce a new state.

  • next_finalized_block: An Envelope wrapping a AckiNackiBlock signed or authenticated with GoshBLS, representing the next finalized block to apply.

• Returns:

  • A new ThreadState instance with the updated last_finalized checkpoint.

• Implementation Details:
  The method extracts the current last_finalized checkpoint, applies the new block to it, and unwraps the result, assuming success. This implies that the apply method on Checkpoint performs all necessary validation and transformation. The method then returns a new ThreadState with this updated checkpoint.

• Usage Example:

let updated_state = current_state.move_finalized(next_block_envelope);

move_prefinalized

pub fn move_prefinalized(self, next_prefinalized_block: Envelope<GoshBLS, AckiNackiBlock>) -> Self

• Purpose:
  Intended to update the last_prefinalized checkpoint with a new prefinalized block. Unlike finalized blocks, this checkpoint can be rolled back if a NACK is received, indicating that the block was rejected by the consensus or validation process.

• Parameters:

  • self: The current ThreadState instance, consumed to produce a new state.

  • next_prefinalized_block: An Envelope wrapping a AckiNackiBlock signed or authenticated with GoshBLS.

• Returns:

  • A new ThreadState instance with the updated last_prefinalized checkpoint.

• Implementation Status:
  The method body is currently empty and needs to be implemented to mirror similar logic to move_finalized, but with rollback capability considerations.

Important Implementation Details

• Immutability of Finalized Checkpoints:
  Once a block is finalized, it becomes immutable and cannot be rolled back. This principle is enforced by storing it separately and only allowing forward progression through move_finalized.

• Rollback Capability for Prefinalized Checkpoints:
  Prefinalized blocks can be reverted if consensus rejects them, thus requiring separate management and logic to handle rollbacks.

• Use of Cryptographic Envelopes:
  Blocks are wrapped in Envelope<GoshBLS, AckiNackiBlock>, ensuring they are authenticated using the Boneh–Lynn–Shacham (BLS) signature scheme implemented by GoshBLS. This integration ensures cryptographic guarantees on block authenticity.

• Error Handling Assumptions:
  The move_finalized method uses .unwrap() on the result of applying a block to a checkpoint, indicating that failure scenarios are considered impossible or handled prior to this call.

• Non-Clonability Enforcement:
  The struct purposely avoids deriving or implementing Clone to prevent accidental copying, which could lead to inconsistent or duplicated state in concurrent or asynchronous environments.

Interactions with Other Components

• Checkpoint Struct:
  The core state transitions rely heavily on the Checkpoint type and its apply method to incorporate new blocks. Checkpoint is responsible for maintaining block data and applying new blocks to update the state.

• Envelope and GoshBLS:
  The file uses Envelope<GoshBLS, AckiNackiBlock> as the container for blocks. This indicates integration with cryptographic signing and verification components, where GoshBLS provides the BLS signature scheme, and Envelope packages blocks with their cryptographic proofs.

• AckiNackiBlock:
  Blocks of type AckiNackiBlock are the fundamental unit of blockchain data passed around and applied to checkpoints. They likely represent blocks with acknowledgment (ACK) or negative acknowledgment (NACK) semantics.

• OptimisticStateImpl and Repository:
  Although not directly referenced in the methods, the import of OptimisticStateImpl suggests that this file's state management may be part of a broader optimistic concurrency control layer within the repository module.

Mermaid Diagram

classDiagram
class ThreadState {
-last_finalized: Checkpoint
-last_prefinalized: Checkpoint
+move_finalized()
+move_prefinalized()
}
ThreadState --> Checkpoint : uses
ThreadState --> Envelope : consumes
Envelope --> GoshBLS : cryptographic wrapper
Envelope --> AckiNackiBlock : contains