use crate::merkle::{Family, Location}; use commonware_codec::{Buf, EncodeSize, Error as CodecError, Read, ReadExt as _, Write}; use commonware_cryptography::Digest; use commonware_runtime::BufMut; use commonware_utils::range::NonEmptyRange; /// Target state to sync to. /// /// `PartialEq`, `Eq`, and `Clone` are implemented manually to avoid requiring `F` to implement /// them. #[derive(Debug)] pub struct Target { /// The ops root the sync engine verifies streaming batches against. pub root: D, /// Operations to sync, from the inclusive lower bound to the exclusive target size. /// /// The target's inactivity floor is declared by its final commit and may differ from the /// lower bound. pub range: NonEmptyRange>, } impl Target { /// Whether this target advances relative to `from`. /// /// Both targets are assumed to describe valid states of the same append-only QMDB. Because /// the root commits to the database size, valid targets at different sizes have distinct /// roots. pub fn advances(&self, from: &Self) -> bool { self.range.end().is_valid() && self.range.end() > from.range.end() && self.range.start() >= from.range.start() } } impl Clone for Target { fn clone(&self) -> Self { Self { root: self.root, range: self.range.clone(), } } } impl PartialEq for Target { fn eq(&self, other: &Self) -> bool { self.root == other.root && self.range == other.range } } impl Eq for Target {} impl Write for Target { fn write(&self, buf: &mut impl BufMut) { self.root.write(buf); self.range.write(buf); } } impl EncodeSize for Target { fn encode_size(&self) -> usize { self.root.encode_size() + self.range.encode_size() } } impl Read for Target { type Cfg = (); fn read_cfg(buf: &mut impl Buf, _: &()) -> Result { let root = D::read(buf)?; let range = NonEmptyRange::>::read(buf)?; if !range.start().is_valid() || !range.end().is_valid() { return Err(CodecError::Invalid( "storage::qmdb::sync::Target", "range bounds out of valid range", )); } Ok(Self { root, range }) } } #[cfg(feature = "arbitrary")] impl arbitrary::Arbitrary<'_> for Target where D: for<'a> arbitrary::Arbitrary<'a>, { fn arbitrary(u: &mut arbitrary::Unstructured<'_>) -> arbitrary::Result { let root = u.arbitrary()?; let max_loc = F::MAX_LEAVES; let lower = u.int_in_range(0..=*max_loc - 1)?; let upper = u.int_in_range(lower + 1..=*max_loc)?; Ok(Self { root, range: commonware_utils::non_empty_range!(Location::new(lower), Location::new(upper)), }) } } #[cfg(test)] // The unit tests use `MmrFamily` only. The codec and predicates are family-agnostic (the // family only influences `Location::is_valid` via `F::MAX_LEAVES` and the `arbitrary` range // picker), so an MMB variant would duplicate coverage. Codec conformance covers both families. mod tests { use super::*; use crate::merkle::mmr::Family as MmrFamily; use bytes::Bytes; use commonware_cryptography::sha256; use commonware_utils::non_empty_range; fn target(root: sha256::Digest, start: u64, end: u64) -> Target { Target { root, range: non_empty_range!(Location::new(start), Location::new(end)), } } #[test] fn test_sync_target_serialization() { let target = target(sha256::Digest::from([42; 32]), 100, 500); // Serialize let mut buffer = Vec::new(); target.write(&mut buffer); // Verify encoded size matches actual size assert_eq!(buffer.len(), target.encode_size()); // Deserialize let mut cursor = Bytes::from(buffer); let deserialized = Target::read(&mut cursor).unwrap(); // Verify assert_eq!(target, deserialized); assert_eq!(target.root, deserialized.root); assert_eq!(target.range, deserialized.range); } #[test] fn test_sync_target_read_invalid_bounds() { // Manually encode root + two Locations with reversed bounds let mut buffer = Vec::new(); sha256::Digest::from([42; 32]).write(&mut buffer); Location::::new(100).write(&mut buffer); // start Location::::new(50).write(&mut buffer); // end (< start = invalid) let mut cursor = Bytes::from(buffer); assert!(matches!( Target::::read(&mut cursor), Err(CodecError::Invalid("NonEmptyRange", "start must be < end")) )); // Manually encode a target with an empty range (start == end) let root = sha256::Digest::from([42; 32]); let mut buffer = Vec::new(); root.write(&mut buffer); Location::::new(100).write(&mut buffer); Location::::new(100).write(&mut buffer); let mut cursor = Bytes::from(buffer); assert!(matches!( Target::::read(&mut cursor), Err(CodecError::Invalid("NonEmptyRange", "start must be < end")) )); } #[test] fn test_sync_target_read_outside_location_domain() { let mut buffer = Vec::new(); sha256::Digest::from([42; 32]).write(&mut buffer); Location::::new(0).write(&mut buffer); Location::::new(*MmrFamily::MAX_LEAVES + 1).write(&mut buffer); assert!(matches!( Target::::read(&mut Bytes::from(buffer)), Err(CodecError::Invalid("Location", "value exceeds MAX_LEAVES")) )); } #[test] fn test_advances() { let current_root = sha256::Digest::from([0; 32]); let advanced_root = sha256::Digest::from([1; 32]); let current = target(current_root, 10, 100); // End strictly increases, start does not decrease. assert!(target(advanced_root, 10, 101).advances(¤t)); assert!(target(advanced_root, 50, 200).advances(¤t)); // Same or smaller end does not advance. assert!(!target(current_root, 10, 100).advances(¤t)); assert!(!target(current_root, 10, 50).advances(¤t)); // A start moving backward does not advance, even with a larger end. assert!(!target(advanced_root, 5, 200).advances(¤t)); // An end outside the location domain does not advance. let beyond = target(advanced_root, 10, *MmrFamily::MAX_LEAVES + 1); assert!(!beyond.advances(¤t)); } #[cfg(feature = "arbitrary")] mod conformance { use super::*; use crate::merkle::mmb; use commonware_codec::conformance::CodecConformance; commonware_conformance::conformance_tests! { CodecConformance>, CodecConformance>, } } }