calimero_node_primitives/
sync.rs

1//! Sync protocol types for state synchronization between nodes.
2//!
3//! This module provides types for the various sync protocols:
4//!
5//! - **Handshake**: Initial negotiation between peers ([`handshake`])
6//! - **Protocol Selection**: Choosing the optimal sync strategy ([`protocol`])
7//! - **Delta Sync**: DAG-based delta synchronization ([`delta`])
8//! - **HashComparison**: Merkle tree traversal sync ([`hash_comparison`])
9//! - **BloomFilter**: Bloom filter-based sync for large trees ([`bloom_filter`])
10//! - **Snapshot**: Full state transfer for fresh nodes ([`snapshot`])
11//! - **SubtreePrefetch**: Subtree prefetch for deep trees with clustered changes ([`subtree`])
12//! - **LevelWise**: Level-by-level sync for wide shallow trees ([`levelwise`])
13//!
14//! # Module Organization
15//!
16//! Each sync protocol has its own module with types and tests:
17//!
18//! ```text
19//! sync/
20//! ├── handshake.rs       # SyncHandshake, SyncCapabilities, etc.
21//! ├── protocol.rs        # SyncProtocol, SyncProtocolKind, select_protocol()
22//! ├── delta.rs           # DeltaSyncRequest, DeltaPayload, etc.
23//! ├── hash_comparison.rs # TreeNode, TreeNodeRequest, compare_tree_nodes()
24//! ├── bloom_filter.rs    # DeltaIdBloomFilter, BloomFilterRequest, etc.
25//! ├── snapshot.rs        # SnapshotPage, BroadcastMessage, StreamMessage, etc.
26//! ├── subtree.rs         # SubtreePrefetchRequest, SubtreeData, etc.
27//! └── levelwise.rs       # LevelWiseRequest, LevelWiseResponse, etc.
28//! ```
29
30#![expect(single_use_lifetimes, reason = "borsh shenanigans")]
31
32// =============================================================================
33// Submodules
34// =============================================================================
35
36pub mod bloom_filter;
37pub mod delta;
38pub mod handshake;
39pub mod hash_comparison;
40pub mod levelwise;
41pub mod protocol;
42pub mod protocol_trait;
43pub mod snapshot;
44pub mod state_machine;
45pub mod storage_bridge;
46pub mod subtree;
47pub mod transport;
48pub mod wire;
49
50// =============================================================================
51// Re-exports
52// =============================================================================
53
54// Handshake types
55pub use handshake::{
56    SyncCapabilities, SyncHandshake, SyncHandshakeResponse, SYNC_PROTOCOL_VERSION,
57};
58
59// Protocol types and selection
60pub use protocol::{
61    calculate_divergence, is_protocol_supported, select_protocol, select_protocol_with_fallback,
62    ProtocolSelection, SyncProtocol, SyncProtocolKind,
63};
64
65// Delta sync types
66pub use delta::{
67    DeltaApplyResult, DeltaPayload, DeltaSyncRequest, DeltaSyncResponse,
68    DEFAULT_DELTA_SYNC_THRESHOLD,
69};
70
71// Hash comparison types
72pub use hash_comparison::{
73    compare_tree_nodes, CrdtType, LeafMetadata, TreeCompareResult, TreeLeafData, TreeNode,
74    TreeNodeRequest, TreeNodeResponse, MAX_CHILDREN_PER_NODE, MAX_LEAF_VALUE_SIZE,
75    MAX_NODES_PER_RESPONSE, MAX_TREE_DEPTH,
76};
77
78// Bloom filter types
79pub use bloom_filter::{
80    BloomFilterRequest, BloomFilterResponse, DeltaIdBloomFilter, DEFAULT_BLOOM_FP_RATE,
81};
82
83// Wire protocol types (used by all sync protocols)
84pub use wire::{InitPayload, MessagePayload, StreamMessage, MAX_TREE_REQUEST_DEPTH};
85
86// Snapshot types
87pub use snapshot::{
88    check_snapshot_safety, BroadcastMessage, SnapshotBoundaryRequest, SnapshotBoundaryResponse,
89    SnapshotComplete, SnapshotCursor, SnapshotEntity, SnapshotEntityPage, SnapshotError,
90    SnapshotPage, SnapshotRequest, SnapshotStreamRequest, SnapshotVerifyResult,
91    DEFAULT_SNAPSHOT_PAGE_SIZE, MAX_COMPRESSED_PAYLOAD_SIZE, MAX_DAG_HEADS, MAX_ENTITIES_PER_PAGE,
92    MAX_ENTITY_DATA_SIZE, MAX_SNAPSHOT_PAGES, MAX_SNAPSHOT_PAGE_SIZE,
93};
94
95// Subtree prefetch types
96pub use subtree::{
97    should_use_subtree_prefetch, SubtreeData, SubtreePrefetchRequest, SubtreePrefetchResponse,
98    DEEP_TREE_THRESHOLD, DEFAULT_SUBTREE_MAX_DEPTH, MAX_CLUSTERED_SUBTREES, MAX_DIVERGENCE_RATIO,
99    MAX_ENTITIES_PER_SUBTREE, MAX_SUBTREES_PER_REQUEST, MAX_SUBTREE_DEPTH, MAX_TOTAL_ENTITIES,
100};
101
102// LevelWise sync types
103pub use levelwise::{
104    compare_level_nodes, should_use_levelwise, LevelCompareResult, LevelNode, LevelWiseRequest,
105    LevelWiseResponse, MAX_LEVELWISE_DEPTH, MAX_NODES_PER_LEVEL, MAX_PARENTS_PER_REQUEST,
106    MAX_REQUESTS_PER_SESSION,
107};
108
109// State machine types (shared between SyncManager and SimNode)
110pub use state_machine::{
111    build_handshake, build_handshake_from_raw, estimate_entity_count, estimate_max_depth,
112    LocalSyncState,
113};
114
115// Transport abstraction (for production streams and simulation)
116pub use transport::{EncryptionState, SyncTransport};
117
118// Protocol trait (common interface for all sync protocols)
119pub use protocol_trait::SyncProtocolExecutor;
120
121// Storage bridge (RuntimeEnv creation for sync protocols)
122pub use storage_bridge::create_runtime_env;
calimero_node_primitives/sync.rs

calimero_node_primitives/
sync.rs
