alloy_primitives/utils/

mod.rs

//! Common Ethereum utilities.

use crate::B256;
use alloc::{boxed::Box, collections::TryReserveError, vec::Vec};
use cfg_if::cfg_if;
use core::{
    fmt,
    mem::{ManuallyDrop, MaybeUninit},
};

mod units;
pub use units::{
    DecimalSeparator, ParseUnits, Unit, UnitsError, format_ether, format_units, format_units_with,
    parse_ether, parse_units,
};

mod hint;

#[cfg(feature = "keccak-cache")]
mod keccak_cache;

/// The prefix used for hashing messages according to EIP-191.
pub const EIP191_PREFIX: &str = "\x19Ethereum Signed Message:\n";

/// The [Keccak-256](keccak256) hash of the empty string `""`.
pub const KECCAK256_EMPTY: B256 =
    b256!("0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470");

/// Tries to create a [`Vec`] containing the arguments.
#[macro_export]
macro_rules! try_vec {
    () => {
        $crate::private::Vec::new()
    };
    ($elem:expr; $n:expr) => {
        $crate::utils::vec_try_from_elem($elem, $n)
    };
    ($($x:expr),+ $(,)?) => {
        match $crate::utils::box_try_new([$($x),+]) {
            ::core::result::Result::Ok(x) => ::core::result::Result::Ok(<[_]>::into_vec(x)),
            ::core::result::Result::Err(e) => ::core::result::Result::Err(e),
        }
    };
}

/// Allocates memory on the heap then places `x` into it, returning an error if the allocation
/// fails.
///
/// Stable version of `Box::try_new`.
#[inline]
pub fn box_try_new<T>(value: T) -> Result<Box<T>, TryReserveError> {
    let mut boxed = box_try_new_uninit::<T>()?;
    unsafe {
        boxed.as_mut_ptr().write(value);
        let ptr = Box::into_raw(boxed);
        Ok(Box::from_raw(ptr.cast()))
    }
}

/// Constructs a new box with uninitialized contents on the heap, returning an error if the
/// allocation fails.
///
/// Stable version of `Box::try_new_uninit`.
#[inline]
pub fn box_try_new_uninit<T>() -> Result<Box<MaybeUninit<T>>, TryReserveError> {
    let mut vec = Vec::<MaybeUninit<T>>::new();

    // Reserve enough space for one `MaybeUninit<T>`.
    vec.try_reserve_exact(1)?;

    // `try_reserve_exact`'s docs note that the allocator might allocate more than requested anyway.
    // Make sure we got exactly 1 element.
    vec.shrink_to(1);

    let mut vec = ManuallyDrop::new(vec);

    // SAFETY: `vec` is exactly one element long and has not been deallocated.
    Ok(unsafe { Box::from_raw(vec.as_mut_ptr()) })
}

/// Tries to collect the elements of an iterator into a `Vec`.
pub fn try_collect_vec<I: Iterator<Item = T>, T>(iter: I) -> Result<Vec<T>, TryReserveError> {
    let mut vec = Vec::new();
    if let Some(size_hint) = iter.size_hint().1 {
        vec.try_reserve(size_hint.max(4))?;
    }
    vec.extend(iter);
    Ok(vec)
}

/// Tries to create a `Vec` with the given capacity.
#[inline]
pub fn vec_try_with_capacity<T>(capacity: usize) -> Result<Vec<T>, TryReserveError> {
    let mut vec = Vec::new();
    vec.try_reserve(capacity).map(|()| vec)
}

/// Tries to create a `Vec` of `n` elements, each initialized to `elem`.
// Not public API. Use `try_vec!` instead.
#[doc(hidden)]
pub fn vec_try_from_elem<T: Clone>(elem: T, n: usize) -> Result<Vec<T>, TryReserveError> {
    let mut vec = Vec::new();
    vec.try_reserve(n)?;
    vec.resize(n, elem);
    Ok(vec)
}

/// Hash a message according to [EIP-191] (version `0x01`).
///
/// The final message is a UTF-8 string, encoded as follows:
/// `"\x19Ethereum Signed Message:\n" + message.length + message`
///
/// This message is then hashed using [Keccak-256](keccak256).
///
/// [EIP-191]: https://eips.ethereum.org/EIPS/eip-191
pub fn eip191_hash_message<T: AsRef<[u8]>>(message: T) -> B256 {
    keccak256(eip191_message(message))
}

/// Constructs a message according to [EIP-191] (version `0x01`).
///
/// The final message is a UTF-8 string, encoded as follows:
/// `"\x19Ethereum Signed Message:\n" + message.length + message`
///
/// [EIP-191]: https://eips.ethereum.org/EIPS/eip-191
pub fn eip191_message<T: AsRef<[u8]>>(message: T) -> Vec<u8> {
    fn eip191_message(message: &[u8]) -> Vec<u8> {
        let len = message.len();
        let mut len_string_buffer = itoa::Buffer::new();
        let len_string = len_string_buffer.format(len);

        let mut eth_message = Vec::with_capacity(EIP191_PREFIX.len() + len_string.len() + len);
        eth_message.extend_from_slice(EIP191_PREFIX.as_bytes());
        eth_message.extend_from_slice(len_string.as_bytes());
        eth_message.extend_from_slice(message);
        eth_message
    }

    eip191_message(message.as_ref())
}

/// Simple interface to the [`Keccak-256`] hash function.
///
/// Uses the cache if the `keccak-cache-global` feature is enabled.
///
/// [`Keccak-256`]: https://en.wikipedia.org/wiki/SHA-3
pub fn keccak256<T: AsRef<[u8]>>(bytes: T) -> B256 {
    #[cfg(feature = "keccak-cache-global")]
    return keccak_cache::compute(bytes.as_ref(), keccak256_impl);
    #[cfg(not(feature = "keccak-cache-global"))]
    return keccak256_impl(bytes.as_ref());
}

/// Simple interface to the [`Keccak-256`] hash function,
/// with a thin cache layer.
///
/// Uses the cache if the `keccak-cache` feature is enabled.
///
/// [`Keccak-256`]: https://en.wikipedia.org/wiki/SHA-3
pub fn keccak256_cached<T: AsRef<[u8]>>(bytes: T) -> B256 {
    #[cfg(feature = "keccak-cache")]
    return keccak_cache::compute(bytes.as_ref(), keccak256_impl);
    #[cfg(not(feature = "keccak-cache"))]
    return keccak256_impl(bytes.as_ref());
}

/// Simple interface to the [`Keccak-256`] hash function.
///
/// This function always computes the hash directly without using the cache.
///
/// Does not use the cache even if the `keccak-cache` feature is enabled.
///
/// [`Keccak-256`]: https://en.wikipedia.org/wiki/SHA-3
#[inline]
pub fn keccak256_uncached<T: AsRef<[u8]>>(bytes: T) -> B256 {
    keccak256_impl(bytes.as_ref())
}

#[allow(unused)]
fn keccak256_impl(bytes: &[u8]) -> B256 {
    let mut output = MaybeUninit::<B256>::uninit();

    cfg_if! {
        if #[cfg(all(feature = "native-keccak", not(any(feature = "sha3-keccak", feature = "tiny-keccak", miri))))] {
            #[link(wasm_import_module = "vm_hooks")]
            unsafe extern "C" {
                /// When targeting VMs with native keccak hooks, the `native-keccak` feature
                /// can be enabled to import and use the host environment's implementation
                /// of [`keccak256`] in place of [`sha3`] or [`tiny_keccak`]. This is overridden
                /// when the `sha3-keccak` or `tiny-keccak` feature is enabled.
                ///
                /// # Safety
                ///
                /// The VM accepts the preimage by pointer and length, and writes the
                /// 32-byte hash.
                /// - `bytes` must point to an input buffer at least `len` long.
                /// - `output` must point to a buffer that is at least 32-bytes long.
                ///
                /// [`keccak256`]: https://en.wikipedia.org/wiki/SHA-3
                /// [`sha3`]: https://docs.rs/sha3/latest/sha3/
                /// [`tiny_keccak`]: https://docs.rs/tiny-keccak/latest/tiny_keccak/
                fn native_keccak256(bytes: *const u8, len: usize, output: *mut u8);
            }

            // SAFETY: The output is 32-bytes, and the input comes from a slice.
            unsafe { native_keccak256(bytes.as_ptr(), bytes.len(), output.as_mut_ptr().cast::<u8>()) };
        } else if #[cfg(all(feature = "asm-keccak", not(miri)))] {
            return B256::new(keccak_asm::Keccak256::digest(bytes).into());
        } else {
            let mut hasher = Keccak256::new();
            hasher.update(bytes);
            // SAFETY: Never reads from `output`.
            unsafe { hasher.finalize_into_raw(output.as_mut_ptr().cast()) };
        }
    }

    // SAFETY: Initialized above.
    unsafe { output.assume_init() }
}

mod keccak256_state {
    cfg_if::cfg_if! {
        if #[cfg(all(feature = "asm-keccak", not(miri)))] {
            pub(super) use keccak_asm::Digest;

            pub(super) type State = keccak_asm::Keccak256;
        } else if #[cfg(feature = "tiny-keccak")] {
            pub(super) use tiny_keccak::Hasher as Digest;

            /// Wraps `tiny_keccak::Keccak` to implement `Digest`-like API.
            #[derive(Clone)]
            pub(super) struct State(tiny_keccak::Keccak);

            impl State {
                #[inline]
                pub(super) fn new() -> Self {
                    Self(tiny_keccak::Keccak::v256())
                }

                #[inline]
                pub(super) fn finalize_into(self, output: &mut [u8; 32]) {
                    self.0.finalize(output);
                }

                #[inline]
                pub(super) fn update(&mut self, bytes: &[u8]) {
                    self.0.update(bytes);
                }
            }
        } else {
            pub(super) use sha3::Digest;

            pub(super) type State = sha3::Keccak256;
        }
    }
}
#[allow(unused_imports)]
use keccak256_state::Digest;

/// Simple [`Keccak-256`] hasher.
///
/// Note that the "native-keccak" feature is not supported for this struct, and will default to the
/// [`sha3`] implementation.
///
/// [`Keccak-256`]: https://en.wikipedia.org/wiki/SHA-3
#[derive(Clone)]
pub struct Keccak256 {
    state: keccak256_state::State,
}

impl Default for Keccak256 {
    #[inline]
    fn default() -> Self {
        Self::new()
    }
}

impl fmt::Debug for Keccak256 {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Keccak256").finish_non_exhaustive()
    }
}

impl Keccak256 {
    /// Creates a new [`Keccak256`] hasher.
    #[inline]
    pub fn new() -> Self {
        Self { state: keccak256_state::State::new() }
    }

    /// Absorbs additional input. Can be called multiple times.
    #[inline]
    pub fn update(&mut self, bytes: impl AsRef<[u8]>) {
        self.state.update(bytes.as_ref());
    }

    /// Pad and squeeze the state.
    #[inline]
    pub fn finalize(self) -> B256 {
        let mut output = MaybeUninit::<B256>::uninit();
        // SAFETY: The output is 32-bytes.
        unsafe { self.finalize_into_raw(output.as_mut_ptr().cast()) };
        // SAFETY: Initialized above.
        unsafe { output.assume_init() }
    }

    /// Pad and squeeze the state into `output`.
    ///
    /// # Panics
    ///
    /// Panics if `output` is not 32 bytes long.
    #[inline]
    #[track_caller]
    pub fn finalize_into(self, output: &mut [u8]) {
        self.finalize_into_array(output.try_into().unwrap())
    }

    /// Pad and squeeze the state into `output`.
    #[inline]
    #[allow(clippy::useless_conversion)]
    pub fn finalize_into_array(self, output: &mut [u8; 32]) {
        self.state.finalize_into(output.into());
    }

    /// Pad and squeeze the state into `output`.
    ///
    /// # Safety
    ///
    /// `output` must point to a buffer that is at least 32-bytes long.
    #[inline]
    pub unsafe fn finalize_into_raw(self, output: *mut u8) {
        self.finalize_into_array(unsafe { &mut *output.cast::<[u8; 32]>() })
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use alloc::string::ToString;

    // test vector taken from:
    // https://web3js.readthedocs.io/en/v1.10.0/web3-eth-accounts.html#hashmessage
    #[test]
    fn test_hash_message() {
        let msg = "Hello World";
        let eip191_msg = eip191_message(msg);
        let hash = keccak256(&eip191_msg);
        assert_eq!(
            eip191_msg,
            [EIP191_PREFIX.as_bytes(), msg.len().to_string().as_bytes(), msg.as_bytes()].concat()
        );
        assert_eq!(
            hash,
            b256!("0xa1de988600a42c4b4ab089b619297c17d53cffae5d5120d82d8a92d0bb3b78f2")
        );
        assert_eq!(eip191_hash_message(msg), hash);
    }

    #[test]
    fn keccak256_hasher() {
        let expected = b256!("0x47173285a8d7341e5e972fc677286384f802f8ef42a5ec5f03bbfa254cb01fad");
        assert_eq!(keccak256("hello world"), expected);

        let mut hasher = Keccak256::new();
        hasher.update(b"hello");
        hasher.update(b" world");

        assert_eq!(hasher.clone().finalize(), expected);

        let mut hash = [0u8; 32];
        hasher.clone().finalize_into(&mut hash);
        assert_eq!(hash, expected);

        let mut hash = [0u8; 32];
        hasher.clone().finalize_into_array(&mut hash);
        assert_eq!(hash, expected);

        let mut hash = [0u8; 32];
        unsafe { hasher.finalize_into_raw(hash.as_mut_ptr()) };
        assert_eq!(hash, expected);
    }

    #[test]
    fn test_try_boxing() {
        let x = Box::new(42);
        let y = box_try_new(42).unwrap();
        assert_eq!(x, y);

        let x = vec![1; 3];
        let y = try_vec![1; 3].unwrap();
        assert_eq!(x, y);

        let x = vec![1, 2, 3];
        let y = try_vec![1, 2, 3].unwrap();
        assert_eq!(x, y);
    }

    #[test]
    #[cfg(feature = "keccak-cache")]
    fn test_keccak256_cache_edge_cases() {
        use keccak256_cached as keccak256;
        assert_eq!(keccak256([]), KECCAK256_EMPTY);
        assert_eq!(keccak256([]), KECCAK256_EMPTY);

        let max_cacheable = vec![0xAA; keccak_cache::MAX_INPUT_LEN];
        let hash1 = keccak256(&max_cacheable);
        let hash2 = keccak256_impl(&max_cacheable);
        assert_eq!(hash1, hash2);

        let over_max = vec![0xBB; keccak_cache::MAX_INPUT_LEN + 1];
        let hash1 = keccak256(&over_max);
        let hash2 = keccak256_impl(&over_max);
        assert_eq!(hash1, hash2);

        let long_input = vec![0xCC; 1000];
        let hash1 = keccak256(&long_input);
        let hash2 = keccak256_impl(&long_input);
        assert_eq!(hash1, hash2);

        let max = if cfg!(miri) { 10 } else { 255 };
        for byte in 0..=max {
            let data = &[byte];
            let hash1 = keccak256(data);
            let hash2 = keccak256_impl(data);
            assert_eq!(hash1, hash2);
        }
    }

    #[test]
    #[cfg(all(feature = "keccak-cache", feature = "rand"))]
    fn test_keccak256_cache_multithreaded() {
        use keccak256_cached as keccak256;
        use rand::{Rng, SeedableRng};
        use std::{sync::Arc, thread};

        // Test parameters (reduced for miri).
        let num_threads = if cfg!(miri) {
            2
        } else {
            thread::available_parallelism().map(|n| n.get()).unwrap_or(8)
        };
        let iterations_per_thread = if cfg!(miri) { 10 } else { 1000 };
        let num_test_vectors = if cfg!(miri) { 5 } else { 100 };
        let max_data_length = keccak_cache::MAX_INPUT_LEN;

        // Shared test vectors that will be hashed repeatedly to test cache hits.
        let test_vectors: Arc<Vec<Vec<u8>>> = Arc::new({
            let mut rng = rand::rngs::StdRng::seed_from_u64(42);
            (0..num_test_vectors)
                .map(|_| {
                    let len = rng.random_range(0..=max_data_length);
                    (0..len).map(|_| rng.random()).collect()
                })
                .collect()
        });

        let mut handles = vec![];

        for thread_id in 0..num_threads {
            let test_vectors = Arc::clone(&test_vectors);

            let handle = thread::spawn(move || {
                // Use thread-local RNG with deterministic seed for reproducibility.
                let mut rng = rand::rngs::StdRng::seed_from_u64(thread_id as u64);
                let max_data_length = keccak_cache::MAX_INPUT_LEN;

                for _ in 0..iterations_per_thread {
                    // 70% chance to use a shared test vector (tests cache hits).
                    if rng.random_range(0..10) < 7 && !test_vectors.is_empty() {
                        let idx = rng.random_range(0..test_vectors.len());
                        let data = &test_vectors[idx];

                        let cached_hash = keccak256(data);
                        let direct_hash = keccak256_impl(data);

                        assert_eq!(
                            cached_hash,
                            direct_hash,
                            "Thread {}: Cached hash mismatch for shared vector {} (len {})",
                            thread_id,
                            idx,
                            data.len()
                        );
                    } else {
                        // 30% chance to use random data (tests cache misses).
                        let len = rng.random_range(0..max_data_length + 20);
                        let data: Vec<u8> = (0..len).map(|_| rng.random()).collect();

                        let cached_hash = keccak256(&data);
                        let direct_hash = keccak256_impl(&data);

                        assert_eq!(
                            cached_hash, direct_hash,
                            "Thread {thread_id}: Cached hash mismatch for random data (len {len})"
                        );
                    }
                }
            });

            handles.push(handle);
        }

        // Wait for all threads to complete.
        for handle in handles {
            handle.join().expect("Thread panicked");
        }
    }
}