foundry_cheatcodes/

crypto.rs

//! Implementations of [`Crypto`](spec::Group::Crypto) Cheatcodes.

use crate::{Cheatcode, CheatcodesCore, Result, Vm::*};
use alloy_primitives::{Address, B256, U256, keccak256};
use alloy_signer::{Signer, SignerSync};
use alloy_signer_local::{
    MnemonicBuilder, PrivateKeySigner,
    coins_bip39::{
        ChineseSimplified, ChineseTraditional, Czech, English, French, Italian, Japanese, Korean,
        Portuguese, Spanish, Wordlist,
    },
};
use alloy_sol_types::SolValue;
use foundry_common::wallet::{derive_private_key, derive_private_key_with_language};
use k256::{
    AffinePoint, EncodedPoint, FieldBytes, FieldElement, ProjectivePoint, Scalar,
    ecdsa::{SigningKey, hazmat},
    elliptic_curve::{
        bigint::{ArrayEncoding, U256 as K256U256},
        group::Group,
        ops::Reduce,
        sec1::{FromEncodedPoint, ToEncodedPoint},
    },
};

use p256::ecdsa::{
    Signature as P256Signature, SigningKey as P256SigningKey, signature::hazmat::PrehashSigner,
};

use ed25519_consensus::{
    Signature as Ed25519Signature, SigningKey as Ed25519SigningKey,
    VerificationKey as Ed25519VerificationKey,
};
use tempo_primitives::transaction::{KeychainSignature, PrimitiveSignature, TempoSignature};

/// The BIP32 default derivation path prefix.
const DEFAULT_DERIVATION_PATH_PREFIX: &str = "m/44'/60'/0'/0/";
const PRIVATE_KEY_SIGNER_CACHE_LIMIT: usize = 64;

impl Cheatcode for createWallet_0Call {
    fn apply_context(&self, state: &mut CheatcodesCore) -> Result {
        let Self { walletLabel } = self;
        create_wallet(&keccak256(walletLabel).into(), Some(walletLabel), state)
    }
}

impl Cheatcode for createWallet_1Call {
    fn apply_context(&self, state: &mut CheatcodesCore) -> Result {
        let Self { privateKey } = self;
        create_wallet(privateKey, None, state)
    }
}

impl Cheatcode for createWallet_2Call {
    fn apply_context(&self, state: &mut CheatcodesCore) -> Result {
        let Self { privateKey, walletLabel } = self;
        create_wallet(privateKey, Some(walletLabel), state)
    }
}

impl Cheatcode for sign_0Call {
    fn apply_context_free(&self) -> Result {
        let Self { wallet, digest } = self;
        let sig = sign(&wallet.privateKey, digest)?;
        Ok(encode_full_sig(sig))
    }
}

impl Cheatcode for signWithNonceUnsafeCall {
    fn apply_context_free(&self) -> Result {
        let pk: U256 = self.privateKey;
        let digest: B256 = self.digest;
        let nonce: U256 = self.nonce;
        let sig: alloy_primitives::Signature = sign_with_nonce(&pk, &digest, &nonce)?;
        Ok(encode_full_sig(sig))
    }
}

impl Cheatcode for signKeychainCall {
    fn apply_context(&self, state: &mut CheatcodesCore) -> Result {
        let Self { privateKey, account, digest } = self;
        sign_keychain(state, privateKey, account, digest)
    }
}

impl Cheatcode for signKeychainAdminCall {
    fn apply_context(&self, state: &mut CheatcodesCore) -> Result {
        let Self { privateKey, account, digest } = self;
        sign_keychain(state, privateKey, account, digest)
    }
}

impl Cheatcode for signCompact_0Call {
    fn apply_context_free(&self) -> Result {
        let Self { wallet, digest } = self;
        let sig = sign(&wallet.privateKey, digest)?;
        Ok(encode_compact_sig(sig))
    }
}

impl Cheatcode for deriveKey_0Call {
    fn apply_context_free(&self) -> Result {
        let Self { mnemonic, index } = self;
        derive_key::<English>(mnemonic, DEFAULT_DERIVATION_PATH_PREFIX, *index)
    }
}

impl Cheatcode for deriveKey_1Call {
    fn apply_context_free(&self) -> Result {
        let Self { mnemonic, derivationPath, index } = self;
        derive_key::<English>(mnemonic, derivationPath, *index)
    }
}

impl Cheatcode for deriveKey_2Call {
    fn apply_context_free(&self) -> Result {
        let Self { mnemonic, index, language } = self;
        derive_key_str(mnemonic, DEFAULT_DERIVATION_PATH_PREFIX, *index, language)
    }
}

impl Cheatcode for deriveKey_3Call {
    fn apply_context_free(&self) -> Result {
        let Self { mnemonic, derivationPath, index, language } = self;
        derive_key_str(mnemonic, derivationPath, *index, language)
    }
}

impl Cheatcode for rememberKeyCall {
    fn apply_context(&self, state: &mut CheatcodesCore) -> Result {
        let Self { privateKey } = self;
        let wallet = with_private_key_signer(state, privateKey, |wallet| Ok(wallet.clone()))?;
        let address = inject_wallet(state, wallet);
        Ok(address.abi_encode())
    }
}

impl Cheatcode for rememberKeys_0Call {
    fn apply_context(&self, state: &mut CheatcodesCore) -> Result {
        let Self { mnemonic, derivationPath, count } = self;
        let wallets = derive_wallets::<English>(mnemonic, derivationPath, *count)?;
        let mut addresses = Vec::<Address>::with_capacity(wallets.len());
        for wallet in wallets {
            let addr = inject_wallet(state, wallet);
            addresses.push(addr);
        }

        Ok(addresses.abi_encode())
    }
}

impl Cheatcode for rememberKeys_1Call {
    fn apply_context(&self, state: &mut CheatcodesCore) -> Result {
        let Self { mnemonic, derivationPath, language, count } = self;
        let wallets = derive_wallets_str(mnemonic, derivationPath, language, *count)?;
        let mut addresses = Vec::<Address>::with_capacity(wallets.len());
        for wallet in wallets {
            let addr = inject_wallet(state, wallet);
            addresses.push(addr);
        }

        Ok(addresses.abi_encode())
    }
}

fn inject_wallet(state: &mut CheatcodesCore, wallet: PrivateKeySigner) -> Address {
    let address = wallet.address();
    state.wallets().add_local_signer(wallet);
    address
}

impl Cheatcode for sign_1Call {
    fn apply_context(&self, state: &mut CheatcodesCore) -> Result {
        let Self { privateKey, digest } = self;
        let sig = sign_cached(state, privateKey, digest)?;
        Ok(encode_full_sig(sig))
    }
}

impl Cheatcode for signCompact_1Call {
    fn apply_context(&self, state: &mut CheatcodesCore) -> Result {
        let Self { privateKey, digest } = self;
        let sig = sign_cached(state, privateKey, digest)?;
        Ok(encode_compact_sig(sig))
    }
}

impl Cheatcode for sign_2Call {
    fn apply_context(&self, state: &mut CheatcodesCore) -> Result {
        let Self { digest } = self;
        let sig = sign_with_wallet(state, None, digest)?;
        Ok(encode_full_sig(sig))
    }
}

impl Cheatcode for signCompact_2Call {
    fn apply_context(&self, state: &mut CheatcodesCore) -> Result {
        let Self { digest } = self;
        let sig = sign_with_wallet(state, None, digest)?;
        Ok(encode_compact_sig(sig))
    }
}

impl Cheatcode for sign_3Call {
    fn apply_context(&self, state: &mut CheatcodesCore) -> Result {
        let Self { signer, digest } = self;
        let sig = sign_with_wallet(state, Some(*signer), digest)?;
        Ok(encode_full_sig(sig))
    }
}

impl Cheatcode for signCompact_3Call {
    fn apply_context(&self, state: &mut CheatcodesCore) -> Result {
        let Self { signer, digest } = self;
        let sig = sign_with_wallet(state, Some(*signer), digest)?;
        Ok(encode_compact_sig(sig))
    }
}

impl Cheatcode for signP256Call {
    fn apply_context_free(&self) -> Result {
        let Self { privateKey, digest } = self;
        sign_p256(privateKey, digest)
    }
}

impl Cheatcode for publicKeyP256Call {
    fn apply_context_free(&self) -> Result {
        let Self { privateKey } = self;
        let pub_key =
            parse_private_key_p256(privateKey)?.verifying_key().as_affine().to_encoded_point(false);
        let pub_key_x = U256::from_be_bytes((*pub_key.x().unwrap()).into());
        let pub_key_y = U256::from_be_bytes((*pub_key.y().unwrap()).into());

        Ok((pub_key_x, pub_key_y).abi_encode())
    }
}

impl Cheatcode for ecAffineToProjectiveCall {
    fn apply_context_free(&self) -> Result {
        let Self { pointX, pointY } = self;
        let point = parse_affine_point(pointX, pointY, "point")?;
        encode_projective_point(ProjectivePoint::from(point))
    }
}

impl Cheatcode for ecProjectiveToAffineCall {
    fn apply_context_free(&self) -> Result {
        let Self { pointX, pointY, pointZ } = self;
        let point = parse_projective_point(pointX, pointY, pointZ, "point")?;
        encode_affine_point(point)
    }
}

impl Cheatcode for ecAddAffineCall {
    fn apply_context_free(&self) -> Result {
        let Self { pointX1, pointY1, pointX2, pointY2 } = self;
        let lhs = parse_affine_point(pointX1, pointY1, "first point")?;
        let rhs = parse_affine_point(pointX2, pointY2, "second point")?;
        encode_affine_point(ProjectivePoint::from(lhs) + rhs)
    }
}

impl Cheatcode for ecAddProjectiveCall {
    fn apply_context_free(&self) -> Result {
        let Self { pointX1, pointY1, pointZ1, pointX2, pointY2, pointZ2 } = self;
        let lhs = parse_projective_point(pointX1, pointY1, pointZ1, "first point")?;
        let rhs = parse_projective_point(pointX2, pointY2, pointZ2, "second point")?;
        encode_projective_point(lhs + rhs)
    }
}

impl Cheatcode for ecMulAffineCall {
    fn apply_context_free(&self) -> Result {
        let Self { pointX, pointY, scalar } = self;
        let point = parse_affine_point(pointX, pointY, "point")?;
        let scalar = reduce_ec_scalar(scalar);
        encode_affine_point(ProjectivePoint::from(point) * scalar)
    }
}

impl Cheatcode for ecMulProjectiveCall {
    fn apply_context_free(&self) -> Result {
        let Self { pointX, pointY, pointZ, scalar } = self;
        let point = parse_projective_point(pointX, pointY, pointZ, "point")?;
        let scalar = reduce_ec_scalar(scalar);
        encode_projective_point(point * scalar)
    }
}

impl Cheatcode for createEd25519KeyCall {
    fn apply_context_free(&self) -> Result {
        let Self { salt } = self;
        create_ed25519_key(salt)
    }
}

impl Cheatcode for publicKeyEd25519Call {
    fn apply_context_free(&self) -> Result {
        let Self { privateKey } = self;
        public_key_ed25519(privateKey)
    }
}

impl Cheatcode for signEd25519Call {
    fn apply_context_free(&self) -> Result {
        let Self { namespace, message, privateKey } = self;
        sign_ed25519(namespace, message, privateKey)
    }
}

impl Cheatcode for verifyEd25519Call {
    fn apply_context_free(&self) -> Result {
        let Self { signature, namespace, message, publicKey } = self;
        verify_ed25519(signature, namespace, message, publicKey)
    }
}

/// Using a given private key, return its public ETH address, its public key affine x and y
/// coordinates, and its private key (see the 'Wallet' struct)
///
/// If 'label' is set to 'Some()', assign that label to the associated ETH address in state
fn create_wallet(private_key: &U256, label: Option<&str>, state: &mut CheatcodesCore) -> Result {
    let (addr, pub_key_x, pub_key_y) = with_private_key_signer(state, private_key, |wallet| {
        let addr = wallet.address();
        let pub_key = wallet.credential().verifying_key().as_affine().to_encoded_point(false);
        let pub_key_x = U256::from_be_bytes((*pub_key.x().unwrap()).into());
        let pub_key_y = U256::from_be_bytes((*pub_key.y().unwrap()).into());
        Ok((addr, pub_key_x, pub_key_y))
    })?;

    if let Some(label) = label {
        state.labels.insert(addr, label.into());
    }

    Ok(Wallet { addr, publicKeyX: pub_key_x, publicKeyY: pub_key_y, privateKey: *private_key }
        .abi_encode())
}

fn encode_full_sig(sig: alloy_primitives::Signature) -> Vec<u8> {
    // Retrieve v, r and s from signature.
    let v = U256::from(sig.v_byte());
    let r = B256::from(sig.r());
    let s = B256::from(sig.s());
    (v, r, s).abi_encode()
}

fn encode_compact_sig(sig: alloy_primitives::Signature) -> Vec<u8> {
    // Implement EIP-2098 compact signature.
    let r = B256::from(sig.r());
    let mut vs = sig.s();
    vs.set_bit(255, sig.v());
    (r, vs).abi_encode()
}

fn sign(private_key: &U256, digest: &B256) -> Result<alloy_primitives::Signature> {
    // The `ecrecover` precompile does not use EIP-155. No chain ID is needed.
    let wallet = parse_wallet(private_key)?;
    let sig = wallet.sign_hash_sync(digest)?;
    debug_assert_eq!(sig.recover_address_from_prehash(digest)?, wallet.address());
    Ok(sig)
}

fn sign_cached(
    state: &mut CheatcodesCore,
    private_key: &U256,
    digest: &B256,
) -> Result<alloy_primitives::Signature> {
    with_private_key_signer(state, private_key, |wallet| {
        let sig = wallet.sign_hash_sync(digest)?;
        debug_assert_eq!(sig.recover_address_from_prehash(digest)?, wallet.address());
        Ok(sig)
    })
}

fn sign_keychain(
    state: &mut CheatcodesCore,
    private_key: &U256,
    account: &Address,
    digest: &B256,
) -> Result {
    let signing_hash = KeychainSignature::signing_hash(*digest, *account);
    let inner = sign_cached(state, private_key, &signing_hash)?;
    let signature = TempoSignature::Keychain(KeychainSignature::new(
        *account,
        PrimitiveSignature::Secp256k1(inner),
    ));
    Ok(signature.to_bytes().abi_encode())
}

/// Signs `digest` on secp256k1 using a user-supplied ephemeral nonce `k` (no RFC6979).
/// - `private_key` and `nonce` must be in (0, n)
/// - `digest` is a 32-byte prehash.
///
/// # Warning
///
/// Use [`sign_with_nonce`] with extreme caution!
/// Reusing the same nonce (`k`) with the same private key in ECDSA will leak the private key.
/// Always generate `nonce` with a cryptographically secure RNG, and never reuse it across
/// signatures.
fn sign_with_nonce(
    private_key: &U256,
    digest: &B256,
    nonce: &U256,
) -> Result<alloy_primitives::Signature> {
    let d_scalar: Scalar =
        <Scalar as k256::elliptic_curve::PrimeField>::from_repr(private_key.to_be_bytes().into())
            .into_option()
            .ok_or_else(|| fmt_err!("invalid private key scalar"))?;
    if bool::from(d_scalar.is_zero()) {
        return Err(fmt_err!("private key cannot be 0"));
    }

    let k_scalar: Scalar =
        <Scalar as k256::elliptic_curve::PrimeField>::from_repr(nonce.to_be_bytes().into())
            .into_option()
            .ok_or_else(|| fmt_err!("invalid nonce scalar"))?;
    if bool::from(k_scalar.is_zero()) {
        return Err(fmt_err!("nonce cannot be 0"));
    }

    let mut z = [0u8; 32];
    z.copy_from_slice(digest.as_slice());
    let z_fb: FieldBytes = FieldBytes::from(z);

    // Hazmat signing using the scalar `d` (SignPrimitive is implemented for `Scalar`)
    // Note: returns (Signature, Option<RecoveryId>)
    let (sig_raw, recid_opt) =
        <Scalar as hazmat::SignPrimitive<k256::Secp256k1>>::try_sign_prehashed(
            &d_scalar, k_scalar, &z_fb,
        )
        .map_err(|e| fmt_err!("sign_prehashed failed: {e}"))?;

    // Enforce low-s; if mirrored, parity flips (we’ll account for it below if we use recid)
    let (sig_low, flipped) =
        if let Some(norm) = sig_raw.normalize_s() { (norm, true) } else { (sig_raw, false) };

    let r_u256 = U256::from_be_bytes(sig_low.r().to_bytes().into());
    let s_u256 = U256::from_be_bytes(sig_low.s().to_bytes().into());

    // Determine v parity in {0,1}
    let v_parity = if let Some(id) = recid_opt {
        let mut v = id.to_byte() & 1;
        if flipped {
            v ^= 1;
        }
        v
    } else {
        // Fallback: choose parity by recovery to expected address
        let expected_addr = {
            let sk: SigningKey = parse_private_key(private_key)?;
            alloy_signer::utils::secret_key_to_address(&sk)
        };
        // Try v = 0
        let cand0 = alloy_primitives::Signature::new(r_u256, s_u256, false);
        if cand0.recover_address_from_prehash(digest).ok() == Some(expected_addr) {
            return Ok(cand0);
        }
        // Try v = 1
        let cand1 = alloy_primitives::Signature::new(r_u256, s_u256, true);
        if cand1.recover_address_from_prehash(digest).ok() == Some(expected_addr) {
            return Ok(cand1);
        }
        return Err(fmt_err!("failed to determine recovery id for signature"));
    };

    let y_parity = v_parity != 0;
    Ok(alloy_primitives::Signature::new(r_u256, s_u256, y_parity))
}

fn sign_with_wallet(
    state: &mut CheatcodesCore,
    signer: Option<Address>,
    digest: &B256,
) -> Result<alloy_primitives::Signature> {
    let mut wallets = state.wallets().inner.lock();
    let maybe_provided_sender = wallets.provided_sender;
    let signers = wallets.multi_wallet.signers()?;
    if signers.is_empty() {
        bail!("no wallets available");
    }

    let signer = if let Some(signer) = signer {
        signer
    } else if let Some(provided_sender) = maybe_provided_sender {
        provided_sender
    } else if signers.len() == 1 {
        *signers.keys().next().unwrap()
    } else {
        bail!(
            "could not determine signer, there are multiple signers available use vm.sign(signer, digest) to specify one"
        );
    };

    let wallet = signers
        .get(&signer)
        .ok_or_else(|| fmt_err!("signer with address {signer} is not available"))?;

    let sig = foundry_common::block_on(wallet.sign_hash(digest))?;
    debug_assert_eq!(sig.recover_address_from_prehash(digest)?, signer);
    Ok(sig)
}

fn sign_p256(private_key: &U256, digest: &B256) -> Result {
    let signing_key = parse_private_key_p256(private_key)?;
    let signature: P256Signature = signing_key.sign_prehash(digest.as_slice())?;
    let signature = signature.normalize_s().unwrap_or(signature);
    let r_bytes: [u8; 32] = signature.r().to_bytes().into();
    let s_bytes: [u8; 32] = signature.s().to_bytes().into();

    Ok((r_bytes, s_bytes).abi_encode())
}

fn parse_affine_point(x: &U256, y: &U256, name: &str) -> Result<AffinePoint> {
    if x.is_zero() && y.is_zero() {
        return Ok(AffinePoint::IDENTITY);
    }

    let encoded = EncodedPoint::from_affine_coordinates(
        &FieldBytes::from(x.to_be_bytes()),
        &FieldBytes::from(y.to_be_bytes()),
        false,
    );
    AffinePoint::from_encoded_point(&encoded)
        .into_option()
        .ok_or_else(|| fmt_err!("invalid secp256k1 {name}"))
}

fn parse_projective_point(x: &U256, y: &U256, z: &U256, name: &str) -> Result<ProjectivePoint> {
    let x_field = parse_field_element(x, name)?;
    let y_field = parse_field_element(y, name)?;
    let z_field = parse_field_element(z, name)?;

    if bool::from(z_field.is_zero()) {
        ensure!(
            bool::from(x_field.is_zero()) && !bool::from(y_field.is_zero()),
            "invalid secp256k1 {name}"
        );
        return Ok(ProjectivePoint::IDENTITY);
    }

    let z_inv = z_field.invert().expect("non-zero field element is invertible");
    let affine_x = U256::from_be_slice(&(x_field * z_inv).to_bytes());
    let affine_y = U256::from_be_slice(&(y_field * z_inv).to_bytes());

    Ok(ProjectivePoint::from(parse_affine_point(&affine_x, &affine_y, name)?))
}

fn parse_field_element(value: &U256, name: &str) -> Result<FieldElement> {
    FieldElement::from_bytes(&FieldBytes::from(value.to_be_bytes()))
        .into_option()
        .ok_or_else(|| fmt_err!("invalid secp256k1 {name}"))
}

fn reduce_ec_scalar(scalar: &U256) -> Scalar {
    <Scalar as Reduce<K256U256>>::reduce_bytes(&scalar.to_be_bytes().into())
}

fn encode_affine_point(point: ProjectivePoint) -> Result {
    if bool::from(point.is_identity()) {
        return Ok((U256::ZERO, U256::ZERO).abi_encode());
    }

    let encoded = point.to_affine().to_encoded_point(false);
    let x = U256::from_be_slice(encoded.x().expect("non-identity point has x coordinate"));
    let y = U256::from_be_slice(encoded.y().expect("non-identity point has y coordinate"));

    Ok((x, y).abi_encode())
}

fn encode_projective_point(point: ProjectivePoint) -> Result {
    if bool::from(point.is_identity()) {
        return Ok((U256::ZERO, U256::ONE, U256::ZERO).abi_encode());
    }

    let encoded = point.to_affine().to_encoded_point(false);
    let x = U256::from_be_slice(encoded.x().expect("non-identity point has x coordinate"));
    let y = U256::from_be_slice(encoded.y().expect("non-identity point has y coordinate"));

    Ok((x, y, U256::ONE).abi_encode())
}

fn validate_private_key<C: ecdsa::PrimeCurve>(private_key: &U256) -> Result<()> {
    ensure!(!private_key.is_zero(), "private key cannot be 0");
    let order = U256::from_be_slice(&C::ORDER.to_be_byte_array());
    ensure!(
        *private_key < order,
        "private key must be less than the {curve:?} curve order ({order})",
        curve = C::default(),
    );

    Ok(())
}

fn parse_private_key(private_key: &U256) -> Result<SigningKey> {
    validate_private_key::<k256::Secp256k1>(private_key)?;
    Ok(SigningKey::from_bytes((&private_key.to_be_bytes()).into())?)
}

fn parse_private_key_p256(private_key: &U256) -> Result<P256SigningKey> {
    validate_private_key::<p256::NistP256>(private_key)?;
    Ok(P256SigningKey::from_bytes((&private_key.to_be_bytes()).into())?)
}

fn parse_signing_key_ed25519(private_key: &B256) -> Result<Ed25519SigningKey> {
    Ed25519SigningKey::try_from(private_key.as_slice())
        .map_err(|e| fmt_err!("invalid Ed25519 private key: {e}"))
}

fn create_ed25519_key(salt: &B256) -> Result {
    let signing_key = parse_signing_key_ed25519(salt)?;
    let public_key = B256::from_slice(signing_key.verification_key().as_ref());
    Ok((public_key, *salt).abi_encode())
}

fn public_key_ed25519(private_key: &B256) -> Result {
    let signing_key = parse_signing_key_ed25519(private_key)?;
    Ok(B256::from_slice(signing_key.verification_key().as_ref()).abi_encode())
}

fn sign_ed25519(namespace: &[u8], message: &[u8], private_key: &B256) -> Result {
    let signing_key = parse_signing_key_ed25519(private_key)?;
    let combined = [namespace, message].concat();
    let signature: [u8; 64] = signing_key.sign(&combined).into();
    Ok(signature.to_vec().abi_encode())
}

fn verify_ed25519(signature: &[u8], namespace: &[u8], message: &[u8], public_key: &B256) -> Result {
    if signature.len() != 64 {
        return Ok(false.abi_encode());
    }

    let Ok(verification_key) = Ed25519VerificationKey::try_from(public_key.as_slice()) else {
        return Ok(false.abi_encode());
    };

    let Ok(sig_bytes): Result<[u8; 64], _> = signature.try_into() else {
        return Ok(false.abi_encode());
    };

    let combined = [namespace, message].concat();
    let valid = verification_key.verify(&Ed25519Signature::from(sig_bytes), &combined).is_ok();
    Ok(valid.abi_encode())
}

pub(super) fn parse_wallet(private_key: &U256) -> Result<PrivateKeySigner> {
    parse_private_key(private_key).map(PrivateKeySigner::from)
}

pub(super) fn with_private_key_signer<R>(
    state: &mut CheatcodesCore,
    private_key: &U256,
    f: impl FnOnce(&PrivateKeySigner) -> Result<R>,
) -> Result<R> {
    if !state.private_key_signers.contains_key(private_key)
        && state.private_key_signers.len() < PRIVATE_KEY_SIGNER_CACHE_LIMIT
    {
        let wallet = parse_wallet(private_key)?;
        state.private_key_signers.insert(*private_key, wallet);
    }

    if let Some(wallet) = state.private_key_signers.get(private_key) {
        f(wallet)
    } else {
        let wallet = parse_wallet(private_key)?;
        f(&wallet)
    }
}

fn derive_key_str(mnemonic: &str, path: &str, index: u32, language: &str) -> Result {
    let private_key = derive_private_key_with_language(mnemonic, path, index, language)
        .map_err(|e| fmt_err!("{e}"))?;
    Ok(private_key.abi_encode())
}

fn derive_key<W: Wordlist>(mnemonic: &str, path: &str, index: u32) -> Result {
    let private_key =
        derive_private_key::<W>(mnemonic, path, index).map_err(|e| fmt_err!("{e}"))?;
    Ok(private_key.abi_encode())
}

fn derive_wallets_str(
    mnemonic: &str,
    path: &str,
    language: &str,
    count: u32,
) -> Result<Vec<PrivateKeySigner>> {
    match language {
        "chinese_simplified" => derive_wallets::<ChineseSimplified>(mnemonic, path, count),
        "chinese_traditional" => derive_wallets::<ChineseTraditional>(mnemonic, path, count),
        "czech" => derive_wallets::<Czech>(mnemonic, path, count),
        "english" => derive_wallets::<English>(mnemonic, path, count),
        "french" => derive_wallets::<French>(mnemonic, path, count),
        "italian" => derive_wallets::<Italian>(mnemonic, path, count),
        "japanese" => derive_wallets::<Japanese>(mnemonic, path, count),
        "korean" => derive_wallets::<Korean>(mnemonic, path, count),
        "portuguese" => derive_wallets::<Portuguese>(mnemonic, path, count),
        "spanish" => derive_wallets::<Spanish>(mnemonic, path, count),
        _ => Err(fmt_err!("unsupported mnemonic language: {language:?}")),
    }
}

fn derive_wallets<W: Wordlist>(
    mnemonic: &str,
    path: &str,
    count: u32,
) -> Result<Vec<PrivateKeySigner>> {
    foundry_common::wallet::validate_bip32_path(path).map_err(|e| fmt_err!("{e}"))?;

    let mut wallets = Vec::with_capacity(count as usize);
    for idx in 0..count {
        let full_path = foundry_common::wallet::derive_key_path_checked(path, idx)
            .map_err(|e| fmt_err!("{e}"))?;
        let wallet =
            MnemonicBuilder::<W>::default().phrase(mnemonic).derivation_path(full_path)?.build()?;
        wallets.push(wallet);
    }

    Ok(wallets)
}

#[cfg(test)]
mod tests {
    use super::*;
    use alloy_primitives::{FixedBytes, LogData, hex::FromHex};
    use alloy_sol_types::SolCall;
    use k256::elliptic_curve::Curve;
    use p256::ecdsa::signature::hazmat::PrehashVerifier;
    use revm::{
        context::journaled_state::JournalCheckpoint,
        state::{AccountInfo, Bytecode},
    };
    use tempo_contracts::precompiles::{IAccountKeychain, ISignatureVerifier};
    use tempo_hardfork::TempoHardfork;
    use tempo_precompiles::{
        Precompile,
        account_keychain::{AccountKeychain, KeyRestrictions, SignatureType},
        error::Result as PrecompileResult,
        signature_verifier::SignatureVerifier,
        storage::{PrecompileStorageProvider, StorageCtx, hashmap::HashMapStorageProvider},
    };
    use tempo_primitives::TempoBlockEnv;

    /// A [`HashMapStorageProvider`] with a settable block timestamp.
    struct TimestampedStorage {
        inner: HashMapStorageProvider,
        block_env: TempoBlockEnv,
    }

    impl TimestampedStorage {
        fn new(chain_id: u64, spec: TempoHardfork, timestamp: u64) -> Self {
            let mut block_env = TempoBlockEnv::default();
            block_env.inner.timestamp = U256::from(timestamp);
            Self { inner: HashMapStorageProvider::new_with_spec(chain_id, spec), block_env }
        }

        fn set_timestamp(&mut self, timestamp: u64) {
            self.block_env.inner.timestamp = U256::from(timestamp);
        }
    }

    impl PrecompileStorageProvider for TimestampedStorage {
        fn chain_id(&self) -> u64 {
            self.inner.chain_id()
        }

        fn block_env(&self) -> &TempoBlockEnv {
            &self.block_env
        }

        fn set_code(&mut self, address: Address, code: Bytecode) -> PrecompileResult<()> {
            self.inner.set_code(address, code)
        }

        fn with_account_info(
            &mut self,
            address: Address,
            f: &mut dyn FnMut(&AccountInfo),
        ) -> PrecompileResult<()> {
            self.inner.with_account_info(address, f)
        }

        fn account_code(&mut self, address: Address) -> PrecompileResult<(B256, Bytecode)> {
            self.inner.account_code(address)
        }

        fn sload(&mut self, address: Address, key: U256) -> PrecompileResult<U256> {
            self.inner.sload(address, key)
        }

        fn tload(&mut self, address: Address, key: U256) -> PrecompileResult<U256> {
            self.inner.tload(address, key)
        }

        fn sstore(&mut self, address: Address, key: U256, value: U256) -> PrecompileResult<()> {
            self.inner.sstore(address, key, value)
        }

        fn tstore(&mut self, address: Address, key: U256, value: U256) -> PrecompileResult<()> {
            self.inner.tstore(address, key, value)
        }

        fn emit_event(&mut self, address: Address, event: LogData) -> PrecompileResult<()> {
            self.inner.emit_event(address, event)
        }

        fn deduct_gas(&mut self, gas: u64) -> PrecompileResult<()> {
            self.inner.deduct_gas(gas)
        }

        fn refund_gas(&mut self, gas: i64) {
            self.inner.refund_gas(gas)
        }

        fn gas_limit(&self) -> u64 {
            self.inner.gas_limit()
        }

        fn gas_used(&self) -> u64 {
            self.inner.gas_used()
        }

        fn state_gas_used(&self) -> u64 {
            self.inner.state_gas_used()
        }

        fn state_gas_spilled(&self) -> u64 {
            self.inner.state_gas_spilled()
        }

        fn gas_refunded(&self) -> i64 {
            self.inner.gas_refunded()
        }

        fn reservoir(&self) -> u64 {
            self.inner.reservoir()
        }

        fn spec(&self) -> TempoHardfork {
            self.inner.spec()
        }

        fn amsterdam_eip8037_enabled(&self) -> bool {
            self.inner.amsterdam_eip8037_enabled()
        }

        fn is_static(&self) -> bool {
            self.inner.is_static()
        }

        fn checkpoint(&mut self) -> JournalCheckpoint {
            self.inner.checkpoint()
        }

        fn checkpoint_commit(&mut self, checkpoint: JournalCheckpoint) {
            self.inner.checkpoint_commit(checkpoint)
        }

        fn checkpoint_revert(&mut self, checkpoint: JournalCheckpoint) {
            self.inner.checkpoint_revert(checkpoint)
        }

        fn set_tip1060_storage_credits(&mut self, enabled: bool) {
            self.inner.set_tip1060_storage_credits(enabled)
        }
    }

    #[test]
    fn test_sign_p256() {
        use p256::ecdsa::VerifyingKey;

        let pk_u256: U256 = "1".parse().unwrap();
        let signing_key = P256SigningKey::from_bytes(&pk_u256.to_be_bytes().into()).unwrap();
        let digest = FixedBytes::from_hex(
            "0x44acf6b7e36c1342c2c5897204fe09504e1e2efb1a900377dbc4e7a6a133ec56",
        )
        .unwrap();

        let result = sign_p256(&pk_u256, &digest).unwrap();
        let result_bytes: [u8; 64] = result.try_into().unwrap();
        let signature = P256Signature::from_bytes(&result_bytes.into()).unwrap();
        let verifying_key = VerifyingKey::from(&signing_key);
        assert!(verifying_key.verify_prehash(digest.as_slice(), &signature).is_ok());
    }

    #[test]
    fn test_sign_p256_pk_too_large() {
        // max n from https://neuromancer.sk/std/secg/secp256r1
        let pk =
            "0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551".parse().unwrap();
        let digest = FixedBytes::from_hex(
            "0x54705ba3baafdbdfba8c5f9a70f7a89bee98d906b53e31074da7baecdc0da9ad",
        )
        .unwrap();
        let result = sign_p256(&pk, &digest);
        assert_eq!(
            result.err().unwrap().to_string(),
            "private key must be less than the NistP256 curve order (115792089210356248762697446949407573529996955224135760342422259061068512044369)"
        );
    }

    #[test]
    fn test_sign_p256_pk_0() {
        let digest = FixedBytes::from_hex(
            "0x54705ba3baafdbdfba8c5f9a70f7a89bee98d906b53e31074da7baecdc0da9ad",
        )
        .unwrap();
        let result = sign_p256(&U256::ZERO, &digest);
        assert_eq!(result.err().unwrap().to_string(), "private key cannot be 0");
    }

    #[test]
    fn test_sign_with_nonce_varies_and_recovers() {
        // Given a fixed private key and digest
        let pk_u256: U256 = U256::ONE;
        let digest = FixedBytes::from_hex(
            "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        )
        .unwrap();

        // Two distinct nonces
        let n1: U256 = U256::from(123u64);
        let n2: U256 = U256::from(456u64);

        // Sign with both nonces
        let sig1 = sign_with_nonce(&pk_u256, &digest, &n1).expect("sig1");
        let sig2 = sign_with_nonce(&pk_u256, &digest, &n2).expect("sig2");

        // (r,s) must differ when nonce differs
        assert!(
            sig1.r() != sig2.r() || sig1.s() != sig2.s(),
            "signatures should differ with different nonces"
        );

        // ecrecover must yield the address for both signatures
        let sk = parse_private_key(&pk_u256).unwrap();
        let expected = alloy_signer::utils::secret_key_to_address(&sk);

        assert_eq!(sig1.recover_address_from_prehash(&digest).unwrap(), expected);
        assert_eq!(sig2.recover_address_from_prehash(&digest).unwrap(), expected);
    }

    #[test]
    fn test_sign_with_nonce_zero_nonce_errors() {
        // nonce = 0 should be rejected
        let pk_u256: U256 = U256::ONE;
        let digest = FixedBytes::from_hex(
            "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
        )
        .unwrap();
        let n0: U256 = U256::ZERO;

        let err = sign_with_nonce(&pk_u256, &digest, &n0).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("nonce cannot be 0"), "unexpected error: {msg}");
    }

    #[test]
    fn test_sign_with_nonce_nonce_ge_order_errors() {
        // nonce >= n should be rejected
        use k256::Secp256k1;
        // Curve order n as U256
        let n_u256 = U256::from_be_slice(&Secp256k1::ORDER.to_be_byte_array());

        let pk_u256: U256 = U256::ONE;
        let digest = FixedBytes::from_hex(
            "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
        )
        .unwrap();

        // Try exactly n (>= n invalid)
        let err = sign_with_nonce(&pk_u256, &digest, &n_u256).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("invalid nonce scalar"), "unexpected error: {msg}");
    }

    #[test]
    fn test_sign_keychain_encodes_v2_signature_for_account() {
        let private_key = U256::from(0xB0Bu64);
        let account = Address::repeat_byte(0x11);
        let digest = B256::repeat_byte(0x22);
        let mut state = CheatcodesCore::default();

        let result = sign_keychain(&mut state, &private_key, &account, &digest).unwrap();
        let signature = Vec::<u8>::abi_decode(&result).unwrap();

        assert_eq!(signature.len(), 86);
        assert_eq!(signature[0], 0x04);
        assert_eq!(Address::from_slice(&signature[1..21]), account);

        let parsed = TempoSignature::from_bytes(&signature).unwrap();
        assert!(parsed.is_v2_keychain());

        let keychain = parsed.as_keychain().unwrap();
        let expected_key = parse_wallet(&private_key).unwrap().address();
        assert_eq!(keychain.user_address, account);
        assert_eq!(keychain.key_id(&digest).unwrap(), expected_key);
    }

    #[test]
    fn private_key_signers_are_cached_for_repeated_lookup() {
        let private_key = U256::from(0xB0Bu64);
        let mut state = CheatcodesCore::default();

        let first =
            with_private_key_signer(&mut state, &private_key, |wallet| Ok(wallet.address()))
                .unwrap();
        assert_eq!(state.private_key_signers.len(), 1);

        let second =
            with_private_key_signer(&mut state, &private_key, |wallet| Ok(wallet.address()))
                .unwrap();
        assert_eq!(state.private_key_signers.len(), 1);
        assert_eq!(first, second);
    }

    #[test]
    fn test_sign_keychain_matches_t6_signature_verifier_state() {
        let root_pk = U256::from(0xA11CEu64);
        let access_pk = U256::from(0xB0Bu64);
        let admin_pk = U256::from(0xC0FFEEu64);
        let revoked_pk = U256::from(0xBADu64);
        let expired_pk = U256::from(0xE441u64);
        let unknown_pk = U256::from(0xFACEu64);

        let root = parse_wallet(&root_pk).unwrap().address();
        let access_key = parse_wallet(&access_pk).unwrap().address();
        let admin_key = parse_wallet(&admin_pk).unwrap().address();
        let revoked_key = parse_wallet(&revoked_pk).unwrap().address();
        let expired_key = parse_wallet(&expired_pk).unwrap().address();

        let hash = B256::repeat_byte(0x44);
        let admin_hash = B256::repeat_byte(0x66);

        let mut storage = TimestampedStorage::new(1, TempoHardfork::T6, 1_000);
        StorageCtx::enter(&mut storage, || {
            let mut keychain = AccountKeychain::new();
            keychain.initialize()?;
            keychain.set_tx_origin(root)?;

            authorize_t6_access_key(&mut keychain, root, access_key, u64::MAX)?;
            authorize_t6_access_key(&mut keychain, root, revoked_key, u64::MAX)?;
            authorize_t6_access_key(&mut keychain, root, expired_key, 1_005)?;
            keychain.authorize_admin_key(root, admin_key, SignatureType::Secp256k1, None)?;
            keychain.revoke_key(root, IAccountKeychain::revokeKeyCall { keyId: revoked_key })?;

            assert!(verify_keychain(root, hash, keychain_signature(&access_pk, root, hash)));
            assert!(!verify_keychain(root, hash, keychain_signature(&revoked_pk, root, hash)));
            assert!(!verify_keychain(root, hash, keychain_signature(&unknown_pk, root, hash)));
            assert!(!verify_keychain(
                Address::repeat_byte(0x99),
                hash,
                keychain_signature(&access_pk, root, hash)
            ));
            assert!(verify_keychain_admin(
                root,
                admin_hash,
                keychain_signature(&admin_pk, root, admin_hash)
            ));
            assert!(verify_keychain_admin(
                root,
                admin_hash,
                keychain_signature(&root_pk, root, admin_hash)
            ));
            assert!(!verify_keychain_admin(
                root,
                admin_hash,
                keychain_signature(&access_pk, root, admin_hash)
            ));
            assert!(!verify_keychain_admin(
                Address::repeat_byte(0x88),
                admin_hash,
                keychain_signature(&admin_pk, root, admin_hash)
            ));
            assert_keychain_signature_reverts(root, hash, vec![0x04]);

            Ok::<_, eyre::Report>(())
        })
        .unwrap();

        storage.set_timestamp(1_006);
        StorageCtx::enter(&mut storage, || {
            assert!(!verify_keychain(root, hash, keychain_signature(&expired_pk, root, hash)));
            Ok::<_, eyre::Report>(())
        })
        .unwrap();
    }

    fn authorize_t6_access_key(
        keychain: &mut AccountKeychain,
        account: Address,
        key_id: Address,
        expiry: u64,
    ) -> eyre::Result<()> {
        keychain.authorize_key(
            account,
            key_id,
            SignatureType::Secp256k1,
            KeyRestrictions {
                expiry,
                enforceLimits: false,
                limits: vec![],
                allowAnyCalls: true,
                allowedCalls: vec![],
            },
            None,
        )?;
        Ok(())
    }

    fn keychain_signature(private_key: &U256, account: Address, hash: B256) -> Vec<u8> {
        let mut state = CheatcodesCore::default();
        Vec::<u8>::abi_decode(&sign_keychain(&mut state, private_key, &account, &hash).unwrap())
            .unwrap()
    }

    fn verify_keychain(account: Address, hash: B256, signature: Vec<u8>) -> bool {
        let calldata =
            ISignatureVerifier::verifyKeychainCall { account, hash, signature: signature.into() }
                .abi_encode();

        let output = SignatureVerifier::new().call(&calldata, Address::ZERO).unwrap();
        assert!(!output.is_revert(), "verifyKeychain reverted: {:?}", output.bytes);
        ISignatureVerifier::verifyKeychainCall::abi_decode_returns(&output.bytes).unwrap()
    }

    fn verify_keychain_admin(account: Address, hash: B256, signature: Vec<u8>) -> bool {
        let calldata = ISignatureVerifier::verifyKeychainAdminCall {
            account,
            hash,
            signature: signature.into(),
        }
        .abi_encode();

        let output = SignatureVerifier::new().call(&calldata, Address::ZERO).unwrap();
        assert!(!output.is_revert(), "verifyKeychainAdmin reverted: {:?}", output.bytes);
        ISignatureVerifier::verifyKeychainAdminCall::abi_decode_returns(&output.bytes).unwrap()
    }

    fn assert_keychain_signature_reverts(account: Address, hash: B256, signature: Vec<u8>) {
        let calldata =
            ISignatureVerifier::verifyKeychainCall { account, hash, signature: signature.into() }
                .abi_encode();

        let output = SignatureVerifier::new().call(&calldata, Address::ZERO).unwrap();
        assert!(output.is_revert(), "malformed keychain signature should revert");
    }

    #[test]
    fn test_create_ed25519_key_determinism() {
        let salt = B256::repeat_byte(1u8);
        let result1 = create_ed25519_key(&salt).unwrap();
        let result2 = create_ed25519_key(&salt).unwrap();
        assert_eq!(result1, result2, "same salt should produce same keys");
    }

    #[test]
    fn test_create_ed25519_key_different_salts() {
        let salt1 = B256::repeat_byte(1u8);
        let salt2 = B256::repeat_byte(2u8);
        let result1 = create_ed25519_key(&salt1).unwrap();
        let result2 = create_ed25519_key(&salt2).unwrap();
        assert_ne!(result1, result2, "different salts should produce different keys");
    }

    #[test]
    fn test_public_key_ed25519_consistency() {
        let salt = B256::repeat_byte(42u8);
        let create_result = create_ed25519_key(&salt).unwrap();
        let (expected_public, private): (B256, B256) =
            <(B256, B256)>::abi_decode(&create_result).unwrap();

        let derived_public_result = public_key_ed25519(&private).unwrap();
        let derived_public = B256::abi_decode(&derived_public_result).unwrap();

        assert_eq!(expected_public, derived_public, "derived public key should match");
    }

    #[test]
    fn test_sign_and_verify_ed25519_valid() {
        let salt = B256::repeat_byte(123u8);
        let create_result = create_ed25519_key(&salt).unwrap();
        let (public_key, private_key): (B256, B256) =
            <(B256, B256)>::abi_decode(&create_result).unwrap();

        let namespace = b"test.namespace";
        let message = b"hello world";
        let sig_result = sign_ed25519(namespace, message, &private_key).unwrap();
        let sig_bytes: Vec<u8> = Vec::abi_decode(&sig_result).unwrap();

        let verify_result = verify_ed25519(&sig_bytes, namespace, message, &public_key).unwrap();
        let valid = bool::abi_decode(&verify_result).unwrap();

        assert!(valid, "signature should be valid");
    }

    #[test]
    fn test_verify_ed25519_invalid_signature() {
        let salt = B256::repeat_byte(123u8);
        let create_result = create_ed25519_key(&salt).unwrap();
        let (public_key, _): (B256, B256) = <(B256, B256)>::abi_decode(&create_result).unwrap();

        let invalid_sig = [0u8; 64];
        let namespace = b"test.namespace";
        let message = b"hello world";

        let verify_result = verify_ed25519(&invalid_sig, namespace, message, &public_key).unwrap();
        let valid = bool::abi_decode(&verify_result).unwrap();

        assert!(!valid, "invalid signature should not verify");
    }

    #[test]
    fn test_verify_ed25519_namespace_separation() {
        let salt = B256::repeat_byte(123u8);
        let create_result = create_ed25519_key(&salt).unwrap();
        let (public_key, private_key): (B256, B256) =
            <(B256, B256)>::abi_decode(&create_result).unwrap();

        let namespace_a = b"namespace.a";
        let message = b"message";
        let sig_result = sign_ed25519(namespace_a, message, &private_key).unwrap();
        let sig_bytes: Vec<u8> = Vec::abi_decode(&sig_result).unwrap();

        let namespace_b = b"namespace.b";
        let verify_result = verify_ed25519(&sig_bytes, namespace_b, message, &public_key).unwrap();
        let valid = bool::abi_decode(&verify_result).unwrap();
        assert!(!valid, "signature with namespace A should not verify with namespace B");

        let verify_result = verify_ed25519(&sig_bytes, namespace_a, message, &public_key).unwrap();
        let valid = bool::abi_decode(&verify_result).unwrap();
        assert!(valid, "signature should verify with correct namespace");
    }

    #[test]
    fn test_verify_ed25519_invalid_signature_length() {
        let salt = B256::repeat_byte(123u8);
        let create_result = create_ed25519_key(&salt).unwrap();
        let (public_key, _): (B256, B256) = <(B256, B256)>::abi_decode(&create_result).unwrap();

        let invalid_sig = [0u8; 32];
        let namespace = b"test";
        let message = b"message";

        let verify_result = verify_ed25519(&invalid_sig, namespace, message, &public_key).unwrap();
        let valid = bool::abi_decode(&verify_result).unwrap();
        assert!(!valid, "signature with wrong length should not verify");
    }

    const MNEMONIC: &str = "test test test test test test test test test test test junk";

    #[test]
    fn derive_key_rejects_harden_bit_overflow() {
        let err = derive_key::<English>(MNEMONIC, "m/44'/60'/0'/0/2147483648'", 0)
            .unwrap_err()
            .to_string();
        assert!(err.contains("harden bit"), "{err}");

        let err = derive_key::<English>(MNEMONIC, "m/44'/60'/0'/0/2147483648h", 0)
            .unwrap_err()
            .to_string();
        assert!(err.contains("harden bit"), "{err}");

        let err =
            derive_key::<English>(MNEMONIC, "m/44'/60'/0'/0", foundry_common::wallet::BIP32_HARDEN)
                .unwrap_err()
                .to_string();
        assert!(err.contains("harden bit"), "{err}");

        assert!(derive_key::<English>(MNEMONIC, "m/44'/60'/0'/0", 0).is_ok());
        assert!(
            derive_key::<English>(
                MNEMONIC,
                &format!("m/44'/60'/0'/0/{}", foundry_common::wallet::BIP32_HARDEN - 1),
                0
            )
            .is_ok()
        );
    }

    #[test]
    fn remember_keys_rejects_harden_bit_overflow() {
        let err = derive_wallets::<English>(MNEMONIC, "m/44'/60'/0'/0/2147483648'", 1)
            .unwrap_err()
            .to_string();
        assert!(err.contains("harden bit"), "{err}");
        assert!(derive_wallets::<English>(MNEMONIC, "m/44'/60'/0'/0", 1).is_ok());
    }
}