calimero-node-primitives 0.10.0

Core Calimero infrastructure and tools
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

//! Sync protocol types for state synchronization between nodes.
//!
//! This module provides types for the various sync protocols:
//!
//! - **Handshake**: Initial negotiation between peers ([`handshake`])
//! - **Protocol Selection**: Choosing the optimal sync strategy ([`protocol`])
//! - **Delta Sync**: DAG-based delta synchronization ([`delta`])
//! - **HashComparison**: Merkle tree traversal sync ([`hash_comparison`])
//! - **BloomFilter**: Bloom filter-based sync for large trees ([`bloom_filter`])
//! - **Snapshot**: Full state transfer for fresh nodes ([`snapshot`])
//! - **SubtreePrefetch**: Subtree prefetch for deep trees with clustered changes ([`subtree`])
//! - **LevelWise**: Level-by-level sync for wide shallow trees ([`levelwise`])
//!
//! # Module Organization
//!
//! Each sync protocol has its own module with types and tests:
//!
//! ```text
//! sync/
//! ├── handshake.rs       # SyncHandshake, SyncCapabilities, etc.
//! ├── protocol.rs        # SyncProtocol, SyncProtocolKind, select_protocol()
//! ├── delta.rs           # DeltaSyncRequest, DeltaPayload, etc.
//! ├── hash_comparison.rs # TreeNode, TreeNodeRequest, compare_tree_nodes()
//! ├── bloom_filter.rs    # DeltaIdBloomFilter, BloomFilterRequest, etc.
//! ├── snapshot.rs        # SnapshotPage, BroadcastMessage, StreamMessage, etc.
//! ├── subtree.rs         # SubtreePrefetchRequest, SubtreeData, etc.
//! └── levelwise.rs       # LevelWiseRequest, LevelWiseResponse, etc.
//! ```

#![expect(single_use_lifetimes, reason = "borsh shenanigans")]

// =============================================================================
// Submodules
// =============================================================================

pub mod bloom_filter;
pub mod delta;
pub mod handshake;
pub mod hash_comparison;
pub mod levelwise;
pub mod protocol;
pub mod protocol_trait;
pub mod snapshot;
pub mod state_machine;
pub mod storage_bridge;
pub mod subtree;
pub mod transport;
pub mod wire;

// =============================================================================
// Re-exports
// =============================================================================

// Handshake types
pub use handshake::{
    SyncCapabilities, SyncHandshake, SyncHandshakeResponse, SYNC_PROTOCOL_VERSION,
};

// Protocol types and selection
pub use protocol::{
    calculate_divergence, is_protocol_supported, select_protocol, select_protocol_with_fallback,
    ProtocolSelection, SyncProtocol, SyncProtocolKind,
};

// Delta sync types
pub use delta::{
    DeltaApplyResult, DeltaPayload, DeltaSyncRequest, DeltaSyncResponse,
    DEFAULT_DELTA_SYNC_THRESHOLD,
};

// Hash comparison types
pub use hash_comparison::{
    compare_tree_nodes, CrdtType, LeafMetadata, TreeCompareResult, TreeLeafData, TreeNode,
    TreeNodeRequest, TreeNodeResponse, MAX_CHILDREN_PER_NODE, MAX_LEAF_VALUE_SIZE,
    MAX_NODES_PER_RESPONSE, MAX_TREE_DEPTH,
};

// Bloom filter types
pub use bloom_filter::{
    BloomFilterRequest, BloomFilterResponse, DeltaIdBloomFilter, DEFAULT_BLOOM_FP_RATE,
};

// Wire protocol types (used by all sync protocols)
pub use wire::{InitPayload, MessagePayload, StreamMessage, MAX_TREE_REQUEST_DEPTH};

// Snapshot types
pub use snapshot::{
    check_snapshot_safety, BroadcastMessage, SnapshotBoundaryRequest, SnapshotBoundaryResponse,
    SnapshotComplete, SnapshotCursor, SnapshotEntity, SnapshotEntityPage, SnapshotError,
    SnapshotPage, SnapshotRequest, SnapshotStreamRequest, SnapshotVerifyResult,
    DEFAULT_SNAPSHOT_PAGE_SIZE, MAX_COMPRESSED_PAYLOAD_SIZE, MAX_DAG_HEADS, MAX_ENTITIES_PER_PAGE,
    MAX_ENTITY_DATA_SIZE, MAX_SNAPSHOT_PAGES, MAX_SNAPSHOT_PAGE_SIZE,
};

// Subtree prefetch types
pub use subtree::{
    should_use_subtree_prefetch, SubtreeData, SubtreePrefetchRequest, SubtreePrefetchResponse,
    DEEP_TREE_THRESHOLD, DEFAULT_SUBTREE_MAX_DEPTH, MAX_CLUSTERED_SUBTREES, MAX_DIVERGENCE_RATIO,
    MAX_ENTITIES_PER_SUBTREE, MAX_SUBTREES_PER_REQUEST, MAX_SUBTREE_DEPTH, MAX_TOTAL_ENTITIES,
};

// LevelWise sync types
pub use levelwise::{
    compare_level_nodes, should_use_levelwise, LevelCompareResult, LevelNode, LevelWiseRequest,
    LevelWiseResponse, MAX_LEVELWISE_DEPTH, MAX_NODES_PER_LEVEL, MAX_PARENTS_PER_REQUEST,
    MAX_REQUESTS_PER_SESSION,
};

// State machine types (shared between SyncManager and SimNode)
pub use state_machine::{
    build_handshake, build_handshake_from_raw, estimate_entity_count, estimate_max_depth,
    LocalSyncState,
};

// Transport abstraction (for production streams and simulation)
pub use transport::{EncryptionState, SyncTransport};

// Protocol trait (common interface for all sync protocols)
pub use protocol_trait::SyncProtocolExecutor;

// Storage bridge (RuntimeEnv creation for sync protocols)
pub use storage_bridge::create_runtime_env;