Skip to main content

blossom/
lib.rs

1//! Blossom v2 consensus protocol.
2//!
3//! This crate contains the protocol messages, quorum selection, block
4//! commitment, membership reducers, runtime service registry, TCP wire surface,
5//! telemetry events, and block-intake primitives needed to build and test
6//! Blossom nodes.
7//!
8//! Blossom is application-agnostic: transaction payload bytes and block-carried
9//! application state are committed by the protocol but interpreted by the
10//! application layer. Ledger, cache, database, and workflow integrations should
11//! live above this crate.
12//!
13//! Start with [`NodeRuntime`] for consensus participation, [`OverlayRuntime`]
14//! for topology-aware fan-out without epoch state, [`WireRequest`] for TCP
15//! integration, and [`Transaction`] plus [`Block`] for application bytes.
16
17#[cfg(feature = "active-active")]
18/// Durable application-owned commands with globally certified ordering.
19pub mod active_active;
20#[cfg(feature = "high-availability")]
21/// Crash-safe coordination between accepted lifecycle and global ordering.
22pub mod active_active_coordinator;
23#[cfg(feature = "high-availability")]
24/// Recovery and contract-cutover orchestration for active-active HA groups.
25pub mod active_active_ha;
26#[cfg(feature = "active-passive")]
27/// Native OpenRaft active-passive replication and durable log adapters.
28pub mod active_passive;
29/// Service records and the node-local address book.
30pub mod address_book;
31/// Signed node admission and reconnect evidence.
32pub mod admission;
33/// Quorum thresholds, deterministic selection, and topology calculations.
34pub mod algorithm;
35#[cfg(feature = "availability-gossip")]
36/// Certified availability metadata and filtered-payload transfer.
37pub mod availability;
38/// Blocks, opaque transactions, commitments, and fair ordering.
39pub mod block;
40/// Durable block indexing by nonce and hash.
41pub mod block_store;
42/// Consensus protocol messages and their validation rules.
43pub mod blossom;
44/// Public keys, signing keys, signatures, and verification helpers.
45pub mod crypto;
46/// Signed peer-encounter evidence.
47pub mod encounter;
48/// Crate-wide errors and the [`Result`] alias.
49pub mod error;
50/// Consensus group identifiers.
51pub mod group;
52/// In-process test and benchmark harnesses.
53pub mod harness;
54/// Protocol hashes, domains, and feature registry.
55pub mod hash;
56#[cfg(feature = "high-availability")]
57/// Trusted fixed-membership HA consensus for two through seven nodes.
58pub mod high_availability;
59/// Latency relationships and topology-aware peer selection.
60pub mod latency_topology;
61/// Node-local block construction and bounded pending queues.
62pub mod local_block;
63/// Transactional embedded persistence backed by ShardLog.
64pub mod log_store;
65/// Validator membership, service capabilities, and freshness certificates.
66pub mod membership;
67/// The top-level consensus message enum and stable message keys.
68pub mod messages;
69/// Public node identity and node-role types.
70pub mod node;
71/// Monotonic epoch nonces.
72pub mod nonce;
73/// Topology fan-out without consensus epoch ownership.
74pub mod overlay;
75#[cfg(feature = "parallel-networks")]
76/// Coordination records for independent HA and Global Blossom networks.
77pub mod parallel_networks;
78#[cfg(any(
79    feature = "propagation-adaptive",
80    feature = "propagation-inventory",
81    feature = "propagation-push"
82))]
83/// Feature-gated latency, bandwidth, and adaptive data-plane policies.
84pub mod propagation;
85/// Per-round message matrices and quorum queues.
86pub mod register;
87/// Certified round skipping and future-round assistance.
88pub mod round_skip;
89/// The embeddable verified and trusted node runtime.
90pub mod runtime;
91/// Site-aware committee layout and safety manifests.
92pub mod safety;
93/// Typed TCP service-client operations.
94pub mod service_client;
95/// Epoch chains and in-progress consensus state.
96pub mod state;
97#[cfg(feature = "availability-gossip")]
98/// Subset-gossip and prefill propagation models.
99pub mod subset_gossip;
100/// TCP nodes, drivers, and connection helpers.
101pub mod tcp;
102/// Structured protocol telemetry and optional exporters.
103pub mod telemetry;
104#[cfg(feature = "trusted-checkpoint-dag")]
105/// Append-only dissemination beneath trusted sequential checkpoints.
106pub mod trusted_dag;
107/// Crash-safe trusted epoch and confirmation storage.
108pub mod trusted_log;
109/// Bounded Borsh wire frames and optimized hot-path codecs.
110pub mod wire;
111
112#[cfg(feature = "active-active")]
113pub use active_active::{
114    ActiveActiveCommand, ActiveActiveConsistencyMode, ActiveActiveDurabilityMetrics,
115    AdmissionBatchReceipt, AdmissionBatchReceiptBody, AdmissionReceipt, AdmissionReceiptBody,
116    AdmittedCommand, ApplicationCommand, ApplicationCommandEnvelope, ApplicationContractActivation,
117    ApplicationResult, AppliedBy, AppliedByTracker, AppliedCompletion, ApplyProgress,
118    AuthenticatedAvailabilityReceipt, AvailabilityCertificate, AvailabilityReceiptBody,
119    AvailabilityTrust, BatchReference, BatchReferenceMetadata, CertifiedReadBarrier, ClientEpoch,
120    ClientId, CommandBatch, CommandIdentity, CommandSpecVersion, DurableAdmissionStore,
121    GlobalOrderedEngine, HolderMembership, LocalAdmissionBatchCertificate,
122    LocalAdmissionCertificate, LocalAdmissionPolicy, MAX_ACTIVE_ACTIVE_SHARD_ID_BYTES,
123    MAX_APPLICATION_COMMAND_BYTES, MAX_APPLICATION_RESULT_BYTES,
124    MAX_PIPELINED_AVAILABILITY_WINDOWS, MAX_REFERENCES_PER_ORDERING_WINDOW, MAX_WAIT_FOR_TIMEOUT,
125    MembershipCutoverDisposition, Milestone, MilestoneEvent, OrderCertificate, OrderStatement,
126    OrderVote, OrderedApplication, OrderedBatch, ReadBarrierCertificate, ReadBarrierChallenge,
127    ReadBarrierRequest, ReadBarrierStatement, ReadBarrierVote, ReadConsistency, ReferenceStatus,
128    ReplicaMembershipEpoch, RetentionEvidence, RouteGeneration, StoreGeneration,
129    ValidatorGeneration, VerifiedLocalAdmissionBatch, WaitForOutcome, Watermark, WriteMode,
130    ordered_batch_references, ordered_batch_references_trusted, required_cutover_disposition,
131};
132#[cfg(feature = "high-availability")]
133pub use active_active_coordinator::{
134    ActiveActiveCoordinatorDurability, ActiveActiveGlobalCoordinator,
135};
136#[cfg(feature = "high-availability")]
137pub use active_active_ha::{
138    ACTIVE_ACTIVE_HA_CUTOVER_MANIFEST_VERSION, ACTIVE_ACTIVE_HA_RECOVERY_MANIFEST_VERSION,
139    AcceptedWriteDisposition, AcceptedWriteRecord, AcceptedWriteResolution, ActiveActiveCutover,
140    ActiveActiveHaCutoverManifest, ActiveActiveHaEngine, ActiveActiveHaLifecycleDurabilityMetrics,
141    ActiveActiveHaRecoveryManifest, ActiveActiveHaRecoveryStatus, LearnerCatchUp,
142    MAX_ACCEPTED_WRITE_ABORT_REASON_BYTES, MAX_ACTIVE_ACTIVE_HA_ACCEPTED_COMMAND_BYTES,
143    MAX_ACTIVE_ACTIVE_HA_ACCEPTED_WRITES, MAX_ACTIVE_ACTIVE_HA_SHARD_LANES,
144    PreparedActiveActiveHaShardBatch,
145};
146#[cfg(feature = "active-passive")]
147pub use active_passive::{
148    ActivePassiveClientWriteRaftError, ActivePassiveClientWriteResponse, ActivePassiveCommand,
149    ActivePassiveContract, ActivePassiveContractChange, ActivePassiveInitializeError,
150    ActivePassiveInitializeRaftError, ActivePassiveLinearizableReadError,
151    ActivePassiveMembershipError, ActivePassiveNode, ActivePassiveNodeId,
152    ActivePassiveOperationalStatus, ActivePassiveRaft, ActivePassiveRaftConfig,
153    ActivePassiveRequest, ActivePassiveResponse, ActivePassiveRuntime, ActivePassiveStartError,
154    ActivePassiveWriteError, MemoryRaftLogStore, RaftLogStoreIdentity, ShardStreamRaftLogStore,
155};
156pub use address_book::{
157    AddressBook, MAX_SERVICE_HOST_BYTES, MAX_SERVICE_PROTOCOL_BYTES,
158    MAX_SERVICE_RECORD_LIFETIME_MILLIS, Service, ServiceKind, ServiceRecordBody,
159    SignedServiceRecord,
160};
161pub use admission::{
162    NODE_ADMISSION_DOMAIN, NodeAdmission, NodeAdmissionBody, RECONNECT_VOTE_DOMAIN, ReconnectVote,
163    ReconnectVoteBody,
164};
165pub use algorithm::{
166    BLOSSOM_QUORUM_SIZE_ENV, CONSENSUS_PARAMETERS_VERSION, ConsensusParameters, QUORUM_SIZE,
167    QuorumSize, SUPERMAJORITY, byzantine_fault_bound, distinct_current_validator_count,
168    find_round_number_with_size, has_distinct_supermajority, has_supermajority,
169    max_liveness_omissions, min_supermajority_intersection, select_prefill_recipients,
170    select_prefill_recipients_with_size, select_quorums, select_quorums_from_index_tree_with_size,
171    select_quorums_with_size, supermajority_count, supermajority_has_honest_overlap,
172    supermajority_order_statistic,
173};
174#[cfg(feature = "availability-gossip")]
175pub use availability::{
176    AvailabilityEntry, AvailabilityGossip, AvailabilityGossipBody, AvailabilityReceipt,
177    AvailabilityStore, FILTERED_PAYLOAD_MAX_BYTES, FilteredPayloadBatchDelivery,
178    FilteredPayloadBatchDeliveryBody, FilteredPayloadBatchFetch, FilteredPayloadBatchFetchBody,
179    FilteredPayloadDelivery, FilteredPayloadDeliveryBody, FilteredPayloadDeliveryItem,
180    FilteredPayloadFetch, FilteredPayloadFetchBody, FilteredPayloadMissing, FilteredPayloadRequest,
181    LocalFilteredPayload, ideal_push_gossip_delay_ms, ideal_push_gossip_rounds,
182    validate_filtered_payload,
183};
184pub use block::{
185    BLOCK_APPLICATION_STATE_MAX_BYTES, BLOCK_APPLICATION_STATE_SOFT_LIMIT_BYTES, Block,
186    BlockApplicationState, BlockBody, Transaction, TransactionPayload,
187};
188#[cfg(feature = "filtered-transactions")]
189pub use block::{FilteredDeliveryPolicy, FilteredPayloadView, FilteredTransactionSlot};
190#[cfg(feature = "fair-block-ordering")]
191pub use block::{
192    fair_block_order_key, fair_block_order_seed, fair_order_transaction_count,
193    fair_ordered_block_commitments, fair_ordered_blocks,
194};
195pub use block_store::{BlockHandle, BlockIndex, BlockRecord, DurableBlockStore};
196pub use blossom::*;
197pub use crypto::{Keypair, PubKey, SecKey, SecretSigner, Signature, verify_batch};
198pub use encounter::{
199    ENCOUNTER_RECORD_DOMAIN, ENCOUNTER_RECORD_ENCODED_LEN, EncounterOutcome, EncounterPhase,
200    EncounterRecord, EncounterRecordBody,
201};
202pub use error::{BlossomError, Result};
203pub use group::ConsensusGroupId;
204pub use harness::{MockBlockService, SimulatedCluster, SimulatedNode, signed_block};
205pub use hash::{
206    DoHash, FAIR_BLOCK_ORDERING_PROTOCOL_FEATURE, FAIR_BLOCK_ORDERING_PROTOCOL_FEATURE_CODE,
207    HIGH_AVAILABILITY_PROTOCOL_FEATURE, HIGH_AVAILABILITY_PROTOCOL_FEATURE_CODE, HashType,
208    PROTOCOL_FEATURE_CODE_VERSION, PROTOCOL_FEATURE_CODES, PROTOCOL_FEATURE_REGISTRY,
209    ProtocolConsensusSurface, ProtocolFeatureCode, ProtocolFeatureRegistryEntry,
210    RESERVED_PROTOCOL_FEATURE_CODE, SHA256_PROTOCOL_HASH_ALGORITHM, XXH3_PROTOCOL_HASH_ALGORITHM,
211    protocol_feature_code_bytes, protocol_feature_registry_entry, protocol_hash_algorithm,
212    protocol_hash_algorithm_is_compatible, validate_protocol_feature_codes,
213    validate_protocol_feature_registry,
214};
215#[cfg(feature = "high-availability")]
216pub use high_availability::*;
217pub use indextreemap::{IndexTreeMap, SharedIndexTreeMap};
218pub use latency_topology::{
219    ClosestPeer, LatencyEstimate, LatencyEstimateMethod, LatencyRelationship, LatencyTopology,
220    LatencyTopologyConfig, LatencyTopologyMetadataV1, unix_time_millis,
221};
222pub use local_block::LocalBlock;
223pub use log_store::{
224    BLOSSOM_LOG_STORE_FORMAT_VERSION, BlossomLogCheckpointReceipt, BlossomLogCommitReceipt,
225    BlossomLogDurabilityMetrics, BlossomLogEntry, BlossomLogSnapshot, BlossomLogStore,
226    BlossomLogStoreConfig, BlossomLogStoreIdentity, BlossomLogTransaction,
227};
228pub use membership::{
229    CommittedMemberOperation, ConsensusNodeAdmissionPlan, ConsensusNodeRemovalDecision,
230    ConsensusNodeRemovalPlan, ConsensusNodeRemovalPolicy, MAX_MEMBERSHIP_LEASE_MILLIS,
231    MemberCapability, MemberOperation, MemberRecord, MemberSet, MemberStatus,
232    MembershipLeaseCertificate, MembershipLeaseChallenge, MembershipLeaseRequest,
233    MembershipLeaseStatement, MembershipLeaseVote, RelaySet, VerifiedMembershipView,
234    apply_committed_member_operations, apply_consensus_node_admission_plan,
235    apply_consensus_node_removal_plan, apply_epoch_member_registry_transition,
236    apply_epoch_membership_transition, derive_consensus_node_admission_plan,
237    derive_consensus_node_removal_plan,
238};
239pub use messages::{MSGKey, Msg};
240pub use node::{NodeIdentity, NodeType};
241pub use nonce::Nonce;
242pub use overlay::{BroadcastReceipt, BroadcastReport, FanOutStrategy, OverlayRuntime};
243#[cfg(feature = "parallel-networks")]
244pub use parallel_networks::{
245    HA_GROUP_STATE_REFERENCE_VERSION, HaGroupRegistration, HaGroupStateReference,
246    HaGroupStateReferenceBody, PARALLEL_NETWORK_SNAPSHOT_VERSION, ParallelNetworkCoordinator,
247    ParallelNetworkEvent, ParallelNetworkSnapshot, ParallelNetworkStatus,
248};
249pub use register::{MessageMatrix, QuorumQueue, Status};
250pub use round_skip::{
251    DataDisseminationManifest, DataDisseminationManifestValidation, FutureRoundAssistDecision,
252    FutureRoundAssistInput, FutureRoundAssistKind, RoundSkipCertificate,
253    RoundSkipCertificateValidation, RoundSkipVote, future_round_assist_decision,
254    skipped_round_assist_decision,
255};
256pub use runtime::{
257    AcceptedBlock, ConsensusRoundStatus, EpochDisseminationStatus, EpochTarget, MessageReceipt,
258    MultiGroupRuntime, NodeRuntime, NodeStatus, ObservedEncounterRecord, PeerApplicationState,
259    PrefillDispatchBroadcastReport, PrefillDispatchPlan, PrefillStageStatus,
260    ReconnectAdmissionDecision, ReconnectAdmissionEvidence, RuntimeConfig, RuntimeMode,
261    RuntimeSnapshotV1, TrustMode, TrustedOperationalStatus, TrustedServiceHealth, genesis_epoch,
262    genesis_epoch_for_group, genesis_epoch_for_group_with_parameters,
263};
264pub use safety::{
265    CommitteeLayout, CommitteeParticipant, SafetyManifest, SiteId, generate_safety_manifest,
266    select_site_balanced_committee,
267};
268pub use service_client::{TcpServiceClient, TimedNodePong};
269pub use state::{
270    CERTIFIED_EPOCH_SUFFIX_VERSION, CertifiedEpochSuffix, DEFAULT_MAX_PENDING_RAW_DISPATCH_BYTES,
271    DEFAULT_MAX_PENDING_RAW_DISPATCH_BYTES_PER_SENDER, Epoch, EpochBody, EpochChain, EpochNonce,
272    LocalState, MAX_CERTIFIED_EPOCH_SUFFIX, MAX_PENDING_RAW_DISPATCH_BYTES_ENV,
273    MAX_PENDING_RAW_DISPATCH_BYTES_PER_SENDER_ENV, PendingDispatch, PrefillDispatchRecord,
274    TempConsensus, TempQuorum, TrustedOrderedTransaction,
275    configured_max_pending_raw_dispatch_bytes,
276    configured_max_pending_raw_dispatch_bytes_per_sender,
277};
278#[cfg(feature = "availability-gossip")]
279pub use subset_gossip::{
280    SubsetGossipConfig, SubsetGossipEpochRow, SubsetGossipProtocolVersion, SubsetGossipReport,
281    SubsetLatencyDistribution, SubsetLatencyProfile, SubsetPrefillMode, run_subset_gossip,
282    run_subset_gossip_v1, run_subset_gossip_v2,
283};
284pub use tcp::{
285    ApplicationHandler, ApplicationHandlerFuture, ConsensusDriverConfig, ConsensusDriverTick,
286    TcpConnection, TcpMultiGroupNode, TcpNode, TcpNodeMetrics, TcpNodeMetricsSnapshot,
287    send_wire_frame, send_wire_request, send_wire_request_raw_response,
288};
289#[cfg(feature = "eden-logger")]
290pub use telemetry::EdenLoggerTelemetrySink;
291#[cfg(feature = "telemetry")]
292pub use telemetry::{
293    BlossomTelemetryMetrics, BlossomTelemetryMetricsSnapshot, FastTelemetryRegistration,
294    FastTelemetrySink,
295};
296pub use telemetry::{
297    FanoutTelemetrySink, InMemoryTelemetrySink, JsonlTcpTelemetrySink, JsonlTcpTelemetrySinkConfig,
298    NoopTelemetrySink, TELEMETRY_SCHEMA_VERSION, TelemetryEvent, TelemetryEventKind,
299    TelemetryHandle, TelemetrySeverity, TelemetrySink,
300};
301#[cfg(feature = "trusted-checkpoint-dag")]
302pub use trusted_dag::{
303    MIN_GLOBAL_BLOSSOM_PARTICIPANTS, SequentialQuorumDagReport, TrustedCheckpointDag,
304    TrustedDagCandidate, TrustedDagCandidateBody, TrustedDagCheckpoint, TrustedDagCheckpointBody,
305    TrustedDagFrontierEntry, TrustedDagIngestOutcome, TrustedDagRoundCompletion,
306    TrustedDagRoundLock, TrustedDagVertex, TrustedDagVertexBody,
307    run_sequential_quorum_dag_experiment,
308};
309pub use trusted_log::{
310    TrustedFailureAssessment, TrustedFailureClass, TrustedLogHead, TrustedRoundId,
311    TrustedServiceDirective, assess_trusted_durability_failure,
312};
313pub use wire::{
314    AddressBookUpdate, ApplicationRequest, ApplicationResponse, EncodedFrame, FRAME_PREFIX_BYTES,
315    FRAME_WRITE_CHUNK_BYTES_ENV, HOT_WIRE_CODEC_ENV, HotDispatch, NodeHealth, NodePing, NodePong,
316    ServiceRegistration, WireRequest, WireRequestFrame, WireResponse,
317    configured_frame_write_chunk_bytes, configured_max_frame_size, decode_wire_request_frame,
318    decode_wire_request_payload, decode_wire_response_payload, encoded_len, framed_len,
319    hot_dispatch_response_into_request_frame, hot_dispatch_response_to_request_frame,
320    hot_wire_codec_enabled, hot_wire_request_framed_len, hot_wire_response_framed_len,
321    read_encoded_frame, read_frame, read_wire_request, read_wire_request_frame,
322    read_wire_request_frame_optional, read_wire_response, wire_request_framed_len,
323    wire_response_framed_len, write_encoded_frame, write_frame, write_wire_request,
324    write_wire_response,
325};