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, mem,
18        str::{from_utf8, 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 out_slice: &mut [u8] = &mut out;
72    // This will never fail because the only possible error is BufferTooSmall,
73    // and we will never call it with too small a buffer.
74    let len = bs58::encode(h.0).onto(out_slice).unwrap();
75    let as_str = from_utf8(&out[..len]).unwrap();
76    f.write_str(as_str)
77}
78
79impl fmt::Debug for Hash {
80    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
81        write_as_base58(f, self)
82    }
83}
84
85impl fmt::Display for Hash {
86    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
87        write_as_base58(f, self)
88    }
89}
90
91#[derive(Debug, Clone, PartialEq, Eq)]
92pub enum ParseHashError {
93    WrongSize,
94    Invalid,
95}
96
97#[cfg(feature = "std")]
98impl std::error::Error for ParseHashError {}
99
100impl fmt::Display for ParseHashError {
101    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
102        match self {
103            ParseHashError::WrongSize => f.write_str("string decoded to wrong size for hash"),
104            ParseHashError::Invalid => f.write_str("failed to decoded string to hash"),
105        }
106    }
107}
108
109impl FromStr for Hash {
110    type Err = ParseHashError;
111
112    fn from_str(s: &str) -> Result<Self, Self::Err> {
113        if s.len() > MAX_BASE58_LEN {
114            return Err(ParseHashError::WrongSize);
115        }
116        let mut bytes = [0; HASH_BYTES];
117        let decoded_size = bs58::decode(s)
118            .onto(&mut bytes)
119            .map_err(|_| ParseHashError::Invalid)?;
120        if decoded_size != mem::size_of::<Hash>() {
121            Err(ParseHashError::WrongSize)
122        } else {
123            Ok(bytes.into())
124        }
125    }
126}
127
128impl Hash {
129    #[deprecated(since = "2.2.0", note = "Use 'Hash::new_from_array' instead")]
130    pub fn new(hash_slice: &[u8]) -> Self {
131        Hash(<[u8; HASH_BYTES]>::try_from(hash_slice).unwrap())
132    }
133
134    pub const fn new_from_array(hash_array: [u8; HASH_BYTES]) -> Self {
135        Self(hash_array)
136    }
137
138    /// unique Hash for tests and benchmarks.
139    pub fn new_unique() -> Self {
140        use solana_atomic_u64::AtomicU64;
141        static I: AtomicU64 = AtomicU64::new(1);
142
143        let mut b = [0u8; HASH_BYTES];
144        let i = I.fetch_add(1);
145        b[0..8].copy_from_slice(&i.to_le_bytes());
146        Self::new_from_array(b)
147    }
148
149    pub fn to_bytes(self) -> [u8; HASH_BYTES] {
150        self.0
151    }
152}
153
154#[cfg(target_arch = "wasm32")]
155#[allow(non_snake_case)]
156#[wasm_bindgen]
157impl Hash {
158    /// Create a new Hash object
159    ///
160    /// * `value` - optional hash as a base58 encoded string, `Uint8Array`, `[number]`
161    #[wasm_bindgen(constructor)]
162    pub fn constructor(value: JsValue) -> Result<Hash, JsValue> {
163        if let Some(base58_str) = value.as_string() {
164            base58_str
165                .parse::<Hash>()
166                .map_err(|x| JsValue::from(x.to_string()))
167        } else if let Some(uint8_array) = value.dyn_ref::<Uint8Array>() {
168            <[u8; HASH_BYTES]>::try_from(uint8_array.to_vec())
169                .map(Hash::new_from_array)
170                .map_err(|err| format!("Invalid Hash value: {err:?}").into())
171        } else if let Some(array) = value.dyn_ref::<Array>() {
172            let mut bytes = vec![];
173            let iterator = js_sys::try_iter(&array.values())?.expect("array to be iterable");
174            for x in iterator {
175                let x = x?;
176
177                if let Some(n) = x.as_f64() {
178                    if n >= 0. && n <= 255. {
179                        bytes.push(n as u8);
180                        continue;
181                    }
182                }
183                return Err(format!("Invalid array argument: {:?}", x).into());
184            }
185            <[u8; HASH_BYTES]>::try_from(bytes)
186                .map(Hash::new_from_array)
187                .map_err(|err| format!("Invalid Hash value: {err:?}").into())
188        } else if value.is_undefined() {
189            Ok(Hash::default())
190        } else {
191            Err("Unsupported argument".into())
192        }
193    }
194
195    /// Return the base58 string representation of the hash
196    pub fn toString(&self) -> String {
197        self.to_string()
198    }
199
200    /// Checks if two `Hash`s are equal
201    pub fn equals(&self, other: &Hash) -> bool {
202        self == other
203    }
204
205    /// Return the `Uint8Array` representation of the hash
206    pub fn toBytes(&self) -> Box<[u8]> {
207        self.0.clone().into()
208    }
209}
210
211#[cfg(test)]
212mod tests {
213    use super::*;
214
215    #[test]
216    fn test_new_unique() {
217        assert!(Hash::new_unique() != Hash::new_unique());
218    }
219
220    #[test]
221    fn test_hash_fromstr() {
222        let hash = Hash::new_from_array([1; 32]);
223
224        let mut hash_base58_str = bs58::encode(hash).into_string();
225
226        assert_eq!(hash_base58_str.parse::<Hash>(), Ok(hash));
227
228        hash_base58_str.push_str(&bs58::encode(hash.as_ref()).into_string());
229        assert_eq!(
230            hash_base58_str.parse::<Hash>(),
231            Err(ParseHashError::WrongSize)
232        );
233
234        hash_base58_str.truncate(hash_base58_str.len() / 2);
235        assert_eq!(hash_base58_str.parse::<Hash>(), Ok(hash));
236
237        hash_base58_str.truncate(hash_base58_str.len() / 2);
238        assert_eq!(
239            hash_base58_str.parse::<Hash>(),
240            Err(ParseHashError::WrongSize)
241        );
242
243        let input_too_big = bs58::encode(&[0xffu8; HASH_BYTES + 1]).into_string();
244        assert!(input_too_big.len() > MAX_BASE58_LEN);
245        assert_eq!(
246            input_too_big.parse::<Hash>(),
247            Err(ParseHashError::WrongSize)
248        );
249
250        let mut hash_base58_str = bs58::encode(hash.as_ref()).into_string();
251        assert_eq!(hash_base58_str.parse::<Hash>(), Ok(hash));
252
253        // throw some non-base58 stuff in there
254        hash_base58_str.replace_range(..1, "I");
255        assert_eq!(
256            hash_base58_str.parse::<Hash>(),
257            Err(ParseHashError::Invalid)
258        );
259    }
260}
solana_hash/lib.rs

solana_hash/
lib.rs
