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

clone_solana_hash/
lib.rs
