service.rs

Overview

This file implements the BlockProcessorService, a core component responsible for processing candidate blocks within a thread of the blockchain. The service manages block validation, attestation processing, signature verification, and the application of blocks to the optimistic state repository. It interacts closely with other system components such as the block state repository, network services, validation services, and shared services to ensure blocks are correctly validated, finalized, and integrated into the chain.

The service operates in a dedicated thread and continuously processes unfinalized blocks, managing their lifecycle from reception through validation and finalization, including handling cross-thread references and synchronization.

Main Structures and Functions

BlockProcessorService

Description

The main service struct that encapsulates the block processing thread handle and a flag indicating whether missing blocks were requested.

Fields

Methods

new
pub fn new(
    security_guarantee: SecurityGuarantee,
    node_id: NodeIdentifier,
    time_to_produce_block: Duration,
    save_state_frequency: u32,
    bls_keys_map: Arc<Mutex<HashMap<PubKey, (Secret, RndSeed)>>>,
    thread_identifier: ThreadIdentifier,
    block_state_repository: BlockStateRepository,
    repository: RepositoryImpl,
    shared_services: SharedServices,
    nack_set_cache: Arc<Mutex<FixedSizeHashSet<UInt256>>>,
    send_direct_tx: NetDirectSender<NodeIdentifier, NetworkMessage>,
    broadcast_tx: NetBroadcastSender<NetworkMessage>,
    skipped_attestation_ids: Arc<Mutex<HashSet<BlockIdentifier>>>,
    block_gap: BlockGap,
    validation_service: ValidationServiceInterface,
    share_service: ExternalFileSharesBased,
    send: AckiNackiSend,
    chain_pulse_monitor: std::sync::mpsc::Sender<ChainPulseEvent>,
    unprocessed_blocks_cache: UnfinalizedCandidateBlockCollection,
    cross_thread_ref_data_availability_synchronization_service: CrossThreadRefDataAvailabilitySynchronizationServiceInterface,
    save_optimistic_service_sender: InstrumentedSender<Arc<OptimisticStateImpl>>,
) -> Self

Creates and starts the block processing service thread.

let service = BlockProcessorService::new(
    security_guarantee,
    node_id,
    time_to_produce_block,
    save_state_frequency,
    bls_keys_map,
    thread_identifier,
    block_state_repository,
    repository,
    shared_services,
    nack_set_cache,
    send_direct_tx,
    broadcast_tx,
    skipped_attestation_ids,
    block_gap,
    validation_service,
    share_service,
    send,
    chain_pulse_monitor,
    unprocessed_blocks_cache,
    cross_thread_ref_data_availability_synchronization_service,
    save_optimistic_service_sender,
);

SecurityGuarantee

Description

Represents a security guarantee as a floating-point number indicating the chance of a successful attack.

Fields

Methods

calculate_v_parameter

fn calculate_v_parameter(
    attestation_target_in_bkset_size: usize,
    chance_of_successful_attack: f64,
    bk_set_size: usize,
) -> f64

Calculates the expected number of acki-nacki (acknowledgment/nacknowledgment) messages v based on the attestation target, attack probability, and block keeper set size.

process_candidate_block

fn process_candidate_block(
    security_guarantee: SecurityGuarantee,
    node_id: NodeIdentifier,
    save_state_frequency: u32,
    bls_keys_map: Arc<Mutex<HashMap<PubKey, (Secret, RndSeed)>>>,
    block_state: &BlockState,
    block_state_repository: &BlockStateRepository,
    repository: &RepositoryImpl,
    shared_services: &mut SharedServices,
    nack_set_cache: Arc<Mutex<FixedSizeHashSet<UInt256>>>,
    skipped_attestation_ids: &Arc<Mutex<HashSet<BlockIdentifier>>>,
    candidate_block: &Envelope<GoshBLS, AckiNackiBlock>,
    validation_service: &ValidationServiceInterface,
    time_to_produce_block: &Duration,
    share_service: ExternalFileSharesBased,
    send: AckiNackiSend,
    chain_pulse_monitor: &Sender<ChainPulseEvent>,
    cross_thread_ref_data_availability_synchronization_service: &mut CrossThreadRefDataAvailabilitySynchronizationServiceInterface,
    save_optimistic_service_sender: &InstrumentedSender<Arc<OptimisticStateImpl>>,
    filter_prehistoric: &FilterPrehistoric,
) -> anyhow::Result<()>

Processes an individual candidate block, including validation, signature verification, attestation processing, optimistic state application, and finalization steps.

process_candidate_block(
    security_guarantee,
    node_id,
    save_state_frequency,
    bls_keys_map,
    block_state,
    &block_state_repository,
    &repository,
    &mut shared_services,
    nack_set_cache,
    &skipped_attestation_ids,
    candidate_block,
    &validation_service,
    &time_to_produce_block,
    share_service,
    send,
    &chain_pulse_monitor,
    &mut cross_thread_ref_data_availability_synchronization_service,
    &save_optimistic_service_sender,
    &filter_prehistoric,
)?;

verify_all_block_signatures

pub(crate) fn verify_all_block_signatures(
    block_state_repository: &BlockStateRepository,
    candidate_block: &Envelope<GoshBLS, AckiNackiBlock>,
    block_state: &BlockState,
    skipped_attestation_ids: &Arc<Mutex<HashSet<BlockIdentifier>>>,
) -> Option<bool>

Verifies the producer's signature on the block envelope and the signatures on all block attestations within the common section.

check_common_block_params

fn check_common_block_params(
    candidate_block: &Envelope<GoshBLS, AckiNackiBlock>,
    parent_block_state: &BlockState,
    _time_to_produce_block: &Duration,
    block_state: &BlockState,
) -> anyhow::Result<bool>

Performs basic validation checks on the candidate block against its parent, including sequence number, block height, and producer selection.

process_block_attestations

fn process_block_attestations(
    block_state: &BlockState,
    parent_block_state: &BlockState,
    block_state_repository: &BlockStateRepository,
    candidate_block: &Envelope<GoshBLS, AckiNackiBlock>,
    validation_service: &ValidationServiceInterface,
    chain_pulse_monitor: &Sender<ChainPulseEvent>,
    filter_prehistoric: &FilterPrehistoric,
    shared_services: &SharedServices,
) -> anyhow::Result<bool>

Processes block attestations, updating finalization checkpoints, setting prefinalization and finalization proofs, and managing fallback attestation states.

Important Implementation Details and Algorithms

Interaction with Other System Components

Visual Diagram of BlockProcessorService Structure and Workflow

flowchart TD
A[BlockProcessorService] --> B[New Service Thread]
B --> C[Main Loop: Process Unfinalized Blocks]
C --> D[Remove Finalized/Invalidated Blocks]
C --> E[Fetch Last Finalized Block]
C --> F[Pulse ChainPulse]
C --> G[Clone Unprocessed Blocks Queue]
G --> H[Iterate Candidate Blocks]
H --> I["process_candidate_block()"]
I --> J[Check Common Block Params]
I --> K[Verify Signatures]
I --> L[Process Block Attestations]
I --> M[Apply Block to Optimistic State]
I --> N[Send Validation Requests]
I --> O[Handle Cross-Thread Ref Data]
I --> P[Update Metrics]

This flowchart outlines the main workflow inside the spawned thread of the BlockProcessorService, showing the processing of unfinalized blocks including validation, attestation processing, application, and interaction with other services.

Additional Notes

For related concepts, see topics such as Block State Management, Attestation Processing, Signature Verification, and Consensus Mechanisms.