nectar_primitives/
lib.rs

1//! Core primitives for a decentralized storage system
2//!
3//! This crate provides the fundamental types and operations used in a decentralized
4//! storage system, including chunk types, address calculations, and binary merkle trees.
5//!
6//! ## Key Components
7//!
8//! - **Chunks**: Content-addressed and signed data chunks ([`ContentChunk`], [`SingleOwnerChunk`])
9//! - **Binary Merkle Tree**: Efficient content addressing and proof generation ([`bmt::Hasher`])
10//! - **SwarmAddress**: 256-bit identifiers for network addressing
11//!
12//! ## Usage Examples
13//!
14//! ```
15//! use nectar_primitives::{Chunk, DefaultContentChunk, DefaultSingleOwnerChunk};
16//! use alloy_signer_local::LocalSigner;
17//! use alloy_primitives::FixedBytes;
18//!
19//! // Creating content chunks
20//! let chunk = DefaultContentChunk::new(b"Hello, world!".as_slice()).unwrap();
21//! let address = chunk.address();
22//!
23//! // Creating content chunks with pre-computed address (e.g., from storage)
24//! let address_copy = *address;
25//! let chunk2 = DefaultContentChunk::with_address(b"Hello, world!".as_slice(), address_copy).unwrap();
26//!
27//! // Creating signed chunks
28//! let wallet = LocalSigner::random();
29//! let id = FixedBytes::random();
30//! let owner_chunk = DefaultSingleOwnerChunk::new(id, b"Signed data".as_slice(), &wallet).unwrap();
31//! ```
32
33// Re-export dependencies that are part of our public API
34pub use bytes;
35
36pub mod address;
37pub mod bin;
38pub mod bmt;
39mod cache;
40pub mod chunk;
41pub mod error;
42pub mod file;
43pub mod neighborhood_depth;
44pub mod network_id;
45pub mod nonce;
46pub mod overlay;
47pub mod proximity_order;
48pub mod signing;
49pub mod spec;
50pub mod store;
51pub mod timestamp;
52
53#[cfg(target_arch = "wasm32")]
54pub mod wasm;
55
56// Re-export core constants
57pub use bmt::DEFAULT_BODY_SIZE;
58
59// Re-export core encryption types
60pub use chunk::encryption::{EncryptedChunkRef, EncryptionKey};
61#[cfg(feature = "encryption")]
62pub use chunk::{ChunkEncrypt, EncryptedContentChunk};
63
64// Re-export core types
65pub use address::{EXTENDED_PO, MAX_PO, SwarmAddress};
66pub use bin::{Bin, BinError};
67pub use error::{PrimitivesError, Result};
68pub use neighborhood_depth::recompute_neighborhood_depth;
69pub use network_id::NetworkId;
70pub use nonce::Nonce;
71pub use overlay::compute_overlay;
72pub use proximity_order::{ProximityOrder, ProximityOrderError};
73pub use spec::{MAINNET, StaticSpec, SwarmSpec, TESTNET};
74pub use timestamp::{Timestamp, TimestampError};
75
76// Core BMT functionality
77pub use bmt::{Hasher, HasherFactory, Proof, Prover};
78
79// Core chunk functionality
80pub use chunk::{
81    // Type system
82    AnyChunk,
83    // Core traits
84    BmtChunk,
85    Chunk,
86    ChunkAddress,
87    ChunkSerialization,
88    ChunkType,
89    ChunkTypeId,
90    ChunkTypeSet,
91    // Concrete chunk types
92    ContentChunk,
93    ContentOnlyChunkSet,
94    SingleOwnerChunk,
95    StandardChunkSet,
96};
97
98/// Default BMT hasher.
99pub type DefaultHasher = Hasher<DEFAULT_BODY_SIZE>;
100/// Default content-addressed chunk.
101pub type DefaultContentChunk = ContentChunk<DEFAULT_BODY_SIZE>;
102/// Default single-owner chunk.
103pub type DefaultSingleOwnerChunk = SingleOwnerChunk<DEFAULT_BODY_SIZE>;
104/// Default polymorphic chunk.
105pub type DefaultAnyChunk = AnyChunk<DEFAULT_BODY_SIZE>;
106/// Default in-memory chunk store.
107pub type DefaultMemoryStore = MemoryStore<DEFAULT_BODY_SIZE>;
108
109// Chunk storage traits
110pub use store::{
111    ChunkGet, ChunkHas, ChunkPut, ChunkStoreError, MemoryStore, SyncChunkGet, SyncChunkHas,
112    SyncChunkPut,
113};
114
115// File operations — async (primary)
116#[cfg(feature = "encryption")]
117pub use file::EncryptedJoiner;
118#[cfg(feature = "tokio")]
119pub use file::JoinerReader;
120pub use file::{
121    ChunkGetExt, ChunkRange, EntryRef, FileError, GenericJoiner, JoinRef, Joiner, TreeParams, join,
122};
123
124// File operations — sync (secondary)
125#[cfg(feature = "encryption")]
126pub use file::{
127    EncryptedSyncJoiner, EncryptedSyncParallelSplitter, EncryptedSyncSplitter, sync_split_encrypted,
128};
129pub use file::{
130    GenericSyncJoiner, SyncChunkGetExt, SyncChunkPutExt, SyncJoiner, SyncParallelSplitter,
131    SyncReadAt, SyncSplitter, sync_join, sync_split,
132};
133
134/// Default sync file splitter.
135pub type DefaultSyncSplitter<S> = file::SyncSplitter<S, DEFAULT_BODY_SIZE>;
136/// Default async file joiner.
137pub type DefaultJoiner<G> = file::Joiner<G, DEFAULT_BODY_SIZE>;
138/// Default sync file joiner.
139pub type DefaultSyncJoiner<G> = file::SyncJoiner<G, DEFAULT_BODY_SIZE>;
140/// Default encrypted sync file joiner.
141#[cfg(feature = "encryption")]
142pub type DefaultEncryptedSyncJoiner<G> = file::EncryptedSyncJoiner<G, DEFAULT_BODY_SIZE>;
nectar_primitives/lib.rs

nectar_primitives/
lib.rs
