espresso_contract_deployer/

lib.rs

use std::{collections::HashMap, io::Write, time::Duration};

use alloy::{
    contract::RawCallBuilder,
    dyn_abi::{DynSolType, DynSolValue, JsonAbiExt},
    hex::{FromHex, ToHexExt},
    json_abi::Function,
    network::{Ethereum, EthereumWallet, TransactionBuilder},
    primitives::{Address, B256, Bytes, U256},
    providers::{
        Provider, ProviderBuilder, RootProvider,
        fillers::{FillProvider, JoinFill, WalletFiller},
        utils::JoinedRecommendedFillers,
    },
    rpc::{client::RpcClient, types::TransactionReceipt},
    signers::{
        ledger::LedgerSigner,
        local::{MnemonicBuilder, PrivateKeySigner, coins_bip39::English},
    },
    transports::http::reqwest::Url,
};
use anyhow::{Context, Result, anyhow};
use clap::{Parser, ValueEnum, builder::OsStr};
use derive_more::Display;
use espresso_types::{v0_1::L1Client, v0_3::Fetcher};
use hotshot_contract_adapter::sol_types::*;

pub mod builder;
pub mod impersonate_filler;
pub mod network_config;
pub mod output;
pub mod proposals;
pub mod provider;

/// Type alias that connects to providers with recommended fillers and wallet
/// use `<HttpProviderWithWallet as WalletProvider>::wallet()` to access internal wallet
/// use `<HttpProviderWithWallet as WalletProvider>::default_signer_address(&provider)` to get wallet address
pub type HttpProviderWithWallet = FillProvider<
    JoinFill<JoinedRecommendedFillers, WalletFiller<EthereumWallet>>,
    RootProvider,
    Ethereum,
>;

/// a handy thin wrapper around wallet builder and provider builder that directly
/// returns an instantiated `Provider` with default fillers with wallet, ready to send tx
pub fn build_provider(
    mnemonic: impl AsRef<str>,
    account_index: u32,
    url: Url,
    poll_interval: Option<Duration>,
) -> HttpProviderWithWallet {
    let signer = build_signer(mnemonic.as_ref(), account_index);
    let wallet = EthereumWallet::from(signer);

    // alloy sets the polling interval automatically. It tries to guess if an RPC is local, but this
    // guess is wrong when the RPC is running inside docker. This results to 7 second polling
    // intervals on a chain with 1s block time. Therefore, allow overriding the polling interval
    // with a custom value.
    if let Some(interval) = poll_interval {
        tracing::info!("Using custom L1 poll interval: {interval:?}");
        let client = RpcClient::new_http(url.clone()).with_poll_interval(interval);
        ProviderBuilder::new().wallet(wallet).connect_client(client)
    } else {
        tracing::info!("Using default L1 poll interval");
        ProviderBuilder::new().wallet(wallet).connect_http(url)
    }
}

// TODO: tech-debt: provider creation logic should be refactored to handle mnemonic and
// ledger signers and consolidated with similar code in staking-cli
pub fn build_provider_ledger(
    signer: LedgerSigner,
    url: Url,
    poll_interval: Option<Duration>,
) -> HttpProviderWithWallet {
    let wallet = EthereumWallet::from(signer);

    // alloy sets the polling interval automatically. It tries to guess if an RPC is local, but this
    // guess is wrong when the RPC is running inside docker. This results to 7 second polling
    // intervals on a chain with 1s block time. Therefore, allow overriding the polling interval
    // with a custom value.
    if let Some(interval) = poll_interval {
        tracing::info!("Using custom L1 poll interval: {interval:?}");
        let client = RpcClient::new_http(url.clone()).with_poll_interval(interval);
        ProviderBuilder::new().wallet(wallet).connect_client(client)
    } else {
        tracing::info!("Using default L1 poll interval");
        ProviderBuilder::new().wallet(wallet).connect_http(url)
    }
}

pub fn build_signer(mnemonic: impl AsRef<str>, account_index: u32) -> PrivateKeySigner {
    MnemonicBuilder::<English>::default()
        .phrase(mnemonic.as_ref())
        .index(account_index)
        .expect("wrong mnemonic or index")
        .build()
        .expect("fail to build signer")
}

/// similar to [`build_provider()`] but using a random wallet
pub fn build_random_provider(url: Url) -> HttpProviderWithWallet {
    let signer = MnemonicBuilder::<English>::default()
        .build_random()
        .expect("fail to build signer");
    let wallet = EthereumWallet::from(signer);
    ProviderBuilder::new().wallet(wallet).connect_http(url)
}

// We pass this during `forge bind --libraries` as a placeholder for the actual deployed library address
const LIBRARY_PLACEHOLDER_ADDRESS: &str = "ffffffffffffffffffffffffffffffffffffffff";
/// `stateHistoryRetentionPeriod` in LightClient.sol as the maximum retention period in seconds
pub const MAX_HISTORY_RETENTION_SECONDS: u32 = 864000;
/// Default exit escrow period for stake table (2 days in seconds)
pub const DEFAULT_EXIT_ESCROW_PERIOD_SECONDS: u64 = 172800;
/// Maximum number of retries for state checks after transactions
pub const MAX_RETRY_ATTEMPTS: u32 = 5;
/// Initial delay in milliseconds for retry exponential backoff
pub const RETRY_INITIAL_DELAY_MS: u64 = 500;

/// Set of predeployed contracts.
#[derive(Clone, Debug, Parser)]
pub struct DeployedContracts {
    /// Use an already-deployed PlonkVerifier.sol instead of deploying a new one.
    #[clap(long, env = Contract::PlonkVerifier)]
    plonk_verifier: Option<Address>,

    /// OpsTimelock.sol
    #[clap(long, env = Contract::OpsTimelock)]
    ops_timelock: Option<Address>,

    /// SafeExitTimelock.sol
    #[clap(long, env = Contract::SafeExitTimelock)]
    safe_exit_timelock: Option<Address>,

    /// PlonkVerifierV2.sol
    #[clap(long, env = Contract::PlonkVerifierV2)]
    plonk_verifier_v2: Option<Address>,

    /// PlonkVerifierV3.sol
    #[clap(long, env = Contract::PlonkVerifierV3)]
    plonk_verifier_v3: Option<Address>,

    /// Use an already-deployed LightClient.sol instead of deploying a new one.
    #[clap(long, env = Contract::LightClient)]
    light_client: Option<Address>,

    /// LightClientV2.sol
    #[clap(long, env = Contract::LightClientV2)]
    light_client_v2: Option<Address>,

    /// LightClientV3.sol
    #[clap(long, env = Contract::LightClientV3)]
    light_client_v3: Option<Address>,

    /// Use an already-deployed LightClient.sol proxy instead of deploying a new one.
    #[clap(long, env = Contract::LightClientProxy)]
    light_client_proxy: Option<Address>,

    /// Use an already-deployed FeeContract.sol instead of deploying a new one.
    #[clap(long, env = Contract::FeeContract)]
    fee_contract: Option<Address>,

    /// Use an already-deployed FeeContract.sol proxy instead of deploying a new one.
    #[clap(long, env = Contract::FeeContractProxy)]
    fee_contract_proxy: Option<Address>,

    /// Use an already-deployed EspToken.sol instead of deploying a new one.
    #[clap(long, env = Contract::EspToken)]
    esp_token: Option<Address>,

    /// Use an already-deployed EspTokenV2.sol instead of deploying a new one.
    #[clap(long, env = Contract::EspTokenV2)]
    esp_token_v2: Option<Address>,

    /// Use an already-deployed EspToken.sol proxy instead of deploying a new one.
    #[clap(long, env = Contract::EspTokenProxy)]
    esp_token_proxy: Option<Address>,

    /// Use an already-deployed StakeTable.sol instead of deploying a new one.
    #[clap(long, env = Contract::StakeTable)]
    stake_table: Option<Address>,

    /// Use an already-deployed StakeTableV2.sol instead of deploying a new one.
    #[clap(long, env = Contract::StakeTableV2)]
    stake_table_v2: Option<Address>,

    /// Use an already-deployed StakeTableV3.sol instead of deploying a new one.
    #[clap(long, env = Contract::StakeTableV3)]
    stake_table_v3: Option<Address>,

    /// Use an already-deployed StakeTable.sol proxy instead of deploying a new one.
    #[clap(long, env = Contract::StakeTableProxy)]
    stake_table_proxy: Option<Address>,

    /// RewardClaim.sol
    #[clap(long, env = Contract::RewardClaim)]
    reward_claim: Option<Address>,

    /// Use an already-deployed RewardClaim.sol proxy instead of deploying a new one.
    #[clap(long, env = Contract::RewardClaimProxy)]
    reward_claim_proxy: Option<Address>,
}

/// An identifier for a particular contract.
#[derive(Clone, Copy, Debug, Display, PartialEq, Eq, Hash)]
pub enum Contract {
    #[display("ESPRESSO_PLONK_VERIFIER_ADDRESS")]
    PlonkVerifier,
    #[display("ESPRESSO_OPS_TIMELOCK_ADDRESS")]
    OpsTimelock,
    #[display("ESPRESSO_SAFE_EXIT_TIMELOCK_ADDRESS")]
    SafeExitTimelock,
    #[display("ESPRESSO_PLONK_VERIFIER_V2_ADDRESS")]
    PlonkVerifierV2,
    #[display("ESPRESSO_PLONK_VERIFIER_V3_ADDRESS")]
    PlonkVerifierV3,
    #[display("ESPRESSO_LIGHT_CLIENT_ADDRESS")]
    LightClient,
    #[display("ESPRESSO_LIGHT_CLIENT_V2_ADDRESS")]
    LightClientV2,
    #[display("ESPRESSO_LIGHT_CLIENT_V3_ADDRESS")]
    LightClientV3,
    #[display("ESPRESSO_LIGHT_CLIENT_PROXY_ADDRESS")]
    LightClientProxy,
    #[display("ESPRESSO_FEE_CONTRACT_ADDRESS")]
    FeeContract,
    #[display("ESPRESSO_FEE_CONTRACT_PROXY_ADDRESS")]
    FeeContractProxy,
    #[display("ESP_TOKEN_ADDRESS")]
    EspToken,
    #[display("ESP_TOKEN_V2_ADDRESS")]
    EspTokenV2,
    #[display("ESP_TOKEN_PROXY_ADDRESS")]
    EspTokenProxy,
    #[display("ESPRESSO_STAKE_TABLE_ADDRESS")]
    StakeTable,
    #[display("ESPRESSO_STAKE_TABLE_V2_ADDRESS")]
    StakeTableV2,
    #[display("ESPRESSO_STAKE_TABLE_V3_ADDRESS")]
    StakeTableV3,
    #[display("ESPRESSO_STAKE_TABLE_PROXY_ADDRESS")]
    StakeTableProxy,
    #[display("ESPRESSO_REWARD_CLAIM_ADDRESS")]
    RewardClaim,
    #[display("ESPRESSO_REWARD_CLAIM_PROXY_ADDRESS")]
    RewardClaimProxy,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, ValueEnum)]
#[clap(rename_all = "kebab-case")]
pub enum OwnableContract {
    #[value(alias = "feecontract", alias = "FeeContract")]
    FeeContractProxy,
    #[value(alias = "lightclient", alias = "LightClient")]
    LightClientProxy,
    #[value(alias = "staketable", alias = "StakeTable")]
    StakeTableProxy,
    #[value(alias = "esptoken", alias = "EspToken")]
    EspTokenProxy,
    #[value(alias = "rewardclaim", alias = "RewardClaim")]
    RewardClaimProxy,
}

impl From<OwnableContract> for Contract {
    fn from(c: OwnableContract) -> Contract {
        match c {
            OwnableContract::FeeContractProxy => Contract::FeeContractProxy,
            OwnableContract::LightClientProxy => Contract::LightClientProxy,
            OwnableContract::StakeTableProxy => Contract::StakeTableProxy,
            OwnableContract::EspTokenProxy => Contract::EspTokenProxy,
            OwnableContract::RewardClaimProxy => Contract::RewardClaimProxy,
        }
    }
}

impl From<Contract> for OsStr {
    fn from(c: Contract) -> OsStr {
        c.to_string().into()
    }
}

/// Cache of contracts predeployed or deployed during this current run.
#[derive(Debug, Clone)]
pub struct Contracts {
    addresses: HashMap<Contract, Address>,
    // TODO: having the cooldown field here is a bit hacky but we postpone a better solution to
    // avoid a large refactor.
    deploy_cooldown: Duration,
}

impl Default for Contracts {
    fn default() -> Self {
        Self {
            addresses: HashMap::new(),
            deploy_cooldown: Duration::ZERO,
        }
    }
}

impl From<DeployedContracts> for Contracts {
    fn from(deployed: DeployedContracts) -> Self {
        let mut m = HashMap::new();
        if let Some(addr) = deployed.plonk_verifier {
            m.insert(Contract::PlonkVerifier, addr);
        }
        if let Some(addr) = deployed.plonk_verifier_v2 {
            m.insert(Contract::PlonkVerifierV2, addr);
        }
        if let Some(addr) = deployed.plonk_verifier_v3 {
            m.insert(Contract::PlonkVerifierV3, addr);
        }
        if let Some(addr) = deployed.safe_exit_timelock {
            m.insert(Contract::SafeExitTimelock, addr);
        }
        if let Some(addr) = deployed.ops_timelock {
            m.insert(Contract::OpsTimelock, addr);
        }
        if let Some(addr) = deployed.light_client {
            m.insert(Contract::LightClient, addr);
        }
        if let Some(addr) = deployed.light_client_v2 {
            m.insert(Contract::LightClientV2, addr);
        }
        if let Some(addr) = deployed.light_client_v3 {
            m.insert(Contract::LightClientV3, addr);
        }
        if let Some(addr) = deployed.light_client_proxy {
            m.insert(Contract::LightClientProxy, addr);
        }
        if let Some(addr) = deployed.fee_contract {
            m.insert(Contract::FeeContract, addr);
        }
        if let Some(addr) = deployed.fee_contract_proxy {
            m.insert(Contract::FeeContractProxy, addr);
        }
        if let Some(addr) = deployed.esp_token {
            m.insert(Contract::EspToken, addr);
        }
        if let Some(addr) = deployed.esp_token_v2 {
            m.insert(Contract::EspTokenV2, addr);
        }
        if let Some(addr) = deployed.esp_token_proxy {
            m.insert(Contract::EspTokenProxy, addr);
        }
        if let Some(addr) = deployed.stake_table {
            m.insert(Contract::StakeTable, addr);
        }
        if let Some(addr) = deployed.stake_table_v2 {
            m.insert(Contract::StakeTableV2, addr);
        }
        if let Some(addr) = deployed.stake_table_v3 {
            m.insert(Contract::StakeTableV3, addr);
        }
        if let Some(addr) = deployed.stake_table_proxy {
            m.insert(Contract::StakeTableProxy, addr);
        }
        if let Some(addr) = deployed.reward_claim {
            m.insert(Contract::RewardClaim, addr);
        }
        if let Some(addr) = deployed.reward_claim_proxy {
            m.insert(Contract::RewardClaimProxy, addr);
        }
        Self {
            addresses: m,
            deploy_cooldown: Duration::ZERO,
        }
    }
}

impl Contracts {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn with_cooldown(cooldown: Duration) -> Self {
        Self {
            addresses: HashMap::new(),
            deploy_cooldown: cooldown,
        }
    }

    pub fn set_cooldown(&mut self, cooldown: Duration) {
        self.deploy_cooldown = cooldown;
    }

    pub fn address(&self, contract: Contract) -> Option<Address> {
        self.addresses.get(&contract).copied()
    }

    pub fn get(&self, contract: &Contract) -> Option<&Address> {
        self.addresses.get(contract)
    }

    pub fn iter(&self) -> impl Iterator<Item = (&Contract, &Address)> {
        self.addresses.iter()
    }

    pub fn remove(&mut self, contract: &Contract) -> Option<Address> {
        self.addresses.remove(contract)
    }

    /// Deploy a contract (with logging and cached deployments)
    ///
    /// The deployment `tx` will be sent only if contract `name` is not already deployed;
    /// otherwise this function will just return the predeployed address.
    pub async fn deploy<P>(&mut self, name: Contract, tx: RawCallBuilder<P>) -> Result<Address>
    where
        P: Provider,
    {
        if let Some(addr) = self.addresses.get(&name) {
            tracing::info!("skipping deployment of {name}, already deployed at {addr:#x}");
            return Ok(*addr);
        }
        tracing::info!("deploying {name}");
        let pending_tx = tx.send().await?;
        let tx_hash = *pending_tx.tx_hash();
        tracing::info!(%tx_hash, "waiting for tx to be mined");
        let receipt = pending_tx.get_receipt().await?;
        if !receipt.inner.is_success() {
            anyhow::bail!("Deployment transaction failed: {:?}", receipt);
        }
        tracing::info!(%receipt.gas_used, %tx_hash, "tx mined");
        let addr = receipt
            .contract_address
            .ok_or(alloy::contract::Error::ContractNotDeployed)?;

        tracing::info!("deployed {name} at {addr:#x}");

        if !self.deploy_cooldown.is_zero() {
            tokio::time::sleep(self.deploy_cooldown).await;
            tracing::info!("cooldown {:?} after deployment", self.deploy_cooldown);
        }

        self.addresses.insert(name, addr);
        Ok(addr)
    }

    /// Write a .env file.
    pub fn write(&self, mut w: impl Write) -> Result<()> {
        for (contract, address) in &self.addresses {
            writeln!(w, "{contract}={address:#x}")?;
        }
        Ok(())
    }
}

/// Default deployment function `LightClient.sol` or `LightClientMock.sol` with `mock: true`.
///
/// # NOTE:
/// In most cases, you only need to use [`deploy_light_client_proxy()`]
///
/// # NOTE:
/// currently, `LightClient.sol` follows upgradable contract, thus a follow-up
/// call to `.initialize()` with proper genesis block (and other constructor args)
/// are expected to be *delegatecall-ed through the proxy contract*.
pub(crate) async fn deploy_light_client_contract(
    provider: impl Provider,
    contracts: &mut Contracts,
    mock: bool,
) -> Result<Address> {
    // Deploy library contracts.
    let plonk_verifier_addr = contracts
        .deploy(
            Contract::PlonkVerifier,
            PlonkVerifier::deploy_builder(&provider),
        )
        .await?;

    assert!(is_contract(&provider, plonk_verifier_addr).await?);

    // when generate alloy's bindings, we supply a placeholder address, now we modify the actual
    // bytecode with deployed address of the library.
    let target_lc_bytecode = if mock {
        LightClientMock::BYTECODE.encode_hex()
    } else {
        LightClient::BYTECODE.encode_hex()
    };
    let lc_linked_bytecode = {
        match target_lc_bytecode
            .matches(LIBRARY_PLACEHOLDER_ADDRESS)
            .count()
        {
            0 => return Err(anyhow!("lib placeholder not found")),
            1 => Bytes::from_hex(target_lc_bytecode.replacen(
                LIBRARY_PLACEHOLDER_ADDRESS,
                &plonk_verifier_addr.encode_hex(),
                1,
            ))?,
            _ => {
                return Err(anyhow!(
                    "more than one lib placeholder found, consider using a different value"
                ));
            },
        }
    };

    // Deploy the light client
    let light_client_addr = if mock {
        // for mock, we don't populate the `contracts` since it only track production-ready deployments
        let addr = LightClientMock::deploy_builder(&provider)
            .map(|req| req.with_deploy_code(lc_linked_bytecode))
            .deploy()
            .await?;
        tracing::info!("deployed LightClientMock at {addr:#x}");
        addr
    } else {
        contracts
            .deploy(
                Contract::LightClient,
                LightClient::deploy_builder(&provider)
                    .map(|req| req.with_deploy_code(lc_linked_bytecode)),
            )
            .await?
    };
    Ok(light_client_addr)
}

/// The primary logic for deploying and initializing an upgradable light client contract.
///
/// Deploy the upgradable proxy contract, point to an already deployed light client contract as its implementation, and invoke `initialize()` on it.
/// This is run after `deploy_light_client_contract()`, returns the proxy address.
/// This works for both mock and production light client proxy.
pub async fn deploy_light_client_proxy(
    provider: impl Provider,
    contracts: &mut Contracts,
    mock: bool,
    genesis_state: LightClientStateSol,
    genesis_stake: StakeTableStateSol,
    admin: Address,
    prover: Option<Address>,
) -> Result<Address> {
    // deploy the light client implementation contract
    let impl_addr = deploy_light_client_contract(&provider, contracts, mock).await?;
    let lc = LightClient::new(impl_addr, &provider);

    // prepare the input arg for `initialize()`
    let init_data = lc
        .initialize(
            genesis_state,
            genesis_stake,
            MAX_HISTORY_RETENTION_SECONDS,
            admin,
        )
        .calldata()
        .to_owned();
    // deploy proxy and initialize
    let lc_proxy_addr = contracts
        .deploy(
            Contract::LightClientProxy,
            ERC1967Proxy::deploy_builder(&provider, impl_addr, init_data),
        )
        .await?;

    // sanity check
    if !is_proxy_contract(&provider, lc_proxy_addr).await? {
        panic!("LightClientProxy detected not as a proxy, report error!");
    }

    // instantiate a proxy instance, cast as LightClient's ABI interface
    let lc_proxy = LightClient::new(lc_proxy_addr, &provider);

    // set permissioned prover
    if let Some(prover) = prover {
        tracing::info!(%lc_proxy_addr, %prover, "Set permissioned prover ");
        lc_proxy
            .setPermissionedProver(prover)
            .send()
            .await?
            .get_receipt()
            .await?;
    }

    // post deploy verification checks
    assert_eq!(lc_proxy.getVersion().call().await?.majorVersion, 1);
    assert_eq!(lc_proxy.owner().call().await?, admin);
    if let Some(prover) = prover {
        assert_eq!(lc_proxy.permissionedProver().call().await?, prover);
    }
    assert_eq!(lc_proxy.stateHistoryRetentionPeriod().call().await?, 864000);
    assert_eq!(
        lc_proxy.currentBlockNumber().call().await?,
        U256::from(provider.get_block_number().await?)
    );

    Ok(lc_proxy_addr)
}

/// Upgrade the light client proxy to use LightClientV2.
/// Internally, first detect existence of proxy, then deploy LCV2, then upgrade and initializeV2.
/// Internal to "deploy LCV2", we deploy PlonkVerifierV2 whose address will be used at LCV2 init time.
/// Assumes:
/// - the proxy is already deployed.
/// - the proxy is owned by a regular EOA, not a multisig.
/// - the proxy is not yet initialized for V2
///
/// Returns the receipt of the upgrade transaction.
pub async fn upgrade_light_client_v2(
    provider: impl Provider,
    contracts: &mut Contracts,
    is_mock: bool,
    blocks_per_epoch: u64,
    epoch_start_block: u64,
) -> Result<TransactionReceipt> {
    match contracts.address(Contract::LightClientProxy) {
        // check if proxy already exists
        None => Err(anyhow!("LightClientProxy not found, can't upgrade")),
        Some(proxy_addr) => {
            let proxy = LightClient::new(proxy_addr, &provider);

            let curr_version = proxy.getVersion().call().await?;
            if curr_version.majorVersion > 2 {
                anyhow::bail!(
                    "Expected LightClient V1 or V2 for upgrade to V2, found V{}",
                    curr_version.majorVersion
                );
            }
            // Log a warning if this is a patch upgrade (re-applying same version)
            if curr_version.majorVersion == 2 {
                tracing::warn!(
                    "Re-applying LightClient V2 (patch upgrade). This will deploy a fresh \
                     implementation."
                );
            }
            let state_history_retention_period = proxy.stateHistoryRetentionPeriod().call().await?;
            // first deploy PlonkVerifierV2.sol
            let pv2_addr = contracts
                .deploy(
                    Contract::PlonkVerifierV2,
                    PlonkVerifierV2::deploy_builder(&provider),
                )
                .await?;

            assert!(is_contract(&provider, pv2_addr).await?);

            // then deploy LightClientV2.sol
            let target_lcv2_bytecode = if is_mock {
                LightClientV2Mock::BYTECODE.encode_hex()
            } else {
                LightClientV2::BYTECODE.encode_hex()
            };
            let lcv2_linked_bytecode = {
                match target_lcv2_bytecode
                    .matches(LIBRARY_PLACEHOLDER_ADDRESS)
                    .count()
                {
                    0 => return Err(anyhow!("lib placeholder not found")),
                    1 => Bytes::from_hex(target_lcv2_bytecode.replacen(
                        LIBRARY_PLACEHOLDER_ADDRESS,
                        &pv2_addr.encode_hex(),
                        1,
                    ))?,
                    _ => {
                        return Err(anyhow!(
                            "more than one lib placeholder found, consider using a different value"
                        ));
                    },
                }
            };
            let lcv2_addr = if is_mock {
                let addr = LightClientV2Mock::deploy_builder(&provider)
                    .map(|req| req.with_deploy_code(lcv2_linked_bytecode))
                    .deploy()
                    .await?;
                tracing::info!("deployed LightClientV2Mock at {addr:#x}");
                addr
            } else {
                // Only check/remove from cache if this is a patch upgrade (V2 -> V2)
                let is_patch_upgrade = curr_version.majorVersion == 2;
                if is_patch_upgrade {
                    let cached_lcv2_addr = contracts.address(Contract::LightClientV2);
                    // For patch upgrades, we need to deploy a fresh implementation contract.
                    // If LightClientV2 is already in the cache, the caller must unset it first
                    // to make the redeployment requirement explicit.
                    if let Some(addr) = cached_lcv2_addr {
                        anyhow::bail!(
                            "LightClientV2 implementation address is already set in cache \
                             ({:#x}). For patch upgrades, the implementation must be redeployed. \
                             Please unset ESPRESSO_LIGHT_CLIENT_V2_ADDRESS or remove it from the \
                             cache first.",
                            addr
                        );
                    }
                }

                contracts
                    .deploy(
                        Contract::LightClientV2,
                        LightClientV2::deploy_builder(&provider)
                            .map(|req| req.with_deploy_code(lcv2_linked_bytecode)),
                    )
                    .await?
            };

            // get owner of proxy
            let owner = proxy.owner().call().await?;
            let owner_addr = owner;
            tracing::info!("Proxy owner: {owner_addr:#x}");

            // prepare initial function call calldata (checks if already initialized)
            // you cannot initialize a proxy that is already initialized
            // so if one wanted to use this function to upgrade a proxy to v2, that's already v2
            // then we shouldn't call the initialize function
            let lcv2 = LightClientV2::new(lcv2_addr, &provider);
            let init_data = if already_initialized(&provider, proxy_addr, 2).await? {
                vec![].into()
            } else {
                lcv2.initializeV2(blocks_per_epoch, epoch_start_block)
                    .calldata()
                    .to_owned()
            };
            // invoke upgrade on proxy
            let receipt = proxy
                .upgradeToAndCall(lcv2_addr, init_data)
                .send()
                .await?
                .get_receipt()
                .await?;
            let proxy_as_v2 = LightClientV2::new(proxy_addr, &provider);

            if receipt.inner.is_success() {
                // check that the upgrade is complete (with retry for RPC timing)
                let is_complete = retry_until_true("LightClientProxy V2 version check", || async {
                    Ok(proxy_as_v2.getVersion().call().await?.majorVersion == 2)
                })
                .await?;

                if !is_complete {
                    anyhow::bail!(
                        "LightClientProxy version check failed after retries: expected V2"
                    );
                }

                // post deploy verification checks
                assert_eq!(proxy_as_v2.blocksPerEpoch().call().await?, blocks_per_epoch);
                assert_eq!(
                    proxy_as_v2.epochStartBlock().call().await?,
                    epoch_start_block
                );
                assert_eq!(
                    proxy_as_v2.stateHistoryRetentionPeriod().call().await?,
                    state_history_retention_period
                );
                assert_eq!(
                    proxy_as_v2.currentBlockNumber().call().await?,
                    U256::from(provider.get_block_number().await?)
                );

                tracing::info!(%lcv2_addr, "LightClientProxy successfully upgraded to V2");
                tracing::info!(
                    "blocksPerEpoch: {}",
                    proxy_as_v2.blocksPerEpoch().call().await?
                );
                tracing::info!(
                    "epochStartBlock: {}",
                    proxy_as_v2.epochStartBlock().call().await?
                );
            } else {
                tracing::error!("LightClientProxy upgrade failed: {:?}", receipt);
            }

            Ok(receipt)
        },
    }
}

/// Upgrade the light client proxy to use LightClientV3.
/// Internally, first detect existence of proxy, then deploy LCV3, then upgrade and initializeV3.
/// Internal to "deploy LCV3", we deploy PlonkVerifierV3 whose address will be used at LCV3 init time.
/// Assumes:
/// - the proxy is already deployed.
/// - the proxy is owned by a regular EOA, not a multisig.
/// - the proxy is not yet initialized for V3
pub async fn upgrade_light_client_v3(
    provider: impl Provider,
    contracts: &mut Contracts,
    is_mock: bool,
) -> Result<TransactionReceipt> {
    match contracts.address(Contract::LightClientProxy) {
        // check if proxy already exists
        None => Err(anyhow!("LightClientProxy not found, can't upgrade")),
        Some(proxy_addr) => {
            let proxy = LightClient::new(proxy_addr, &provider);

            // Check proxy version, V3 requires at least V2 as a prerequisite
            // This ensures we don't try to upgrade from V1 directly to V3
            // V1 -> V2 -> V3 is the correct upgrade path
            let version = proxy.getVersion().call().await?;
            if version.majorVersion < 2 {
                anyhow::bail!(
                    "LightClientProxy is V{}, can't upgrade to V3. Must upgrade to V2 first.",
                    version.majorVersion
                );
            }

            // first deploy PlonkVerifierV3.sol
            let pv3_addr = contracts
                .deploy(
                    Contract::PlonkVerifierV3,
                    PlonkVerifierV3::deploy_builder(&provider),
                )
                .await?;
            assert!(is_contract(&provider, pv3_addr).await?);

            // then deploy LightClientV3.sol
            let target_lcv3_bytecode = if is_mock {
                LightClientV3Mock::BYTECODE.encode_hex()
            } else {
                LightClientV3::BYTECODE.encode_hex()
            };
            let lcv3_linked_bytecode = {
                match target_lcv3_bytecode
                    .matches(LIBRARY_PLACEHOLDER_ADDRESS)
                    .count()
                {
                    0 => return Err(anyhow!("lib placeholder not found")),
                    1 => Bytes::from_hex(target_lcv3_bytecode.replacen(
                        LIBRARY_PLACEHOLDER_ADDRESS,
                        &pv3_addr.encode_hex(),
                        1,
                    ))?,
                    _ => {
                        return Err(anyhow!(
                            "more than one lib placeholder found, consider using a different value"
                        ));
                    },
                }
            };
            let lcv3_addr = if is_mock {
                let addr = LightClientV3Mock::deploy_builder(&provider)
                    .map(|req| req.with_deploy_code(lcv3_linked_bytecode))
                    .deploy()
                    .await?;
                tracing::info!("deployed LightClientV3Mock at {addr:#x}");
                addr
            } else {
                contracts
                    .deploy(
                        Contract::LightClientV3,
                        LightClientV3::deploy_builder(&provider)
                            .map(|req| req.with_deploy_code(lcv3_linked_bytecode)),
                    )
                    .await?
            };

            // get owner of proxy
            let owner = proxy.owner().call().await?;
            let owner_addr = owner;
            tracing::info!("Proxy owner: {owner_addr:#x}");

            let lcv3 = LightClientV3::new(lcv3_addr, &provider);

            // prepare initial function call calldata (checks if already initialized)
            // you cannot initialize a proxy that is already initialized
            // so if one wanted to use this function to upgrade a proxy to v3, that's already v3
            // then we shouldn't call the initialize function
            let init_data = if already_initialized(&provider, proxy_addr, 3).await? {
                vec![].into()
            } else {
                lcv3.initializeV3().calldata().to_owned()
            };

            // invoke upgrade on proxy
            let receipt = proxy
                .upgradeToAndCall(lcv3_addr, init_data)
                .send()
                .await?
                .get_receipt()
                .await?;

            let proxy_as_v3 = LightClientV3::new(proxy_addr, &provider);

            if receipt.inner.is_success() {
                // check that the upgrade is complete (with retry for RPC timing)
                let version_is_v3 =
                    retry_until_true("LightClientProxy V3 version check", || async {
                        Ok(proxy_as_v3.getVersion().call().await?.majorVersion == 3)
                    })
                    .await?;

                if !version_is_v3 {
                    anyhow::bail!(
                        "LightClientProxy version check failed after retries: expected V3"
                    );
                }

                tracing::info!(%lcv3_addr, "LightClientProxy successfully upgraded to V3");
            } else {
                tracing::error!("LightClientProxy upgrade failed: {:?}", receipt);
            }

            Ok(receipt)
        },
    }
}

async fn already_initialized(
    provider: impl Provider,
    proxy_addr: Address,
    expected_major_version: u8,
) -> Result<bool> {
    let initialized = get_proxy_initialized_version(&provider, proxy_addr).await?;
    tracing::info!("Initialized version: {}", initialized);

    // since all upgradable contracts have a getVersion() function, we can use it to get the major version
    let contract_proxy = LightClientV2::new(proxy_addr, &provider);
    let contract_major_version = contract_proxy.getVersion().call().await?.majorVersion;

    Ok(initialized == contract_major_version && contract_major_version == expected_major_version)
}

/// The primary logic for deploying and initializing an upgradable fee contract.
///
/// Deploy the upgradable proxy contract, point to a deployed fee contract as its implementation, and invoke `initialize()` on it.
/// - `admin`: is the new owner (e.g. a multisig address) of the proxy contract
///
/// Return the proxy address.
pub async fn deploy_fee_contract_proxy(
    provider: impl Provider,
    contracts: &mut Contracts,
    admin: Address,
) -> Result<Address> {
    // deploy the fee implementation contract
    let fee_addr = contracts
        .deploy(
            Contract::FeeContract,
            FeeContract::deploy_builder(&provider),
        )
        .await?;
    let fee = FeeContract::new(fee_addr, &provider);

    // prepare the input arg for `initialize()`
    let init_data = fee.initialize(admin).calldata().to_owned();
    // deploy proxy and initialize
    let fee_proxy_addr = contracts
        .deploy(
            Contract::FeeContractProxy,
            ERC1967Proxy::deploy_builder(&provider, fee_addr, init_data),
        )
        .await?;
    // sanity check
    if !is_proxy_contract(&provider, fee_proxy_addr).await? {
        panic!("FeeContractProxy detected not as a proxy, report error!");
    }

    // post deploy verification checks
    let fee_proxy = FeeContract::new(fee_proxy_addr, &provider);
    assert_eq!(fee_proxy.getVersion().call().await?.majorVersion, 1);
    assert_eq!(fee_proxy.owner().call().await?, admin);

    Ok(fee_proxy_addr)
}

/// The primary logic for deploying and initializing an upgradable Espresso Token contract.
pub async fn deploy_token_proxy(
    provider: impl Provider,
    contracts: &mut Contracts,
    owner: Address,
    init_grant_recipient: Address,
    initial_supply: U256,
    name: &str,
    symbol: &str,
) -> Result<Address> {
    let token_addr = contracts
        .deploy(Contract::EspToken, EspToken::deploy_builder(&provider))
        .await?;
    let token = EspToken::new(token_addr, &provider);

    let init_data = token
        .initialize(
            owner,
            init_grant_recipient,
            initial_supply,
            name.to_string(),
            symbol.to_string(),
        )
        .calldata()
        .to_owned();

    let token_proxy_addr = contracts
        .deploy(
            Contract::EspTokenProxy,
            ERC1967Proxy::deploy_builder(&provider, token_addr, init_data),
        )
        .await?;

    if !is_proxy_contract(&provider, token_proxy_addr).await? {
        panic!("EspTokenProxy detected not as a proxy, report error!");
    }

    // post deploy verification checks
    let token_proxy = EspToken::new(token_proxy_addr, &provider);
    assert_eq!(token_proxy.getVersion().call().await?.majorVersion, 1);
    assert_eq!(token_proxy.owner().call().await?, owner);
    assert_eq!(token_proxy.symbol().call().await?, symbol);
    assert_eq!(token_proxy.decimals().call().await?, 18);
    assert_eq!(token_proxy.name().call().await?, name);
    let total_supply = token_proxy.totalSupply().call().await?;
    assert_eq!(
        token_proxy.balanceOf(init_grant_recipient).call().await?,
        total_supply
    );

    Ok(token_proxy_addr)
}

/// Upgrade the esp token proxy to use EspTokenV2.
pub async fn upgrade_esp_token_v2(
    provider: impl Provider,
    contracts: &mut Contracts,
) -> Result<TransactionReceipt> {
    let Some(proxy_addr) = contracts.address(Contract::EspTokenProxy) else {
        anyhow::bail!("EspTokenProxy not found, can't upgrade")
    };

    let proxy = EspToken::new(proxy_addr, &provider);
    // Deploy the new implementation
    let v2_addr = contracts
        .deploy(Contract::EspTokenV2, EspTokenV2::deploy_builder(&provider))
        .await?;

    assert!(is_contract(&provider, v2_addr).await?);

    // prepare init calldata for V2
    let reward_claim_addr = contracts
        .address(Contract::RewardClaimProxy)
        .ok_or_else(|| anyhow!("RewardClaimProxy not found"))?;
    let proxy_as_v2 = EspTokenV2::new(proxy_addr, &provider);
    let init_data = proxy_as_v2
        .initializeV2(reward_claim_addr)
        .calldata()
        .to_owned();

    // invoke upgrade on proxy with initializeV2 call
    let receipt = proxy
        .upgradeToAndCall(v2_addr, init_data)
        .send()
        .await?
        .get_receipt()
        .await?;

    if receipt.inner.is_success() {
        // check that the upgrade is complete (with retry for RPC timing)
        let version_is_v2 = retry_until_true("EspTokenProxy V2 version check", || async {
            Ok(proxy_as_v2.getVersion().call().await?.majorVersion == 2)
        })
        .await?;

        if !version_is_v2 {
            anyhow::bail!("EspTokenProxy version check failed after retries: expected V2");
        }

        // post deploy verification checks
        assert_eq!(proxy_as_v2.name().call().await?, "Espresso");
        assert_eq!(proxy_as_v2.rewardClaim().call().await?, reward_claim_addr);
        tracing::info!(%v2_addr, "EspToken successfully upgraded to");
    } else {
        anyhow::bail!("EspToken upgrade failed: {:?}", receipt);
    }

    Ok(receipt)
}

/// The primary logic for deploying and initializing an upgradable permissionless StakeTable contract.
pub async fn deploy_stake_table_proxy(
    provider: impl Provider,
    contracts: &mut Contracts,
    token_addr: Address,
    light_client_addr: Address,
    exit_escrow_period: U256,
    owner: Address,
) -> Result<Address> {
    let stake_table_addr = contracts
        .deploy(Contract::StakeTable, StakeTable::deploy_builder(&provider))
        .await?;
    let stake_table = StakeTable::new(stake_table_addr, &provider);

    // TODO: verify the light client address contains a contract
    // See #3163, it's a cyclic dependency in the demo environment
    // assert!(is_contract(&provider, light_client_addr).await?);

    // verify the token address contains a contract
    if !is_contract(&provider, token_addr).await? {
        anyhow::bail!("Token address is not a contract, can't deploy StakeTableProxy");
    }

    let init_data = stake_table
        .initialize(token_addr, light_client_addr, exit_escrow_period, owner)
        .calldata()
        .to_owned();

    let st_proxy_addr = contracts
        .deploy(
            Contract::StakeTableProxy,
            ERC1967Proxy::deploy_builder(&provider, stake_table_addr, init_data),
        )
        .await?;

    if !is_proxy_contract(&provider, st_proxy_addr).await? {
        panic!("StakeTableProxy detected not as a proxy, report error!");
    }

    let st_proxy = StakeTable::new(st_proxy_addr, &provider);
    assert_eq!(st_proxy.getVersion().call().await?.majorVersion, 1);
    assert_eq!(st_proxy.owner().call().await?, owner);
    assert_eq!(st_proxy.token().call().await?, token_addr);
    assert_eq!(st_proxy.lightClient().call().await?, light_client_addr);
    assert_eq!(
        st_proxy.exitEscrowPeriod().call().await?,
        exit_escrow_period
    );

    Ok(st_proxy_addr)
}

/// Deploy and initialize the RewardClaim contract behind a proxy
pub async fn deploy_reward_claim_proxy(
    provider: impl Provider,
    contracts: &mut Contracts,
    esp_token_addr: Address,
    light_client_addr: Address,
    admin: Address,
    pauser: Address,
) -> Result<Address> {
    let reward_claim_addr = contracts
        .deploy(
            Contract::RewardClaim,
            RewardClaim::deploy_builder(&provider),
        )
        .await?;
    let reward_claim = RewardClaim::new(reward_claim_addr, &provider);

    // verify the esp token address contains a contract
    if !is_contract(&provider, esp_token_addr).await? {
        anyhow::bail!("EspToken address is not a contract, can't deploy RewardClaimProxy");
    }

    // verify the light client address contains a contract
    if !is_contract(&provider, light_client_addr).await? {
        anyhow::bail!("LightClient address is not a contract, can't deploy RewardClaimProxy");
    }

    let init_data = reward_claim
        .initialize(admin, esp_token_addr, light_client_addr, pauser)
        .calldata()
        .to_owned();
    let reward_claim_proxy_addr = contracts
        .deploy(
            Contract::RewardClaimProxy,
            ERC1967Proxy::deploy_builder(&provider, reward_claim_addr, init_data),
        )
        .await?;

    if !is_proxy_contract(&provider, reward_claim_proxy_addr).await? {
        panic!("RewardClaimProxy detected not as a proxy, report error!");
    }

    let reward_claim_proxy = RewardClaim::new(reward_claim_proxy_addr, &provider);
    assert_eq!(
        reward_claim_proxy.getVersion().call().await?,
        (1, 0, 0).into()
    );
    // Verify admin has DEFAULT_ADMIN_ROLE
    let admin_role = reward_claim_proxy.DEFAULT_ADMIN_ROLE().call().await?;
    assert!(
        reward_claim_proxy.hasRole(admin_role, admin).call().await?,
        "admin should have DEFAULT_ADMIN_ROLE"
    );
    assert_eq!(reward_claim_proxy.espToken().call().await?, esp_token_addr);
    assert_eq!(
        reward_claim_proxy.lightClient().call().await?,
        light_client_addr
    );

    Ok(reward_claim_proxy_addr)
}

/// Read stake table data from L1 StakeTable V1 events for V2 migration
///
/// Returns both the active stake and commissions needed for StakeTable V2 initialization.
/// Assumes an infura RPC is used, otherwise it may hit other rate limits.
pub async fn fetch_stake_table_for_stake_table_storage_migration(
    l1_client: L1Client,
    stake_table_address: Address,
) -> Result<(U256, Vec<StakeTableV2::InitialCommission>)> {
    let stake_table = StakeTable::new(stake_table_address, &l1_client);

    // Verify this is a V1 contract
    let version = stake_table.getVersion().call().await?;
    if version.majorVersion != 1 {
        anyhow::bail!(
            "Expected StakeTable V1 for migration, found V{}",
            version.majorVersion
        );
    }

    tracing::info!("Fetching all validators from StakeTable V1 contract");

    // Get the latest L1 block to query up to
    let latest_block = l1_client.provider.get_block_number().await?;

    // Use Fetcher to get all validators from contract events
    let (validators, _stake_table_hash) =
        Fetcher::fetch_all_validators_from_contract(l1_client, stake_table_address, latest_block)
            .await
            .context("Failed to fetch validators from V1 contract")?;

    // Sum up total active stake from all validators
    let active_stake = validators.values().map(|v| v.stake).sum::<U256>();

    // Extract commissions from validators
    let commissions = validators
        .values()
        .map(|v| StakeTableV2::InitialCommission {
            validator: v.account,
            commission: v.commission,
        })
        .collect::<Vec<_>>();

    tracing::info!(
        "Found {} active stake and {} commissions from {} validators to migrate from V1",
        active_stake,
        commissions.len(),
        validators.len()
    );

    Ok((active_stake, commissions))
}

/// Prepare the upgrade data for StakeTable V2, checking version and fetching commissions if needed.
///
/// Returns:
/// - The initialization commissions (maybe used for post deployment verification)
/// - The initialization calldata (if initialization is needed)
pub async fn prepare_stake_table_v2_upgrade(
    l1_client: L1Client,
    proxy_addr: Address,
    pauser: Address,
    admin: Address,
) -> Result<(
    Option<Vec<StakeTableV2::InitialCommission>>,
    Option<U256>,
    Option<Bytes>,
)> {
    let proxy = StakeTable::new(proxy_addr, &l1_client);

    let current_version = proxy.getVersion().call().await?;
    let target_version = 2;
    if current_version.majorVersion > target_version {
        anyhow::bail!(
            "Expected StakeTable V1 or V2, found V{}",
            current_version.majorVersion
        );
    }

    // For a non-major version upgrade the proxy storage must already be initialized.
    let needs_initialization =
        !already_initialized(&l1_client.provider, proxy_addr, target_version).await?;
    assert_eq!(
        needs_initialization,
        current_version.majorVersion < target_version,
        "unexpected version initialized"
    );

    if needs_initialization {
        tracing::info!("Fetching stake table data from V1 contract for migration");
        let (active_stake, commissions) =
            fetch_stake_table_for_stake_table_storage_migration(l1_client.clone(), proxy_addr)
                .await?;

        tracing::info!(
            %pauser,
            %admin,
            active_stake = %format!("{:?} wei", active_stake),
            commission_count = commissions.len(),
            "Init Data to be signed. Function: initializeV2",
        );

        // We can use any address here since we're just building calldata
        let data = StakeTableV2::new(Address::ZERO, &l1_client)
            .initializeV2(pauser, admin, active_stake, commissions.clone())
            .calldata()
            .to_owned();

        Ok((Some(commissions), Some(active_stake), Some(data)))
    } else {
        tracing::info!(
            "Proxy was already initialized for version {}",
            target_version
        );
        Ok((None, None, None))
    }
}

/// Upgrade the stake table proxy from V1 to V2, or patch V2
pub async fn upgrade_stake_table_v2(
    provider: impl Provider,
    l1_client: L1Client,
    contracts: &mut Contracts,
    pauser: Address,
    admin: Address,
) -> Result<TransactionReceipt> {
    tracing::info!("Upgrading StakeTableProxy to StakeTableV2 with EOA admin");
    let Some(proxy_addr) = contracts.address(Contract::StakeTableProxy) else {
        anyhow::bail!("StakeTableProxy not found, can't upgrade")
    };

    // First prepare upgrade data (including fetching commissions if needed)
    let (init_commissions, init_active_stake, init_data) =
        prepare_stake_table_v2_upgrade(l1_client.clone(), proxy_addr, pauser, admin).await?;

    // Then deploy the new implementation
    let v2_addr = contracts
        .deploy(
            Contract::StakeTableV2,
            StakeTableV2::deploy_builder(&provider),
        )
        .await?;

    let proxy = StakeTable::new(proxy_addr, &provider);

    let receipt = proxy
        .upgradeToAndCall(v2_addr, init_data.unwrap_or_default())
        .send()
        .await?
        .get_receipt()
        .await?;

    let proxy_as_v2 = StakeTableV2::new(proxy_addr, &provider);

    if receipt.inner.is_success() {
        //TODO: check event emission instead as it's more reliable
        // check that the upgrade is complete (with retry for RPC timing)
        let version_is_v2 = retry_until_true("StakeTableProxy V2 version check", || async {
            Ok(proxy_as_v2.getVersion().call().await?.majorVersion == 2)
        })
        .await?;
        if !version_is_v2 {
            anyhow::bail!("StakeTableProxy version check failed after retries: expected V2");
        }

        // post deploy verification checks
        let pauser_role = proxy_as_v2.PAUSER_ROLE().call().await?;
        assert!(
            proxy_as_v2.hasRole(pauser_role, pauser).call().await?,
            "pauser should have PAUSER_ROLE"
        );

        let admin_role = proxy_as_v2.DEFAULT_ADMIN_ROLE().call().await?;
        assert!(proxy_as_v2.hasRole(admin_role, admin).call().await?,);

        if let Some(migrated) = init_commissions {
            tracing::info!("Verifying migrated commissions, may take a minute");
            for init_comm in migrated {
                let tracking = proxy_as_v2
                    .commissionTracking(init_comm.validator)
                    .call()
                    .await?;
                assert_eq!(tracking.commission, init_comm.commission);
            }
        }

        tracing::info!("Verifying migrated active stake");
        assert_eq!(
            proxy_as_v2.activeStake().call().await?,
            init_active_stake.unwrap_or_default(),
            "migrated active stake does not match"
        );

        tracing::info!(%v2_addr, "StakeTable successfully upgraded to");
    } else {
        anyhow::bail!("StakeTable upgrade failed: {:?}", receipt);
    }

    Ok(receipt)
}

/// Upgrade the stake table proxy from V2 to V3.
///
/// V3 adds x25519 key and p2p address registration. No data migration needed.
pub async fn upgrade_stake_table_v3(
    provider: impl Provider,
    contracts: &mut Contracts,
) -> Result<TransactionReceipt> {
    tracing::info!("Upgrading StakeTableProxy to StakeTableV3");
    let Some(proxy_addr) = contracts.address(Contract::StakeTableProxy) else {
        anyhow::bail!("StakeTableProxy not found, can't upgrade")
    };

    let proxy = StakeTableV3::new(proxy_addr, &provider);

    // V3 requires V2 as a prerequisite. V1 -> V2 -> V3 is the only supported path.
    let version = proxy.getVersion().call().await?;
    if version.majorVersion < 2 {
        anyhow::bail!(
            "StakeTableProxy must be at major version >= 2 to upgrade to V3, found {}",
            version.majorVersion
        );
    }

    let v3_addr = contracts
        .deploy(
            Contract::StakeTableV3,
            StakeTableV3::deploy_builder(&provider),
        )
        .await?;

    // If already initialized at V3, skip initializeV3() to avoid the "already
    // initialized" revert. Mirrors upgrade_light_client_v3 behavior.
    let init_data = if already_initialized(&provider, proxy_addr, 3).await? {
        tracing::info!("StakeTableProxy already initialized at V3, skipping initializeV3()");
        vec![].into()
    } else {
        StakeTableV3::new(Address::ZERO, &provider)
            .initializeV3()
            .calldata()
            .to_owned()
    };

    let receipt = proxy
        .upgradeToAndCall(v3_addr, init_data)
        .send()
        .await?
        .get_receipt()
        .await?;

    if receipt.inner.is_success() {
        let version_is_v3 = retry_until_true("StakeTableProxy V3 version check", || async {
            Ok(proxy.getVersion().call().await?.majorVersion == 3)
        })
        .await?;
        if !version_is_v3 {
            anyhow::bail!("StakeTableProxy version check failed after retries: expected V3");
        }
        tracing::info!(%v3_addr, "StakeTable successfully upgraded to V3");
    } else {
        anyhow::bail!("StakeTable V3 upgrade failed: {:?}", receipt);
    }

    Ok(receipt)
}

/// Upgrade the fee contract from V1.x.x to V1.0.1
/// This is for fee contracts owned by an EOA
pub async fn upgrade_fee_v1(
    provider: impl Provider,
    contracts: &mut Contracts,
) -> Result<TransactionReceipt> {
    tracing::info!("Upgrading FeeContract to FeeContractV1.0.1 with EOA admin");
    let Some(fee_contract_proxy_addr) = contracts.address(Contract::FeeContractProxy) else {
        anyhow::bail!("FeeContractProxy not found, can't upgrade")
    };

    let fee_contract_proxy = FeeContract::new(fee_contract_proxy_addr, &provider);

    let owner = fee_contract_proxy.owner().call().await?;
    if is_contract(&provider, owner).await? {
        anyhow::bail!(
            "FeeContract owner ({:#x}) is not an EOA, can't upgrade",
            owner
        );
    }

    let curr_version = fee_contract_proxy.getVersion().call().await?;
    if curr_version.majorVersion != 1 {
        anyhow::bail!(
            "Expected FeeContract V1 for upgrade, found V{}.{}.{}",
            curr_version.majorVersion,
            curr_version.minorVersion,
            curr_version.patchVersion
        );
    }

    let cached_fee_contract_addr = contracts.address(Contract::FeeContract);

    // For patch upgrades, we need to deploy a fresh implementation contract.
    // If FeeContract is already in the cache, the caller must unset it first
    // to make the redeployment requirement explicit.
    if let Some(cached_fee_contract_addr) = cached_fee_contract_addr {
        anyhow::bail!(
            "FeeContract implementation address is already set in cache ({:#x}). For patch \
             upgrades, the implementation must be redeployed. Please unset \
             ESPRESSO_FEE_CONTRACT_ADDRESS or remove it from the cache first.",
            cached_fee_contract_addr
        );
    }

    // now deploy the new implementation contract
    let new_fee_contract_addr = contracts
        .deploy(
            Contract::FeeContract,
            FeeContract::deploy_builder(&provider),
        )
        .await?;

    let receipt = fee_contract_proxy
        .upgradeToAndCall(new_fee_contract_addr, vec![].into())
        .send()
        .await?
        .get_receipt()
        .await
        .context("Failed to get upgrade transaction receipt")?;

    if receipt.inner.is_success() {
        let new_version = fee_contract_proxy.getVersion().call().await?;
        if new_version != (1, 0, 1).into() {
            anyhow::bail!(
                "Upgrade transaction succeeded but version is incorrect: V{}.{}.{} (expected \
                 V1.0.1). Proxy: {fee_contract_proxy_addr:#x}, New impl: \
                 {new_fee_contract_addr:#x}",
                new_version.majorVersion,
                new_version.minorVersion,
                new_version.patchVersion
            );
        }
        tracing::info!(
            proxy = %fee_contract_proxy_addr,
            impl = %new_fee_contract_addr,
            "FeeContract successfully upgraded to v1.0.1"
        );
    } else {
        anyhow::bail!("FeeContract upgrade failed: {:?}", receipt);
    }

    Ok(receipt)
}

/// Common logic for any Ownable contract to transfer ownership
pub async fn transfer_ownership(
    provider: impl Provider,
    target_contract: Contract,
    target_address: Address,
    new_owner: Address,
) -> Result<TransactionReceipt> {
    // Use OwnableUpgradeable interface for all Ownable contracts
    // This is more generic and maintainable than matching on each contract type
    let ownable = OwnableUpgradeable::new(target_address, &provider);

    // Verify the contract is actually Ownable by checking if we can read the owner
    let current_owner = ownable.owner().call().await.context(format!(
        "Contract at {target_address:#x} does not implement Ownable interface"
    ))?;

    tracing::info!(%target_contract, %target_address, current_owner = %current_owner, new_owner = %new_owner, "Transferring ownership of {target_contract}");

    let receipt = ownable
        .transferOwnership(new_owner)
        .send()
        .await?
        .get_receipt()
        .await?;

    let tx_hash = receipt.transaction_hash;
    tracing::info!(%receipt.gas_used, %tx_hash, "ownership transferred");
    Ok(receipt)
}

/// Grant DEFAULT_ADMIN_ROLE to a new admin for AccessControl-based contracts
/// This handles contracts like RewardClaim that use AccessControl instead of Ownable
pub async fn grant_admin_role(
    provider: impl Provider,
    target_contract: Contract,
    target_address: Address,
    new_admin: Address,
) -> Result<TransactionReceipt> {
    // Use AccessControlUpgradeable interface
    let access_control = AccessControlUpgradeable::new(target_address, &provider);

    // Verify the contract is actually AccessControl by checking if we can read roles
    let admin_role = access_control
        .DEFAULT_ADMIN_ROLE()
        .call()
        .await
        .context(format!(
            "Contract at {target_address:#x} does not implement AccessControl interface"
        ))?;

    // Check if new_admin already has the role (for logging purposes)
    let already_has_role = access_control.hasRole(admin_role, new_admin).call().await?;

    tracing::info!(
        %target_contract,
        %target_address,
        new_admin = %new_admin,
        already_has_role = %already_has_role,
        "Granting DEFAULT_ADMIN_ROLE for {target_contract}"
    );

    // For RewardClaim, grantRole handles the revoke of the previous admin internally
    let receipt = access_control
        .grantRole(admin_role, new_admin)
        .send()
        .await?
        .get_receipt()
        .await?;

    let tx_hash = receipt.transaction_hash;
    tracing::info!(%receipt.gas_used, %tx_hash, "admin role granted");
    Ok(receipt)
}

/// helper function to decide if the contract at given address `addr` is a proxy contract
pub async fn is_proxy_contract(provider: impl Provider, addr: Address) -> Result<bool> {
    // when the implementation address is not equal to zero, it's a proxy
    Ok(read_proxy_impl(provider, addr).await? != Address::default())
}

pub async fn read_proxy_impl(provider: impl Provider, addr: Address) -> Result<Address> {
    // confirm that the proxy_address is a proxy
    // using the implementation slot, 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc, which is the keccak-256 hash of "eip1967.proxy.implementation" subtracted by 1
    let impl_slot = U256::from_str_radix(
        "360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc",
        16,
    )?;

    // Use retry_until_true to verify storage is readable (non-zero address)
    let is_readable = retry_until_true("Read proxy implementation", || async {
        match provider.get_storage_at(addr, impl_slot).await {
            Ok(_) => {
                // storage is readable so return true
                Ok(true)
            },
            Err(e) => {
                tracing::debug!("Storage read failed (will retry): {}", e);
                Ok(false)
            },
        }
    })
    .await?;

    if !is_readable {
        anyhow::bail!(
            "Proxy implementation storage is not readable after retries at address {addr:#x}"
        );
    }

    // Final read to get the actual address (we know it's readable now)
    let storage = provider.get_storage_at(addr, impl_slot).await?;
    let impl_addr = Address::from_slice(&storage.to_be_bytes_vec()[12..]);

    Ok(impl_addr)
}

pub async fn is_contract(provider: impl Provider, address: Address) -> Result<bool> {
    if address == Address::ZERO {
        return Ok(false);
    }
    Ok(!provider.get_code_at(address).await?.is_empty())
}

pub async fn get_proxy_initialized_version(
    provider: impl Provider,
    proxy_addr: Address,
) -> Result<u8> {
    // From openzeppelin Initializable.sol, the initialized version slot is keccak256("openzeppelin.storage.Initializable");
    let slot: B256 = "0xf0c57e16840df040f15088dc2f81fe391c3923bec73e23a9662efc9c229c6a00"
        .parse()
        .context("Failed to parse OpenZeppelin Initializable slot")?;
    let value = provider.get_storage_at(proxy_addr, slot.into()).await?;
    let initialized = value.as_le_bytes()[0]; // `_initialized` is u8 stored in the last byte
    Ok(initialized)
}

/// Deploy and initialize the Ops Timelock contract
///
/// Parameters:
/// - `min_delay`: The minimum delay for operations
/// - `proposers`: The list of addresses that can propose
/// - `executors`: The list of addresses that can execute
/// - `admin`: The address that can perform admin actions
pub async fn deploy_ops_timelock(
    provider: impl Provider,
    contracts: &mut Contracts,
    min_delay: U256,
    proposers: Vec<Address>,
    executors: Vec<Address>,
    admin: Address,
) -> Result<Address> {
    tracing::info!(
        "OpsTimelock will be deployed with the following parameters: min_delay: {:?}, proposers: \
         {:?}, executors: {:?}, admin: {:?}",
        min_delay,
        proposers,
        executors,
        admin
    );
    let timelock_addr = contracts
        .deploy(
            Contract::OpsTimelock,
            OpsTimelock::deploy_builder(
                &provider,
                min_delay,
                proposers.clone(),
                executors.clone(),
                admin,
            ),
        )
        .await?;

    // Verify deployment
    let timelock = OpsTimelock::new(timelock_addr, &provider);

    // Verify initialization parameters
    assert_eq!(timelock.getMinDelay().call().await?, min_delay);
    assert!(
        timelock
            .hasRole(timelock.PROPOSER_ROLE().call().await?, proposers[0])
            .call()
            .await?
    );
    assert!(
        timelock
            .hasRole(timelock.EXECUTOR_ROLE().call().await?, executors[0])
            .call()
            .await?
    );

    // test that the admin is in the default admin role where DEFAULT_ADMIN_ROLE = 0x00
    let default_admin_role = U256::ZERO;
    assert!(
        timelock
            .hasRole(default_admin_role.into(), admin)
            .call()
            .await?
    );

    Ok(timelock_addr)
}

/// Deploy and initialize the Safe Exit Timelock contract
///
/// Parameters:
/// - `min_delay`: The minimum delay for operations
/// - `proposers`: The list of addresses that can propose
/// - `executors`: The list of addresses that can execute
/// - `admin`: The address that can perform admin actions
pub async fn deploy_safe_exit_timelock(
    provider: impl Provider,
    contracts: &mut Contracts,
    min_delay: U256,
    proposers: Vec<Address>,
    executors: Vec<Address>,
    admin: Address,
) -> Result<Address> {
    tracing::info!(
        "SafeExitTimelock will be deployed with the following parameters: min_delay: {:?}, \
         proposers: {:?}, executors: {:?}, admin: {:?}",
        min_delay,
        proposers,
        executors,
        admin
    );
    let timelock_addr = contracts
        .deploy(
            Contract::SafeExitTimelock,
            SafeExitTimelock::deploy_builder(
                &provider,
                min_delay,
                proposers.clone(),
                executors.clone(),
                admin,
            ),
        )
        .await?;

    // Verify deployment
    let timelock = SafeExitTimelock::new(timelock_addr, &provider);

    // Verify initialization parameters
    assert_eq!(timelock.getMinDelay().call().await?, min_delay);
    assert!(
        timelock
            .hasRole(timelock.PROPOSER_ROLE().call().await?, proposers[0])
            .call()
            .await?
    );
    assert!(
        timelock
            .hasRole(timelock.EXECUTOR_ROLE().call().await?, executors[0])
            .call()
            .await?
    );

    // test that the admin is in the default admin role where DEFAULT_ADMIN_ROLE = 0x00
    let default_admin_role = U256::ZERO;
    assert!(
        timelock
            .hasRole(default_admin_role.into(), admin)
            .call()
            .await?
    );

    Ok(timelock_addr)
}

/// Encode a function call with the given signature and arguments
///
/// Parameters:
/// - `signature`: e.g. `"transfer(address,uint256)"`
/// - `args`: Solidity typed arguments as `Vec<&str>`
///
/// Returns:
/// - Full calldata: selector + encoded arguments
pub fn encode_function_call(signature: &str, args: Vec<String>) -> Result<Bytes> {
    let func = Function::parse(signature)?;

    // Check if argument count matches the function signature
    if args.len() != func.inputs.len() {
        anyhow::bail!(
            "Mismatch between argument count ({}) and parameter count ({})",
            args.len(),
            func.inputs.len()
        );
    }

    // Parse argument values using the function's parameter types directly
    let arg_values: Vec<DynSolValue> =
        func.inputs
            .iter()
            .enumerate()
            .map(|(i, param)| {
                let arg_str = &args[i];
                let dyn_type: DynSolType =
                    param.ty.to_string().parse().map_err(|e| {
                        anyhow!("Failed to parse parameter type '{}': {}", param.ty, e)
                    })?;
                dyn_type.coerce_str(arg_str).map_err(|e| {
                    anyhow!(
                        "Failed to coerce argument '{}' to type '{}': {}",
                        arg_str,
                        param.ty,
                        e
                    )
                })
            })
            .collect::<Result<Vec<_>>>()?;

    let encoded_input = func.abi_encode_input(&arg_values)?;
    let data = Bytes::from(encoded_input);
    Ok(data)
}

/// retry helper for checking state after transactions
/// Retries up to 5 times with exponential backoff (500ms, 1s, 2s, 4s, 8s)
/// Parameters:
/// - `check_name`: the name of the check
/// - `check_fn`: the function to check, must return `Result<bool>`
///
/// Returns:
/// - `Ok(true)` if the check passed, `Ok(false)`
pub async fn retry_until_true<F, Fut>(check_name: &str, mut check_fn: F) -> Result<bool>
where
    F: FnMut() -> Fut,
    Fut: std::future::Future<Output = Result<bool>>,
{
    for attempt in 0..MAX_RETRY_ATTEMPTS {
        match check_fn().await {
            Ok(true) => return Ok(true),
            Ok(false) | Err(_) if attempt < MAX_RETRY_ATTEMPTS - 1 => {
                let delay_ms = RETRY_INITIAL_DELAY_MS * (1 << attempt);
                tracing::warn!("{} not ready, retrying in {}ms...", check_name, delay_ms);
                tokio::time::sleep(Duration::from_millis(delay_ms)).await;
            },
            Ok(false) => {
                tracing::error!(
                    "{} not ready after {} attempts, returning false",
                    check_name,
                    MAX_RETRY_ATTEMPTS
                );
                return Ok(false);
            },
            Err(e) => {
                tracing::error!(
                    "{} not ready after {} attempts,  (treating as not ready): {e:#}",
                    check_name,
                    MAX_RETRY_ATTEMPTS
                );
                return Ok(false);
            },
        }
    }
    // should never reach here, but defensive fallback to return false
    Ok(false)
}

#[cfg(test)]
mod tests {
    use std::sync::Arc;

    use alloy::{
        node_bindings::{Anvil, AnvilInstance},
        primitives::utils::parse_ether,
        providers::{ProviderBuilder, ext::AnvilApi, layers::AnvilProvider},
        sol_types::SolValue,
    };
    use espresso_types::testing::TestValidator;
    use hotshot_contract_adapter::sol_types::{FeeContract, StakeTableV2, StakeTableV3};

    use super::*;
    use crate::{
        Contracts,
        builder::DeployerArgsBuilder,
        impersonate_filler::ImpersonateFiller,
        proposals::{
            multisig::{
                LightClientV2UpgradeParams, MultisigOwnerCheck, StakeTableV2UpgradeParams,
                TransferOwnershipParams, transfer_ownership_from_multisig_to_timelock,
                upgrade_esp_token_v2_multisig_owner, upgrade_fee_contract_multisig_owner,
                upgrade_light_client_v2_multisig_owner, upgrade_stake_table_v2_multisig_owner,
            },
            timelock::{
                TimelockOperationParams, TimelockOperationPayload, TimelockOperationType,
                derive_timelock_address_from_contract_type, perform_timelock_operation,
            },
        },
    };

    trait ProviderBuilderExt: Sized {
        fn connect_anvil_with_l1_client(
            self,
        ) -> Result<(AnvilInstance, HttpProviderWithWallet, L1Client)> {
            let anvil = Anvil::new().spawn();
            let wallet = anvil.wallet().unwrap();
            let provider = ProviderBuilder::new()
                .wallet(wallet)
                .connect_http(anvil.endpoint_url());
            let l1_client = L1Client::anvil(&anvil)?;
            Ok((anvil, provider, l1_client))
        }
    }

    impl<L, F, N> ProviderBuilderExt for ProviderBuilder<L, F, N> {}

    #[test_log::test(tokio::test)]
    async fn test_is_contract() -> Result<(), anyhow::Error> {
        let provider = ProviderBuilder::new().connect_anvil_with_wallet();

        // test with zero address returns false
        let zero_address = Address::ZERO;
        assert!(!is_contract(&provider, zero_address).await?);

        // Test with a non-contract address (e.g., a random address)
        let random_address = Address::random();
        assert!(!is_contract(&provider, random_address).await?);

        // Deploy a contract and test with its address
        let fee_contract = FeeContract::deploy(&provider).await?;
        let contract_address = *fee_contract.address();
        assert!(is_contract(&provider, contract_address).await?);

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_is_proxy_contract() -> Result<()> {
        let provider = ProviderBuilder::new().connect_anvil_with_wallet();
        let deployer = provider.get_accounts().await?[0];

        let fee_contract = FeeContract::deploy(&provider).await?;
        let init_data = fee_contract.initialize(deployer).calldata().clone();
        let proxy =
            ERC1967Proxy::deploy(&provider, *fee_contract.address(), init_data.clone()).await?;

        assert!(is_proxy_contract(&provider, *proxy.address()).await?);
        assert!(!is_proxy_contract(&provider, *fee_contract.address()).await?);
        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_deploy_light_client() -> Result<()> {
        let provider = ProviderBuilder::new().connect_anvil_with_wallet();
        let mut contracts = Contracts::new();

        // first test if LightClientMock can be deployed
        let mock_lc_addr = deploy_light_client_contract(&provider, &mut contracts, true).await?;
        let pv_addr = contracts.address(Contract::PlonkVerifier).unwrap();

        // then deploy the actual LightClient
        let lc_addr = deploy_light_client_contract(&provider, &mut contracts, false).await?;
        assert_ne!(mock_lc_addr, lc_addr);
        // check that we didn't redeploy PlonkVerifier again, instead use existing ones
        assert_eq!(contracts.address(Contract::PlonkVerifier).unwrap(), pv_addr);
        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_deploy_mock_light_client_proxy() -> Result<()> {
        let provider = ProviderBuilder::new().connect_anvil_with_wallet();
        let mut contracts = Contracts::new();

        // prepare `initialize()` input
        let genesis_state = LightClientStateSol::dummy_genesis();
        let genesis_stake = StakeTableStateSol::dummy_genesis();
        let admin = provider.get_accounts().await?[0];
        let prover = admin;

        let lc_proxy_addr = deploy_light_client_proxy(
            &provider,
            &mut contracts,
            true, // is_mock = true
            genesis_state.clone(),
            genesis_stake.clone(),
            admin,
            Some(prover),
        )
        .await?;

        // check initialization is correct
        let lc = LightClientMock::new(lc_proxy_addr, &provider);
        let finalized_state: LightClientStateSol = lc.finalizedState().call().await?.into();
        assert_eq!(
            genesis_state.abi_encode_params(),
            finalized_state.abi_encode_params()
        );
        // mock set the state
        let new_state = LightClientStateSol {
            viewNum: 10,
            blockHeight: 10,
            blockCommRoot: U256::from(42),
        };
        lc.setFinalizedState(new_state.clone().into())
            .send()
            .await?
            .watch()
            .await?;
        let finalized_state: LightClientStateSol = lc.finalizedState().call().await?.into();
        assert_eq!(
            new_state.abi_encode_params(),
            finalized_state.abi_encode_params()
        );

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_deploy_light_client_proxy() -> Result<()> {
        let provider = ProviderBuilder::new().connect_anvil_with_wallet();
        let mut contracts = Contracts::new();

        // prepare `initialize()` input
        let genesis_state = LightClientStateSol::dummy_genesis();
        let genesis_stake = StakeTableStateSol::dummy_genesis();
        let admin = provider.get_accounts().await?[0];
        let prover = Address::random();

        let lc_proxy_addr = deploy_light_client_proxy(
            &provider,
            &mut contracts,
            false,
            genesis_state.clone(),
            genesis_stake.clone(),
            admin,
            Some(prover),
        )
        .await?;

        // check initialization is correct
        let lc = LightClient::new(lc_proxy_addr, &provider);
        let finalized_state = lc.finalizedState().call().await?;
        assert_eq!(finalized_state.viewNum, genesis_state.viewNum);
        assert_eq!(finalized_state.blockHeight, genesis_state.blockHeight);
        assert_eq!(&finalized_state.blockCommRoot, &genesis_state.blockCommRoot);

        let fetched_stake = lc.genesisStakeTableState().call().await?;
        assert_eq!(fetched_stake.blsKeyComm, genesis_stake.blsKeyComm);
        assert_eq!(fetched_stake.schnorrKeyComm, genesis_stake.schnorrKeyComm);
        assert_eq!(fetched_stake.amountComm, genesis_stake.amountComm);
        assert_eq!(fetched_stake.threshold, genesis_stake.threshold);

        let fetched_prover = lc.permissionedProver().call().await?;
        assert_eq!(fetched_prover, prover);

        // test transfer ownership to multisig
        let multisig = Address::random();
        let _receipt = transfer_ownership(
            &provider,
            Contract::LightClientProxy,
            lc_proxy_addr,
            multisig,
        )
        .await?;
        assert_eq!(lc.owner().call().await?, multisig);

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_deploy_fee_contract_proxy() -> Result<()> {
        let provider = ProviderBuilder::new().connect_anvil_with_wallet();
        let mut contracts = Contracts::new();
        let admin = provider.get_accounts().await?[0];
        let alice = Address::random();

        let fee_proxy_addr = deploy_fee_contract_proxy(&provider, &mut contracts, alice).await?;

        // check initialization is correct
        let fee = FeeContract::new(fee_proxy_addr, &provider);
        let fetched_owner = fee.owner().call().await?;
        assert_eq!(fetched_owner, alice);

        // redeploy new fee with admin being the owner
        contracts = Contracts::new();
        let fee_proxy_addr = deploy_fee_contract_proxy(&provider, &mut contracts, admin).await?;
        let fee = FeeContract::new(fee_proxy_addr, &provider);

        // test transfer ownership to multisig
        let multisig = Address::random();
        let _receipt = transfer_ownership(
            &provider,
            Contract::FeeContractProxy,
            fee_proxy_addr,
            multisig,
        )
        .await?;
        assert_eq!(fee.owner().call().await?, multisig);

        Ok(())
    }

    async fn test_upgrade_light_client_to_v2_helper(is_mock: bool) -> Result<()> {
        let provider = ProviderBuilder::new().connect_anvil_with_wallet();
        let mut contracts = Contracts::new();
        let blocks_per_epoch = 10; // for test
        let epoch_start_block = 22;

        // prepare `initialize()` input
        let genesis_state = LightClientStateSol::dummy_genesis();
        let genesis_stake = StakeTableStateSol::dummy_genesis();
        let admin = provider.get_accounts().await?[0];
        let prover = Address::random();

        // deploy proxy and V1
        let lc_proxy_addr = deploy_light_client_proxy(
            &provider,
            &mut contracts,
            false,
            genesis_state.clone(),
            genesis_stake.clone(),
            admin,
            Some(prover),
        )
        .await?;

        let state_history_retention_period = LightClient::new(lc_proxy_addr, &provider)
            .stateHistoryRetentionPeriod()
            .call()
            .await?;

        // then upgrade to v2
        upgrade_light_client_v2(
            &provider,
            &mut contracts,
            is_mock,
            blocks_per_epoch,
            epoch_start_block,
        )
        .await?;

        // test correct v1 state persistence
        let lc = LightClientV2::new(lc_proxy_addr, &provider);
        let finalized_state: LightClientStateSol = lc.finalizedState().call().await?.into();
        assert_eq!(
            genesis_state.abi_encode_params(),
            finalized_state.abi_encode_params()
        );
        // test new v2 state
        let next_stake: StakeTableStateSol = lc.votingStakeTableState().call().await?.into();
        assert_eq!(
            genesis_stake.abi_encode_params(),
            next_stake.abi_encode_params()
        );
        assert_eq!(lc.getVersion().call().await?.majorVersion, 2);
        assert_eq!(lc.blocksPerEpoch().call().await?, blocks_per_epoch);
        assert_eq!(lc.epochStartBlock().call().await?, epoch_start_block);
        assert_eq!(
            lc.stateHistoryRetentionPeriod().call().await?,
            state_history_retention_period
        );

        // test mock-specific functions
        if is_mock {
            // recast to mock
            let lc_mock = LightClientV2Mock::new(lc_proxy_addr, &provider);
            let new_blocks_per_epoch = blocks_per_epoch + 10;
            lc_mock
                .setBlocksPerEpoch(new_blocks_per_epoch)
                .send()
                .await?
                .watch()
                .await?;
            assert_eq!(new_blocks_per_epoch, lc_mock.blocksPerEpoch().call().await?);
        }
        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_upgrade_light_client_to_v2() -> Result<()> {
        test_upgrade_light_client_to_v2_helper(false).await
    }

    #[test_log::test(tokio::test)]
    async fn test_upgrade_mock_light_client_v2() -> Result<()> {
        test_upgrade_light_client_to_v2_helper(true).await
    }

    #[test_log::test(tokio::test)]
    async fn test_fetch_stake_table_for_stake_table_storage_migration() -> Result<()> {
        let (_anvil, provider, l1_client) =
            ProviderBuilder::new().connect_anvil_with_l1_client()?;
        let mut contracts = Contracts::new();
        let owner = provider.get_accounts().await?[0];

        let token_addr = deploy_token_proxy(
            &provider,
            &mut contracts,
            owner,
            owner,
            U256::from(10_000_000u64),
            "Test Token",
            "TEST",
        )
        .await?;
        let lc_addr = deploy_light_client_contract(&provider, &mut contracts, false).await?;
        let exit_escrow_period = U256::from(DEFAULT_EXIT_ESCROW_PERIOD_SECONDS);

        let stake_table_proxy_addr = deploy_stake_table_proxy(
            &provider,
            &mut contracts,
            token_addr,
            lc_addr,
            exit_escrow_period,
            owner,
        )
        .await?;

        // Use V3 interface even for older contracts (V3 ABI is a superset)
        let stake_table = StakeTableV3::new(stake_table_proxy_addr, &provider);

        let accounts = provider.get_accounts().await?;
        let validators = [
            TestValidator::random_update_keys(accounts[4], 1234),
            TestValidator::random_update_keys(accounts[5], 4567),
        ];

        for validator in validators.iter() {
            let receipt = stake_table
                .registerValidator(
                    validator.bls_vk,
                    validator.schnorr_vk,
                    validator.bls_sig.into(),
                    validator.commission,
                )
                .from(validator.account)
                .send()
                .await?
                .get_receipt()
                .await?;
            assert!(receipt.status());
        }

        let delegators = [
            (
                accounts[0],
                validators[0].account,
                parse_ether("10").unwrap(),
            ),
            (
                accounts[1],
                validators[1].account,
                parse_ether("10").unwrap(),
            ),
            (
                accounts[2],
                validators[0].account,
                parse_ether("100").unwrap(),
            ),
        ];

        let token = EspToken::new(token_addr, &provider);

        for (delegator, validator, amount) in delegators.iter() {
            let receipt = token
                .transfer(*delegator, *amount)
                .from(Address::from(*owner))
                .send()
                .await?
                .get_receipt()
                .await?;
            assert!(receipt.status());

            let receipt = token
                .approve(stake_table_proxy_addr, *amount)
                .from(*delegator)
                .send()
                .await?
                .get_receipt()
                .await?;
            assert!(receipt.status());

            let receipt = stake_table
                .delegate(*validator, *amount)
                .from(*delegator)
                .send()
                .await?
                .get_receipt()
                .await?;
            assert!(receipt.status());
        }

        let receipt = stake_table
            .deregisterValidator()
            .from(validators[1].account)
            .send()
            .await?
            .get_receipt()
            .await?;
        assert!(receipt.status());

        let undelegations = [
            (
                accounts[0],
                validators[0].account,
                parse_ether("5").unwrap(),
            ),
            (
                accounts[2],
                validators[0].account,
                parse_ether("3").unwrap(),
            ),
        ];

        for (delegator_addr, validator_addr, amount) in undelegations.iter() {
            let receipt = stake_table
                .undelegate(*validator_addr, *amount)
                .from(*delegator_addr)
                .send()
                .await?
                .get_receipt()
                .await?;
            assert!(receipt.status());
        }

        let (fetched_active_stake, fetched_commissions) =
            fetch_stake_table_for_stake_table_storage_migration(
                l1_client.clone(),
                stake_table_proxy_addr,
            )
            .await?;

        let expected_active_stake: U256 = delegators
            .iter()
            .map(|(_, _, amount)| *amount)
            .sum::<U256>()
            - delegators
                .iter()
                .filter(|(_, validator, _)| *validator == validators[1].account)
                .map(|(_, _, amount)| *amount)
                .sum::<U256>()
            - undelegations
                .iter()
                .map(|(_, _, amount)| *amount)
                .sum::<U256>();

        assert_eq!(fetched_active_stake, expected_active_stake);
        assert!(fetched_active_stake <= token.balanceOf(stake_table_proxy_addr).call().await?);

        assert_eq!(fetched_commissions.len(), 1);
        assert_eq!(fetched_commissions[0].validator, validators[0].account);
        assert_eq!(fetched_commissions[0].commission, validators[0].commission);

        // Migration only applies to V1 contract
        let stake_table_v2 = StakeTableV2::deploy(&provider).await?;
        let err = fetch_stake_table_for_stake_table_storage_migration(
            l1_client.clone(),
            *stake_table_v2.address(),
        )
        .await
        .unwrap_err();
        assert!(err.to_string().contains("Expected StakeTable V1"));

        Ok(())
    }

    /// Check that we can fetch stake table data on sepolia for the migration.
    ///
    /// Assumes an infura RPC is used, otherwise fetching may hit other rate limits.
    ///
    /// env RPC_URL=... cargo test -p espresso-contract-deployer -- --ignored test_fetch_stake_table_sepolia
    #[ignore]
    #[test_log::test(tokio::test)]
    async fn test_fetch_stake_table_sepolia() -> Result<()> {
        let rpc_url: Url = std::env::var("RPC_URL")
            .expect("RPC_URL environment variable not set")
            .parse()?;
        let provider = ProviderBuilder::new().connect_http(rpc_url.clone());
        let l1_client = L1Client::new(vec![rpc_url])?;

        // Decaf / sepolia stake table address
        let stake_table_address: Address = "0x40304FbE94D5E7D1492Dd90c53a2D63E8506a037".parse()?;
        let (fetched_active_stake, fetched_commissions) =
            fetch_stake_table_for_stake_table_storage_migration(l1_client, stake_table_address)
                .await?;

        assert!(!fetched_commissions.is_empty());
        assert!(!fetched_active_stake.is_zero());

        println!(
            "Fetched {} commissions from Sepolia StakeTable",
            fetched_commissions.len()
        );
        for commission in &fetched_commissions {
            println!(
                "  Validator: {}, Commission: {}",
                commission.validator, commission.commission
            );
        }
        println!("Fetched active stake: {}", fetched_active_stake);

        let pauser = Address::random();
        let admin = Address::random();
        let init_v2_calldata = StakeTableV2::new(stake_table_address, &provider)
            .initializeV2(pauser, admin, fetched_active_stake, fetched_commissions)
            .calldata()
            .clone();
        println!("Calldata size: {} bytes", init_v2_calldata.len());

        // The max calldata size is 128 kB per tx, but at the time of writing we
        // only need about 7 kB therefore applying a stricter limit of 32 kB
        assert!(init_v2_calldata.len() < 32 * 1024);
        Ok(())
    }

    impl Contracts {
        fn insert(&mut self, name: Contract, address: Address) -> Option<Address> {
            self.addresses.insert(name, address)
        }
    }

    /// Fork test to test if we can upgrade the decaf stake table from V1 to V2
    /// This test forks Sepolia (where decaf runs) using anvil, fetches existing commissions,
    /// impersonates the proxy owner, and performs the upgrade.
    ///
    /// Assumes an infura RPC is used, otherwise fetching commissions may hit other rate limits.
    ///
    /// env RPC_URL=... cargo test -p espresso-contract-deployer -- --ignored test_upgrade_decaf_stake_table_fork
    #[ignore]
    #[test_log::test(tokio::test)]
    async fn test_upgrade_decaf_stake_table_fork() -> Result<()> {
        let rpc_url = std::env::var("RPC_URL").expect("RPC_URL environment variable not set");

        // Decaf / sepolia stake table address
        let stake_table_address: Address = "0x40304FbE94D5E7D1492Dd90c53a2D63E8506a037".parse()?;
        let anvil = Anvil::new()
            .fork(rpc_url)
            .arg("--retries")
            .arg("20")
            .spawn();

        let provider = ProviderBuilder::new().connect_http(anvil.endpoint().parse()?);
        let proxy = StakeTable::new(stake_table_address, &provider);
        let proxy_owner = proxy.owner().call().await?;
        tracing::info!("Proxy owner address: {proxy_owner:#x}");

        // Enable impersonation for the proxy owner
        let provider = ProviderBuilder::new()
            .filler(ImpersonateFiller::new(proxy_owner))
            .connect_http(anvil.endpoint().parse()?);
        let l1_client = L1Client::anvil(&anvil)?;
        let anvil_arc = Arc::new(anvil);
        let anvil_provider = AnvilProvider::new(provider.clone(), anvil_arc);
        anvil_provider.anvil_auto_impersonate_account(true).await?;
        anvil_provider
            .anvil_set_balance(proxy_owner, parse_ether("100")?)
            .await?;

        // We need a Contracts instance with proxy deployed
        let mut contracts = Contracts::new();
        contracts.insert(Contract::StakeTableProxy, stake_table_address);
        let pauser = Address::random();
        let admin = proxy_owner;

        upgrade_stake_table_v2(&provider, l1_client, &mut contracts, pauser, admin).await?;
        Ok(())
    }

    async fn test_upgrade_light_client_to_v3_helper(options: UpgradeTestOptions) -> Result<()> {
        let provider = ProviderBuilder::new().connect_anvil_with_wallet();
        let mut contracts = Contracts::new();
        let blocks_per_epoch = 10; // for test
        let epoch_start_block = 22;

        // prepare `initialize()` input
        let genesis_state = LightClientStateSol::dummy_genesis();
        let genesis_stake = StakeTableStateSol::dummy_genesis();
        let admin = provider.get_accounts().await?[0];
        let prover = Address::random();

        // deploy proxy and V1
        let lc_proxy_addr = deploy_light_client_proxy(
            &provider,
            &mut contracts,
            false,
            genesis_state.clone(),
            genesis_stake.clone(),
            admin,
            Some(prover),
        )
        .await?;

        // first upgrade to v2
        upgrade_light_client_v2(
            &provider,
            &mut contracts,
            options.is_mock,
            blocks_per_epoch,
            epoch_start_block,
        )
        .await?;

        // then upgrade to v3
        upgrade_light_client_v3(&provider, &mut contracts, options.is_mock).await?;

        // test correct v1 and v2 state persistence
        let lc = LightClientV3::new(lc_proxy_addr, &provider);
        let finalized_state: LightClientStateSol = lc.finalizedState().call().await?.into();
        assert_eq!(
            genesis_state.abi_encode_params(),
            finalized_state.abi_encode_params()
        );

        // test v2 state persistence
        let next_stake: StakeTableStateSol = lc.votingStakeTableState().call().await?.into();
        assert_eq!(
            genesis_stake.abi_encode_params(),
            next_stake.abi_encode_params()
        );

        // test v3 specific properties
        assert_eq!(lc.getVersion().call().await?.majorVersion, 3);

        // V3 inherits blocks_per_epoch and epoch_start_block from V2
        let lc_as_v2 = LightClientV2::new(lc_proxy_addr, &provider);
        assert_eq!(lc_as_v2.blocksPerEpoch().call().await?, blocks_per_epoch);
        assert_eq!(lc_as_v2.epochStartBlock().call().await?, epoch_start_block);

        // test mock-specific functions
        if options.is_mock {
            // recast to mock
            let lc_mock = LightClientV3Mock::new(lc_proxy_addr, &provider);
            // Test that mock-specific functions work
            let new_blocks_per_epoch = blocks_per_epoch + 10;
            lc_mock
                .setBlocksPerEpoch(new_blocks_per_epoch)
                .send()
                .await?
                .watch()
                .await?;
            assert_eq!(new_blocks_per_epoch, lc_mock.blocksPerEpoch().call().await?);
        }
        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_upgrade_light_client_to_v3() -> Result<()> {
        test_upgrade_light_client_to_v3_helper(UpgradeTestOptions {
            is_mock: false,
            upgrade_count: UpgradeCount::Once,
        })
        .await
    }

    #[test_log::test(tokio::test)]
    async fn test_upgrade_mock_light_client_v3() -> Result<()> {
        test_upgrade_light_client_to_v3_helper(UpgradeTestOptions {
            is_mock: true,
            upgrade_count: UpgradeCount::Once,
        })
        .await
    }

    #[derive(Debug, Clone, Copy)]
    pub enum UpgradeCount {
        Once,
        Twice,
    }

    #[derive(Debug, Clone, Copy)]
    pub struct UpgradeTestOptions {
        pub is_mock: bool,
        pub upgrade_count: UpgradeCount,
    }
    // This test is used to test the upgrade of the LightClientProxy via the multisig wallet
    // It only tests the upgrade proposal via the typescript script and thus requires the upgrade proposal to be sent to a real network
    // However, the contracts are deployed on anvil, so the test will pass even if the upgrade proposal is not executed
    // The test assumes that there is a file .env.deployer.rs.test in the root directory:
    // Ensure that the private key has proposal rights on the Safe Multisig Wallet and the SDK supports the network
    async fn test_upgrade_light_client_to_v2_multisig_owner_helper(
        options: UpgradeTestOptions,
    ) -> Result<()> {
        let multisig_admin = Address::random();
        let mnemonic = "test test test test test test test test test test test junk".to_string();
        let account_index = 0u32;
        let anvil = Anvil::default().spawn();

        let mut contracts = Contracts::new();
        let blocks_per_epoch = 10; // for test
        let epoch_start_block = 22;
        let admin_signer = MnemonicBuilder::<English>::default()
            .phrase(mnemonic)
            .index(account_index)
            .expect("wrong mnemonic or index")
            .build()?;
        let admin = admin_signer.address();
        let provider = ProviderBuilder::new()
            .wallet(admin_signer)
            .connect(&anvil.endpoint())
            .await?;

        // prepare `initialize()` input
        let genesis_state = LightClientStateSol::dummy_genesis();
        let genesis_stake = StakeTableStateSol::dummy_genesis();

        let prover = Address::random();

        // deploy proxy and V1
        let lc_proxy_addr = deploy_light_client_proxy(
            &provider,
            &mut contracts,
            false,
            genesis_state.clone(),
            genesis_stake.clone(),
            admin,
            Some(prover),
        )
        .await?;
        if matches!(options.upgrade_count, UpgradeCount::Twice) {
            // upgrade to v2
            upgrade_light_client_v2(
                &provider,
                &mut contracts,
                options.is_mock,
                blocks_per_epoch,
                epoch_start_block,
            )
            .await?;
        }

        // transfer ownership to multisig
        let _receipt = transfer_ownership(
            &provider,
            Contract::LightClientProxy,
            lc_proxy_addr,
            multisig_admin,
        )
        .await?;
        let lc = LightClient::new(lc_proxy_addr, &provider);
        assert_eq!(lc.owner().call().await?, multisig_admin);

        // then encode upgrade calldata for the multisig wallet
        let calldata = upgrade_light_client_v2_multisig_owner(
            &provider,
            &mut contracts,
            LightClientV2UpgradeParams {
                blocks_per_epoch,
                epoch_start_block,
            },
            options.is_mock,
            MultisigOwnerCheck::Skip,
        )
        .await?;
        tracing::info!(
            "Encoded calldata for LightClientProxy upgrade: to={:#x}, data={}",
            calldata.to,
            calldata.data
        );
        // Calldata target is the proxy
        assert_eq!(calldata.to, lc_proxy_addr);
        // Calldata is non-empty (encodes upgradeToAndCall)
        assert!(!calldata.data.is_empty());

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_upgrade_light_client_to_v2_multisig_owner() -> Result<()> {
        test_upgrade_light_client_to_v2_multisig_owner_helper(UpgradeTestOptions {
            is_mock: false,
            upgrade_count: UpgradeCount::Once,
        })
        .await
    }

    // We expect no init data for the second upgrade because the proxy was already initialized
    #[test_log::test(tokio::test)]
    async fn test_upgrade_light_client_to_v2_twice_multisig_owner() -> Result<()> {
        test_upgrade_light_client_to_v2_multisig_owner_helper(UpgradeTestOptions {
            is_mock: false,
            upgrade_count: UpgradeCount::Twice,
        })
        .await
    }

    #[test_log::test(tokio::test)]
    async fn test_deploy_token_proxy() -> Result<()> {
        let provider = ProviderBuilder::new().connect_anvil_with_wallet();
        let mut contracts = Contracts::new();

        let init_recipient = provider.get_accounts().await?[0];
        let rand_owner = Address::random();
        let initial_supply = U256::from(3590000000u64);
        let name = "Espresso";
        let symbol = "ESP";

        let addr = deploy_token_proxy(
            &provider,
            &mut contracts,
            rand_owner,
            init_recipient,
            initial_supply,
            name,
            symbol,
        )
        .await?;
        let token = EspToken::new(addr, &provider);

        assert_eq!(token.owner().call().await?, rand_owner);
        let total_supply = token.totalSupply().call().await?;
        assert_eq!(
            total_supply,
            parse_ether(&initial_supply.to_string()).unwrap()
        );
        assert_eq!(token.balanceOf(init_recipient).call().await?, total_supply);
        assert_eq!(token.name().call().await?, name);
        assert_eq!(token.symbol().call().await?, symbol);

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_deploy_stake_table_proxy() -> Result<()> {
        let provider = ProviderBuilder::new().connect_anvil_with_wallet();
        let mut contracts = Contracts::new();

        // deploy token
        let init_recipient = provider.get_accounts().await?[0];
        let token_owner = Address::random();
        let token_name = "Espresso";
        let token_symbol = "ESP";
        let initial_supply = U256::from(3590000000u64);
        let token_addr = deploy_token_proxy(
            &provider,
            &mut contracts,
            token_owner,
            init_recipient,
            initial_supply,
            token_name,
            token_symbol,
        )
        .await?;

        // deploy light client proxy
        let lc_proxy_addr = deploy_light_client_proxy(
            &provider,
            &mut contracts,
            false,
            LightClientStateSol::dummy_genesis(),
            StakeTableStateSol::dummy_genesis(),
            init_recipient,
            Some(init_recipient),
        )
        .await?;

        // deploy stake table
        let exit_escrow_period = U256::from(DEFAULT_EXIT_ESCROW_PERIOD_SECONDS);
        let owner = init_recipient;
        let stake_table_addr = deploy_stake_table_proxy(
            &provider,
            &mut contracts,
            token_addr,
            lc_proxy_addr,
            exit_escrow_period,
            owner,
        )
        .await?;
        let stake_table = StakeTable::new(stake_table_addr, &provider);

        assert_eq!(
            stake_table.exitEscrowPeriod().call().await?,
            exit_escrow_period
        );
        assert_eq!(stake_table.owner().call().await?, owner);
        assert_eq!(stake_table.token().call().await?, token_addr);
        assert_eq!(stake_table.lightClient().call().await?, lc_proxy_addr);
        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_upgrade_stake_table_v2() -> Result<()> {
        let (_anvil, provider, l1_client) =
            ProviderBuilder::new().connect_anvil_with_l1_client()?;
        let mut contracts = Contracts::new();

        // deploy token
        let init_recipient = provider.get_accounts().await?[0];
        let token_owner = Address::random();
        let token_name = "Espresso";
        let token_symbol = "ESP";
        let initial_supply = U256::from(3590000000u64);
        let token_addr = deploy_token_proxy(
            &provider,
            &mut contracts,
            token_owner,
            init_recipient,
            initial_supply,
            token_name,
            token_symbol,
        )
        .await?;

        // deploy light client proxy
        let lc_proxy_addr = deploy_light_client_proxy(
            &provider,
            &mut contracts,
            false,
            LightClientStateSol::dummy_genesis(),
            StakeTableStateSol::dummy_genesis(),
            init_recipient,
            Some(init_recipient),
        )
        .await?;

        // deploy stake table
        let exit_escrow_period = U256::from(DEFAULT_EXIT_ESCROW_PERIOD_SECONDS);
        let owner = init_recipient;
        let stake_table_addr = deploy_stake_table_proxy(
            &provider,
            &mut contracts,
            token_addr,
            lc_proxy_addr,
            exit_escrow_period,
            owner,
        )
        .await?;
        let stake_table_v1 = StakeTable::new(stake_table_addr, &provider);
        assert_eq!(stake_table_v1.getVersion().call().await?, (1, 0, 0).into());

        // snapshot for later patch upgrade, the upgrade will skip the v2
        // deployment if contracts already contains a v2
        let mut contracts_v1 = contracts.clone();

        // upgrade to v2
        let pauser = Address::random();
        upgrade_stake_table_v2(&provider, l1_client.clone(), &mut contracts, pauser, owner).await?;

        let stake_table_v2 = StakeTableV2::new(stake_table_addr, &provider);

        assert_eq!(stake_table_v2.getVersion().call().await?, (2, 0, 0).into());
        assert_eq!(stake_table_v2.owner().call().await?, owner);
        assert_eq!(stake_table_v2.token().call().await?, token_addr);
        assert_eq!(stake_table_v2.lightClient().call().await?, lc_proxy_addr);

        // get pauser role
        let pauser_role = stake_table_v2.PAUSER_ROLE().call().await?;
        assert!(
            stake_table_v2.hasRole(pauser_role, pauser).call().await?,
            "pauser should have PAUSER_ROLE"
        );

        // get admin role
        let admin_role = stake_table_v2.DEFAULT_ADMIN_ROLE().call().await?;
        assert!(stake_table_v2.hasRole(admin_role, owner).call().await?,);

        // ensure we can upgrade (again) to a V2 patch version
        let current_impl = read_proxy_impl(&provider, stake_table_addr).await?;
        upgrade_stake_table_v2(&provider, l1_client, &mut contracts_v1, pauser, owner).await?;
        assert_ne!(
            read_proxy_impl(&provider, stake_table_addr).await?,
            current_impl
        );

        Ok(())
    }

    // This test is used to test the upgrade of the StakeTableProxy via the multisig wallet
    // It only tests the upgrade proposal via the typescript script and thus requires the upgrade proposal to be sent to a real network
    // However, the contracts are deployed on anvil, so the test will pass even if the upgrade proposal is not executed
    // The test assumes that there is a file .env.deployer.rs.test in the root directory with the following variables:
    // RPC_URL=
    // SAFE_MULTISIG_ADDRESS=0x0000000000000000000000000000000000000000
    // SAFE_ORCHESTRATOR_PRIVATE_KEY=0x0000000000000000000000000000000000000000000000000000000000000000
    // Ensure that the private key has proposal rights on the Safe Multisig Wallet and the SDK supports the network
    async fn test_upgrade_stake_table_to_v2_multisig_owner_helper() -> Result<()> {
        let multisig_admin = Address::random();
        let (_anvil, provider, l1_client) =
            ProviderBuilder::new().connect_anvil_with_l1_client()?;
        let mut contracts = Contracts::new();
        let init_recipient = provider.get_accounts().await?[0];
        let token_owner = Address::random();
        let initial_supply = U256::from(3590000000u64);

        // deploy proxy and V1
        let token_addr = deploy_token_proxy(
            &provider,
            &mut contracts,
            token_owner,
            init_recipient,
            initial_supply,
            "Espresso",
            "ESP",
        )
        .await?;
        // deploy light client proxy
        let lc_proxy_addr = deploy_light_client_proxy(
            &provider,
            &mut contracts,
            false,
            LightClientStateSol::dummy_genesis(),
            StakeTableStateSol::dummy_genesis(),
            init_recipient,
            Some(init_recipient),
        )
        .await?;

        let exit_escrow_period = U256::from(DEFAULT_EXIT_ESCROW_PERIOD_SECONDS);
        let owner = init_recipient;
        let stake_table_proxy_addr = deploy_stake_table_proxy(
            &provider,
            &mut contracts,
            token_addr,
            lc_proxy_addr,
            exit_escrow_period,
            owner,
        )
        .await?;
        // transfer ownership to multisig
        let _receipt = transfer_ownership(
            &provider,
            Contract::StakeTableProxy,
            stake_table_proxy_addr,
            multisig_admin,
        )
        .await?;
        let stake_table = StakeTable::new(stake_table_proxy_addr, &provider);
        assert_eq!(stake_table.owner().call().await?, multisig_admin);
        // then encode upgrade calldata for the multisig wallet
        let pauser = Address::random();
        let calldata = upgrade_stake_table_v2_multisig_owner(
            &provider,
            l1_client,
            &mut contracts,
            StakeTableV2UpgradeParams {
                multisig_address: multisig_admin,
                pauser,
            },
            MultisigOwnerCheck::Skip,
        )
        .await?;
        assert_eq!(calldata.to, stake_table_proxy_addr);

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_upgrade_stake_table_to_v2_multisig_owner() -> Result<()> {
        test_upgrade_stake_table_to_v2_multisig_owner_helper().await
    }

    #[test_log::test(tokio::test)]
    async fn test_deploy_ops_timelock() -> Result<()> {
        let provider = ProviderBuilder::new().connect_anvil_with_wallet();
        let mut contracts = Contracts::new();

        // Setup test parameters
        let min_delay = U256::from(86400); // 1 day in seconds
        let admin = provider.get_accounts().await?[0];
        let proposers = vec![Address::random()];
        let executors = vec![Address::random()];

        let timelock_addr = deploy_ops_timelock(
            &provider,
            &mut contracts,
            min_delay,
            proposers.clone(),
            executors.clone(),
            admin,
        )
        .await?;

        // Verify deployment
        let timelock = OpsTimelock::new(timelock_addr, &provider);
        assert_eq!(timelock.getMinDelay().call().await?, min_delay);

        // Verify initialization parameters
        assert_eq!(timelock.getMinDelay().call().await?, min_delay);
        assert!(
            timelock
                .hasRole(timelock.PROPOSER_ROLE().call().await?, proposers[0])
                .call()
                .await?
        );
        assert!(
            timelock
                .hasRole(timelock.EXECUTOR_ROLE().call().await?, executors[0])
                .call()
                .await?
        );

        // test that the admin is in the default admin role where DEFAULT_ADMIN_ROLE = 0x00
        let default_admin_role = U256::ZERO;
        assert!(
            timelock
                .hasRole(default_admin_role.into(), admin)
                .call()
                .await?
        );
        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_deploy_safe_exit_timelock() -> Result<()> {
        let provider = ProviderBuilder::new().connect_anvil_with_wallet();
        let mut contracts = Contracts::new();

        // Setup test parameters
        let min_delay = U256::from(86400); // 1 day in seconds
        let admin = provider.get_accounts().await?[0];
        let proposers = vec![Address::random()];
        let executors = vec![Address::random()];

        let timelock_addr = deploy_safe_exit_timelock(
            &provider,
            &mut contracts,
            min_delay,
            proposers.clone(),
            executors.clone(),
            admin,
        )
        .await?;

        // Verify deployment
        let timelock = SafeExitTimelock::new(timelock_addr, &provider);
        assert_eq!(timelock.getMinDelay().call().await?, min_delay);

        // Verify initialization parameters
        assert_eq!(timelock.getMinDelay().call().await?, min_delay);
        assert!(
            timelock
                .hasRole(timelock.PROPOSER_ROLE().call().await?, proposers[0])
                .call()
                .await?
        );
        assert!(
            timelock
                .hasRole(timelock.EXECUTOR_ROLE().call().await?, executors[0])
                .call()
                .await?
        );

        // test that the admin is in the default admin role where DEFAULT_ADMIN_ROLE = 0x00
        let default_admin_role = U256::ZERO;
        assert!(
            timelock
                .hasRole(default_admin_role.into(), admin)
                .call()
                .await?
        );
        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_upgrade_esp_token_v2() -> Result<()> {
        let provider = ProviderBuilder::new().connect_anvil_with_wallet();
        let mut contracts = Contracts::new();

        // deploy token
        let init_recipient = provider.get_accounts().await?[1];
        let token_owner = provider.get_accounts().await?[0];
        let token_name = "Espresso";
        let token_symbol = "ESP";
        let initial_supply = U256::from(3590000000u64);
        let token_proxy_addr = deploy_token_proxy(
            &provider,
            &mut contracts,
            token_owner,
            init_recipient,
            initial_supply,
            token_name,
            token_symbol,
        )
        .await?;
        let esp_token = EspToken::new(token_proxy_addr, &provider);
        assert_eq!(esp_token.name().call().await?, token_name);

        let fake_reward_claim = Address::random();
        contracts.insert(Contract::RewardClaimProxy, fake_reward_claim);

        // upgrade to v2
        upgrade_esp_token_v2(&provider, &mut contracts).await?;

        let esp_token_v2 = EspTokenV2::new(token_proxy_addr, &provider);

        assert_eq!(esp_token_v2.getVersion().call().await?, (2, 0, 0).into());
        assert_eq!(esp_token_v2.owner().call().await?, token_owner);

        // name is hardcoded in the EspTokenV2 contract
        assert_eq!(esp_token_v2.name().call().await?, "Espresso");
        assert_eq!(esp_token_v2.symbol().call().await?, "ESP");
        assert_eq!(esp_token_v2.decimals().call().await?, 18);

        let initial_supply_in_wei = parse_ether(&initial_supply.to_string()).unwrap();
        assert_eq!(
            esp_token_v2.totalSupply().call().await?,
            initial_supply_in_wei
        );
        assert_eq!(
            esp_token_v2.balanceOf(init_recipient).call().await?,
            initial_supply_in_wei
        );
        assert_eq!(
            esp_token_v2.balanceOf(token_owner).call().await?,
            U256::ZERO
        );

        assert_eq!(esp_token_v2.rewardClaim().call().await?, fake_reward_claim);

        Ok(())
    }

    // We expect no init data for the upgrade because there is no reinitializer for v2
    #[test_log::test(tokio::test)]
    async fn test_upgrade_esp_token_v2_multisig_owner() -> Result<()> {
        test_upgrade_esp_token_v2_multisig_owner_helper(UpgradeTestOptions {
            is_mock: false,
            upgrade_count: UpgradeCount::Once,
        })
        .await
    }

    // This test is used to test the upgrade of the EspTokenProxy via the multisig wallet
    // It only tests the upgrade proposal via the typescript script and thus requires the upgrade proposal to be sent to a real network
    // However, the contracts are deployed on anvil, so the test will pass even if the upgrade proposal is not executed
    // The test assumes that there is a file .env.deployer.rs.test in the root directory:
    // Ensure that the private key has proposal rights on the Safe Multisig Wallet and the SDK supports the network
    async fn test_upgrade_esp_token_v2_multisig_owner_helper(
        options: UpgradeTestOptions,
    ) -> Result<()> {
        let multisig_admin = Address::random();
        let mnemonic = "test test test test test test test test test test test junk".to_string();
        let account_index = 0u32;
        let anvil = Anvil::default().spawn();

        let mut contracts = Contracts::new();
        let admin_signer = MnemonicBuilder::<English>::default()
            .phrase(mnemonic)
            .index(account_index)
            .expect("wrong mnemonic or index")
            .build()?;
        let admin = admin_signer.address();
        let provider = ProviderBuilder::new()
            .wallet(admin_signer)
            .connect(&anvil.endpoint())
            .await?;
        let init_recipient = provider.get_accounts().await?[0];
        let initial_supply = U256::from(3590000000u64);
        let token_name = "Espresso";
        let token_symbol = "ESP";

        // deploy proxy and V1
        let esp_token_proxy_addr = deploy_token_proxy(
            &provider,
            &mut contracts,
            admin,
            init_recipient,
            initial_supply,
            token_name,
            token_symbol,
        )
        .await?;
        if matches!(options.upgrade_count, UpgradeCount::Twice) {
            // upgrade to v2
            upgrade_esp_token_v2(&provider, &mut contracts).await?;
        }

        // transfer ownership to multisig
        let _receipt = transfer_ownership(
            &provider,
            Contract::EspTokenProxy,
            esp_token_proxy_addr,
            multisig_admin,
        )
        .await?;
        let esp_token = EspToken::new(esp_token_proxy_addr, &provider);
        assert_eq!(esp_token.owner().call().await?, multisig_admin);

        let fake_reward_claim = Address::random();
        contracts.insert(Contract::RewardClaimProxy, fake_reward_claim);

        // then encode upgrade calldata for the multisig wallet
        let calldata = upgrade_esp_token_v2_multisig_owner(
            &provider,
            &mut contracts,
            MultisigOwnerCheck::Skip,
        )
        .await?;
        tracing::info!(
            "Encoded calldata for EspTokenProxy upgrade: to={:#x}, data={}",
            calldata.to,
            calldata.data
        );
        assert_eq!(calldata.to, esp_token_proxy_addr);
        assert!(!calldata.data.is_empty());

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_schedule_and_execute_timelock_operation() -> Result<()> {
        let provider = ProviderBuilder::new().connect_anvil_with_wallet();
        let mut contracts = Contracts::new();
        let delay = U256::from(0);

        // Get the provider's wallet address (the one actually sending transactions)
        let provider_wallet = provider.get_accounts().await?[0];

        let proposers = vec![provider_wallet];
        let executors = vec![provider_wallet];

        let timelock_addr = deploy_ops_timelock(
            &provider,
            &mut contracts,
            delay,
            proposers,
            executors,
            provider_wallet, // Use provider wallet as admin too
        )
        .await?;

        // deploy fee contract and set the timelock as the admin
        let fee_contract_proxy_addr =
            deploy_fee_contract_proxy(&provider, &mut contracts, timelock_addr).await?;

        let proxy = FeeContract::new(fee_contract_proxy_addr, &provider);
        let upgrade_data = proxy
            .transferOwnership(provider_wallet)
            .calldata()
            .to_owned();

        // propose a timelock operation
        let mut operation = TimelockOperationPayload {
            target: fee_contract_proxy_addr,
            value: U256::ZERO,
            data: upgrade_data,
            predecessor: B256::ZERO,
            salt: B256::ZERO,
            delay,
        };
        let operation_id = perform_timelock_operation(
            &provider,
            Contract::FeeContractProxy,
            operation.clone(),
            TimelockOperationType::Schedule,
            TimelockOperationParams::default(),
        )
        .await?;

        // check that the tx is scheduled
        let timelock = OpsTimelock::new(timelock_addr, &provider);
        assert!(timelock.isOperationPending(operation_id).call().await?);
        assert!(timelock.isOperationReady(operation_id).call().await?);
        assert!(!timelock.isOperationDone(operation_id).call().await?);
        assert!(timelock.getTimestamp(operation_id).call().await? > U256::ZERO);

        // execute the tx since the delay is 0
        perform_timelock_operation(
            &provider,
            Contract::FeeContractProxy,
            operation.clone(),
            TimelockOperationType::Execute,
            TimelockOperationParams::default(),
        )
        .await?;

        // check that the tx is executed
        assert!(timelock.isOperationDone(operation_id).call().await?);
        assert!(!timelock.isOperationPending(operation_id).call().await?);
        assert!(!timelock.isOperationReady(operation_id).call().await?);
        // check that the new owner is the provider_wallet
        let fee_contract = FeeContract::new(operation.target, &provider);
        assert_eq!(fee_contract.owner().call().await?, provider_wallet);

        operation.value = U256::from(1);
        //transfer ownership back to the timelock
        let tx_receipt = fee_contract
            .transferOwnership(timelock_addr)
            .send()
            .await?
            .get_receipt()
            .await?;
        assert!(tx_receipt.inner.is_success());

        let operation_id = perform_timelock_operation(
            &provider,
            Contract::FeeContractProxy,
            operation.clone(),
            TimelockOperationType::Schedule,
            TimelockOperationParams::default(),
        )
        .await?;

        perform_timelock_operation(
            &provider,
            Contract::FeeContractProxy,
            operation.clone(),
            TimelockOperationType::Cancel,
            TimelockOperationParams::default(),
        )
        .await?;

        // check that the tx is cancelled
        timelock
            .hashOperation(
                operation.target,
                operation.value,
                operation.data.clone(),
                operation.predecessor,
                operation.salt,
            )
            .call()
            .await?;
        assert!(timelock.getTimestamp(operation_id).call().await? == U256::ZERO);

        let operation_id = perform_timelock_operation(
            &provider,
            Contract::FeeContractProxy,
            operation.clone(),
            TimelockOperationType::Schedule,
            TimelockOperationParams::default(),
        )
        .await?;

        // Test canceling with only the operation_id (operation payload not needed)
        perform_timelock_operation(
            &provider,
            Contract::FeeContractProxy,
            // Use a minimal/empty operation payload since operation_id is provided
            TimelockOperationPayload {
                target: fee_contract_proxy_addr, // Not used when operation_id is provided
                value: U256::ZERO,
                data: Bytes::new(),
                predecessor: B256::ZERO,
                salt: B256::ZERO,
                delay: U256::ZERO,
            },
            TimelockOperationType::Cancel,
            TimelockOperationParams {
                operation_id: Some(operation_id), // Only operation_id is needed
                ..Default::default()
            },
        )
        .await?;
        assert!(timelock.getTimestamp(operation_id).call().await? == U256::ZERO);
        Ok(())
    }

    async fn test_transfer_ownership_helper(contract_type: Contract) -> Result<()> {
        let multisig_admin = Address::random();
        let timelock = Address::random();
        let mnemonic = "test test test test test test test test test test test junk".to_string();
        let account_index = 0u32;
        let anvil = Anvil::default().spawn();

        let mut contracts = Contracts::new();
        let admin_signer = MnemonicBuilder::<English>::default()
            .phrase(mnemonic)
            .index(account_index)
            .expect("wrong mnemonic or index")
            .build()?;
        let admin = admin_signer.address();
        let provider = ProviderBuilder::new()
            .wallet(admin_signer)
            .connect_http(anvil.endpoint_url());

        // prepare `initialize()` input
        let genesis_state = LightClientStateSol::dummy_genesis();
        let genesis_stake = StakeTableStateSol::dummy_genesis();

        let prover = Address::random();

        // deploy proxy and V1
        let proxy_addr = match contract_type {
            Contract::LightClientProxy => {
                deploy_light_client_proxy(
                    &provider,
                    &mut contracts,
                    false,
                    genesis_state.clone(),
                    genesis_stake.clone(),
                    admin,
                    Some(prover),
                )
                .await?
            },
            Contract::FeeContractProxy => {
                deploy_fee_contract_proxy(&provider, &mut contracts, admin).await?
            },
            Contract::EspTokenProxy => {
                deploy_token_proxy(
                    &provider,
                    &mut contracts,
                    admin,
                    multisig_admin,
                    U256::from(0u64),
                    "Test",
                    "TEST",
                )
                .await?
            },
            Contract::StakeTableProxy => {
                let token_addr = deploy_token_proxy(
                    &provider,
                    &mut contracts,
                    admin,
                    admin,
                    U256::from(0u64),
                    "Test",
                    "TEST",
                )
                .await?;
                let initial_admin = provider.get_accounts().await?[0];
                // deploy light client proxy
                let lc_proxy_addr = deploy_light_client_proxy(
                    &provider,
                    &mut contracts,
                    false,
                    LightClientStateSol::dummy_genesis(),
                    StakeTableStateSol::dummy_genesis(),
                    initial_admin,
                    Some(prover),
                )
                .await?;
                // upgrade to v2
                let blocks_per_epoch = 50;
                let epoch_start_block = 50;
                upgrade_light_client_v2(
                    &provider,
                    &mut contracts,
                    false,
                    blocks_per_epoch,
                    epoch_start_block,
                )
                .await?;
                let lc_v2 = LightClientV2::new(lc_proxy_addr, &provider);
                assert_eq!(lc_v2.getVersion().call().await?.majorVersion, 2);
                assert_eq!(lc_v2.blocksPerEpoch().call().await?, blocks_per_epoch);
                assert_eq!(lc_v2.epochStartBlock().call().await?, epoch_start_block);

                deploy_stake_table_proxy(
                    &provider,
                    &mut contracts,
                    token_addr,
                    lc_proxy_addr,
                    U256::from(DEFAULT_EXIT_ESCROW_PERIOD_SECONDS),
                    admin,
                )
                .await?
            },
            _ => anyhow::bail!("Not a proxy contract, can't transfer ownership"),
        };

        // transfer ownership to multisig
        let _receipt =
            transfer_ownership(&provider, contract_type, proxy_addr, multisig_admin).await?;
        assert_eq!(
            OwnableUpgradeable::new(proxy_addr, &provider)
                .owner()
                .call()
                .await?,
            multisig_admin
        );

        // encode transfer ownership calldata for the multisig wallet
        let calldata = transfer_ownership_from_multisig_to_timelock(
            &mut contracts,
            contract_type,
            TransferOwnershipParams {
                new_owner: timelock,
            },
        )?;
        tracing::info!(
            "Transfer ownership calldata: to={:#x}, data={}",
            calldata.to,
            calldata.data
        );
        assert_eq!(calldata.to, proxy_addr);

        let expected_calldata =
            crate::encode_function_call("transferOwnership(address)", vec![timelock.to_string()])
                .unwrap();
        assert_eq!(calldata.data, expected_calldata);

        // Execute the calldata on Anvil as multisig_admin to verify it works
        let impersonation_provider = ProviderBuilder::new()
            .filler(ImpersonateFiller::new(multisig_admin))
            .connect_http(anvil.endpoint_url());
        let anvil_provider = AnvilProvider::new(impersonation_provider.clone(), Arc::new(anvil));
        anvil_provider.anvil_auto_impersonate_account(true).await?;
        anvil_provider
            .anvil_set_balance(multisig_admin, parse_ether("100")?)
            .await?;

        let tx = alloy::rpc::types::TransactionRequest::default()
            .to(calldata.to)
            .input(calldata.data.into());
        impersonation_provider
            .send_transaction(tx)
            .await?
            .get_receipt()
            .await?;

        assert_eq!(
            OwnableUpgradeable::new(proxy_addr, &impersonation_provider)
                .owner()
                .call()
                .await?,
            timelock,
            "ownership should have transferred to timelock"
        );

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_encode_function_call() -> Result<()> {
        let function_signature = "transfer(address,uint256)".to_string();
        let values = vec![
            "0x000000000000000000000000000000000000dead".to_string(),
            "1000".to_string(),
        ];
        let expected = "0xa9059cbb000000000000000000000000000000000000000000000000000000000000dead00000000000000000000000000000000000000000000000000000000000003e8".parse::<Bytes>()?;
        let encoded = encode_function_call(&function_signature, values).expect("encoding failed");

        assert_eq!(encoded, expected);
        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_encode_function_call_upgrade_to_and_call() -> Result<()> {
        let function_signature = "upgradeToAndCall(address,bytes)".to_string();
        let values = vec![
            "0xe1f131b07550a689d6a11f21d9e9238a5c466996".to_string(),
            "0x".to_string(),
        ];
        let expected = "0x4f1ef286000000000000000000000000e1f131b07550a689d6a11f21d9e9238a5c46699600000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000000".parse::<Bytes>()?;
        let encoded = encode_function_call(&function_signature, values).expect("encoding failed");

        assert_eq!(encoded, expected);
        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_encode_function_call_with_bytes32() -> Result<()> {
        let function_signature = "setHash(bytes32)".to_string();
        let values =
            vec!["0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef".to_string()];
        let expected = "0x0c4c42850123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
            .parse::<Bytes>()?;
        let encoded = encode_function_call(&function_signature, values).expect("encoding failed");

        assert_eq!(encoded, expected);
        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_encode_function_call_with_bytes() -> Result<()> {
        let function_signature = "emitData(bytes)".to_string();
        let values = vec!["0xdeadbeef".to_string()];
        let expected = "0xd836083e00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000004deadbeef00000000000000000000000000000000000000000000000000000000".parse::<Bytes>()?;
        let encoded = encode_function_call(&function_signature, values).expect("encoding failed");

        assert_eq!(encoded, expected);
        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_encode_function_call_with_bool() -> Result<()> {
        let function_signature = "setFlag(bool)".to_string();
        let mut values = vec!["true".to_string()];
        let mut expected =
            "0x3927f6af0000000000000000000000000000000000000000000000000000000000000001"
                .parse::<Bytes>()?;
        let mut encoded =
            encode_function_call(&function_signature, values).expect("encoding failed");

        assert_eq!(encoded, expected);

        values = vec!["false".to_string()];
        expected = "0x3927f6af0000000000000000000000000000000000000000000000000000000000000000"
            .parse::<Bytes>()?;
        encoded = encode_function_call(&function_signature, values).expect("encoding failed");

        assert_eq!(encoded, expected);
        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_encode_function_call_with_string() -> Result<()> {
        let function_signature = "logMessage(string)".to_string();
        let values = vec!["Hello, world!".to_string()];
        let expected = "0x7c9900520000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000d48656c6c6f2c20776f726c642100000000000000000000000000000000000000".parse::<Bytes>()?;
        let encoded = encode_function_call(&function_signature, values).expect("encoding failed");

        assert_eq!(encoded, expected);
        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_transfer_ownership_light_client_proxy() -> Result<()> {
        test_transfer_ownership_helper(Contract::LightClientProxy).await
    }

    #[test_log::test(tokio::test)]
    async fn test_transfer_ownership_fee_contract_proxy() -> Result<()> {
        test_transfer_ownership_helper(Contract::FeeContractProxy).await
    }

    #[test_log::test(tokio::test)]
    async fn test_transfer_ownership_esp_token_proxy() -> Result<()> {
        test_transfer_ownership_helper(Contract::EspTokenProxy).await
    }

    #[test_log::test(tokio::test)]
    async fn test_transfer_ownership_stake_table_proxy() -> Result<()> {
        test_transfer_ownership_helper(Contract::StakeTableProxy).await
    }

    #[test_log::test(tokio::test)]
    async fn test_get_proxy_initialized_version_initialized() -> Result<()> {
        let provider = ProviderBuilder::new().connect_anvil_with_wallet();
        let mut contracts = Contracts::new();
        let owner = provider.get_accounts().await?[0];

        let token_addr = deploy_token_proxy(
            &provider,
            &mut contracts,
            owner,
            owner,
            U256::from(10_000_000u64),
            "Test Token",
            "TEST",
        )
        .await?;

        let lc_addr = deploy_light_client_contract(&provider, &mut contracts, false).await?;
        let exit_escrow_period = U256::from(DEFAULT_EXIT_ESCROW_PERIOD_SECONDS);

        let stake_table_proxy_addr = deploy_stake_table_proxy(
            &provider,
            &mut contracts,
            token_addr,
            lc_addr,
            exit_escrow_period,
            owner,
        )
        .await?;

        let version = get_proxy_initialized_version(&provider, stake_table_proxy_addr).await?;
        assert_eq!(version, 1, "Initialized proxy should return version 1");

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_get_proxy_initialized_version_reinitialized() -> Result<()> {
        let (_anvil, provider, l1_client) =
            ProviderBuilder::new().connect_anvil_with_l1_client()?;
        let mut contracts = Contracts::new();
        let owner = l1_client.get_accounts().await?[0];

        let token_addr = deploy_token_proxy(
            &provider,
            &mut contracts,
            owner,
            owner,
            U256::from(10_000_000u64),
            "Test Token",
            "TEST",
        )
        .await?;

        let lc_addr = deploy_light_client_contract(&provider, &mut contracts, false).await?;
        let exit_escrow_period = U256::from(DEFAULT_EXIT_ESCROW_PERIOD_SECONDS);

        let stake_table_proxy_addr = deploy_stake_table_proxy(
            &provider,
            &mut contracts,
            token_addr,
            lc_addr,
            exit_escrow_period,
            owner,
        )
        .await?;

        let pauser = Address::random();
        let admin = Address::random();
        upgrade_stake_table_v2(&provider, l1_client.clone(), &mut contracts, pauser, admin).await?;

        let version = get_proxy_initialized_version(&l1_client, stake_table_proxy_addr).await?;
        assert_eq!(version, 2, "Reinitialized proxy should return version 2");

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_grant_admin_role_reward_claim() -> Result<()> {
        let (_anvil, provider, l1_client) =
            ProviderBuilder::new().connect_anvil_with_l1_client()?;

        let mut contracts = Contracts::new();
        let deployer = l1_client.get_accounts().await?[0];
        let new_admin = Address::random();

        // Deploy RewardClaim
        let esp_token_addr = deploy_token_proxy(
            &provider,
            &mut contracts,
            deployer,
            deployer,
            U256::from(10_000_000u64),
            "Test Token",
            "TEST",
        )
        .await?;
        let lc_addr = deploy_light_client_contract(&provider, &mut contracts, false).await?;
        let reward_claim_addr = deploy_reward_claim_proxy(
            &provider,
            &mut contracts,
            esp_token_addr,
            lc_addr,
            deployer,
            deployer, // pauser
        )
        .await?;

        // Verify initial admin
        let reward_claim = RewardClaim::new(reward_claim_addr, &provider);
        let admin_role = reward_claim.DEFAULT_ADMIN_ROLE().call().await?;
        assert!(reward_claim.hasRole(admin_role, deployer).call().await?);
        assert!(!reward_claim.hasRole(admin_role, new_admin).call().await?);

        // Grant admin role
        let receipt = grant_admin_role(
            &provider,
            Contract::RewardClaimProxy,
            reward_claim_addr,
            new_admin,
        )
        .await?;

        assert!(receipt.inner.is_success());

        // Verify new admin has role and old admin doesn't
        assert!(reward_claim.hasRole(admin_role, new_admin).call().await?);
        assert!(!reward_claim.hasRole(admin_role, deployer).call().await?);

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_transfer_ownership_from_eoa_reward_claim_routes_to_grant_role() -> Result<()> {
        let (anvil, provider, l1_client) = ProviderBuilder::new().connect_anvil_with_l1_client()?;

        let mut contracts = Contracts::new();
        let deployer = l1_client.get_accounts().await?[0];
        let new_admin = Address::random();

        // Deploy RewardClaim
        let esp_token_addr = deploy_token_proxy(
            &provider,
            &mut contracts,
            deployer,
            deployer,
            U256::from(10_000_000u64),
            "Test Token",
            "TEST",
        )
        .await?;
        let lc_addr = deploy_light_client_contract(&provider, &mut contracts, false).await?;
        let reward_claim_addr = deploy_reward_claim_proxy(
            &provider,
            &mut contracts,
            esp_token_addr,
            lc_addr,
            deployer,
            deployer, // pauser
        )
        .await?;

        // Verify initial admin
        let reward_claim = RewardClaim::new(reward_claim_addr, &provider);
        let admin_role = reward_claim.DEFAULT_ADMIN_ROLE().call().await?;
        assert!(reward_claim.hasRole(admin_role, deployer).call().await?);
        assert!(!reward_claim.hasRole(admin_role, new_admin).call().await?);

        use builder::DeployerArgsBuilder;

        let mut args_builder = DeployerArgsBuilder::default();
        args_builder
            .deployer(provider.clone())
            .rpc_url(anvil.endpoint_url())
            .transfer_ownership_from_eoa(true)
            .target_contract(OwnableContract::RewardClaimProxy)
            .transfer_ownership_new_owner(new_admin);
        let args = args_builder.build()?;

        args.transfer_ownership_from_eoa(&mut contracts).await?;

        // Verify new admin has role and old admin doesn't
        assert!(reward_claim.hasRole(admin_role, new_admin).call().await?);
        assert!(!reward_claim.hasRole(admin_role, deployer).call().await?);

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_perform_timelock_operation_reward_claim() -> Result<()> {
        let (anvil, provider, _l1_client) =
            ProviderBuilder::new().connect_anvil_with_l1_client()?;
        let mut contracts = Contracts::new();
        let delay = U256::from(0);
        let provider_wallet = provider.get_accounts().await?[0];

        // Deploy SafeExitTimelock
        let timelock_addr = deploy_safe_exit_timelock(
            &provider,
            &mut contracts,
            delay,
            vec![provider_wallet],
            vec![provider_wallet],
            provider_wallet,
        )
        .await?;

        // Deploy dependencies
        let token_addr = deploy_token_proxy(
            &provider,
            &mut contracts,
            provider_wallet,
            provider_wallet,
            U256::from(10_000_000u64),
            "Test Token",
            "TEST",
        )
        .await?;
        let lc_addr = deploy_light_client_contract(&provider, &mut contracts, false).await?;

        // Deploy RewardClaim with timelock as admin
        let reward_claim_addr = deploy_reward_claim_proxy(
            &provider,
            &mut contracts,
            token_addr,
            lc_addr,
            timelock_addr,
            provider_wallet,
        )
        .await?;

        let reward_claim = RewardClaim::new(reward_claim_addr, &provider);
        let pauser_role = reward_claim.PAUSER_ROLE().call().await?;
        let new_pauser = Address::random();

        // Verify new_pauser doesn't have the role yet
        assert!(!reward_claim.hasRole(pauser_role, new_pauser).call().await?);

        // Use DeployerArgsBuilder to test propose_timelock_operation_for_contract
        use builder::DeployerArgsBuilder;
        use proposals::timelock::TimelockOperationType;

        let mut args_builder = DeployerArgsBuilder::default();
        args_builder
            .deployer(provider.clone())
            .rpc_url(anvil.endpoint_url())
            .timelock_operation_type(TimelockOperationType::Schedule)
            .target_contract(OwnableContract::RewardClaimProxy)
            .timelock_operation_value(U256::ZERO)
            .timelock_operation_function_signature("grantRole(bytes32,address)".to_string())
            .timelock_operation_function_values(vec![
                format!("{:#x}", pauser_role),
                format!("{:#x}", new_pauser),
            ])
            .timelock_operation_salt(
                "0x0000000000000000000000000000000000000000000000000000000000000001".to_string(),
            )
            .timelock_operation_delay(delay);

        let args = args_builder.build()?;

        // Schedule the operation using the high-level function
        args.propose_timelock_operation_for_contract(&mut contracts)
            .await?;

        // Now execute it
        let mut args_builder = DeployerArgsBuilder::default();
        args_builder
            .deployer(provider.clone())
            .rpc_url(anvil.endpoint_url())
            .timelock_operation_type(TimelockOperationType::Execute)
            .target_contract(OwnableContract::RewardClaimProxy)
            .timelock_operation_value(U256::ZERO)
            .timelock_operation_function_signature("grantRole(bytes32,address)".to_string())
            .timelock_operation_function_values(vec![
                format!("{:#x}", pauser_role),
                format!("{:#x}", new_pauser),
            ])
            .timelock_operation_salt(
                "0x0000000000000000000000000000000000000000000000000000000000000001".to_string(),
            )
            .timelock_operation_delay(delay);

        let args = args_builder.build()?;
        args.propose_timelock_operation_for_contract(&mut contracts)
            .await?;

        // Verify the function was actually called
        assert!(reward_claim.hasRole(pauser_role, new_pauser).call().await?);

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_derive_timelock_address_from_contracts() -> Result<()> {
        use builder::DeployerArgsBuilder;
        use proposals::timelock::{TimelockContract, get_timelock_for_contract};

        let (anvil, provider, _l1_client) =
            ProviderBuilder::new().connect_anvil_with_l1_client()?;
        let mut contracts = Contracts::new();
        let delay = U256::from(0);
        let provider_wallet = provider.get_accounts().await?[0];
        let proposers = vec![provider_wallet];
        let executors = vec![provider_wallet];
        let rpc_url = anvil.endpoint_url();

        // Deploy both timelocks first
        let ops_timelock_addr = deploy_ops_timelock(
            &provider,
            &mut contracts,
            delay,
            proposers.clone(),
            executors.clone(),
            provider_wallet,
        )
        .await?;

        let safe_exit_timelock_addr = deploy_safe_exit_timelock(
            &provider,
            &mut contracts,
            delay,
            proposers,
            executors,
            provider_wallet,
        )
        .await?;

        //  Use DeployerArgsBuilder to deploy FeeContractProxy with use_timelock_owner
        // This tests the actual deployment code path and verifies it chooses OpsTimelock
        let mut args_builder = DeployerArgsBuilder::default();
        args_builder
            .deployer(provider.clone())
            .use_timelock_owner(true)
            .rpc_url(rpc_url.clone());
        let args = args_builder.build()?;

        // Deploy FeeContractProxy - it should automatically use OpsTimelock
        args.deploy(&mut contracts, Contract::FeeContractProxy)
            .await?;

        // Verify derivation function returns correct timelock
        let fee_contract_derived_timelock = derive_timelock_address_from_contract_type(
            OwnableContract::FeeContractProxy,
            &contracts,
        )?;
        assert_eq!(fee_contract_derived_timelock, ops_timelock_addr);

        // Verify on-chain that FeeContractProxy has OpsTimelock as owner
        let fee_contract_addr = contracts
            .address(Contract::FeeContractProxy)
            .expect("FeeContractProxy should be deployed");
        let fee_contract = FeeContract::new(fee_contract_addr, &provider);
        let actual_owner = fee_contract.owner().call().await?;
        assert_eq!(
            actual_owner, ops_timelock_addr,
            "FeeContractProxy should have OpsTimelock as owner"
        );

        let queried_timelock =
            get_timelock_for_contract(&provider, Contract::FeeContractProxy, fee_contract_addr)
                .await?;

        match queried_timelock {
            TimelockContract::OpsTimelock(addr) => {
                assert_eq!(
                    addr, ops_timelock_addr,
                    "Queried timelock should match deployed OpsTimelock"
                );
                assert_eq!(
                    addr, fee_contract_derived_timelock,
                    "Queried timelock should match derived timelock"
                );
            },
            _ => panic!(
                "FeeContractProxy should use OpsTimelock, got: {:?}",
                queried_timelock
            ),
        }

        //  Deploy RewardsClaimProxy - it should automatically use SafeExitTimelock
        let _esp_token_addr = deploy_token_proxy(
            &provider,
            &mut contracts,
            provider_wallet,
            provider_wallet,
            U256::from(10_000_000u64),
            "Test Token",
            "TEST",
        )
        .await?;

        // prepare `initialize()` input
        let genesis_state = LightClientStateSol::dummy_genesis();
        let genesis_stake = StakeTableStateSol::dummy_genesis();
        let admin = provider.get_accounts().await?[0];
        let prover = admin;

        let _lc_proxy_addr = deploy_light_client_proxy(
            &provider,
            &mut contracts,
            true, // is_mock = true
            genesis_state.clone(),
            genesis_stake.clone(),
            admin,
            Some(prover),
        )
        .await?;

        let mut args_builder2 = DeployerArgsBuilder::default();
        args_builder2
            .deployer(provider.clone())
            .use_timelock_owner(true)
            .rpc_url(rpc_url.clone());
        let args2 = args_builder2.build()?;

        args2
            .deploy(&mut contracts, Contract::RewardClaimProxy)
            .await?;

        // Verify derivation
        let reward_claim_derived_timelock = derive_timelock_address_from_contract_type(
            OwnableContract::RewardClaimProxy,
            &contracts,
        )?;
        assert_eq!(reward_claim_derived_timelock, safe_exit_timelock_addr);

        // Verify on-chain
        let reward_claim_addr = contracts
            .address(Contract::RewardClaimProxy)
            .expect("RewardClaimProxy should be deployed");
        let reward_claim = RewardClaim::new(reward_claim_addr, &provider);
        let actual_owner = reward_claim.currentAdmin().call().await?;
        assert_eq!(
            actual_owner, safe_exit_timelock_addr,
            "RewardClaimProxy should have SafeExitTimelock as owner"
        );

        let queried_timelock =
            get_timelock_for_contract(&provider, Contract::RewardClaimProxy, reward_claim_addr)
                .await?;

        match queried_timelock {
            TimelockContract::SafeExitTimelock(addr) => {
                assert_eq!(
                    addr, safe_exit_timelock_addr,
                    "Queried timelock should match deployed SafeExitTimelock"
                );
                assert_eq!(
                    addr, reward_claim_derived_timelock,
                    "Queried timelock should match derived timelock"
                );
            },
            _ => panic!(
                "RewardClaimProxy should use SafeExitTimelock, got: {:?}",
                queried_timelock
            ),
        }

        // Error case - missing timelock
        let empty_contracts = Contracts::new();
        let result = derive_timelock_address_from_contract_type(
            OwnableContract::FeeContractProxy,
            &empty_contracts,
        );
        assert!(
            result.is_err(),
            "Should error when timelock is missing from contracts map"
        );
        let error_msg = result.unwrap_err().to_string();
        assert!(
            error_msg.contains("not found") || error_msg.contains("OpsTimelock"),
            "Error should mention missing timelock, got: {}",
            error_msg
        );

        // NOTE: Invalid contract type test removed - OwnableContract enum now provides
        // compile-time safety so invalid types can't be passed to the function.

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_upgrade_esp_token_v2_with_timelock_owner() -> Result<()> {
        use builder::DeployerArgsBuilder;

        let (anvil, provider, _l1_client) =
            ProviderBuilder::new().connect_anvil_with_l1_client()?;
        let mut contracts = Contracts::new();
        let delay = U256::from(0);
        let provider_wallet = provider.get_accounts().await?[0];
        let proposers = vec![provider_wallet];
        let executors = vec![provider_wallet];
        let rpc_url = anvil.endpoint_url();

        let safe_exit_timelock_addr = deploy_safe_exit_timelock(
            &provider,
            &mut contracts,
            delay,
            proposers,
            executors,
            provider_wallet,
        )
        .await?;

        let token_owner = provider_wallet;
        let init_recipient = provider_wallet;
        let initial_supply = U256::from(10_000_000u64);
        let token_name = "Espresso";
        let token_symbol = "ESP";

        let token_proxy_addr = deploy_token_proxy(
            &provider,
            &mut contracts,
            token_owner,
            init_recipient,
            initial_supply,
            token_name,
            token_symbol,
        )
        .await?;

        let fake_reward_claim = Address::random();
        contracts.insert(Contract::RewardClaimProxy, fake_reward_claim);

        let mut args_builder = DeployerArgsBuilder::default();
        args_builder
            .deployer(provider.clone())
            .use_timelock_owner(true)
            .rpc_url(rpc_url);
        let args = args_builder.build()?;

        args.deploy(&mut contracts, Contract::EspTokenV2).await?;

        let esp_token_v2 = EspTokenV2::new(token_proxy_addr, &provider);
        assert_eq!(esp_token_v2.getVersion().call().await?, (2, 0, 0).into());
        assert_eq!(
            esp_token_v2.owner().call().await?,
            safe_exit_timelock_addr,
            "EspTokenProxy should have SafeExitTimelock as owner after V2 upgrade"
        );

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_upgrade_light_client_v3_with_timelock_owner() -> Result<()> {
        use builder::DeployerArgsBuilder;

        let (anvil, provider, _l1_client) =
            ProviderBuilder::new().connect_anvil_with_l1_client()?;
        let mut contracts = Contracts::new();
        let delay = U256::from(0);
        let provider_wallet = provider.get_accounts().await?[0];
        let proposers = vec![provider_wallet];
        let executors = vec![provider_wallet];
        let rpc_url = anvil.endpoint_url();

        let ops_timelock_addr = deploy_ops_timelock(
            &provider,
            &mut contracts,
            delay,
            proposers,
            executors,
            provider_wallet,
        )
        .await?;

        let genesis_state = LightClientStateSol::dummy_genesis();
        let genesis_stake = StakeTableStateSol::dummy_genesis();

        let lc_proxy_addr = deploy_light_client_proxy(
            &provider,
            &mut contracts,
            false,
            genesis_state,
            genesis_stake,
            provider_wallet,
            Some(provider_wallet),
        )
        .await?;

        upgrade_light_client_v2(&provider, &mut contracts, false, 10, 22).await?;

        let mut args_builder = DeployerArgsBuilder::default();
        args_builder
            .deployer(provider.clone())
            .use_timelock_owner(true)
            .rpc_url(rpc_url);
        let args = args_builder.build()?;

        args.deploy(&mut contracts, Contract::LightClientV3).await?;

        let lc_v3 = LightClientV3::new(lc_proxy_addr, &provider);
        assert_eq!(lc_v3.getVersion().call().await?.majorVersion, 3);
        assert_eq!(
            lc_v3.owner().call().await?,
            ops_timelock_addr,
            "LightClientProxy should have OpsTimelock as owner after V3 upgrade"
        );

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_upgrade_stake_table_v2_with_timelock_owner() -> Result<()> {
        use builder::DeployerArgsBuilder;

        let (anvil, provider, _l1_client) =
            ProviderBuilder::new().connect_anvil_with_l1_client()?;
        let mut contracts = Contracts::new();
        let delay = U256::from(0);
        let provider_wallet = provider.get_accounts().await?[0];
        let proposers = vec![provider_wallet];
        let executors = vec![provider_wallet];
        let rpc_url = anvil.endpoint_url();

        let ops_timelock_addr = deploy_ops_timelock(
            &provider,
            &mut contracts,
            delay,
            proposers,
            executors,
            provider_wallet,
        )
        .await?;

        let token_proxy_addr = deploy_token_proxy(
            &provider,
            &mut contracts,
            provider_wallet,
            provider_wallet,
            U256::from(10_000_000u64),
            "Espresso",
            "ESP",
        )
        .await?;

        let genesis_state = LightClientStateSol::dummy_genesis();
        let genesis_stake = StakeTableStateSol::dummy_genesis();

        let lc_proxy_addr = deploy_light_client_proxy(
            &provider,
            &mut contracts,
            false,
            genesis_state,
            genesis_stake,
            provider_wallet,
            Some(provider_wallet),
        )
        .await?;

        let escrow_period = U256::from(crate::DEFAULT_EXIT_ESCROW_PERIOD_SECONDS);
        let st_proxy_addr = deploy_stake_table_proxy(
            &provider,
            &mut contracts,
            token_proxy_addr,
            lc_proxy_addr,
            escrow_period,
            provider_wallet,
        )
        .await?;

        let mut args_builder = DeployerArgsBuilder::default();
        args_builder
            .deployer(provider.clone())
            .use_timelock_owner(true)
            .rpc_url(rpc_url);
        let args = args_builder.build()?;

        args.deploy(&mut contracts, Contract::StakeTableV2).await?;

        let st_v2 = StakeTableV2::new(st_proxy_addr, &provider);
        assert_eq!(st_v2.getVersion().call().await?, (2, 0, 0).into());
        assert_eq!(
            st_v2.owner().call().await?,
            ops_timelock_addr,
            "StakeTableProxy should have OpsTimelock as owner after V2 upgrade"
        );

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_perform_timelock_operation_unified() -> Result<()> {
        use crate::proposals::timelock::{
            TimelockOperationParams, TimelockOperationPayload, TimelockOperationType,
            perform_timelock_operation,
        };

        let provider = ProviderBuilder::new().connect_anvil_with_wallet();
        let mut contracts = Contracts::new();
        let delay = U256::from(0);
        let provider_wallet = provider.get_accounts().await?[0];
        let another_wallet = provider.get_accounts().await?[1];
        let proposers = vec![provider_wallet];
        let executors = vec![provider_wallet];

        let timelock_addr = deploy_ops_timelock(
            &provider,
            &mut contracts,
            delay,
            proposers,
            executors,
            provider_wallet,
        )
        .await?;
        let timelock = OpsTimelock::new(timelock_addr, &provider);

        let fee_contract_proxy_addr =
            deploy_fee_contract_proxy(&provider, &mut contracts, timelock_addr).await?;
        let proxy = FeeContract::new(fee_contract_proxy_addr, &provider);

        let transfer_ownership_data = proxy
            .transferOwnership(another_wallet)
            .calldata()
            .to_owned();

        assert_eq!(proxy.owner().call().await?, timelock_addr);

        let operation = TimelockOperationPayload {
            target: fee_contract_proxy_addr,
            value: U256::ZERO,
            data: transfer_ownership_data.clone(),
            predecessor: B256::ZERO,
            salt: B256::ZERO,
            delay,
        };

        // Test Cancel via unified function (schedule and cancel a new operation)
        let mut cancel_operation = operation.clone();
        cancel_operation.value = U256::from(1);
        let cancel_params = TimelockOperationParams::default();
        let cancel_operation_id = perform_timelock_operation(
            &provider,
            Contract::FeeContractProxy,
            cancel_operation.clone(),
            TimelockOperationType::Schedule,
            cancel_params.clone(),
        )
        .await?;

        perform_timelock_operation(
            &provider,
            Contract::FeeContractProxy,
            cancel_operation,
            TimelockOperationType::Cancel,
            cancel_params,
        )
        .await?;

        assert!(timelock.getTimestamp(cancel_operation_id).call().await? == U256::ZERO);

        // Test schedule transfer ownership operation
        let params = TimelockOperationParams::default();
        let operation_id = perform_timelock_operation(
            &provider,
            Contract::FeeContractProxy,
            operation.clone(),
            TimelockOperationType::Schedule,
            params,
        )
        .await?;

        assert!(timelock.isOperationPending(operation_id).call().await?);

        let params = TimelockOperationParams::default();
        perform_timelock_operation(
            &provider,
            Contract::FeeContractProxy,
            operation.clone(),
            TimelockOperationType::Execute,
            params,
        )
        .await?;

        assert!(timelock.isOperationDone(operation_id).call().await?);

        // confirm that the operation occurred on the fee contract
        assert_eq!(proxy.owner().call().await?, another_wallet);
        Ok(())
    }
    #[test_log::test(tokio::test)]
    async fn test_upgrade_fee_contract_multisig_owner() -> Result<()> {
        let multisig_admin = Address::random();
        let (anvil, provider, _l1_client) =
            ProviderBuilder::new().connect_anvil_with_l1_client()?;
        let mut contracts = Contracts::new();
        let admin = provider.get_accounts().await?[0];

        // Deploy FeeContract proxy
        let fee_contract_proxy_addr =
            deploy_fee_contract_proxy(&provider, &mut contracts, admin).await?;

        // transfer ownership to multisig
        let _receipt = transfer_ownership(
            &provider,
            Contract::FeeContractProxy,
            fee_contract_proxy_addr,
            multisig_admin,
        )
        .await?;

        // For patch upgrades the implementation must be redeployed; clear the cached address
        contracts.remove(&Contract::FeeContract);

        // Encode upgrade calldata for the multisig wallet
        let calldata = upgrade_fee_contract_multisig_owner(
            &provider,
            &mut contracts,
            MultisigOwnerCheck::Skip,
        )
        .await?;

        tracing::info!(
            "Encoded calldata for FeeContractProxy upgrade: to={:#x}, data={}",
            calldata.to,
            calldata.data
        );

        assert_eq!(calldata.to, fee_contract_proxy_addr);
        // Verify it encodes upgradeToAndCall with empty init data
        let fee_impl_addr = contracts.address(Contract::FeeContract).unwrap_or_default();
        let expected = crate::encode_function_call(
            "upgradeToAndCall(address,bytes)",
            vec![fee_impl_addr.to_string(), "0x".to_string()],
        )
        .unwrap();
        assert_eq!(calldata.data, expected);

        // Execute the calldata on Anvil as multisig_admin to verify it works
        let impersonation_provider = ProviderBuilder::new()
            .filler(ImpersonateFiller::new(multisig_admin))
            .connect_http(anvil.endpoint_url());
        let anvil_provider = AnvilProvider::new(impersonation_provider.clone(), Arc::new(anvil));
        anvil_provider.anvil_auto_impersonate_account(true).await?;
        anvil_provider
            .anvil_set_balance(multisig_admin, parse_ether("100")?)
            .await?;

        let tx = alloy::rpc::types::TransactionRequest::default()
            .to(calldata.to)
            .input(calldata.data.into());
        let receipt = impersonation_provider
            .send_transaction(tx)
            .await?
            .get_receipt()
            .await?;
        assert!(receipt.inner.is_success(), "upgrade tx failed");

        // Verify the proxy now points to the new implementation
        let new_impl = read_proxy_impl(&impersonation_provider, fee_contract_proxy_addr).await?;
        assert_eq!(new_impl, fee_impl_addr, "proxy should point to new impl");

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_upgrade_fee_contract_v1_0_1_eoa() -> Result<()> {
        let (_anvil, provider, _l1_client) =
            ProviderBuilder::new().connect_anvil_with_l1_client()?;
        let mut contracts = Contracts::new();
        let admin = provider.get_accounts().await?[0];

        let fee_contract_proxy_addr =
            deploy_fee_contract_proxy(&provider, &mut contracts, admin).await?;
        let fee_contract_proxy = FeeContract::new(fee_contract_proxy_addr, &provider);
        let curr_version = fee_contract_proxy.getVersion().call().await?;
        assert_eq!(curr_version, (1, 0, 1).into()); // since the current version of the contract is 1.0.1 as needed for the patch

        let cached_impl_addr = contracts.address(Contract::FeeContract);

        // For patch upgrades, we need to clear the cache to allow redeployment
        contracts.remove(&Contract::FeeContract);

        // Test the upgrade function directly
        let receipt = upgrade_fee_v1(&provider, &mut contracts).await?;

        assert!(receipt.inner.is_success());

        // Verify a new implementation was deployed (if old one existed)
        let new_impl_addr = contracts.address(Contract::FeeContract);
        if let Some(old_addr) = cached_impl_addr {
            assert_ne!(
                old_addr,
                new_impl_addr.expect("New implementation should be deployed"),
                "New implementation should have a different address"
            );
        }

        // Verify the proxy now points to the new implementation
        let new_proxy_impl = read_proxy_impl(&provider, fee_contract_proxy_addr).await?;
        assert_eq!(
            new_proxy_impl,
            new_impl_addr.expect("New implementation should be deployed"),
            "Proxy should point to the new implementation address"
        );

        // Verify version is correct (this is already checked in upgrade_fee_v1, but explicit here)
        let new_version = fee_contract_proxy.getVersion().call().await?;
        assert_eq!(new_version, (1, 0, 1).into());

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_upgrade_light_client_v2_twice_checks_impl_address() -> Result<()> {
        let provider = ProviderBuilder::new().connect_anvil_with_wallet();
        let mut contracts = Contracts::new();
        let blocks_per_epoch = 10;
        let epoch_start_block = 22;

        // Prepare initialization inputs
        let genesis_state = LightClientStateSol::dummy_genesis();
        let genesis_stake = StakeTableStateSol::dummy_genesis();
        let admin = provider.get_accounts().await?[0];
        let prover = Address::random();

        // Deploy proxy and V1
        let lc_proxy_addr = deploy_light_client_proxy(
            &provider,
            &mut contracts,
            false,
            genesis_state.clone(),
            genesis_stake.clone(),
            admin,
            Some(prover),
        )
        .await?;

        // First upgrade to V2
        upgrade_light_client_v2(
            &provider,
            &mut contracts,
            false, // is_mock
            blocks_per_epoch,
            epoch_start_block,
        )
        .await?;

        // Capture the implementation address after first upgrade
        let first_impl_addr = read_proxy_impl(&provider, lc_proxy_addr).await?;

        // Also capture what's in the cache
        let cached_impl_addr = contracts.address(Contract::LightClientV2);
        assert_eq!(
            first_impl_addr,
            cached_impl_addr.expect("LightClientV2 should be in cache"),
            "First upgrade: proxy should point to cached implementation"
        );

        // Second upgrade to V2 (re-applying same version)
        // For patch upgrades, we need to clear the cache to allow redeployment
        contracts.remove(&Contract::LightClientV2);

        // Second upgrade to V2 (re-applying same version)
        upgrade_light_client_v2(
            &provider,
            &mut contracts,
            false, // is_mock
            blocks_per_epoch,
            epoch_start_block,
        )
        .await?;

        // Check if implementation address changed
        let second_impl_addr = read_proxy_impl(&provider, lc_proxy_addr).await?;

        let cached_impl_addr_after = contracts.address(Contract::LightClientV2);
        assert_ne!(
            first_impl_addr, second_impl_addr,
            "LightClientV2 should have been deployed again"
        );
        assert_eq!(
            second_impl_addr,
            cached_impl_addr_after.expect("LightClientV2 should still be in cache"),
            "Second upgrade: proxy should point to cached implementation"
        );

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn test_encode_multisig_transaction() -> Result<()> {
        let (anvil, provider, _l1_client) =
            ProviderBuilder::new().connect_anvil_with_l1_client()?;
        let mut contracts = Contracts::new();
        let provider_wallet = provider.get_accounts().await?[0];

        let fee_contract_proxy_addr =
            deploy_fee_contract_proxy(&provider, &mut contracts, provider_wallet).await?;
        let new_owner = Address::random();

        // Use DeployerArgsBuilder to test encode_multisig_transaction
        use builder::DeployerArgsBuilder;

        let mut args_builder = DeployerArgsBuilder::default();
        args_builder
            .deployer(provider.clone())
            .rpc_url(anvil.endpoint_url())
            .multisig(provider_wallet)
            .multisig_transaction_target(fee_contract_proxy_addr)
            .multisig_transaction_function_signature("transferOwnership(address)".to_string())
            .multisig_transaction_function_args(vec![new_owner.to_string()])
            .multisig_transaction_value("0".to_string());

        let args = args_builder.build()?;

        let result = args.encode_multisig_transaction().await;

        match result {
            Ok(_) => {
                tracing::info!("Multisig transaction proposal succeeded in dry_run mode");
                tracing::info!("Result: {:?}", result);
            },
            Err(e) => {
                tracing::info!("Multisig transaction proposal failed: {}", e);
            },
        }

        Ok(())
    }

    #[test_log::test(tokio::test)]
    async fn transfer_ownership_to_timelock_target_eoa_fails() -> Result<()> {
        let provider = ProviderBuilder::new().connect_anvil_with_wallet();
        let multisig = Address::random();
        let eoa_address = Address::random();

        // Set up contracts with an EOA address registered as the OpsTimelock
        let mut contracts = Contracts::new();
        contracts.insert(Contract::OpsTimelock, eoa_address);

        // Deploy a FeeContractProxy so there's a target contract
        let admin = provider.get_accounts().await?[0];
        deploy_fee_contract_proxy(&provider, &mut contracts, admin).await?;

        let mut args_builder = DeployerArgsBuilder::default();
        args_builder
            .deployer(provider.clone())
            .rpc_url(Url::parse("http://localhost:8545")?)
            .multisig(multisig)
            .target_contract(OwnableContract::FeeContractProxy);

        let args = args_builder.build()?;
        assert!(
            args.encode_transfer_ownership_to_timelock(&mut contracts)
                .await
                .unwrap_err()
                .to_string()
                .contains("Timelock address is not a contract")
        );

        Ok(())
    }
}