feedback.rs

Overview

This file defines the AckiNackiSend struct and its associated functionality for sending acknowledgment (ACK) and negative acknowledgment (NACK) messages related to block states within a distributed network. It handles the cryptographic signing of these messages using BLS signatures, manages the destinations for ACK messages, and broadcasts NACK messages when necessary. The file plays a critical role in the communication protocol between nodes by signaling block acceptance or rejection during consensus or validation phases.

Structs and Main Components

AckiNackiSend

A struct responsible for sending ACK and NACK messages in response to block states.

Fields

• node_id: NodeIdentifier
  The identifier of the current node sending the messages.

• bls_keys_map: Arc<Mutex<HashMap<PubKey, (Secret, RndSeed)>>>
  An atomic reference-counted, mutex-protected map storing BLS keys (private secrets and random seeds) indexed by public keys. Used for signing messages.

• ack_network_direct_tx: NetDirectSender<NodeIdentifier, NetworkMessage>
  A direct network sender channel used to send ACK messages to specific nodes.

• nack_network_broadcast_tx: NetBroadcastSender<NetworkMessage>
  A broadcast network sender channel used to broadcast NACK messages to all relevant nodes.

Methods

send_ack(&self, block_state: BlockState) -> anyhow::Result<()>

Sends an ACK message to all interested parties (nodes) for a given block state.

Parameters

• block_state — The current state of the block to acknowledge.

Returns

• Ok(()) if the ACK messages are sent successfully.

• An error (anyhow::Result error type) if required data is missing or sending fails (except during shutdown).

Description

• Extracts block identifier, sequence number, interested parties for attestation, and thread identifier from block_state.

• Removes the current node from the list of destinations.

• Retrieves the current node's signer index and secret for the block epoch.

• Signs an AckData payload containing the block ID and sequence number using the node's secret.

• Constructs an Envelope wrapping the signature and payload.

• Sends the ACK message directly to each destination node.

• Handles errors gracefully, allowing continued operation during shutdown.

Usage Example

let ack_sender = AckiNackiSend::builder()
    .node_id(my_node_id)
    .bls_keys_map(my_bls_keys_map)
    .ack_network_direct_tx(my_ack_sender)
    .nack_network_broadcast_tx(my_nack_sender)
    .build();

ack_sender.send_ack(current_block_state)?;

send_nack(&self, block_state: BlockState, reason: NackReason) -> anyhow::Result<()>

Broadcasts a NACK message indicating rejection of a block state with a specified reason.

Parameters

• block_state — The block state that is being negatively acknowledged.

• reason — The reason for the NACK, encapsulated in a NackReason enum.

Returns

• Ok(()) if the NACK message is broadcast successfully.

• An error if required data is missing or broadcasting fails (except during shutdown).

Description

• Extracts block identifier, sequence number, and thread identifier from block_state.

• Retrieves the current node's signer index and secret for the block epoch.

• Signs a NackData payload containing the block ID, sequence number, and reason.

• Constructs an Envelope wrapping the signature and payload.

• Broadcasts the NACK message to all nodes.

• Handles errors with awareness of shutdown state.

get_signer_data(&self, block_state: &BlockState) -> Option<(SignerIndex, Secret)>

Retrieves the signer index and secret key for the current node based on the block state's BK (Byzantine Knowledge) data.

Parameters

• block_state — Reference to the block state to extract BK data.

Returns

• Some((SignerIndex, Secret)) if the node's BK data and secret key are available.

• None if the node is not part of the BK set or secret key is missing.

Description

• Accesses BK data for the node from the block state.

• Looks up the corresponding secret key in the bls_keys_map.

• If the secret key is missing, triggers a shutdown request and logs an error.

Important Implementation Details

• Thread Safety and Concurrency:
  Uses Arc<Mutex<...>> from the parking_lot crate to safely share the mutable BLS keys map across threads.

• BLS Signature Scheme:
  Utilizes the BLS signature scheme implemented by <GoshBLS as BLSSignatureScheme> to cryptographically sign ACK and NACK data payloads.

• Error Handling:
  Uses anyhow for error propagation and ensures that send failures during shutdown do not cause panic.

• Envelope Construction:
  Messages are wrapped in Envelope structs that carry signatures, signature occurrence counts, and payload data to ensure message authenticity and integrity.

• Network Messaging:

  • ACK messages are sent directly to specific interested nodes.

  • NACK messages are broadcast to the entire network or relevant subset.

• Shutdown Coordination:
  The system monitors a global SHUTDOWN_FLAG to handle errors gracefully during shutdown sequences.

Interaction with Other Parts of the System

• BlockState
  This struct provides guarded access to block-related metadata such as block identifiers, sequence numbers, BK data, and thread identifiers.

• BLS Cryptography Modules (bls, BLSSignatureScheme, GoshBLS)
  Responsible for signing and verifying cryptographic messages used for consensus.

• Network Channels (NetDirectSender, NetBroadcastSender)
  Provide abstractions for sending messages directly to nodes or broadcasting within the network.

• NetworkMessage Enum
  Used to wrap ACK and NACK messages for transmission.

• Shutdown Coordination Helper (start_shutdown, SHUTDOWN_FLAG)
  Used to signal and detect system shutdown state.

Mermaid Diagram: AckiNackiSend Structure and Method Relationships

classDiagram
class AckiNackiSend {
- node_id: NodeIdentifier
- bls_keys_map: Arc<Mutex<HashMap<PubKey, (Secret, RndSeed)>>>
- ack_network_direct_tx: NetDirectSender
- nack_network_broadcast_tx: NetBroadcastSender
+ send_ack()
+ send_nack()
- get_signer_data()
}
AckiNackiSend --> BlockState : Uses
AckiNackiSend --> NetworkMessage : Sends
AckiNackiSend --> BLSSignatureScheme : Uses for signing
AckiNackiSend --> Envelope : Wraps messages
AckiNackiSend --> SHUTDOWN_FLAG : Checks shutdown state