nectar-primitives 0.1.1

Core primitives for Ethereum Swarm: chunks, addresses, and binary merkle trees
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

//! Traits for chunk types and operations
//!
//! This module defines the core traits that all chunk types must implement,
//! along with serialization and deserialization functionality.

use crate::SwarmAddress;
use crate::chunk::error;
use crate::error::Result;
use bytes::{BufMut, Bytes, BytesMut};

/// Type alias for chunk addresses
pub type ChunkAddress = SwarmAddress;

/// Core trait for chunk metadata
pub trait ChunkMetadata {
    /// Get the metadata bytes for this chunk
    fn bytes(&self) -> Bytes;
}

/// Core trait for chunk header
pub trait ChunkHeader {
    /// The metadata type for this chunk
    type Metadata: ChunkMetadata;

    /// Get the identifier byte for this chunk type
    fn id(&self) -> u8;

    /// Get the version byte for this chunk type
    fn version(&self) -> u8;

    /// Get the metadata bytes for this chunk
    fn metadata(&self) -> &Self::Metadata;

    /// Get the header bytes for this chunk
    fn bytes(&self) -> Bytes {
        let mut buf = BytesMut::with_capacity(2);
        buf.put_u8(self.id());
        buf.put_u8(self.version());
        buf.put_slice(self.metadata().bytes().as_ref());
        buf.freeze()
    }
}

/// Core trait for all chunk types in the system.
///
/// This trait defines the common interface that all chunk implementations must provide.
/// Each implementation must specify its type ID and version as associated constants.
pub trait Chunk: Send + Sync + 'static {
    /// The header type for this chunk
    type Header: ChunkHeader;

    /// Get the address of this chunk
    fn address(&self) -> &ChunkAddress;

    /// Get the header for this chunk
    fn header(&self) -> &Self::Header;

    /// Get the raw data contained in this chunk
    fn data(&self) -> &Bytes;

    /// Get the total size of this chunk in bytes
    fn size(&self) -> usize {
        self.header().bytes().len() + self.data().len()
    }

    /// Verify that this chunk matches an expected address
    fn verify(&self, expected: &ChunkAddress) -> Result<()> {
        let actual = self.address();
        if actual != expected {
            return Err(error::ChunkError::verification_failed(*expected, *actual).into());
        }
        Ok(())
    }
}

/// Trait for serializing chunks with type prefix.
///
/// This trait provides methods for serializing a chunk with its type
/// ID and version prefix.
pub trait ChunkSerialization {
    /// Serialize this chunk with its type ID and version prefix
    fn serialize_with_prefix(&self) -> Bytes;
}

impl<T: Chunk> ChunkSerialization for T {
    fn serialize_with_prefix(&self) -> Bytes {
        let mut bytes = BytesMut::with_capacity(2 + self.size());
        bytes.extend(self.header().bytes());
        bytes.extend(self.data());
        bytes.freeze()
    }
}

/// Trait for chunks that contain a BMT body
pub trait BmtChunk: Chunk {
    /// Get the span of the chunk data
    fn span(&self) -> u64;
}