associated_types.rs

Overview

The associated_types.rs file defines key data types, enumerations, traits, and implementations related to node operation within the system, particularly focusing on node identifiers, block acknowledgments (Ack), negative acknowledgments (Nack), attestations, and synchronization results. It establishes the types associated with node messaging envelopes and processing outcomes, supporting cryptographic signing and deserialization/serialization for network communication. This file is central to managing node identities, block validation responses, and synchronization workflows in the distributed environment.

Detailed Descriptions

Type Aliases

• SignerIndex: An alias for u16 representing the index of a signer.

Structs and Enums

NodeIdentifier

Represents a unique identifier for a node. It wraps around the AccountAddress type and provides serialization, deserialization, string parsing, and display formatting.

• Purpose: Used to uniquely identify nodes in the network.

• Key Traits: Implements Serialize, Deserialize, FromStr, Display, and conversions from and to AccountAddress and tvm_types::AccountId.

• Methods:

  • some_id() (test/feature gated): Returns a fixed example NodeIdentifier.

  • test(seed: usize) (test/feature gated): Generates a NodeIdentifier from a numeric seed.

Usage example:

let node_id: NodeIdentifier = "81a6bea128f5...".parse().unwrap();
println!("{}", node_id);

NackReason

An enum representing reasons for negative acknowledgment (Nack) of blocks.

• Variants:

  • BadBlock { envelope }: Indicates a block was invalid.

  • TooComplexExecution { envelope }: Indicates block execution was too complex.

  • WrongNack { nack_data_envelope }: Indicates an invalid Nack was received.

• Methods:

  • get_hash_nack() -> anyhow::Result<UInt256>: Returns the hash associated with the Nack reason. For WrongNack, returns an error.

  • get_node_data(block_state_repository: BlockStateRepository) -> Option<(NodeIdentifier, PubKey, AccountAddress)>: Extracts node-related data (node ID, public key, wallet address) relevant to the Nack reason by querying the block state repository.

• Debug Implementation: Provides formatted debug strings for each variant.

Implementation details: Uses cryptographic hash calculations and state repository lookups to associate Nack reasons with node metadata.

Trait NodeAssociatedTypes

Defines associated envelope types for a node, representing different types of signed messages.

• Associated Types:

  • CandidateBlock: Envelope type carrying candidate block data.

  • Ack: Envelope type for acknowledgment data.

  • Nack: Envelope type for negative acknowledgment data.

  • BlockAttestation: Envelope type for block attestation data.

• Implementations:

  • For Node<TStateSyncService, TRandomGenerator>: Uses Envelope<GoshBLS, ...> with respective data types.

  • For BlockRequestService: Same associated types as the Node implementation.

Enum SynchronizationResult<TNetworkMessage>

Describes outcomes of node synchronization processes.

• Variants:

  • Ok: Synchronization finished successfully.

  • Forward(TNetworkMessage): Synchronization succeeded and produced a block message to continue with.

  • Interrupted: Synchronization failed due to disconnected node receive channel.

Enum ExecutionResult

Represents results of block execution attempts.

• Variants:

  • SynchronizationRequired: Node missed blocks and must synchronize.

  • Disconnected: Node receive channel disconnected.

Enum BlockStatus

Indicates the processing status of a block.

• Variants:

  • Ok: Block processed successfully.

  • Skipped: Block skipped (too old).

  • BadBlock: Block failed hash/signature checks.

  • BlockCantBeApplied: Block cannot be applied to the current state.

  • SynchronizationRequired: Block triggered synchronization.

Struct AckData

Data carried in an acknowledgment message.

• Fields:

  • block_id: BlockIdentifier: Identifier of the acknowledged block.

  • block_seq_no: BlockSeqNo: Sequence number of the block.

Struct NackData

Data carried in a negative acknowledgment message.

• Fields:

  • block_id: BlockIdentifier: Identifier of the block that is negatively acknowledged.

  • block_seq_no: BlockSeqNo: Sequence number.

  • reason: NackReason: Reason for the negative acknowledgment.

Enum AttestationTargetType

Defines the type of attestation target.

• Variants:

  • Primary

  • Fallback

Struct AttestationData

Represents data for block attestation messages.

• Fields (all private with getters):

  • parent_block_id: BlockIdentifier

  • block_id: BlockIdentifier

  • block_seq_no: BlockSeqNo

  • envelope_hash: AckiNackiEnvelopeHash

  • target_type: AttestationTargetType

• Built via TypedBuilder pattern for ergonomic construction.

Struct SyncFinalizedData

Data structure representing finalized synchronization information.

• Fields (private with getters):

  • block_identifier: BlockIdentifier

  • block_seq_no: BlockSeqNo

  • thread_refs: BTreeMap<ThreadIdentifier, BlockIdentifier> — references to blocks per thread.

• Uses TypedBuilder for construction and supports serialization/deserialization.

Implementation Details and Algorithms

• NackReason Hashing: The get_hash_nack() method computes a hash for the Nack reason by extracting the hash from the envelope's underlying block data.

• Node Data Extraction from NackReason: The get_node_data() method accesses the BlockStateRepository to fetch the BLS public key and wallet address associated with the node that produced the block causing the Nack.

• Serialization/Deserialization: NodeIdentifier and envelope data types implement Serde traits for network communication.

• TypedBuilder Usage: Structures like AttestationData and SyncFinalizedData use the TypedBuilder macro for flexible and readable construction.

• Trait-Based Associated Types: The NodeAssociatedTypes trait abstracts over types of envelopes used by different node implementations, enforcing type consistency.

Interactions with Other System Components

• BlockRequestService and Node: Both implement NodeAssociatedTypes, linking envelope types to these services.

• BlockStateRepository: Used within NackReason to query blockchain state for node metadata.

• Envelope Types: Utilize cryptographic envelopes (Envelope<GoshBLS, T>) for signed messages related to blocks and acknowledgments.

• AccountAddress and UInt256: Used extensively for node identification and cryptographic hashes.

• StateSyncService and RepositoryImpl: Referenced in trait bounds to ensure correct repository types are used with node synchronization.

• BTreeMap/ThreadIdentifier: Used in synchronization data to track finalized blocks per thread.

Visual Diagram

classDiagram
class NodeIdentifier {
+AccountAddress value
+some_id()
+test(seed)
+from_str()
+to_string()
}
class NackReason {
<<enum>>
+BadBlock
+TooComplexExecution
+WrongNack
+get_hash_nack()
+get_node_data()
}
class NodeAssociatedTypes {
<<trait>>
+CandidateBlock
+Ack
+Nack
+BlockAttestation
}
class SynchronizationResult {
<<enum>>
+Ok
+Forward
+Interrupted
}
class ExecutionResult {
<<enum>>
+SynchronizationRequired
+Disconnected
}
class BlockStatus {
<<enum>>
+Ok
+Skipped
+BadBlock
+BlockCantBeApplied
+SynchronizationRequired
}
class AckData {
+BlockIdentifier block_id
+BlockSeqNo block_seq_no
}
class NackData {
+BlockIdentifier block_id
+BlockSeqNo block_seq_no
+NackReason reason
}
class AttestationTargetType {
<<enum>>
+Primary
+Fallback
}
class AttestationData {
+BlockIdentifier parent_block_id
+BlockIdentifier block_id
+BlockSeqNo block_seq_no
+AckiNackiEnvelopeHash envelope_hash
+AttestationTargetType target_type
}
class SyncFinalizedData {
+BlockIdentifier block_identifier
+BlockSeqNo block_seq_no
+BTreeMap thread_refs
}
NodeAssociatedTypes <|.. Node
NodeAssociatedTypes <|.. BlockRequestService
NackData --> NackReason
AttestationData --> AttestationTargetType
SyncFinalizedData --> BTreeMap
NackReason --> BlockStateRepository : uses
NodeIdentifier --> AccountAddress

This diagram illustrates the main data types, their relationships, and their role in representing node-related data and message envelopes within the system. The trait NodeAssociatedTypes connects node implementations to their associated envelope types, while enums and structs model processing results and block metadata.