mod.rs

Overview

This file defines core network message structures and related functionality for handling block propagation, acknowledgments, synchronization, and authority switch protocols within the system. It provides serializable types for transmitting blocks and various network messages among nodes. The file's primary focus is on representing blocks and network messages with associated metadata, enabling their serialization/deserialization and formatted display for debugging and logging purposes.

The file interacts heavily with cryptographic envelope structures (Envelope), block-related types (AckiNackiBlock, BlockIdentifier, etc.), node identifiers, threading, and the authority switch protocol. It serves as a bridge between raw cryptographic block envelopes and higher-level network message types used by the system's node communication layer.

Structures and Enums

NetBlock

A serializable wrapper around a block envelope, extracting and storing metadata needed for network transmission.

Fields

• producer_id: NodeIdentifier
  Identifier of the node that produced the block.

• producer_selector: Option<ProducerSelector>
  Optional selector information used to select the producer.

• thread_id: ThreadIdentifier
  Identifier of the thread to which the block belongs.

• identifier: BlockIdentifier
  Unique identifier of the block.

• seq_no: BlockSeqNo
  Sequence number of the block within the thread.

• envelope_data: Vec<u8>
  Serialized bytes of the block envelope.

Methods

• with_envelope(value: &Envelope<GoshBLS, AckiNackiBlock>) -> anyhow::Result<Self>
  Constructs a NetBlock instance from a reference to a cryptographic envelope containing an AckiNackiBlock. It serializes the envelope using bincode, extracts the block metadata, and populates the fields accordingly.

  Parameters:

  • value: Reference to an Envelope wrapping an AckiNackiBlock.

  Returns:

  • Ok(NetBlock) on success.

  • Err if serialization fails.

  Usage example:

  let net_block = NetBlock::with_envelope(&envelope)?;
  

• get_envelope(&self) -> anyhow::Result<Envelope<GoshBLS, AckiNackiBlock>>
  Deserializes the stored envelope_data back into an Envelope.

  Returns:

  • Ok(Envelope) deserialized from envelope_data.

  • Err if deserialization fails.

  Usage example:

  let envelope = net_block.get_envelope()?;
  

Trait Implementations

• Display and Debug
  Both provide formatted output focusing on the block's sequence number, identifier, and thread. This helps in logging and debugging without printing all envelope data.

Command Enum

Represents internal commands used within the authority switch service.

• Variants:

  • StartSynchronization
    Indicates a command to initiate synchronization.

NetworkMessage Enum

Defines all possible network messages transmitted between nodes. It encapsulates various block-related messages, synchronization commands, authority switch protocol messages, and local commands.

Variants

• Candidate(NetBlock)
  A candidate block submitted to the network.

• ResentCandidate((NetBlock, NodeIdentifier))
  A candidate block envelope re-sent by a replacing producer, along with the node identifier of the sender.

• Ack((Envelope<GoshBLS, AckData>, ThreadIdentifier))
  Acknowledgment message carrying an envelope with acknowledgment data.

• Nack((Envelope<GoshBLS, NackData>, ThreadIdentifier))
  Negative acknowledgment message. Intended currently for full stake nodes only.

• ExternalMessage((WrappedMessage, ThreadIdentifier))
  External messages wrapped and associated with a thread ID.

• NodeJoining((NodeIdentifier, ThreadIdentifier))
  Notification that a node is joining a thread.

• BlockAttestation((Envelope<GoshBLS, AttestationData>, ThreadIdentifier))
  Attestation related to a block.

• BlockRequest { ... }
  Request for a range of blocks from a node.

  Fields:

  • inclusive_from: BlockSeqNo — Start sequence number (inclusive).

  • exclusive_to: BlockSeqNo — End sequence number (exclusive).

  • requester: NodeIdentifier — Node making the request.

  • thread_id: ThreadIdentifier — Thread to which the request pertains.

  • at_least_n_blocks: Option<usize> — Optional minimum number of blocks requested.

• SyncFinalized((Envelope<GoshBLS, SyncFinalizedData>, ThreadIdentifier))
  Message broadcast when the network is not running, intended for disaster recovery and restarting synchronization.

• SyncFrom((BlockSeqNo, ThreadIdentifier))
  Request or notification to synchronize from a specific block sequence number.

• AuthoritySwitchProtocol(AuthoritySwitch)
  Messages related to the authority switch protocol, such as requests, rejections, success, or failure notifications.

• InnerCommand(Command)
  Local commands, such as StartSynchronization.

Methods

• candidate(envelope: &Envelope<GoshBLS, AckiNackiBlock>) -> anyhow::Result<Self>
  Creates a NetworkMessage::Candidate from a given envelope.

  Usage example:

  let msg = NetworkMessage::candidate(&envelope)?;
  

• resent_candidate(envelope: &Envelope<GoshBLS, AckiNackiBlock>, node_id: NodeIdentifier) -> anyhow::Result<Self>
  Creates a NetworkMessage::ResentCandidate variant from an envelope and node identifier.

  Usage example:

  let msg = NetworkMessage::resent_candidate(&envelope, node_id)?;
  

Trait Implementations

• Debug
  Provides formatted debug output that varies depending on whether the alternate formatting flag ({:#?}) is set:

  • Without alternate: prints variant names and concise information about content.

  • With alternate: prints only variant names for brevity.

Implementation Details and Algorithms

• Serialization and Deserialization:
  The NetBlock structure serializes the entire block envelope using bincode to a byte vector (envelope_data). This allows efficient network transmission of blocks with associated metadata. The deserialization reconstructs the original envelope from the byte vector.

• Envelope Usage:
  The system uses cryptographic envelopes (Envelope<GoshBLS, T>) to wrap messages for signing and verification purposes, ensuring authenticity and integrity of blocks and messages.

• Message Enum Design:
  The NetworkMessage enum is designed with variants to cover all message types exchanged in the network protocol, from block propagation to synchronization and authority switching. The use of tuple structs and named fields allows flexible and type-safe encapsulation of data.

• Debug Formatting:
  The conditional debug output supports both concise and detailed logging modes, aiding diagnostics.

Interactions with Other Modules

• crate::bls
  Uses Envelope and BLSSignedEnvelope for cryptographic signing and verification of messages.

• crate::message
  Wraps external messages into WrappedMessage for network transmission.

• crate::node::associated_types
  Uses specific data types like AckData, NackData, AttestationData, and SyncFinalizedData which represent the payloads of different message types.

• crate::node
  Uses NodeIdentifier to uniquely identify peers in the network.

• crate::protocol::authority_switch
  Integrates with AuthoritySwitch messages to handle authority switching protocol communication.

• crate::types
  Uses types such as BlockIdentifier, BlockSeqNo, ThreadIdentifier, and ProducerSelector to identify blocks, threads, and producers.

• serde_network_message (private module)
  Likely contains customized serialization/deserialization logic for network messages (not shown here).

Visual Diagram

classDiagram
class NetBlock {
+producer_id: NodeIdentifier
+producer_selector: Option<ProducerSelector>
+thread_id: ThreadIdentifier
+identifier: BlockIdentifier
+seq_no: BlockSeqNo
+envelope_data: Vec<u8>
+with_envelope()
+get_envelope()
}
class Command {
<<enum>>
+StartSynchronization
}
class NetworkMessage {
<<enum>>
+Candidate
+ResentCandidate
+Ack
+Nack
+ExternalMessage
+NodeJoining
+BlockAttestation
+BlockRequest
+SyncFinalized
+SyncFrom
+AuthoritySwitchProtocol
+InnerCommand
+candidate()
+resent_candidate()
}
NetBlock --> Envelope
NetworkMessage --> NetBlock
NetworkMessage --> Envelope
NetworkMessage --> Command
NetworkMessage --> AuthoritySwitch

Usage Examples

Creating a NetBlock from an Envelope

let envelope: Envelope<GoshBLS, AckiNackiBlock> = ...;
let net_block = NetBlock::with_envelope(&envelope)?;
println!("NetBlock: {}", net_block);

Creating a Candidate Network Message

let candidate_msg = NetworkMessage::candidate(&envelope)?;
match candidate_msg {
    NetworkMessage::Candidate(block) => {
        // Process candidate block
    }
    _ => {}
}

Debugging a Network Message

let network_msg: NetworkMessage = ...;
println!("{:?}", network_msg);       // Concise debug output
println!("{:#?}", network_msg);      // Verbose debug output (only variant names)

References

• Envelope Structure and Cryptographic Signing

• Block and Thread Identifiers

• Authority Switch Protocol

• Node Identifiers and Associated Types

• Serialization with Serde and Bincode

• Message Wrapping and External Messages