Skip to main content

ab_core_primitives/
segments.rs

1//! Segments-related data structures
2
3#[cfg(feature = "alloc")]
4mod archival_history_segment;
5#[cfg(all(test, feature = "alloc"))]
6mod tests;
7
8use crate::block::BlockNumber;
9use crate::hashes::Blake3Hash;
10use crate::pieces::{PieceIndex, Record, SegmentProof};
11#[cfg(feature = "alloc")]
12pub use crate::segments::archival_history_segment::ArchivedHistorySegment;
13use crate::shard::ShardIndex;
14use crate::trees::SuperSegmentMerkleTree;
15use ab_blake3::{single_block_hash, single_chunk_hash};
16use ab_io_type::trivial_type::TrivialType;
17use ab_io_type::unaligned::Unaligned;
18#[cfg(feature = "alloc")]
19use alloc::boxed::Box;
20#[cfg(feature = "alloc")]
21use alloc::sync::Arc as StdArc;
22use blake3::{CHUNK_LEN, OUT_LEN};
23use core::fmt;
24use core::iter::Step;
25#[cfg(feature = "alloc")]
26use core::mem::MaybeUninit;
27use core::num::{NonZeroU32, NonZeroU64};
28use derive_more::{
29    Add, AddAssign, Deref, DerefMut, Display, Div, DivAssign, From, Into, Mul, MulAssign, Sub,
30    SubAssign,
31};
32#[cfg(feature = "scale-codec")]
33use parity_scale_codec::{Decode, Encode, MaxEncodedLen};
34#[cfg(feature = "serde")]
35use serde::{Deserialize, Deserializer, Serialize, Serializer};
36#[cfg(feature = "serde")]
37use serde_big_array::BigArray;
38use transparent_wrapper::TransparentWrapper;
39
40/// Super segment index
41#[derive(
42    Debug,
43    Display,
44    Default,
45    Copy,
46    Clone,
47    Ord,
48    PartialOrd,
49    Eq,
50    PartialEq,
51    Hash,
52    Add,
53    AddAssign,
54    Sub,
55    SubAssign,
56    Mul,
57    MulAssign,
58    Div,
59    DivAssign,
60    TrivialType,
61)]
62#[cfg_attr(feature = "scale-codec", derive(Encode, Decode, MaxEncodedLen))]
63#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
64#[repr(C)]
65pub struct SuperSegmentIndex(u64);
66
67impl Step for SuperSegmentIndex {
68    #[inline]
69    fn steps_between(start: &Self, end: &Self) -> (usize, Option<usize>) {
70        u64::steps_between(&start.0, &end.0)
71    }
72
73    #[inline]
74    fn forward_checked(start: Self, count: usize) -> Option<Self> {
75        u64::forward_checked(start.0, count).map(Self)
76    }
77
78    #[inline(always)]
79    fn forward_overflowing(start: Self, count: usize) -> (Self, bool) {
80        let (n, overflowing) = u64::forward_overflowing(start.0, count);
81        (Self(n), overflowing)
82    }
83
84    #[inline]
85    fn backward_checked(start: Self, count: usize) -> Option<Self> {
86        u64::backward_checked(start.0, count).map(Self)
87    }
88
89    #[inline(always)]
90    fn backward_overflowing(start: Self, count: usize) -> (Self, bool) {
91        let (n, overflowing) = u64::backward_overflowing(start.0, count);
92        (Self(n), overflowing)
93    }
94}
95
96const impl From<u64> for SuperSegmentIndex {
97    #[inline(always)]
98    fn from(value: u64) -> Self {
99        Self(value)
100    }
101}
102
103const impl From<SuperSegmentIndex> for u64 {
104    #[inline(always)]
105    fn from(value: SuperSegmentIndex) -> Self {
106        value.0
107    }
108}
109
110impl SuperSegmentIndex {
111    /// Super segment index 0
112    pub const ZERO: Self = Self(0);
113    /// Super segment index 1
114    pub const ONE: Self = Self(1);
115
116    /// Checked integer subtraction. Computes `self - rhs`, returning `None` if underflow occurred
117    #[inline]
118    pub fn checked_sub(self, rhs: Self) -> Option<Self> {
119        self.0.checked_sub(rhs.0).map(Self)
120    }
121
122    /// Saturating integer subtraction. Computes `self - rhs`, returning zero if underflow
123    /// occurred
124    #[inline]
125    pub const fn saturating_sub(self, rhs: Self) -> Self {
126        Self(self.0.saturating_sub(rhs.0))
127    }
128}
129
130/// Super segment root contained within a beacon chain block
131#[derive(Copy, Clone, Eq, PartialEq, Hash, Deref, DerefMut, From, Into, TrivialType)]
132#[cfg_attr(feature = "scale-codec", derive(Encode, Decode, MaxEncodedLen))]
133#[repr(C)]
134pub struct SuperSegmentRoot([u8; SuperSegmentRoot::SIZE]);
135
136impl fmt::Debug for SuperSegmentRoot {
137    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
138        for byte in self.0 {
139            write!(f, "{byte:02x}")?;
140        }
141        Ok(())
142    }
143}
144
145const impl Default for SuperSegmentRoot {
146    #[inline]
147    fn default() -> Self {
148        Self([0; _])
149    }
150}
151
152#[cfg(feature = "serde")]
153#[derive(Serialize, Deserialize)]
154#[serde(transparent)]
155struct SuperSegmentRootBinary(#[serde(with = "BigArray")] [u8; SuperSegmentRoot::SIZE]);
156
157#[cfg(feature = "serde")]
158#[derive(Serialize, Deserialize)]
159#[serde(transparent)]
160struct SuperSegmentRootHex(#[serde(with = "hex")] [u8; SuperSegmentRoot::SIZE]);
161
162#[cfg(feature = "serde")]
163impl Serialize for SuperSegmentRoot {
164    #[inline]
165    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
166    where
167        S: Serializer,
168    {
169        if serializer.is_human_readable() {
170            SuperSegmentRootHex(self.0).serialize(serializer)
171        } else {
172            SuperSegmentRootBinary(self.0).serialize(serializer)
173        }
174    }
175}
176
177#[cfg(feature = "serde")]
178impl<'de> Deserialize<'de> for SuperSegmentRoot {
179    #[inline]
180    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
181    where
182        D: Deserializer<'de>,
183    {
184        Ok(Self(if deserializer.is_human_readable() {
185            SuperSegmentRootHex::deserialize(deserializer)?.0
186        } else {
187            SuperSegmentRootBinary::deserialize(deserializer)?.0
188        }))
189    }
190}
191
192impl AsRef<[u8]> for SuperSegmentRoot {
193    #[inline]
194    fn as_ref(&self) -> &[u8] {
195        &self.0
196    }
197}
198
199impl AsMut<[u8]> for SuperSegmentRoot {
200    #[inline]
201    fn as_mut(&mut self) -> &mut [u8] {
202        &mut self.0
203    }
204}
205
206impl SuperSegmentRoot {
207    /// Size in bytes
208    pub const SIZE: usize = 32;
209    /// The maximum number of segments in a super segment's Merkle Tree.
210    ///
211    /// `-1` to minimize the number of bits needed to represent it (exactly 20).
212    pub const MAX_SEGMENTS: u32 = 2u32.pow(20) - 1;
213}
214
215/// Segment position in a super segment
216#[derive(
217    Debug,
218    Display,
219    Default,
220    Copy,
221    Clone,
222    Ord,
223    PartialOrd,
224    Eq,
225    PartialEq,
226    Hash,
227    From,
228    Into,
229    TrivialType,
230)]
231#[cfg_attr(feature = "scale-codec", derive(Encode, Decode, MaxEncodedLen))]
232#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
233#[repr(C)]
234pub struct SegmentPosition(u32);
235
236impl From<SegmentPosition> for u64 {
237    #[inline]
238    fn from(original: SegmentPosition) -> Self {
239        Self::from(original.0)
240    }
241}
242
243impl SegmentPosition {
244    /// Zero position
245    pub const ZERO: Self = Self(0);
246}
247
248/// Shard segment root with position
249#[derive(Debug, Clone, Copy, TrivialType)]
250#[cfg_attr(feature = "scale-codec", derive(Encode, Decode, MaxEncodedLen))]
251#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
252#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
253#[repr(C)]
254pub struct ShardSegmentRootWithPosition {
255    /// Shard index
256    pub shard_index: ShardIndex,
257    /// Position of the segment in the super segment
258    pub segment_position: SegmentPosition,
259    /// Local segment index
260    pub local_segment_index: LocalSegmentIndex,
261    /// Segment root
262    pub segment_root: SegmentRoot,
263}
264
265impl ShardSegmentRootWithPosition {
266    /// Hash for super segment creation
267    #[inline(always)]
268    pub fn hash(&self) -> [u8; OUT_LEN] {
269        single_block_hash(self.as_bytes()).expect("Less than a single block worth of bytes; qed")
270    }
271}
272
273/// Super segment header
274#[derive(Debug, Clone, Copy, Eq, PartialEq, TrivialType)]
275#[cfg_attr(feature = "scale-codec", derive(Encode, Decode, MaxEncodedLen))]
276#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
277#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
278#[repr(C)]
279pub struct SuperSegmentHeader {
280    /// Super segment index
281    pub index: Unaligned<SuperSegmentIndex>,
282    /// Super segment root
283    pub root: SuperSegmentRoot,
284    /// Hash of the previous super segment header
285    pub prev_super_segment_header_hash: Blake3Hash,
286    /// Max index of the segment in the super segment
287    pub max_segment_index: Unaligned<SegmentIndex>,
288    /// Target beacon chain block number for the super segment
289    pub target_beacon_chain_block_number: Unaligned<BlockNumber>,
290    // TODO: New type?
291    /// Number of segments in the super segment
292    pub num_segments: u32,
293}
294
295/// Super segment
296#[cfg(feature = "alloc")]
297#[derive(Debug, Clone)]
298// TODO: Implement SCALE serialization/deserialization manually (if necessary at all)
299// #[cfg_attr(feature = "scale-codec", derive(Encode, Decode, MaxEncodedLen))]
300#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
301#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
302pub struct SuperSegment {
303    /// Super segment root
304    pub header: SuperSegmentHeader,
305    /// Segment roots that are included in the super segment
306    pub segment_roots: StdArc<[ShardSegmentRootWithPosition]>,
307}
308
309#[cfg(feature = "alloc")]
310impl SuperSegment {
311    /// Create a new instance and derive super segment root.
312    ///
313    /// Returns `None` if the list of segment roots is empty or there are too many of them.
314    pub fn new(
315        previous_header: &SuperSegmentHeader,
316        target_beacon_chain_block_number: BlockNumber,
317        segment_roots: StdArc<[ShardSegmentRootWithPosition]>,
318    ) -> Option<Self> {
319        let num_segments = u32::try_from(segment_roots.len()).ok()?;
320        let max_segment_index = SegmentIndex::from(
321            u64::from(previous_header.max_segment_index.as_inner()) + u64::from(num_segments),
322        );
323
324        let maybe_super_segment_root =
325            SuperSegmentMerkleTree::compute_root_only::<
326                { u64::from(SuperSegmentRoot::MAX_SEGMENTS) },
327                _,
328                _,
329            >(segment_roots.iter().map(ShardSegmentRootWithPosition::hash))?;
330
331        Some(Self {
332            header: SuperSegmentHeader {
333                index: (previous_header.index.as_inner() + SuperSegmentIndex::ONE).into(),
334                root: SuperSegmentRoot::from(maybe_super_segment_root),
335                prev_super_segment_header_hash: Blake3Hash::from(
336                    single_chunk_hash(previous_header.as_bytes())
337                        .expect("Less than a single chunk worth of bytes; qed"),
338                ),
339                max_segment_index: max_segment_index.into(),
340                target_beacon_chain_block_number: target_beacon_chain_block_number.into(),
341                num_segments,
342            },
343            segment_roots,
344        })
345    }
346
347    /// Produce a proof for a segment in the super segment at a given position
348    pub fn proof_for_segment(&self, segment_position: SegmentPosition) -> Option<SegmentProof> {
349        let mut segment_proof = [MaybeUninit::uninit(); _];
350        let (_root, proof_hashes) = SuperSegmentMerkleTree::compute_root_and_proof_in::<
351            { u64::from(SuperSegmentRoot::MAX_SEGMENTS) },
352            _,
353            _,
354        >(
355            self.segment_roots.iter().map(|shard_segment_root| {
356                single_block_hash(shard_segment_root.as_bytes())
357                    .expect("Less than a single block worth of bytes; qed")
358            }),
359            u32::from(segment_position) as usize,
360            &mut segment_proof,
361        )?;
362        let proof_length = proof_hashes.len();
363
364        // Unused hashes must be zeroed
365        segment_proof
366            .get_mut(proof_length..)
367            .expect("Proof is a prefix of the provided memory; qed")
368            .write_filled([0; OUT_LEN]);
369        // SAFETY: The first `proof_length` hashes were initialized by proof generation above, the
370        // rest were just zeroed
371        let segment_proof = unsafe { MaybeUninit::from(segment_proof).assume_init() };
372
373        Some(SegmentProof::from(segment_proof))
374    }
375}
376
377/// Local segment index of a shard
378#[derive(
379    Debug,
380    Display,
381    Default,
382    Copy,
383    Clone,
384    Ord,
385    PartialOrd,
386    Eq,
387    PartialEq,
388    Hash,
389    Add,
390    AddAssign,
391    Sub,
392    SubAssign,
393    Mul,
394    MulAssign,
395    Div,
396    DivAssign,
397    TrivialType,
398)]
399#[cfg_attr(feature = "scale-codec", derive(Encode, Decode, MaxEncodedLen))]
400#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
401#[repr(C)]
402pub struct LocalSegmentIndex(u64);
403
404impl Step for LocalSegmentIndex {
405    #[inline]
406    fn steps_between(start: &Self, end: &Self) -> (usize, Option<usize>) {
407        u64::steps_between(&start.0, &end.0)
408    }
409
410    #[inline]
411    fn forward_checked(start: Self, count: usize) -> Option<Self> {
412        u64::forward_checked(start.0, count).map(Self)
413    }
414
415    #[inline(always)]
416    fn forward_overflowing(start: Self, count: usize) -> (Self, bool) {
417        let (n, overflowing) = u64::forward_overflowing(start.0, count);
418        (Self(n), overflowing)
419    }
420
421    #[inline]
422    fn backward_checked(start: Self, count: usize) -> Option<Self> {
423        u64::backward_checked(start.0, count).map(Self)
424    }
425
426    #[inline(always)]
427    fn backward_overflowing(start: Self, count: usize) -> (Self, bool) {
428        let (n, overflowing) = u64::backward_overflowing(start.0, count);
429        (Self(n), overflowing)
430    }
431}
432
433const impl From<u64> for LocalSegmentIndex {
434    #[inline(always)]
435    fn from(value: u64) -> Self {
436        Self(value)
437    }
438}
439
440const impl From<LocalSegmentIndex> for u64 {
441    #[inline(always)]
442    fn from(value: LocalSegmentIndex) -> Self {
443        value.0
444    }
445}
446
447impl LocalSegmentIndex {
448    /// Local segment index 0
449    pub const ZERO: Self = Self(0);
450    /// Local segment index 1
451    pub const ONE: Self = Self(1);
452
453    /// Checked addition, returns `None` on overflow
454    #[inline(always)]
455    pub const fn checked_add(self, rhs: Self) -> Option<Self> {
456        if let Some(n) = self.0.checked_add(rhs.0) {
457            Some(Self(n))
458        } else {
459            None
460        }
461    }
462
463    /// Checked integer subtraction. Computes `self - rhs`, returning `None` if underflow occurred
464    #[inline]
465    pub fn checked_sub(self, rhs: Self) -> Option<Self> {
466        self.0.checked_sub(rhs.0).map(Self)
467    }
468
469    /// Saturating integer subtraction. Computes `self - rhs`, returning zero if underflow
470    /// occurred
471    #[inline]
472    pub const fn saturating_sub(self, rhs: Self) -> Self {
473        Self(self.0.saturating_sub(rhs.0))
474    }
475}
476
477/// Segment index
478#[derive(
479    Debug,
480    Display,
481    Default,
482    Copy,
483    Clone,
484    Ord,
485    PartialOrd,
486    Eq,
487    PartialEq,
488    Hash,
489    Add,
490    AddAssign,
491    Sub,
492    SubAssign,
493    Mul,
494    MulAssign,
495    Div,
496    DivAssign,
497    TrivialType,
498)]
499#[cfg_attr(feature = "scale-codec", derive(Encode, Decode, MaxEncodedLen))]
500#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
501#[repr(C)]
502pub struct SegmentIndex(u64);
503
504impl Step for SegmentIndex {
505    #[inline]
506    fn steps_between(start: &Self, end: &Self) -> (usize, Option<usize>) {
507        u64::steps_between(&start.0, &end.0)
508    }
509
510    #[inline]
511    fn forward_checked(start: Self, count: usize) -> Option<Self> {
512        u64::forward_checked(start.0, count).map(Self)
513    }
514
515    #[inline(always)]
516    fn forward_overflowing(start: Self, count: usize) -> (Self, bool) {
517        let (n, overflowing) = u64::forward_overflowing(start.0, count);
518        (Self(n), overflowing)
519    }
520
521    #[inline]
522    fn backward_checked(start: Self, count: usize) -> Option<Self> {
523        u64::backward_checked(start.0, count).map(Self)
524    }
525
526    #[inline(always)]
527    fn backward_overflowing(start: Self, count: usize) -> (Self, bool) {
528        let (n, overflowing) = u64::backward_overflowing(start.0, count);
529        (Self(n), overflowing)
530    }
531}
532
533const impl From<u64> for SegmentIndex {
534    #[inline(always)]
535    fn from(value: u64) -> Self {
536        Self(value)
537    }
538}
539
540const impl From<SegmentIndex> for u64 {
541    #[inline(always)]
542    fn from(value: SegmentIndex) -> Self {
543        value.0
544    }
545}
546
547impl SegmentIndex {
548    /// Segment index 0
549    pub const ZERO: Self = Self(0);
550    /// Segment index 1
551    pub const ONE: Self = Self(1);
552
553    /// Get the first piece index in this segment
554    #[inline]
555    pub const fn first_piece_index(&self) -> PieceIndex {
556        PieceIndex::from(self.0 * RecordedHistorySegment::NUM_PIECES as u64)
557    }
558
559    /// Get the last piece index in this segment
560    #[inline]
561    pub const fn last_piece_index(&self) -> PieceIndex {
562        PieceIndex::from((self.0 + 1) * RecordedHistorySegment::NUM_PIECES as u64 - 1)
563    }
564
565    /// List of piece indexes that belong to this segment
566    #[inline]
567    pub fn segment_piece_indexes(&self) -> [PieceIndex; RecordedHistorySegment::NUM_PIECES] {
568        let mut piece_indices = [PieceIndex::ZERO; RecordedHistorySegment::NUM_PIECES];
569        (self.first_piece_index()..=self.last_piece_index())
570            .zip(&mut piece_indices)
571            .for_each(|(input, output)| {
572                *output = input;
573            });
574
575        piece_indices
576    }
577
578    /// Checked integer subtraction. Computes `self - rhs`, returning `None` if underflow occurred
579    #[inline]
580    pub fn checked_sub(self, rhs: Self) -> Option<Self> {
581        self.0.checked_sub(rhs.0).map(Self)
582    }
583
584    /// Saturating integer subtraction. Computes `self - rhs`, returning zero if underflow
585    /// occurred
586    #[inline]
587    pub const fn saturating_sub(self, rhs: Self) -> Self {
588        Self(self.0.saturating_sub(rhs.0))
589    }
590}
591
592/// Segment root contained within a segment
593#[derive(
594    Copy, Clone, Eq, PartialEq, Hash, Deref, DerefMut, From, Into, TrivialType, TransparentWrapper,
595)]
596#[cfg_attr(feature = "scale-codec", derive(Encode, Decode, MaxEncodedLen))]
597#[repr(C)]
598pub struct SegmentRoot([u8; SegmentRoot::SIZE]);
599
600impl fmt::Debug for SegmentRoot {
601    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
602        for byte in self.0 {
603            write!(f, "{byte:02x}")?;
604        }
605        Ok(())
606    }
607}
608
609#[cfg(feature = "serde")]
610#[derive(Serialize, Deserialize)]
611#[serde(transparent)]
612struct SegmentRootBinary(#[serde(with = "BigArray")] [u8; SegmentRoot::SIZE]);
613
614#[cfg(feature = "serde")]
615#[derive(Serialize, Deserialize)]
616#[serde(transparent)]
617struct SegmentRootHex(#[serde(with = "hex")] [u8; SegmentRoot::SIZE]);
618
619#[cfg(feature = "serde")]
620impl Serialize for SegmentRoot {
621    #[inline]
622    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
623    where
624        S: Serializer,
625    {
626        if serializer.is_human_readable() {
627            SegmentRootHex(self.0).serialize(serializer)
628        } else {
629            SegmentRootBinary(self.0).serialize(serializer)
630        }
631    }
632}
633
634#[cfg(feature = "serde")]
635impl<'de> Deserialize<'de> for SegmentRoot {
636    #[inline]
637    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
638    where
639        D: Deserializer<'de>,
640    {
641        Ok(Self(if deserializer.is_human_readable() {
642            SegmentRootHex::deserialize(deserializer)?.0
643        } else {
644            SegmentRootBinary::deserialize(deserializer)?.0
645        }))
646    }
647}
648
649impl Default for SegmentRoot {
650    #[inline(always)]
651    fn default() -> Self {
652        Self([0; _])
653    }
654}
655
656impl AsRef<[u8]> for SegmentRoot {
657    #[inline(always)]
658    fn as_ref(&self) -> &[u8] {
659        &self.0
660    }
661}
662
663impl AsMut<[u8]> for SegmentRoot {
664    #[inline(always)]
665    fn as_mut(&mut self) -> &mut [u8] {
666        &mut self.0
667    }
668}
669
670impl SegmentRoot {
671    /// Size in bytes
672    pub const SIZE: usize = 32;
673
674    /// Convenient conversion from a slice of underlying representation for efficiency purposes
675    #[inline(always)]
676    pub const fn slice_from_repr(value: &[[u8; Self::SIZE]]) -> &[Self] {
677        Self::wrap_slice(value)
678    }
679
680    /// Convenient conversion to a slice of underlying representation for efficiency purposes
681    #[inline(always)]
682    pub const fn repr_from_slice(value: &[Self]) -> &[[u8; Self::SIZE]] {
683        Self::peel_slice(value)
684    }
685
686    /// Check whether a segment root is a part of the super segment
687    pub fn is_valid(
688        &self,
689        shard_index: ShardIndex,
690        local_segment_index: LocalSegmentIndex,
691        segment_position: SegmentPosition,
692        segment_proof: &SegmentProof,
693        num_segments: u32,
694        super_segment_root: &SuperSegmentRoot,
695    ) -> bool {
696        let shard_segment_root = ShardSegmentRootWithPosition {
697            shard_index,
698            segment_position,
699            local_segment_index,
700            segment_root: *self,
701        };
702        // The proof is fixed size and contains zero padding elements, which must be skipped for
703        // verification purposes
704        let (segment_proof, padding) = segment_proof
705            .split_once(|hash| hash == &[0; _])
706            .unwrap_or((segment_proof.as_slice(), &[]));
707        // Padding must only contain zeroes, so that a proof has a single encoding
708        if padding.iter().any(|hash| hash != &[0; _]) {
709            return false;
710        }
711        SuperSegmentMerkleTree::verify(
712            super_segment_root,
713            segment_proof,
714            u64::from(segment_position),
715            shard_segment_root.hash(),
716            u64::from(num_segments),
717        )
718    }
719}
720
721/// Size of blockchain history in segments
722#[derive(
723    Debug,
724    Display,
725    Copy,
726    Clone,
727    Ord,
728    PartialOrd,
729    Eq,
730    PartialEq,
731    Hash,
732    From,
733    Into,
734    Deref,
735    DerefMut,
736    TrivialType,
737)]
738#[cfg_attr(feature = "scale-codec", derive(Encode, Decode, MaxEncodedLen))]
739#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
740#[repr(C)]
741// Storing `SegmentIndex` to make all invariants valid
742pub struct HistorySize(SegmentIndex);
743
744impl HistorySize {
745    /// History size of one
746    pub const ONE: Self = Self(SegmentIndex::ZERO);
747
748    /// Create a new instance
749    #[inline(always)]
750    pub const fn new(value: NonZeroU64) -> Self {
751        Self(SegmentIndex::from(value.get() - 1))
752    }
753
754    /// Get internal representation
755    pub const fn as_segment_index(&self) -> SegmentIndex {
756        self.0
757    }
758
759    /// Get internal representation
760    pub const fn as_non_zero_u64(&self) -> NonZeroU64 {
761        NonZeroU64::new(u64::from(self.0).saturating_add(1)).expect("Not zero; qed")
762    }
763
764    /// Size of blockchain history in pieces
765    #[inline(always)]
766    pub const fn in_pieces(&self) -> NonZeroU64 {
767        NonZeroU64::new(
768            u64::from(self.0)
769                .saturating_add(1)
770                .saturating_mul(RecordedHistorySegment::NUM_PIECES as u64),
771        )
772        .expect("Not zero; qed")
773    }
774
775    /// Segment index that corresponds to this history size
776    #[inline(always)]
777    pub fn segment_index(&self) -> SegmentIndex {
778        self.0
779    }
780
781    /// History size at which expiration check for a sector happens.
782    ///
783    /// Returns `None` on overflow.
784    #[inline(always)]
785    pub fn sector_expiration_check(&self, min_sector_lifetime: Self) -> Option<Self> {
786        self.as_non_zero_u64()
787            .checked_add(min_sector_lifetime.as_non_zero_u64().get())
788            .map(Self::new)
789    }
790}
791
792/// Progress of an archived block.
793#[derive(Debug, Copy, Clone, PartialEq, Eq, Ord, PartialOrd, Hash, TrivialType)]
794#[cfg_attr(feature = "scale-codec", derive(Encode, Decode))]
795#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
796#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
797#[repr(C)]
798pub struct ArchivedBlockProgress {
799    /// Number of partially archived bytes of a block, `0` for a full block
800    bytes: u32,
801}
802
803impl Default for ArchivedBlockProgress {
804    /// We assume a block can always fit into the segment initially, but it is definitely possible
805    /// to be transitioned into the partial state after some overflow checking.
806    #[inline(always)]
807    fn default() -> Self {
808        Self::new_complete()
809    }
810}
811
812impl ArchivedBlockProgress {
813    /// Block is archived fully
814    #[inline(always)]
815    pub const fn new_complete() -> Self {
816        Self { bytes: 0 }
817    }
818
819    /// Block is partially archived with the provided number of bytes
820    #[inline(always)]
821    pub const fn new_partial(new_partial: NonZeroU32) -> Self {
822        Self {
823            bytes: new_partial.get(),
824        }
825    }
826
827    /// Return the number of partially archived bytes if the progress is not complete
828    #[inline(always)]
829    pub const fn partial(&self) -> Option<NonZeroU32> {
830        NonZeroU32::new(self.bytes)
831    }
832}
833
834/// Last archived block
835#[derive(Debug, Copy, Clone, PartialEq, Eq, Ord, PartialOrd, Hash, TrivialType)]
836#[cfg_attr(feature = "scale-codec", derive(Encode, Decode))]
837#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
838#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
839#[repr(C)]
840pub struct LastArchivedBlock {
841    /// Block number
842    pub number: Unaligned<BlockNumber>,
843    /// Progress of an archived block
844    pub archived_progress: ArchivedBlockProgress,
845}
846
847impl LastArchivedBlock {
848    /// Returns the number of partially archived bytes for a block
849    #[inline(always)]
850    pub fn partial_archived(&self) -> Option<NonZeroU32> {
851        self.archived_progress.partial()
852    }
853
854    /// Sets the number of partially archived bytes if block progress was archived partially
855    #[inline(always)]
856    pub fn set_partial_archived(&mut self, new_partial: NonZeroU32) {
857        self.archived_progress = ArchivedBlockProgress::new_partial(new_partial);
858    }
859
860    /// Indicate the last archived block was archived fully
861    #[inline(always)]
862    pub fn set_complete(&mut self) {
863        self.archived_progress = ArchivedBlockProgress::new_complete();
864    }
865
866    /// Get the block number (unwrap `Unaligned`)
867    pub const fn number(&self) -> BlockNumber {
868        self.number.as_inner()
869    }
870}
871
872/// Segment header for a specific segment of a shard
873#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, TrivialType)]
874#[cfg_attr(feature = "scale-codec", derive(Encode, Decode))]
875#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
876#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
877#[repr(C)]
878pub struct SegmentHeader {
879    /// Local segment index
880    pub index: Unaligned<LocalSegmentIndex>,
881    /// Root of roots of all records in a segment.
882    pub root: SegmentRoot,
883    /// Hash of the segment header of the previous segment
884    pub prev_segment_header_hash: Blake3Hash,
885    /// Last archived block
886    pub last_archived_block: LastArchivedBlock,
887}
888
889impl SegmentHeader {
890    /// Hash of the whole segment header
891    #[inline(always)]
892    pub fn hash(&self) -> Blake3Hash {
893        const {
894            assert!(size_of::<Self>() <= CHUNK_LEN);
895        }
896        Blake3Hash::new(
897            single_chunk_hash(self.as_bytes())
898                .expect("Less than a single chunk worth of bytes; qed"),
899        )
900    }
901}
902
903/// Recorded history segment before archiving is applied.
904///
905/// NOTE: This is a stack-allocated data structure and can cause stack overflow!
906#[derive(Copy, Clone, Eq, PartialEq, Deref, DerefMut)]
907#[repr(C)]
908pub struct RecordedHistorySegment([Record; Self::NUM_RAW_RECORDS]);
909
910impl fmt::Debug for RecordedHistorySegment {
911    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
912        f.debug_struct("RecordedHistorySegment")
913            .finish_non_exhaustive()
914    }
915}
916
917impl AsRef<[u8]> for RecordedHistorySegment {
918    #[inline]
919    fn as_ref(&self) -> &[u8] {
920        Record::slice_to_repr(&self.0).as_flattened().as_flattened()
921    }
922}
923
924impl AsMut<[u8]> for RecordedHistorySegment {
925    #[inline]
926    fn as_mut(&mut self) -> &mut [u8] {
927        Record::slice_mut_to_repr(&mut self.0)
928            .as_flattened_mut()
929            .as_flattened_mut()
930    }
931}
932
933impl RecordedHistorySegment {
934    /// Number of raw records in one segment of recorded history
935    pub const NUM_RAW_RECORDS: usize = 128;
936    /// Erasure coding rate for records during the archiving process
937    pub const ERASURE_CODING_RATE: (usize, usize) = (1, 2);
938    /// Number of pieces in one segment of archived history (taking erasure coding rate into
939    /// account)
940    pub const NUM_PIECES: usize =
941        Self::NUM_RAW_RECORDS * Self::ERASURE_CODING_RATE.1 / Self::ERASURE_CODING_RATE.0;
942    /// Size of recorded history segment in bytes.
943    ///
944    /// It includes half of the records (just source records) that will later be erasure coded and
945    /// together with corresponding roots and proofs will result in
946    /// [`Self::NUM_PIECES`] `Piece`s of archival history.
947    pub const SIZE: usize = Record::SIZE * Self::NUM_RAW_RECORDS;
948
949    /// Create boxed value without hitting stack overflow
950    #[inline]
951    #[cfg(feature = "alloc")]
952    pub fn new_boxed() -> Box<Self> {
953        // TODO: Should have been just `::new()`, but https://github.com/rust-lang/rust/issues/53827
954        // SAFETY: Data structure filled with zeroes is a valid invariant
955        unsafe { Box::<Self>::new_zeroed().assume_init() }
956    }
957}