solana_hash/
lib.rs

1#![no_std]
2#![cfg_attr(docsrs, feature(doc_auto_cfg))]
3#![cfg_attr(feature = "frozen-abi", feature(min_specialization))]
4#[cfg(feature = "borsh")]
5use borsh::{BorshDeserialize, BorshSchema, BorshSerialize};
6#[cfg(any(feature = "std", target_arch = "wasm32"))]
7extern crate std;
8#[cfg(feature = "bytemuck")]
9use bytemuck_derive::{Pod, Zeroable};
10#[cfg(feature = "serde")]
11use serde_derive::{Deserialize, Serialize};
12#[cfg(any(all(feature = "borsh", feature = "std"), target_arch = "wasm32"))]
13use std::string::ToString;
14use {
15    core::{
16        convert::TryFrom,
17        fmt,
18        str::{from_utf8_unchecked, FromStr},
19    },
20    solana_sanitize::Sanitize,
21};
22#[cfg(target_arch = "wasm32")]
23use {
24    js_sys::{Array, Uint8Array},
25    std::{boxed::Box, format, string::String, vec},
26    wasm_bindgen::{prelude::*, JsCast},
27};
28
29/// Size of a hash in bytes.
30pub const HASH_BYTES: usize = 32;
31/// Maximum string length of a base58 encoded hash.
32pub const MAX_BASE58_LEN: usize = 44;
33
34/// A hash; the 32-byte output of a hashing algorithm.
35///
36/// This struct is used most often in `solana-sdk` and related crates to contain
37/// a [SHA-256] hash, but may instead contain a [blake3] hash.
38///
39/// [SHA-256]: https://en.wikipedia.org/wiki/SHA-2
40/// [blake3]: https://github.com/BLAKE3-team/BLAKE3
41#[cfg_attr(target_arch = "wasm32", wasm_bindgen)]
42#[cfg_attr(feature = "frozen-abi", derive(solana_frozen_abi_macro::AbiExample))]
43#[cfg_attr(
44    feature = "borsh",
45    derive(BorshSerialize, BorshDeserialize),
46    borsh(crate = "borsh")
47)]
48#[cfg_attr(all(feature = "borsh", feature = "std"), derive(BorshSchema))]
49#[cfg_attr(feature = "bytemuck", derive(Pod, Zeroable))]
50#[cfg_attr(feature = "serde", derive(Serialize, Deserialize,))]
51#[derive(Clone, Copy, Default, Eq, PartialEq, Ord, PartialOrd, Hash)]
52#[repr(transparent)]
53pub struct Hash(pub(crate) [u8; HASH_BYTES]);
54
55impl Sanitize for Hash {}
56
57impl From<[u8; HASH_BYTES]> for Hash {
58    fn from(from: [u8; 32]) -> Self {
59        Self(from)
60    }
61}
62
63impl AsRef<[u8]> for Hash {
64    fn as_ref(&self) -> &[u8] {
65        &self.0[..]
66    }
67}
68
69fn write_as_base58(f: &mut fmt::Formatter, h: &Hash) -> fmt::Result {
70    let mut out = [0u8; MAX_BASE58_LEN];
71    let len = five8::encode_32(&h.0, &mut out) as usize;
72    // any sequence of base58 chars is valid utf8
73    let as_str = unsafe { from_utf8_unchecked(&out[..len]) };
74    f.write_str(as_str)
75}
76
77impl fmt::Debug for Hash {
78    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
79        write_as_base58(f, self)
80    }
81}
82
83impl fmt::Display for Hash {
84    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
85        write_as_base58(f, self)
86    }
87}
88
89#[derive(Debug, Clone, PartialEq, Eq)]
90pub enum ParseHashError {
91    WrongSize,
92    Invalid,
93}
94
95#[cfg(feature = "std")]
96impl std::error::Error for ParseHashError {}
97
98impl fmt::Display for ParseHashError {
99    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
100        match self {
101            ParseHashError::WrongSize => f.write_str("string decoded to wrong size for hash"),
102            ParseHashError::Invalid => f.write_str("failed to decoded string to hash"),
103        }
104    }
105}
106
107impl FromStr for Hash {
108    type Err = ParseHashError;
109
110    fn from_str(s: &str) -> Result<Self, Self::Err> {
111        use five8::DecodeError;
112        if s.len() > MAX_BASE58_LEN {
113            return Err(ParseHashError::WrongSize);
114        }
115        let mut bytes = [0; HASH_BYTES];
116        five8::decode_32(s, &mut bytes).map_err(|e| match e {
117            DecodeError::InvalidChar(_) => ParseHashError::Invalid,
118            DecodeError::TooLong
119            | DecodeError::TooShort
120            | DecodeError::LargestTermTooHigh
121            | DecodeError::OutputTooLong => ParseHashError::WrongSize,
122        })?;
123        Ok(Self::from(bytes))
124    }
125}
126
127impl Hash {
128    #[deprecated(since = "2.2.0", note = "Use 'Hash::new_from_array' instead")]
129    pub fn new(hash_slice: &[u8]) -> Self {
130        Hash(<[u8; HASH_BYTES]>::try_from(hash_slice).unwrap())
131    }
132
133    pub const fn new_from_array(hash_array: [u8; HASH_BYTES]) -> Self {
134        Self(hash_array)
135    }
136
137    /// unique Hash for tests and benchmarks.
138    pub fn new_unique() -> Self {
139        use solana_atomic_u64::AtomicU64;
140        static I: AtomicU64 = AtomicU64::new(1);
141
142        let mut b = [0u8; HASH_BYTES];
143        let i = I.fetch_add(1);
144        b[0..8].copy_from_slice(&i.to_le_bytes());
145        Self::new_from_array(b)
146    }
147
148    pub fn to_bytes(self) -> [u8; HASH_BYTES] {
149        self.0
150    }
151}
152
153#[cfg(target_arch = "wasm32")]
154#[allow(non_snake_case)]
155#[wasm_bindgen]
156impl Hash {
157    /// Create a new Hash object
158    ///
159    /// * `value` - optional hash as a base58 encoded string, `Uint8Array`, `[number]`
160    #[wasm_bindgen(constructor)]
161    pub fn constructor(value: JsValue) -> Result<Hash, JsValue> {
162        if let Some(base58_str) = value.as_string() {
163            base58_str
164                .parse::<Hash>()
165                .map_err(|x| JsValue::from(x.to_string()))
166        } else if let Some(uint8_array) = value.dyn_ref::<Uint8Array>() {
167            <[u8; HASH_BYTES]>::try_from(uint8_array.to_vec())
168                .map(Hash::new_from_array)
169                .map_err(|err| format!("Invalid Hash value: {err:?}").into())
170        } else if let Some(array) = value.dyn_ref::<Array>() {
171            let mut bytes = vec![];
172            let iterator = js_sys::try_iter(&array.values())?.expect("array to be iterable");
173            for x in iterator {
174                let x = x?;
175
176                if let Some(n) = x.as_f64() {
177                    if n >= 0. && n <= 255. {
178                        bytes.push(n as u8);
179                        continue;
180                    }
181                }
182                return Err(format!("Invalid array argument: {:?}", x).into());
183            }
184            <[u8; HASH_BYTES]>::try_from(bytes)
185                .map(Hash::new_from_array)
186                .map_err(|err| format!("Invalid Hash value: {err:?}").into())
187        } else if value.is_undefined() {
188            Ok(Hash::default())
189        } else {
190            Err("Unsupported argument".into())
191        }
192    }
193
194    /// Return the base58 string representation of the hash
195    pub fn toString(&self) -> String {
196        self.to_string()
197    }
198
199    /// Checks if two `Hash`s are equal
200    pub fn equals(&self, other: &Hash) -> bool {
201        self == other
202    }
203
204    /// Return the `Uint8Array` representation of the hash
205    pub fn toBytes(&self) -> Box<[u8]> {
206        self.0.clone().into()
207    }
208}
209
210#[cfg(test)]
211mod tests {
212    use super::*;
213
214    #[test]
215    fn test_new_unique() {
216        assert!(Hash::new_unique() != Hash::new_unique());
217    }
218
219    #[test]
220    fn test_hash_fromstr() {
221        let hash = Hash::new_from_array([1; 32]);
222
223        let mut hash_base58_str = bs58::encode(hash).into_string();
224
225        assert_eq!(hash_base58_str.parse::<Hash>(), Ok(hash));
226
227        hash_base58_str.push_str(&bs58::encode(hash.as_ref()).into_string());
228        assert_eq!(
229            hash_base58_str.parse::<Hash>(),
230            Err(ParseHashError::WrongSize)
231        );
232
233        hash_base58_str.truncate(hash_base58_str.len() / 2);
234        assert_eq!(hash_base58_str.parse::<Hash>(), Ok(hash));
235
236        hash_base58_str.truncate(hash_base58_str.len() / 2);
237        assert_eq!(
238            hash_base58_str.parse::<Hash>(),
239            Err(ParseHashError::WrongSize)
240        );
241
242        let input_too_big = bs58::encode(&[0xffu8; HASH_BYTES + 1]).into_string();
243        assert!(input_too_big.len() > MAX_BASE58_LEN);
244        assert_eq!(
245            input_too_big.parse::<Hash>(),
246            Err(ParseHashError::WrongSize)
247        );
248
249        let mut hash_base58_str = bs58::encode(hash.as_ref()).into_string();
250        assert_eq!(hash_base58_str.parse::<Hash>(), Ok(hash));
251
252        // throw some non-base58 stuff in there
253        hash_base58_str.replace_range(..1, "I");
254        assert_eq!(
255            hash_base58_str.parse::<Hash>(),
256            Err(ParseHashError::Invalid)
257        );
258    }
259}
solana_hash/lib.rs

solana_hash/
lib.rs
