Skip to main content

blossom/
hash.rs

1//! Protocol hash types, domain separation, and feature compatibility registry.
2
3use borsh::{BorshDeserialize, BorshSerialize};
4use indextreemap::{IndexTreeMap, SharedIndexTreeMap};
5use serde::{Deserialize, Deserializer, Serialize, Serializer};
6#[cfg(not(feature = "insecure-fast-hash"))]
7use sha2::{Digest, Sha256};
8use std::collections::{BTreeMap, BTreeSet};
9use std::fmt;
10use std::ops::Deref;
11use std::sync::OnceLock;
12#[cfg(feature = "insecure-fast-hash")]
13use xxhash_rust::xxh3::Xxh3;
14
15use crate::error::{BlossomError, Result};
16
17pub const SHA256_PROTOCOL_HASH_ALGORITHM: &str = "sha256";
18pub const XXH3_PROTOCOL_HASH_ALGORITHM: &str = "xxh3-128x2";
19pub const PROTOCOL_FEATURE_CODE_VERSION: u8 = 1;
20pub const RESERVED_PROTOCOL_FEATURE_CODE: u16 = 0x0000;
21
22#[derive(Debug, Clone, Copy, PartialEq, Eq)]
23pub struct ProtocolFeatureCode {
24    pub id: u16,
25    pub label: &'static str,
26}
27
28impl ProtocolFeatureCode {
29    pub const fn new(id: u16, label: &'static str) -> Self {
30        Self { id, label }
31    }
32}
33
34pub const FAIR_BLOCK_ORDERING_PROTOCOL_FEATURE_CODE: ProtocolFeatureCode =
35    ProtocolFeatureCode::new(0x0001, "fair-block-ordering");
36pub const HIGH_AVAILABILITY_PROTOCOL_FEATURE_CODE: ProtocolFeatureCode =
37    ProtocolFeatureCode::new(0x0002, "high-availability");
38
39#[derive(Debug, Clone, Copy, PartialEq, Eq)]
40pub enum ProtocolConsensusSurface {
41    EpochBlockOrdering,
42    HighAvailabilityFinality,
43}
44
45#[derive(Debug, Clone, Copy, PartialEq, Eq)]
46pub struct ProtocolFeatureRegistryEntry {
47    pub code: ProtocolFeatureCode,
48    pub dependencies: &'static [u16],
49    pub conflicts: &'static [u16],
50    pub consensus_surface: ProtocolConsensusSurface,
51}
52
53pub const FAIR_BLOCK_ORDERING_PROTOCOL_FEATURE: ProtocolFeatureRegistryEntry =
54    ProtocolFeatureRegistryEntry {
55        code: FAIR_BLOCK_ORDERING_PROTOCOL_FEATURE_CODE,
56        dependencies: &[],
57        conflicts: &[],
58        consensus_surface: ProtocolConsensusSurface::EpochBlockOrdering,
59    };
60pub const HIGH_AVAILABILITY_PROTOCOL_FEATURE: ProtocolFeatureRegistryEntry =
61    ProtocolFeatureRegistryEntry {
62        code: HIGH_AVAILABILITY_PROTOCOL_FEATURE_CODE,
63        dependencies: &[],
64        conflicts: &[],
65        consensus_surface: ProtocolConsensusSurface::HighAvailabilityFinality,
66    };
67
68pub const PROTOCOL_FEATURE_REGISTRY: &[ProtocolFeatureRegistryEntry] = &[
69    FAIR_BLOCK_ORDERING_PROTOCOL_FEATURE,
70    HIGH_AVAILABILITY_PROTOCOL_FEATURE,
71];
72
73#[cfg(all(feature = "fair-block-ordering", feature = "high-availability"))]
74pub const PROTOCOL_FEATURE_CODES: &[ProtocolFeatureCode] = &[
75    FAIR_BLOCK_ORDERING_PROTOCOL_FEATURE_CODE,
76    HIGH_AVAILABILITY_PROTOCOL_FEATURE_CODE,
77];
78#[cfg(all(feature = "fair-block-ordering", not(feature = "high-availability")))]
79pub const PROTOCOL_FEATURE_CODES: &[ProtocolFeatureCode] =
80    &[FAIR_BLOCK_ORDERING_PROTOCOL_FEATURE_CODE];
81#[cfg(all(not(feature = "fair-block-ordering"), feature = "high-availability"))]
82pub const PROTOCOL_FEATURE_CODES: &[ProtocolFeatureCode] =
83    &[HIGH_AVAILABILITY_PROTOCOL_FEATURE_CODE];
84#[cfg(all(
85    not(feature = "fair-block-ordering"),
86    not(feature = "high-availability")
87))]
88pub const PROTOCOL_FEATURE_CODES: &[ProtocolFeatureCode] = &[];
89
90pub fn protocol_hash_algorithm() -> &'static str {
91    static PROTOCOL_HASH_ALGORITHM: OnceLock<String> = OnceLock::new();
92    PROTOCOL_HASH_ALGORITHM
93        .get_or_init(protocol_hash_algorithm_string)
94        .as_str()
95}
96
97fn protocol_base_hash_algorithm() -> &'static str {
98    #[cfg(feature = "insecure-fast-hash")]
99    {
100        XXH3_PROTOCOL_HASH_ALGORITHM
101    }
102
103    #[cfg(not(feature = "insecure-fast-hash"))]
104    {
105        SHA256_PROTOCOL_HASH_ALGORITHM
106    }
107}
108
109fn protocol_hash_algorithm_string() -> String {
110    let mut profile = protocol_base_hash_algorithm().to_string();
111    for feature_code in PROTOCOL_FEATURE_CODES {
112        profile.push('+');
113        profile.push_str(feature_code.label);
114    }
115    profile
116}
117
118pub fn protocol_hash_algorithm_is_compatible(peer: &str) -> bool {
119    peer == protocol_hash_algorithm()
120}
121
122pub fn protocol_feature_registry_entry(id: u16) -> Option<&'static ProtocolFeatureRegistryEntry> {
123    PROTOCOL_FEATURE_REGISTRY
124        .iter()
125        .find(|entry| entry.code.id == id)
126}
127
128pub fn validate_protocol_feature_registry() -> Result<()> {
129    let mut seen = BTreeSet::new();
130    let mut previous = None;
131    for entry in PROTOCOL_FEATURE_REGISTRY {
132        let code = entry.code;
133        if code.id == RESERVED_PROTOCOL_FEATURE_CODE {
134            return Err(BlossomError::WireProtocol(
135                "protocol feature registry uses reserved feature id 0x0000".to_string(),
136            ));
137        }
138        if code.label.is_empty() {
139            return Err(BlossomError::WireProtocol(
140                "protocol feature registry contains an empty feature label".to_string(),
141            ));
142        }
143        if previous.is_some_and(|previous| previous >= code.id) {
144            return Err(BlossomError::WireProtocol(
145                "protocol feature registry must be sorted by ascending feature id".to_string(),
146            ));
147        }
148        if !seen.insert(code.id) {
149            return Err(BlossomError::WireProtocol(format!(
150                "protocol feature registry duplicates feature id 0x{:04x}",
151                code.id
152            )));
153        }
154        previous = Some(code.id);
155    }
156
157    for entry in PROTOCOL_FEATURE_REGISTRY {
158        for dependency in entry.dependencies {
159            if *dependency == entry.code.id {
160                return Err(BlossomError::WireProtocol(format!(
161                    "protocol feature {} depends on itself",
162                    entry.code.label
163                )));
164            }
165            if !seen.contains(dependency) {
166                return Err(BlossomError::WireProtocol(format!(
167                    "protocol feature {} depends on unregistered feature id 0x{dependency:04x}",
168                    entry.code.label
169                )));
170            }
171        }
172        for conflict in entry.conflicts {
173            if *conflict == entry.code.id {
174                return Err(BlossomError::WireProtocol(format!(
175                    "protocol feature {} conflicts with itself",
176                    entry.code.label
177                )));
178            }
179            if !seen.contains(conflict) {
180                return Err(BlossomError::WireProtocol(format!(
181                    "protocol feature {} conflicts with unregistered feature id 0x{conflict:04x}",
182                    entry.code.label
183                )));
184            }
185            if entry.dependencies.contains(conflict) {
186                return Err(BlossomError::WireProtocol(format!(
187                    "protocol feature {} both depends on and conflicts with feature id 0x{conflict:04x}",
188                    entry.code.label
189                )));
190            }
191        }
192    }
193
194    Ok(())
195}
196
197pub fn validate_protocol_feature_codes(codes: &[ProtocolFeatureCode]) -> Result<()> {
198    validate_protocol_feature_registry()?;
199
200    if codes.len() > u16::MAX as usize {
201        return Err(BlossomError::WireProtocol(
202            "protocol feature profile has too many active features".to_string(),
203        ));
204    }
205
206    let mut seen = BTreeSet::new();
207    let mut previous = None;
208    for code in codes {
209        if code.id == RESERVED_PROTOCOL_FEATURE_CODE {
210            return Err(BlossomError::WireProtocol(
211                "protocol feature profile uses reserved feature id 0x0000".to_string(),
212            ));
213        }
214        if code.label.is_empty() {
215            return Err(BlossomError::WireProtocol(
216                "protocol feature profile contains an empty feature label".to_string(),
217            ));
218        }
219        if previous.is_some_and(|previous| previous >= code.id) {
220            return Err(BlossomError::WireProtocol(
221                "protocol feature profile must be sorted by ascending feature id".to_string(),
222            ));
223        }
224        if !seen.insert(code.id) {
225            return Err(BlossomError::WireProtocol(format!(
226                "protocol feature profile duplicates feature id 0x{:04x}",
227                code.id
228            )));
229        }
230        let Some(entry) = protocol_feature_registry_entry(code.id) else {
231            return Err(BlossomError::WireProtocol(format!(
232                "protocol feature profile uses unregistered feature id 0x{:04x}",
233                code.id
234            )));
235        };
236        if entry.code.label != code.label {
237            return Err(BlossomError::WireProtocol(format!(
238                "protocol feature id 0x{:04x} label mismatch: expected {}, got {}",
239                code.id, entry.code.label, code.label
240            )));
241        }
242        previous = Some(code.id);
243    }
244
245    for code in codes {
246        let entry = protocol_feature_registry_entry(code.id).expect("entry checked above");
247        for dependency in entry.dependencies {
248            if !seen.contains(dependency) {
249                return Err(BlossomError::WireProtocol(format!(
250                    "protocol feature {} requires missing feature id 0x{dependency:04x}",
251                    entry.code.label
252                )));
253            }
254        }
255        for conflict in entry.conflicts {
256            if seen.contains(conflict) {
257                return Err(BlossomError::WireProtocol(format!(
258                    "protocol feature {} conflicts with feature id 0x{conflict:04x}",
259                    entry.code.label
260                )));
261            }
262        }
263    }
264
265    Ok(())
266}
267
268pub fn protocol_feature_code_bytes() -> Vec<u8> {
269    validate_protocol_feature_codes(PROTOCOL_FEATURE_CODES)
270        .expect("compiled protocol feature profile must be valid");
271
272    let mut bytes = Vec::with_capacity(3 + (PROTOCOL_FEATURE_CODES.len() * 2));
273    bytes.push(PROTOCOL_FEATURE_CODE_VERSION);
274    bytes.extend_from_slice(&(PROTOCOL_FEATURE_CODES.len() as u16).to_be_bytes());
275    for feature_code in PROTOCOL_FEATURE_CODES {
276        bytes.extend_from_slice(&feature_code.id.to_be_bytes());
277    }
278    bytes
279}
280
281#[derive(
282    Debug,
283    Clone,
284    PartialEq,
285    Default,
286    Eq,
287    Hash,
288    PartialOrd,
289    Ord,
290    Copy,
291    BorshSerialize,
292    BorshDeserialize,
293)]
294pub struct HashType(pub [u8; 32]);
295
296impl HashType {
297    pub fn hash(bytes: &[u8]) -> Self {
298        let mut hasher = ProtocolHasher::new();
299        hasher.update(bytes);
300        hasher.finalize()
301    }
302
303    pub fn hash_slices<'a, I>(slices: I) -> Self
304    where
305        I: IntoIterator<Item = &'a [u8]>,
306    {
307        let mut hasher = ProtocolHasher::new();
308        for bytes in slices {
309            hasher.update(bytes);
310        }
311        hasher.finalize()
312    }
313
314    pub fn from_byte_hash(hash: [u8; 32]) -> Self {
315        Self(hash)
316    }
317
318    pub fn to_bytes(self) -> Vec<u8> {
319        self.0.to_vec()
320    }
321
322    pub fn try_from_hex(value: &str) -> Result<Self> {
323        let bytes = hex::decode(value).map_err(|_| BlossomError::InvalidHex)?;
324        Self::try_from(bytes.as_slice())
325    }
326}
327
328impl Deref for HashType {
329    type Target = [u8; 32];
330
331    fn deref(&self) -> &Self::Target {
332        &self.0
333    }
334}
335
336impl AsRef<[u8]> for HashType {
337    fn as_ref(&self) -> &[u8] {
338        &self.0
339    }
340}
341
342impl fmt::Display for HashType {
343    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
344        write!(f, "{}", hex::encode(self.0))
345    }
346}
347
348impl TryFrom<&[u8]> for HashType {
349    type Error = BlossomError;
350
351    fn try_from(value: &[u8]) -> Result<Self> {
352        let actual = value.len();
353        let bytes: [u8; 32] = value.try_into().map_err(|_| BlossomError::InvalidLength {
354            expected: 32,
355            actual,
356        })?;
357        Ok(Self(bytes))
358    }
359}
360
361impl From<[u8; 32]> for HashType {
362    fn from(value: [u8; 32]) -> Self {
363        Self(value)
364    }
365}
366
367impl Serialize for HashType {
368    fn serialize<S: Serializer>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error> {
369        serializer.serialize_str(&self.to_string())
370    }
371}
372
373impl<'de> Deserialize<'de> for HashType {
374    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> std::result::Result<Self, D::Error> {
375        let value = <String as Deserialize>::deserialize(deserializer)?;
376        Self::try_from_hex(&value).map_err(serde::de::Error::custom)
377    }
378}
379
380pub trait DoHash {
381    fn hash(&self) -> HashType;
382}
383
384#[cfg(not(feature = "insecure-fast-hash"))]
385pub struct ProtocolHasher {
386    inner: Sha256,
387}
388
389#[cfg(not(feature = "insecure-fast-hash"))]
390impl ProtocolHasher {
391    pub fn new() -> Self {
392        Self {
393            inner: Sha256::new(),
394        }
395    }
396
397    pub fn update(&mut self, bytes: impl AsRef<[u8]>) {
398        self.inner.update(bytes.as_ref());
399    }
400
401    pub fn finalize(self) -> HashType {
402        HashType::from_byte_hash(self.inner.finalize().into())
403    }
404}
405
406#[cfg(feature = "insecure-fast-hash")]
407pub struct ProtocolHasher {
408    primary: Xxh3,
409    secondary: Xxh3,
410}
411
412#[cfg(feature = "insecure-fast-hash")]
413impl ProtocolHasher {
414    pub fn new() -> Self {
415        Self {
416            primary: Xxh3::new(),
417            secondary: Xxh3::with_seed(0xb105_50ff_0d15_ea5e),
418        }
419    }
420
421    pub fn update(&mut self, bytes: impl AsRef<[u8]>) {
422        let bytes = bytes.as_ref();
423        self.primary.update(bytes);
424        self.secondary.update(bytes);
425    }
426
427    pub fn finalize(self) -> HashType {
428        let mut bytes = [0; 32];
429        bytes[..16].copy_from_slice(&self.primary.digest128().to_le_bytes());
430        bytes[16..].copy_from_slice(&self.secondary.digest128().to_le_bytes());
431        HashType::from_byte_hash(bytes)
432    }
433}
434
435impl Default for ProtocolHasher {
436    fn default() -> Self {
437        Self::new()
438    }
439}
440
441impl<K, V> DoHash for BTreeMap<K, V>
442where
443    K: Ord + AsRef<[u8]>,
444{
445    fn hash(&self) -> HashType {
446        HashType::hash_slices(self.keys().map(AsRef::as_ref))
447    }
448}
449
450impl<K, V> DoHash for IndexTreeMap<K, V>
451where
452    K: Sized + Ord + AsRef<[u8]>,
453{
454    fn hash(&self) -> HashType {
455        HashType::hash_slices(self.keys_ref().map(AsRef::as_ref))
456    }
457}
458
459impl<K, V> DoHash for SharedIndexTreeMap<K, V>
460where
461    K: AsRef<[u8]>,
462{
463    fn hash(&self) -> HashType {
464        HashType::hash_slices(self.keys_ref().map(AsRef::as_ref))
465    }
466}
467
468#[cfg(test)]
469mod tests {
470    use super::*;
471    use crate::crypto::PubKey;
472
473    #[test]
474    #[cfg(not(feature = "fair-block-ordering"))]
475    fn protocol_hash_algorithm_reports_raw_ordering_profile() {
476        #[cfg(feature = "insecure-fast-hash")]
477        assert_eq!(protocol_hash_algorithm(), XXH3_PROTOCOL_HASH_ALGORITHM);
478
479        #[cfg(not(feature = "insecure-fast-hash"))]
480        assert_eq!(protocol_hash_algorithm(), SHA256_PROTOCOL_HASH_ALGORITHM);
481
482        assert_eq!(PROTOCOL_FEATURE_CODES, &[]);
483        assert_eq!(
484            protocol_feature_code_bytes(),
485            vec![PROTOCOL_FEATURE_CODE_VERSION, 0x00, 0x00]
486        );
487    }
488
489    #[test]
490    #[cfg(feature = "fair-block-ordering")]
491    fn protocol_hash_algorithm_reports_fair_ordering_profile() {
492        #[cfg(all(feature = "insecure-fast-hash", feature = "high-availability"))]
493        assert_eq!(
494            protocol_hash_algorithm(),
495            "xxh3-128x2+fair-block-ordering+high-availability"
496        );
497        #[cfg(all(not(feature = "insecure-fast-hash"), feature = "high-availability"))]
498        assert_eq!(
499            protocol_hash_algorithm(),
500            "sha256+fair-block-ordering+high-availability"
501        );
502        #[cfg(feature = "insecure-fast-hash")]
503        #[cfg(not(feature = "high-availability"))]
504        assert_eq!(protocol_hash_algorithm(), "xxh3-128x2+fair-block-ordering");
505
506        #[cfg(not(feature = "insecure-fast-hash"))]
507        #[cfg(not(feature = "high-availability"))]
508        assert_eq!(protocol_hash_algorithm(), "sha256+fair-block-ordering");
509
510        #[cfg(feature = "high-availability")]
511        assert_eq!(
512            PROTOCOL_FEATURE_CODES,
513            &[
514                FAIR_BLOCK_ORDERING_PROTOCOL_FEATURE_CODE,
515                HIGH_AVAILABILITY_PROTOCOL_FEATURE_CODE
516            ]
517        );
518        #[cfg(not(feature = "high-availability"))]
519        assert_eq!(
520            PROTOCOL_FEATURE_CODES,
521            &[FAIR_BLOCK_ORDERING_PROTOCOL_FEATURE_CODE]
522        );
523        #[cfg(feature = "high-availability")]
524        assert_eq!(
525            protocol_feature_code_bytes(),
526            vec![
527                PROTOCOL_FEATURE_CODE_VERSION,
528                0x00,
529                0x02,
530                0x00,
531                0x01,
532                0x00,
533                0x02
534            ]
535        );
536        #[cfg(not(feature = "high-availability"))]
537        assert_eq!(
538            protocol_feature_code_bytes(),
539            vec![PROTOCOL_FEATURE_CODE_VERSION, 0x00, 0x01, 0x00, 0x01]
540        );
541        assert!(!protocol_hash_algorithm_is_compatible(
542            protocol_base_hash_algorithm()
543        ));
544    }
545
546    #[test]
547    fn protocol_feature_code_namespace_has_extension_room() {
548        assert!(u16::MAX as usize > 65_000);
549        assert!(PROTOCOL_FEATURE_CODES.len() <= u16::MAX as usize);
550        assert!(
551            PROTOCOL_FEATURE_CODES
552                .iter()
553                .all(|feature_code| feature_code.id != RESERVED_PROTOCOL_FEATURE_CODE)
554        );
555        assert!(
556            PROTOCOL_FEATURE_CODES
557                .windows(2)
558                .all(|window| window[0].id < window[1].id)
559        );
560    }
561
562    #[test]
563    fn protocol_feature_registry_validates_active_profile() {
564        assert_eq!(
565            protocol_feature_registry_entry(FAIR_BLOCK_ORDERING_PROTOCOL_FEATURE_CODE.id),
566            Some(&FAIR_BLOCK_ORDERING_PROTOCOL_FEATURE)
567        );
568        assert_eq!(
569            protocol_feature_registry_entry(HIGH_AVAILABILITY_PROTOCOL_FEATURE_CODE.id),
570            Some(&HIGH_AVAILABILITY_PROTOCOL_FEATURE)
571        );
572        assert!(validate_protocol_feature_registry().is_ok());
573        assert!(validate_protocol_feature_codes(PROTOCOL_FEATURE_CODES).is_ok());
574        assert!(
575            PROTOCOL_FEATURE_REGISTRY
576                .windows(2)
577                .all(|window| window[0].code.id < window[1].code.id)
578        );
579    }
580
581    #[test]
582    fn protocol_feature_registry_rejects_invalid_profiles() {
583        assert!(
584            validate_protocol_feature_codes(&[ProtocolFeatureCode::new(
585                RESERVED_PROTOCOL_FEATURE_CODE,
586                "reserved"
587            )])
588            .is_err()
589        );
590        assert!(
591            validate_protocol_feature_codes(&[ProtocolFeatureCode::new(0x7fff, "not-registered")])
592                .is_err()
593        );
594        assert!(
595            validate_protocol_feature_codes(&[ProtocolFeatureCode::new(
596                FAIR_BLOCK_ORDERING_PROTOCOL_FEATURE_CODE.id,
597                "wrong-label"
598            )])
599            .is_err()
600        );
601        assert!(
602            validate_protocol_feature_codes(&[
603                FAIR_BLOCK_ORDERING_PROTOCOL_FEATURE_CODE,
604                FAIR_BLOCK_ORDERING_PROTOCOL_FEATURE_CODE
605            ])
606            .is_err()
607        );
608    }
609
610    #[test]
611    fn hex_display_parse_and_json_round_trip() {
612        let hash = HashType([7; 32]);
613        let encoded = hash.to_string();
614
615        assert_eq!(HashType::try_from_hex(&encoded), Ok(hash));
616        assert_eq!(
617            serde_json::to_string(&hash).unwrap(),
618            format!("\"{encoded}\"")
619        );
620        assert_eq!(
621            serde_json::from_str::<HashType>(&format!("\"{encoded}\"")).unwrap(),
622            hash
623        );
624    }
625
626    #[test]
627    fn invalid_hex_and_length_are_rejected() {
628        assert_eq!(
629            HashType::try_from_hex("not-hex"),
630            Err(BlossomError::InvalidHex)
631        );
632        assert_eq!(
633            HashType::try_from(&[1, 2, 3][..]),
634            Err(BlossomError::InvalidLength {
635                expected: 32,
636                actual: 3
637            })
638        );
639    }
640
641    #[test]
642    fn map_hashes_are_key_ordered_and_value_independent() {
643        let mut first = BTreeMap::new();
644        first.insert(PubKey([2; 32]), "two");
645        first.insert(PubKey([1; 32]), "one");
646
647        let mut second = BTreeMap::new();
648        second.insert(PubKey([1; 32]), "different");
649        second.insert(PubKey([2; 32]), "values");
650
651        assert_eq!(DoHash::hash(&first), DoHash::hash(&second));
652    }
653
654    #[test]
655    fn index_tree_hash_uses_indexed_keys() {
656        let mut tree = IndexTreeMap::new();
657        tree.insert(PubKey([1; 32]), ());
658        tree.insert(PubKey([2; 32]), ());
659
660        let mut map = BTreeMap::new();
661        map.insert(PubKey([1; 32]), ());
662        map.insert(PubKey([2; 32]), ());
663
664        assert_eq!(DoHash::hash(&tree), DoHash::hash(&map));
665    }
666}