bc_components/
reference.rs

1use bc_ur::prelude::*;
2
3use crate::{Digest, Error, Result, digest_provider::DigestProvider, tags};
4
5/// Implementers of this trait provide a globally unique reference to
6/// themselves.
7///
8/// The `ReferenceProvider` trait is used to create a unique, cryptographic
9/// reference to an object. This is particularly useful for distributed systems
10/// where objects need to be uniquely identified across networks or storage
11/// systems.
12///
13/// The reference is derived from a cryptographic digest of the object's
14/// serialized form, ensuring that the reference uniquely identifies the
15/// object's contents.
16pub trait ReferenceProvider {
17    /// Returns a cryptographic reference that uniquely identifies this object.
18    ///
19    /// The reference is derived from a digest of the object's serialized form,
20    /// ensuring that it uniquely identifies the object's contents.
21    fn reference(&self) -> Reference;
22
23    /// Returns the reference data as a hexadecimal string.
24    ///
25    /// This is a convenience method that returns the full 32-byte reference
26    /// as a 64-character hexadecimal string.
27    fn ref_hex(&self) -> String { self.reference().ref_hex() }
28
29    /// Returns the first four bytes of the reference.
30    ///
31    /// This is a convenience method for when a shorter, more user-friendly
32    /// representation is needed, such as for display or comparison purposes.
33    fn ref_data_short(&self) -> [u8; 4] { self.reference().ref_data_short() }
34
35    /// Returns the first four bytes of the reference as a hexadecimal string.
36    ///
37    /// This produces an 8-character string that is useful for display purposes,
38    /// such as in debug output or logs.
39    fn ref_hex_short(&self) -> String { self.reference().ref_hex_short() }
40
41    /// Returns the first four bytes of the reference as upper-case ByteWords.
42    ///
43    /// ByteWords is a human-readable encoding format that uses common English
44    /// words to represent binary data, making it easier to communicate
45    /// verbally or in text.
46    ///
47    /// # Parameters
48    ///
49    /// * `prefix` - An optional prefix to add before the ByteWords
50    ///   representation
51    fn ref_bytewords(&self, prefix: Option<&str>) -> String {
52        self.reference().bytewords_identifier(prefix)
53    }
54
55    /// Returns the first four bytes of the reference as Bytemoji.
56    ///
57    /// Bytemoji is an emoji-based encoding that represents binary data using
58    /// emoji characters, which can be more visually distinctive and memorable.
59    ///
60    /// # Parameters
61    ///
62    /// * `prefix` - An optional prefix to add before the Bytemoji
63    ///   representation
64    fn ref_bytemoji(&self, prefix: Option<&str>) -> String {
65        self.reference().bytemoji_identifier(prefix)
66    }
67}
68
69/// A globally unique reference to a globally unique object.
70///
71/// `Reference` provides a cryptographically secure way to uniquely identify
72/// objects based on their content. It is a fixed-size (32 bytes) identifier,
73/// typically derived from the SHA-256 hash of the object's serialized form.
74///
75/// References are useful in distributed systems for:
76/// - Unique identification of objects across networks
77/// - Verification that an object hasn't been modified
78/// - Content-addressable storage systems
79/// - Linking between objects in a content-addressed way
80///
81/// A `Reference` can be displayed in various formats, including hexadecimal,
82/// ByteWords (a human-readable partial hash as words), and Bytemoji (a
83/// human-readable partial hash based on emojis).
84#[derive(Clone, Copy, PartialEq, Eq, Hash)]
85pub struct Reference([u8; Self::REFERENCE_SIZE]);
86
87impl Reference {
88    pub const REFERENCE_SIZE: usize = 32;
89
90    /// Create a new reference from data.
91    pub fn from_data(data: [u8; Self::REFERENCE_SIZE]) -> Self { Self(data) }
92
93    /// Create a new reference from data.
94    ///
95    /// Returns `None` if the data is not the correct length.
96    pub fn from_data_ref(data: impl AsRef<[u8]>) -> Result<Self> {
97        let data = data.as_ref();
98        if data.len() != Self::REFERENCE_SIZE {
99            return Err(Error::invalid_size(
100                "reference",
101                Self::REFERENCE_SIZE,
102                data.len(),
103            ));
104        }
105        let mut arr = [0u8; Self::REFERENCE_SIZE];
106        arr.copy_from_slice(data.as_ref());
107        Ok(Self::from_data(arr))
108    }
109
110    /// Create a new reference from the given digest.
111    pub fn from_digest(digest: Digest) -> Self {
112        Self::from_data(*digest.data())
113    }
114
115    /// Get the data of the reference.
116    pub fn data(&self) -> &[u8; Self::REFERENCE_SIZE] { self.into() }
117
118    /// Get the data of the reference as a byte slice.
119    pub fn as_bytes(&self) -> &[u8] { self.as_ref() }
120
121    /// Create a new reference from the given hexadecimal string.
122    ///
123    /// # Panics
124    /// Panics if the string is not exactly 64 hexadecimal digits.
125    pub fn from_hex(hex: impl AsRef<str>) -> Self {
126        Self::from_data_ref(hex::decode(hex.as_ref()).unwrap()).unwrap()
127    }
128
129    /// The data as a hexadecimal string.
130    pub fn ref_hex(&self) -> String { hex::encode(self.0) }
131
132    /// The first four bytes of the reference
133    pub fn ref_data_short(&self) -> [u8; 4] { self.0[0..4].try_into().unwrap() }
134
135    /// The first four bytes of the reference as a hexadecimal string.
136    pub fn ref_hex_short(&self) -> String { hex::encode(self.ref_data_short()) }
137
138    /// The first four bytes of the XID as upper-case ByteWords.
139    pub fn bytewords_identifier(&self, prefix: Option<&str>) -> String {
140        let s = bytewords::identifier(&self.ref_data_short()).to_uppercase();
141        if let Some(prefix) = prefix {
142            format!("{prefix} {s}")
143        } else {
144            s
145        }
146    }
147
148    /// The first four bytes of the XID as Bytemoji.
149    pub fn bytemoji_identifier(&self, prefix: Option<&str>) -> String {
150        let s =
151            bytewords::bytemoji_identifier(&self.0[..4].try_into().unwrap())
152                .to_uppercase();
153        if let Some(prefix) = prefix {
154            format!("{prefix} {s}")
155        } else {
156            s
157        }
158    }
159}
160
161/// Implement the `ReferenceProvider` trait for `Reference`.
162///
163/// Yes, this creates a Reference to a Reference.
164impl ReferenceProvider for Reference {
165    fn reference(&self) -> Reference { Reference::from_digest(self.digest()) }
166}
167
168impl<'a> From<&'a Reference> for &'a [u8; Reference::REFERENCE_SIZE] {
169    fn from(value: &'a Reference) -> Self { &value.0 }
170}
171
172impl<'a> From<&'a Reference> for &'a [u8] {
173    fn from(value: &'a Reference) -> Self { &value.0 }
174}
175
176impl AsRef<[u8]> for Reference {
177    fn as_ref(&self) -> &[u8] { &self.0 }
178}
179
180impl AsRef<Reference> for Reference {
181    fn as_ref(&self) -> &Reference { self }
182}
183
184impl std::cmp::PartialOrd for Reference {
185    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
186        Some(self.cmp(other))
187    }
188}
189
190impl std::cmp::Ord for Reference {
191    fn cmp(&self, other: &Self) -> std::cmp::Ordering { self.0.cmp(&other.0) }
192}
193
194impl DigestProvider for Reference {
195    fn digest(&self) -> Digest {
196        Digest::from_image(self.tagged_cbor().to_cbor_data())
197    }
198}
199
200impl std::fmt::Debug for Reference {
201    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
202        write!(f, "Reference({})", self.ref_hex())
203    }
204}
205
206impl std::fmt::Display for Reference {
207    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
208        write!(f, "Reference({})", self.ref_hex_short())
209    }
210}
211
212impl CBORTagged for Reference {
213    fn cbor_tags() -> Vec<Tag> { tags_for_values(&[tags::TAG_REFERENCE]) }
214}
215
216impl From<Reference> for CBOR {
217    fn from(value: Reference) -> Self { value.tagged_cbor() }
218}
219
220impl CBORTaggedEncodable for Reference {
221    fn untagged_cbor(&self) -> CBOR { CBOR::to_byte_string(self.0) }
222}
223
224impl TryFrom<CBOR> for Reference {
225    type Error = dcbor::Error;
226
227    fn try_from(cbor: CBOR) -> dcbor::Result<Self> {
228        Self::from_tagged_cbor(cbor)
229    }
230}
231
232impl CBORTaggedDecodable for Reference {
233    fn from_untagged_cbor(cbor: CBOR) -> dcbor::Result<Self> {
234        let data = CBOR::try_into_byte_string(cbor)?;
235        Ok(Self::from_data_ref(data)?)
236    }
237}
238
239// Convert from an instance reference to an instance.
240impl From<&Reference> for Reference {
241    fn from(digest: &Reference) -> Self { *digest }
242}
243
244// Convert from a byte vector to an instance.
245impl From<Reference> for Vec<u8> {
246    fn from(digest: Reference) -> Self { digest.0.to_vec() }
247}
248
249// Convert a reference to an instance to a byte vector.
250impl From<&Reference> for Vec<u8> {
251    fn from(digest: &Reference) -> Self { digest.0.to_vec() }
252}
bc_components/reference.rs

bc_components/
reference.rs
