1use 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}