espresso_contract_deployer/

builder.rs

//! builder pattern for

use std::{fs, path::PathBuf};

use alloy::{
    hex::FromHex,
    primitives::{Address, B256, Bytes, U256},
    providers::{Provider, WalletProvider},
};
use anyhow::{Context, Result, ensure};
use derive_builder::Builder;
use espresso_types::v0_1::L1Client;
use hotshot_contract_adapter::sol_types::{LightClientStateSol, StakeTableStateSol};
use url::Url;

use crate::{
    Contract, Contracts, OwnableContract, encode_function_call,
    output::output_safe_tx_builder,
    proposals::{
        multisig::{
            LightClientV2UpgradeParams, MultisigOwnerCheck, StakeTableV2UpgradeParams,
            StakeTableV3UpgradeParams, TransferOwnershipParams, encode_generic_calldata,
            transfer_ownership_from_multisig_to_timelock, upgrade_esp_token_v2_multisig_owner,
            upgrade_fee_contract_multisig_owner, upgrade_light_client_v2_multisig_owner,
            upgrade_light_client_v3_multisig_owner, upgrade_stake_table_v2_multisig_owner,
            upgrade_stake_table_v3_multisig_owner,
        },
        timelock::{
            StakeTableV3TimelockProposalParams, TimelockOperationParams, TimelockOperationPayload,
            TimelockOperationType, derive_timelock_address_from_contract_type,
            perform_timelock_operation, upgrade_stake_table_v3_timelock_proposal,
        },
    },
};

/// Convenient handler that builds all the input arguments ready to be deployed.
/// - `deployer`: deployer's wallet provider
/// - `rpc_url`: RPC URL for the L1 network
/// - `token_recipient`: initial token holder, same as deployer if None.
/// - `mock_light_client`: flag to indicate whether deploying mocked contract
/// - `use_multisig`: flag to indicate whether to use multisig for upgrades
/// - `genesis_lc_state`: Genesis light client state
/// - `genesis_st_state`: Genesis stake table state
/// - `permissioned_prover`: permissioned light client prover address
/// - `blocks_per_epoch`: epoch length in block height
/// - `epoch_start_block`: block height for the first *activated* epoch
/// - `exit_escrow_period`: exit escrow period for stake table (in seconds)
/// - `multisig`: new owner/multisig that owns all the proxy contracts
/// - `multisig_pauser`: multisig address that has the pauser role
/// - `initial_token_supply`: initial token supply for the token contract
/// - `token_name`: name of the token
/// - `token_symbol`: symbol of the token
/// - `ops_timelock_admin`: admin address for the ops timelock
/// - `ops_timelock_delay`: delay for the ops timelock
/// - `ops_timelock_executors`: executors for the ops timelock
/// - `ops_timelock_proposers`: proposers for the ops timelock
/// - `safe_exit_timelock_admin`: admin address for the safe exit timelock
/// - `safe_exit_timelock_delay`: delay for the safe exit timelock
/// - `safe_exit_timelock_executors`: executors for the safe exit timelock
/// - `safe_exit_timelock_proposers`: proposers for the safe exit timelock
/// - `timelock_operation_type`: type of the timelock operation
/// - `target_contract`: target contract for the contract operations
/// - `timelock_operation_value`: value for the timelock operation
/// - `timelock_operation_delay`: delay for the timelock operation
/// - `timelock_operation_function_signature`: function signature for the timelock operation
/// - `timelock_operation_function_values`: function values for the timelock operation
/// - `timelock_operation_salt`: salt for the timelock operation
/// - `use_timelock_owner`: flag to indicate whether to transfer ownership to the timelock owner
/// - `timelock_address`: address of the timelock contract
#[derive(Builder, Clone)]
#[builder(setter(strip_option))]
pub struct DeployerArgs<P: Provider + WalletProvider> {
    deployer: P,
    rpc_url: Url,
    #[builder(default)]
    token_recipient: Option<Address>,
    #[builder(default)]
    mock_light_client: bool,
    #[builder(default)]
    use_multisig: bool,
    #[builder(default)]
    genesis_lc_state: Option<LightClientStateSol>,
    #[builder(default)]
    genesis_st_state: Option<StakeTableStateSol>,
    #[builder(default)]
    permissioned_prover: Option<Address>,
    #[builder(default)]
    blocks_per_epoch: Option<u64>,
    #[builder(default)]
    epoch_start_block: Option<u64>,
    #[builder(default)]
    exit_escrow_period: Option<U256>,
    #[builder(default)]
    multisig: Option<Address>,
    #[builder(default)]
    multisig_pauser: Option<Address>,
    #[builder(default)]
    initial_token_supply: Option<U256>,
    #[builder(default)]
    token_name: Option<String>,
    #[builder(default)]
    token_symbol: Option<String>,
    #[builder(default)]
    ops_timelock_admin: Option<Address>,
    #[builder(default)]
    ops_timelock_delay: Option<U256>,
    #[builder(default)]
    ops_timelock_executors: Option<Vec<Address>>,
    #[builder(default)]
    ops_timelock_proposers: Option<Vec<Address>>,
    #[builder(default)]
    safe_exit_timelock_admin: Option<Address>,
    #[builder(default)]
    safe_exit_timelock_delay: Option<U256>,
    #[builder(default)]
    safe_exit_timelock_executors: Option<Vec<Address>>,
    #[builder(default)]
    safe_exit_timelock_proposers: Option<Vec<Address>>,
    #[builder(default)]
    timelock_operation_type: Option<TimelockOperationType>,
    #[builder(default)]
    target_contract: Option<OwnableContract>,
    #[builder(default)]
    timelock_operation_value: Option<U256>,
    #[builder(default)]
    timelock_operation_delay: Option<U256>,
    #[builder(default)]
    timelock_operation_function_signature: Option<String>,
    #[builder(default)]
    timelock_operation_function_values: Option<Vec<String>>,
    #[builder(default)]
    timelock_operation_salt: Option<String>,
    #[builder(default)]
    use_timelock_owner: Option<bool>,
    #[builder(default)]
    transfer_ownership_from_eoa: Option<bool>,
    #[builder(default)]
    transfer_ownership_new_owner: Option<Address>,
    #[builder(default)]
    timelock_operation_id: Option<String>,
    #[builder(default)]
    multisig_transaction_target: Option<Address>,
    #[builder(default)]
    multisig_transaction_function_signature: Option<String>,
    #[builder(default)]
    multisig_transaction_function_args: Option<Vec<String>>,
    #[builder(default)]
    multisig_transaction_value: Option<String>,
    #[builder(default)]
    output_path: Option<PathBuf>,
    #[builder(default)]
    output_dir: Option<PathBuf>,
    #[builder(default)]
    chain_id: u64,
}

impl<P: Provider + WalletProvider> DeployerArgs<P> {
    /// deploy target contracts
    pub async fn deploy(&self, contracts: &mut Contracts, target: Contract) -> Result<()> {
        let provider = &self.deployer;
        let admin = provider.default_signer_address();
        match target {
            Contract::FeeContractProxy => {
                if contracts.address(Contract::FeeContractProxy).is_some() {
                    // Upgrade path
                    let use_multisig = self.use_multisig;

                    tracing::info!(?use_multisig, "Upgrading FeeContract to V1.0.1");
                    if use_multisig {
                        let calldata = upgrade_fee_contract_multisig_owner(
                            provider,
                            contracts,
                            MultisigOwnerCheck::RequireContract,
                        )
                        .await?
                        .with_description("Upgrade FeeContract to V1.0.1".to_string());
                        output_safe_tx_builder(
                            &calldata,
                            self.output_path.as_deref(),
                            self.chain_id,
                        )?;
                    } else {
                        crate::upgrade_fee_v1(provider, contracts).await?;
                    }
                } else {
                    // Deploy path
                    let addr = crate::deploy_fee_contract_proxy(provider, contracts, admin).await?;

                    if let Some(use_timelock_owner) = self.use_timelock_owner {
                        // FeeContract uses OpsTimelock because:
                        // - It handles critical fee collection and distribution logic
                        // - May require emergency updates for security or functionality
                        // - OpsTimelock provides a shorter delay for critical operations
                        tracing::info!(
                            "Transferring ownership to OpsTimelock: {:?}",
                            use_timelock_owner
                        );
                        // deployer is the timelock owner
                        if use_timelock_owner {
                            let timelock_addr = derive_timelock_address_from_contract_type(
                                OwnableContract::FeeContractProxy,
                                contracts,
                            )?;
                            crate::transfer_ownership(
                                provider,
                                Contract::FeeContractProxy,
                                addr,
                                timelock_addr,
                            )
                            .await?;
                        }
                    } else if let Some(multisig) = self.multisig {
                        tracing::info!("Transferring ownership to multisig: {:?}", multisig);
                        crate::transfer_ownership(
                            provider,
                            Contract::FeeContractProxy,
                            addr,
                            multisig,
                        )
                        .await?;
                    }
                }
            },
            Contract::EspTokenProxy => {
                let token_recipient = self.token_recipient.unwrap_or(admin);
                let token_name = self
                    .token_name
                    .clone()
                    .context("Token name must be set when deploying esp token")?;
                let token_symbol = self
                    .token_symbol
                    .clone()
                    .context("Token symbol must be set when deploying esp token")?;
                let initial_supply = self
                    .initial_token_supply
                    .context("Initial token supply must be set when deploying esp token")?;
                crate::deploy_token_proxy(
                    provider,
                    contracts,
                    admin,
                    token_recipient,
                    initial_supply,
                    &token_name,
                    &token_symbol,
                )
                .await?;

                // NOTE: we don't transfer ownership to multisig, we only do so after V2 upgrade
            },
            Contract::EspTokenV2 => {
                let use_multisig = self.use_multisig;

                if use_multisig {
                    let calldata = upgrade_esp_token_v2_multisig_owner(
                        provider,
                        contracts,
                        MultisigOwnerCheck::RequireContract,
                    )
                    .await?
                    .with_description("Upgrade EspToken to V2".to_string());
                    output_safe_tx_builder(&calldata, self.output_path.as_deref(), self.chain_id)?;
                } else {
                    crate::upgrade_esp_token_v2(provider, contracts).await?;
                    let addr = contracts
                        .address(Contract::EspTokenProxy)
                        .expect("fail to get EspTokenProxy address");

                    if let Some(use_timelock_owner) = self.use_timelock_owner {
                        // deployer is the timelock owner
                        if use_timelock_owner {
                            // EspToken uses SafeExitTimelock (not OpsTimelock) because:
                            // - It's a simple ERC20 token with minimal upgrade complexity
                            // - No emergency updates are expected for token functionality
                            // - SafeExitTimelock provides sufficient security for token operations
                            tracing::info!("Transferring ownership to SafeExitTimelock");
                            let timelock_addr = derive_timelock_address_from_contract_type(
                                OwnableContract::EspTokenProxy,
                                contracts,
                            )?;
                            crate::transfer_ownership(
                                provider,
                                Contract::EspTokenProxy,
                                addr,
                                timelock_addr,
                            )
                            .await?;
                        }
                    } else if let Some(multisig) = self.multisig {
                        let token_proxy = contracts
                            .address(Contract::EspTokenProxy)
                            .expect("fail to get EspTokenProxy address");
                        crate::transfer_ownership(
                            provider,
                            Contract::EspTokenProxy,
                            token_proxy,
                            multisig,
                        )
                        .await?;
                    }
                }
            },
            Contract::LightClientProxy => {
                assert!(
                    self.genesis_lc_state.is_some(),
                    "forget to specify genesis_lc_state()"
                );
                assert!(
                    self.genesis_st_state.is_some(),
                    "forget to specify genesis_st_state()"
                );
                crate::deploy_light_client_proxy(
                    provider,
                    contracts,
                    self.mock_light_client,
                    self.genesis_lc_state.clone().unwrap(),
                    self.genesis_st_state.clone().unwrap(),
                    admin,
                    self.permissioned_prover,
                )
                .await?;
                // NOTE: we don't transfer ownership to multisig, we only do so after V2 upgrade
            },
            Contract::LightClientV2 => {
                assert!(
                    self.blocks_per_epoch.is_some(),
                    "forgot to specify blocks_per_epoch()"
                );
                assert!(
                    self.epoch_start_block.is_some(),
                    "forgot to specify epoch_start_block()"
                );

                let use_mock = self.mock_light_client;
                let use_multisig = self.use_multisig;
                let mut blocks_per_epoch = self.blocks_per_epoch.unwrap();
                let epoch_start_block = self.epoch_start_block.unwrap();

                // TEST-ONLY: if this config is not yet set, we use u64::MAX
                // to avoid contract complaining about invalid zero-valued blocks_per_epoch.
                // This value will allow tests to proceed with realistic epoch behavior.
                // TODO: remove this once we have a proper way to set blocks_per_epoch
                if use_mock && blocks_per_epoch == 0 {
                    blocks_per_epoch = u64::MAX;
                }
                tracing::info!(%blocks_per_epoch, ?use_multisig, "Upgrading LightClientV2 with ");
                if use_multisig {
                    let calldata = upgrade_light_client_v2_multisig_owner(
                        provider,
                        contracts,
                        LightClientV2UpgradeParams {
                            blocks_per_epoch,
                            epoch_start_block,
                        },
                        use_mock,
                        MultisigOwnerCheck::RequireContract,
                    )
                    .await?
                    .with_description("Upgrade LightClient to V2".to_string());
                    output_safe_tx_builder(&calldata, self.output_path.as_deref(), self.chain_id)?;
                } else {
                    crate::upgrade_light_client_v2(
                        provider,
                        contracts,
                        use_mock,
                        blocks_per_epoch,
                        epoch_start_block,
                    )
                    .await?;
                    // NOTE: we don't transfer ownership to multisig, we only do so after V3 upgrade
                }
            },
            Contract::LightClientV3 => {
                let use_mock = self.mock_light_client;
                let use_multisig = self.use_multisig;

                tracing::info!(?use_multisig, "Upgrading LightClientV3 with ");
                if use_multisig {
                    let calldata = upgrade_light_client_v3_multisig_owner(
                        provider,
                        contracts,
                        use_mock,
                        MultisigOwnerCheck::RequireContract,
                    )
                    .await?
                    .with_description("Upgrade LightClient to V3".to_string());
                    output_safe_tx_builder(&calldata, self.output_path.as_deref(), self.chain_id)?;
                } else {
                    crate::upgrade_light_client_v3(provider, contracts, use_mock).await?;

                    // Transfer ownership to Timelook or MultiSig
                    let addr = contracts
                        .address(Contract::LightClientProxy)
                        .expect("fail to get LightClientProxy address");

                    if let Some(use_timelock_owner) = self.use_timelock_owner {
                        // LightClient uses OpsTimelock because:
                        // - It's a critical security component for the network
                        // - May require emergency updates for security vulnerabilities
                        // - OpsTimelock provides a shorter delay for critical operations
                        tracing::info!("Transferring ownership to OpsTimelock");
                        // deployer is the timelock owner
                        if use_timelock_owner {
                            let timelock_addr = derive_timelock_address_from_contract_type(
                                OwnableContract::LightClientProxy,
                                contracts,
                            )?;
                            crate::transfer_ownership(
                                provider,
                                Contract::LightClientProxy,
                                addr,
                                timelock_addr,
                            )
                            .await?;
                        }
                    } else if let Some(multisig) = self.multisig {
                        crate::transfer_ownership(
                            provider,
                            Contract::LightClientProxy,
                            addr,
                            multisig,
                        )
                        .await?;
                    }
                }
            },
            Contract::StakeTableProxy => {
                let token_addr = contracts
                    .address(Contract::EspTokenProxy)
                    .context("no ESP token proxy address")?;
                let lc_addr = contracts
                    .address(Contract::LightClientProxy)
                    .context("no LightClient proxy address")?;
                let escrow_period = self
                    .exit_escrow_period
                    .unwrap_or(U256::from(crate::DEFAULT_EXIT_ESCROW_PERIOD_SECONDS));
                crate::deploy_stake_table_proxy(
                    provider,
                    contracts,
                    token_addr,
                    lc_addr,
                    escrow_period,
                    admin,
                )
                .await?;

                // NOTE: we don't transfer ownership to multisig, we only do so after V2 upgrade
            },
            Contract::StakeTableV2 => {
                let use_multisig = self.use_multisig;
                // Default to deployer address if pauser not explicitly set (for local demos)
                let multisig_pauser = self.multisig_pauser.unwrap_or(admin);
                let l1_client = L1Client::new(vec![self.rpc_url.clone()])?;
                tracing::info!(?use_multisig, "Upgrading to StakeTableV2 with ");
                if use_multisig {
                    let calldata = upgrade_stake_table_v2_multisig_owner(
                        provider,
                        l1_client,
                        contracts,
                        StakeTableV2UpgradeParams {
                            multisig_address: self.multisig.context(
                                "Multisig address must be set when upgrading to --use-multisig \
                                 flag is present",
                            )?,
                            pauser: multisig_pauser,
                        },
                        MultisigOwnerCheck::RequireContract,
                    )
                    .await?
                    .with_description("Upgrade StakeTable to V2".to_string());
                    output_safe_tx_builder(&calldata, self.output_path.as_deref(), self.chain_id)?;
                } else {
                    // Pick admin from config. StakeTable uses OpsTimelock for faster
                    // emergency updates since it handles critical staking ops.
                    let admin = match self.use_timelock_owner {
                        Some(true) => derive_timelock_address_from_contract_type(
                            OwnableContract::StakeTableProxy,
                            contracts,
                        )?,
                        Some(false) => admin, // deployer
                        None => {
                            if let Some(multisig) = self.multisig {
                                multisig
                            } else {
                                admin // deployer
                            }
                        },
                    };

                    tracing::info!("Upgrading StakeTableV2 with admin: {:?}", admin);
                    crate::upgrade_stake_table_v2(
                        provider,
                        l1_client,
                        contracts,
                        multisig_pauser,
                        admin,
                    )
                    .await?;

                    // initializeV2() handles ownership transfer, so no separate call needed
                }
            },
            Contract::StakeTableV3 => {
                let use_multisig = self.use_multisig;
                let use_timelock_owner = self.use_timelock_owner.unwrap_or(false);
                tracing::info!(
                    ?use_multisig,
                    ?use_timelock_owner,
                    "Upgrading to StakeTableV3"
                );
                if use_timelock_owner {
                    // StakeTableV3 upgrade via timelock-owned proxy: deploy the new impl
                    // and emit `schedule` + `execute` timelock calldata. An operator
                    // submits `schedule` through a timelock proposer, waits for the
                    // delay to elapse, then submits `execute` through an executor.
                    let salt_str = self.timelock_operation_salt.clone().context(
                        "timelock_operation_salt must be set for StakeTableV3 upgrade with \
                         --use-timelock-owner",
                    )?;
                    let salt_trimmed = salt_str.trim();
                    let hex_str = salt_trimmed.strip_prefix("0x").unwrap_or(salt_trimmed);
                    let salt = B256::from_hex(hex_str).context("Invalid salt hex format")?;
                    ensure!(
                        salt != B256::ZERO,
                        "timelock_operation_salt must be non-zero"
                    );
                    let delay = self.timelock_operation_delay.context(
                        "timelock_operation_delay must be set for StakeTableV3 upgrade with \
                         --use-timelock-owner",
                    )?;

                    let proposal = upgrade_stake_table_v3_timelock_proposal(
                        provider,
                        contracts,
                        StakeTableV3TimelockProposalParams { salt, delay },
                    )
                    .await?;

                    let output_dir = self
                        .output_dir
                        .as_deref()
                        .context("--calldata-out-dir required for StakeTableV3 timelock upgrade")?;
                    fs::create_dir_all(output_dir).with_context(|| {
                        format!("failed to create output dir {}", output_dir.display())
                    })?;
                    output_safe_tx_builder(
                        &proposal.schedule,
                        Some(&output_dir.join("schedule.json")),
                        self.chain_id,
                    )?;
                    output_safe_tx_builder(
                        &proposal.execute,
                        Some(&output_dir.join("execute.json")),
                        self.chain_id,
                    )?;
                } else if use_multisig {
                    let calldata = upgrade_stake_table_v3_multisig_owner(
                        provider,
                        contracts,
                        StakeTableV3UpgradeParams {
                            multisig_address: self.multisig.context(
                                "Multisig address required for StakeTableV3 upgrade with \
                                 --use-multisig",
                            )?,
                        },
                        MultisigOwnerCheck::RequireContract,
                    )
                    .await?
                    .with_description("Upgrade StakeTable to V3".to_string());
                    output_safe_tx_builder(&calldata, self.output_path.as_deref(), self.chain_id)?;
                } else {
                    crate::upgrade_stake_table_v3(provider, contracts).await?;
                }
            },
            Contract::OpsTimelock => {
                let ops_timelock_delay = self
                    .ops_timelock_delay
                    .context("Ops Timelock delay must be set when deploying Ops Timelock")?;
                let ops_timelock_proposers = self
                    .ops_timelock_proposers
                    .clone()
                    .context("Ops Timelock proposers must be set when deploying Ops Timelock")?;
                let ops_timelock_executors = self
                    .ops_timelock_executors
                    .clone()
                    .context("Ops Timelock executors must be set when deploying Ops Timelock")?;
                let ops_timelock_admin = self
                    .ops_timelock_admin
                    .context("Ops Timelock admin must be set when deploying Ops Timelock")?;
                crate::deploy_ops_timelock(
                    provider,
                    contracts,
                    ops_timelock_delay,
                    ops_timelock_proposers,
                    ops_timelock_executors,
                    ops_timelock_admin,
                )
                .await?;
            },
            Contract::SafeExitTimelock => {
                let safe_exit_timelock_delay = self.safe_exit_timelock_delay.context(
                    "SafeExitTimelock delay must be set when deploying SafeExitTimelock",
                )?;
                let safe_exit_timelock_proposers =
                    self.safe_exit_timelock_proposers.clone().context(
                        "SafeExitTimelock proposers must be set when deploying SafeExitTimelock",
                    )?;
                let safe_exit_timelock_executors =
                    self.safe_exit_timelock_executors.clone().context(
                        "SafeExitTimelock executors must be set when deploying SafeExitTimelock",
                    )?;
                let safe_exit_timelock_admin = self.safe_exit_timelock_admin.context(
                    "SafeExitTimelock admin must be set when deploying SafeExitTimelock",
                )?;
                crate::deploy_safe_exit_timelock(
                    provider,
                    contracts,
                    safe_exit_timelock_delay,
                    safe_exit_timelock_proposers,
                    safe_exit_timelock_executors,
                    safe_exit_timelock_admin,
                )
                .await?;
            },
            Contract::RewardClaimProxy => {
                let token_addr = contracts
                    .address(Contract::EspTokenProxy)
                    .context("no ESP token proxy address")?;
                let lc_addr = contracts
                    .address(Contract::LightClientProxy)
                    .context("no LightClient proxy address")?;
                // RewardClaimProxy only needs one pauser
                // Default to deployer address if pauser not explicitly set (for local demos)
                let deployer_addr = provider.default_signer_address();
                let pauser = self.multisig_pauser.unwrap_or(deployer_addr);

                // RewardClaim uses SafeExitTimelock (longer delay) since it can mint tokens
                // and users need time to react to upgrades. Can be paused in emergencies.
                let admin = match self.use_timelock_owner {
                    Some(true) => derive_timelock_address_from_contract_type(
                        OwnableContract::RewardClaimProxy,
                        contracts,
                    )?,
                    Some(false) => admin, // deployer
                    None => {
                        if let Some(multisig) = self.multisig {
                            multisig
                        } else {
                            admin // deployer
                        }
                    },
                };

                tracing::info!("Deploying RewardClaimProxy with admin: {:?}", admin);
                crate::deploy_reward_claim_proxy(
                    provider, contracts, token_addr, lc_addr, admin, pauser,
                )
                .await?;

                // RewardClaim uses AccessControl only (no Ownable). Admin is set in initialize(),
                // not via separate transfer_ownership() call.
            },
            _ => {
                panic!("Deploying {target} not supported.");
            },
        }
        Ok(())
    }

    /// Deploy all contracts up to and including stake table v1
    pub async fn deploy_to_stake_table_v1(&self, contracts: &mut Contracts) -> Result<()> {
        // Deploy timelocks first so they can be used as owners for other contracts
        self.deploy(contracts, Contract::OpsTimelock).await?;
        self.deploy(contracts, Contract::SafeExitTimelock).await?;

        // Then deploy other contracts
        self.deploy(contracts, Contract::FeeContractProxy).await?;
        self.deploy(contracts, Contract::EspTokenProxy).await?;
        self.deploy(contracts, Contract::LightClientProxy).await?;
        self.deploy(contracts, Contract::LightClientV2).await?;
        self.deploy(contracts, Contract::StakeTableProxy).await?;
        Ok(())
    }

    /// Deploy all contracts up to and including stake table V2.
    pub async fn deploy_to_stake_table_v2(&self, contracts: &mut Contracts) -> Result<()> {
        self.deploy_to_stake_table_v1(contracts).await?;
        self.deploy(contracts, Contract::StakeTableV2).await?;
        self.deploy(contracts, Contract::LightClientV3).await?;
        self.deploy(contracts, Contract::RewardClaimProxy).await?;
        self.deploy(contracts, Contract::EspTokenV2).await?;
        Ok(())
    }

    /// Deploy all contracts up to and including stake table V3.
    pub async fn deploy_to_stake_table_v3(&self, contracts: &mut Contracts) -> Result<()> {
        self.deploy_to_stake_table_v2(contracts).await?;
        self.deploy(contracts, Contract::StakeTableV3).await?;
        Ok(())
    }

    // Perform a timelock operation
    ///
    /// This function can perform timelock operations via two paths:
    /// - **Multisig path**: If `multisig` field from DeployerArgs is set, the operation will be proposed via Safe multisig
    /// - **EOA path**: If `multisig` field from DeployerArgs is not set, the operation will be executed directly via EOA (useful for tests/local development)
    ///
    /// Parameters:
    /// - `contracts`: ref to deployed contracts
    ///
    pub async fn propose_timelock_operation_for_contract(
        &self,
        contracts: &mut Contracts,
    ) -> Result<()> {
        let timelock_operation_type = self
            .timelock_operation_type
            .context("Timelock operation type not found")?;
        let target_contract = self.target_contract.context("Timelock target not found")?;
        let contract_type: Contract = target_contract.into();
        let target_addr = contracts
            .address(contract_type)
            .context(format!("{:?} address not found", contract_type))?;

        let (timelock_operation_data, operation_id) = if timelock_operation_type
            == TimelockOperationType::Cancel
            && self.timelock_operation_id.is_some()
        {
            // Cancel operation with explicit operation_id - use minimal payload
            let op_id_str = self
                .timelock_operation_id
                .as_ref()
                .context("Operation ID not found")?;
            let op_id = if let Some(stripped) = op_id_str.strip_prefix("0x") {
                B256::from_hex(stripped).context("Invalid operation ID hex format")?
            } else {
                B256::from_hex(op_id_str).context("Invalid operation ID hex format")?
            };

            let minimal_payload = TimelockOperationPayload {
                target: target_addr,
                value: U256::ZERO,
                data: Bytes::new(),
                predecessor: B256::ZERO,
                salt: B256::ZERO,
                delay: U256::ZERO,
            };
            (minimal_payload, Some(op_id))
        } else {
            // Schedule or Execute operation - we need full operation details
            let value = self
                .timelock_operation_value
                .context("Timelock operation value not found")?;
            let function_signature = self
                .timelock_operation_function_signature
                .as_ref()
                .context("Timelock operation function signature not found")?;
            let function_values = self
                .timelock_operation_function_values
                .clone()
                .context("Timelock operation function values not found")?;
            let salt = self
                .timelock_operation_salt
                .clone()
                .context("Timelock operation salt not found")?;
            let delay = self
                .timelock_operation_delay
                .context("Timelock operation delay not found")?;

            let function_calldata =
                encode_function_call(function_signature, function_values.clone())
                    .context("Failed to encode function data")?;

            let salt_trimmed = salt.trim();
            let hex_str = salt_trimmed.strip_prefix("0x").unwrap_or(salt_trimmed);
            let salt_bytes = B256::from_hex(hex_str).context("Invalid salt hex format")?;
            ensure!(
                salt_bytes != B256::ZERO,
                "timelock_operation_salt must be non-zero"
            );

            let operation = TimelockOperationPayload {
                target: target_addr,
                value,
                data: function_calldata,
                predecessor: B256::ZERO, // Default to no predecessor
                salt: salt_bytes,
                delay,
            };
            (operation, None)
        };

        let params = if let Some(multisig_proposer) = self.multisig {
            // Multisig path
            TimelockOperationParams {
                multisig_proposer: Some(multisig_proposer),
                operation_id,
                dry_run: false,
            }
        } else {
            // EOA path (for tests/local development)
            TimelockOperationParams {
                multisig_proposer: None,
                operation_id,
                dry_run: false,
            }
        };

        perform_timelock_operation(
            &self.deployer,
            contract_type,
            timelock_operation_data,
            timelock_operation_type,
            params,
        )
        .await?;

        Ok(())
    }

    /// Encode ownership transfer from multisig to timelock as calldata
    pub async fn encode_transfer_ownership_to_timelock(
        &self,
        contracts: &mut Contracts,
    ) -> Result<()> {
        // Validate multisig is set (even though we now encode calldata rather than submit to Safe)
        let _multisig = self.multisig.expect(
            "Multisig address must be set when proposing ownership transfer. Use \
             --multisig-address or ESPRESSO_ETH_MULTISIG_ADDRESS",
        );
        let ownable_contract = self.target_contract.ok_or_else(|| {
            anyhow::anyhow!(
                "Must provide target_contract when using \
                 --propose-transfer-ownership-to-timelock. Use --target-contract or \
                 ESPRESSO_TARGET_CONTRACT"
            )
        })?;

        let timelock_address =
            derive_timelock_address_from_contract_type(ownable_contract, contracts)?;

        if !crate::is_contract(&self.deployer, timelock_address).await? {
            anyhow::bail!(
                "Timelock address is not a contract (expected timelock at {timelock_address:#x})"
            );
        }

        let contract: Contract = ownable_contract.into();
        tracing::info!(
            "Encoding transfer of ownership from multisig to timelock for {:?} (timelock: {:?})",
            contract,
            timelock_address
        );
        let calldata = transfer_ownership_from_multisig_to_timelock(
            contracts,
            contract,
            TransferOwnershipParams {
                new_owner: timelock_address,
            },
        )?
        .with_description(format!(
            "Transfer {} ownership to timelock {timelock_address}",
            contract
        ));
        output_safe_tx_builder(&calldata, self.output_path.as_deref(), self.chain_id)?;
        tracing::info!("Successfully encoded ownership transfer for {}", contract);
        Ok(())
    }

    /// Transfer ownership from EOA to new owner
    pub async fn transfer_ownership_from_eoa(&self, contracts: &mut Contracts) -> Result<()> {
        let transfer_ownership_from_eoa = self
            .transfer_ownership_from_eoa
            .ok_or_else(|| anyhow::anyhow!("transfer_ownership_from_eoa flag not set"))?;

        if !transfer_ownership_from_eoa {
            return Ok(());
        }

        let ownable_contract = self.target_contract.ok_or_else(|| {
            anyhow::anyhow!("Must provide target_contract when using transfer_ownership_from_eoa")
        })?;
        let new_owner = self.transfer_ownership_new_owner.ok_or_else(|| {
            anyhow::anyhow!(
                "Must provide transfer_ownership_new_owner when using transfer_ownership_from_eoa"
            )
        })?;

        let contract_type: Contract = ownable_contract.into();
        let contract_address = contracts.address(contract_type).ok_or_else(|| {
            anyhow::anyhow!(
                "Contract {:?} not found in deployed contracts",
                contract_type
            )
        })?;

        // RewardClaim uses AccessControl instead of Ownable, so we need to grant the admin role
        // instead of transferring ownership
        let receipt = if contract_type == Contract::RewardClaimProxy {
            tracing::info!(
                "Granting DEFAULT_ADMIN_ROLE for {:?} to {} (RewardClaim uses AccessControl, not \
                 Ownable)",
                contract_type,
                new_owner
            );
            crate::grant_admin_role(&self.deployer, contract_type, contract_address, new_owner)
                .await?
        } else {
            tracing::info!(
                "Transferring ownership of {:?} from EOA to {}",
                contract_type,
                new_owner
            );
            crate::transfer_ownership(&self.deployer, contract_type, contract_address, new_owner)
                .await?
        };

        tracing::info!(
            "Successfully transferred admin control of {:?} to {}. Transaction: {}",
            contract_type,
            new_owner,
            receipt.transaction_hash
        );

        Ok(())
    }

    /// Encode a multisig transaction as calldata and output it
    pub async fn encode_multisig_transaction(&self) -> Result<()> {
        let target = self
            .multisig_transaction_target
            .context("Multisig transaction target address not found")?;
        let function_signature = self
            .multisig_transaction_function_signature
            .as_ref()
            .context("Multisig transaction function signature not found")?;
        let function_args = self
            .multisig_transaction_function_args
            .clone()
            .unwrap_or_default();
        let value: U256 = self
            .multisig_transaction_value
            .as_deref()
            .unwrap_or("0")
            .parse()
            .context("Failed to parse multisig transaction value as U256")?;

        let calldata = encode_generic_calldata(target, function_signature, function_args, value)?
            .with_description(format!("Call {} on {target}", function_signature));
        output_safe_tx_builder(&calldata, self.output_path.as_deref(), self.chain_id)?;

        Ok(())
    }
}