iota_adapter_latest/

execution_engine.rs

// Copyright (c) Mysten Labs, Inc.
// Modifications Copyright (c) 2024 IOTA Stiftung
// SPDX-License-Identifier: Apache-2.0

pub use checked::*;

#[iota_macros::with_checked_arithmetic]
mod checked {

    use std::{
        cell::RefCell,
        collections::{BTreeMap, BTreeSet, HashSet},
        rc::Rc,
        sync::Arc,
    };

    use iota_move_natives::all_natives;
    use iota_protocol_config::{LimitThresholdCrossed, ProtocolConfig, check_limit_by_meter};
    use iota_sdk_types::{
        Address, Argument, ChangeEpoch, ChangeEpochV2, ChangeEpochV3, ChangeEpochV4, Command,
        EndOfEpochTransactionKind, ExecutionStatus, GasCostSummary, GasPayment, GenesisTransaction,
        Identifier, MoveAuthenticator, ObjectId, ProgrammableTransaction, RandomnessStateUpdate,
        SharedObjectReference, StructTag, SystemPackage, TransactionDenyRulesUpdate,
        TransactionDigest, TransactionEffects, TransactionKind, TypeTag, Version,
    };
    #[cfg(msim)]
    use iota_types::iota_system_state::advance_epoch_result_injection::maybe_modify_result;
    use iota_types::{
        account_abstraction::authenticator_function::{
            AuthenticatorFunctionRef, AuthenticatorFunctionRefForExecution,
            AuthenticatorFunctionRefV1, MoveAuthenticatorForExecution,
            MoveAuthenticatorsForExecution,
        },
        auth_context::{AuthContext, AuthContextData},
        balance::{BALANCE_CREATE_REWARDS_FUNCTION_NAME, BALANCE_DESTROY_REBATES_FUNCTION_NAME},
        base_types::TxContext,
        clock::CONSENSUS_COMMIT_PROLOGUE_FUNCTION_NAME,
        committee::EpochId,
        error::{ExecutionError, ExecutionErrorKind},
        execution::{
            AuthenticateThenExecuteOutput, ExecutionResults, ExecutionResultsV1, ExecutionTiming,
            ResultWithTimings, SharedInput, is_any_invariant_violation, is_cancellation,
            is_certificate_denied, unwrap_move_authentication_error,
        },
        execution_config_utils::to_binary_config,
        gas::{IotaGasStatus, IotaGasStatusAPI},
        inner_temporary_store::InnerTemporaryStore,
        iota_system_state::{ADVANCE_EPOCH_FUNCTION_NAME, AdvanceEpochParams},
        messages_checkpoint::CheckpointTimestamp,
        metrics::LimitsMetrics,
        move_authenticator::MoveAuthenticatorExt,
        object::{OBJECT_START_VERSION, Object, ObjectInner},
        programmable_transaction_builder::ProgrammableTransactionBuilder,
        randomness_state::RANDOMNESS_STATE_UPDATE_FUNCTION_NAME,
        storage::{BackingStore, Storage},
        transaction::{
            CallArg, CancelledObjects, CheckedInputObjects, InputObjects, TransactionKindExt,
        },
        transaction_deny_rules::{
            TRANSACTION_DENY_RULES_CREATE_FUNCTION_NAME, TRANSACTION_DENY_RULES_MODULE,
            TRANSACTION_DENY_RULES_UPDATE_FUNCTION_NAME,
        },
    };
    use move_binary_format::CompiledModule;
    use move_trace_format::format::MoveTraceBuilder;
    use move_vm_runtime::move_vm::MoveVM;
    use tracing::{info, instrument, trace, warn};

    use crate::{
        adapter::new_move_vm,
        execution_mode::{self, ExecutionMode},
        gas_charger::GasCharger,
        programmable_transactions,
        temporary_store::TemporaryStore,
        type_layout_resolver::TypeLayoutResolver,
    };

    /// The main entry point to the adapter's transaction execution. It
    /// prepares a transaction for execution, then executes it through an
    /// inner execution method and finally produces an instance of
    /// transaction effects. It also returns the inner temporary store, which
    /// contains the objects resulting from the transaction execution, the gas
    /// status instance, which tracks the gas usage, and the execution result.
    /// The function handles transaction execution based on the provided
    /// `TransactionKind`. It checks for any expensive operations, manages
    /// shared object references, and ensures transaction dependencies are
    /// met. The returned objects are not committed to the store until the
    /// resulting effects are applied by the caller.
    #[instrument(name = "tx_execute_to_effects", level = "debug", skip_all)]
    pub fn execute_transaction_to_effects<Mode: ExecutionMode>(
        store: &dyn BackingStore,
        input_objects: CheckedInputObjects,
        gas_data: GasPayment,
        gas_status: IotaGasStatus,
        transaction_kind: TransactionKind,
        transaction_signer: Address,
        transaction_digest: TransactionDigest,
        move_vm: &Arc<MoveVM>,
        epoch_id: &EpochId,
        epoch_timestamp_ms: u64,
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
        enable_expensive_checks: bool,
        certificate_deny_set: &HashSet<TransactionDigest>,
        trace_builder_opt: &mut Option<MoveTraceBuilder>,
    ) -> (
        InnerTemporaryStore,
        IotaGasStatus,
        TransactionEffects,
        Vec<ExecutionTiming>,
        Result<Mode::ExecutionResults, ExecutionError>,
    ) {
        let input_objects = input_objects.into_inner();
        let mutable_inputs = if enable_expensive_checks {
            input_objects.mutable_inputs().keys().copied().collect()
        } else {
            HashSet::new()
        };
        let shared_object_refs = input_objects.filter_shared_objects();
        let receiving_objects = transaction_kind.receiving_objects();
        let transaction_dependencies = input_objects.transaction_dependencies();
        let contains_deleted_input = input_objects.contains_deleted_objects();
        let cancelled_objects = input_objects.get_cancelled_objects();

        let temporary_store = TemporaryStore::new(
            store,
            input_objects,
            receiving_objects,
            transaction_digest,
            protocol_config,
            *epoch_id,
        );

        let sponsor = resolve_sponsor(&gas_data, &transaction_signer);
        let gas_price = gas_status.gas_price();
        let rgp = gas_status.reference_gas_price();
        let gas_charger = GasCharger::new(
            transaction_digest,
            gas_data.objects,
            gas_status,
            protocol_config,
        );

        let tx_ctx = TxContext::new_from_components(
            &transaction_signer,
            &transaction_digest,
            epoch_id,
            epoch_timestamp_ms,
            rgp,
            gas_price,
            gas_data.budget,
            sponsor,
            protocol_config,
        );
        let tx_ctx = Rc::new(RefCell::new(tx_ctx));

        execute_transaction_to_effects_inner::<Mode>(
            temporary_store,
            gas_charger,
            tx_ctx,
            &mutable_inputs,
            shared_object_refs,
            transaction_dependencies,
            contains_deleted_input,
            cancelled_objects,
            transaction_kind,
            transaction_signer,
            transaction_digest,
            move_vm,
            epoch_id,
            protocol_config,
            metrics,
            enable_expensive_checks,
            certificate_deny_set,
            trace_builder_opt,
            None,
        )
    }

    /// The main execution function that processes a transaction and produces
    /// effects. It handles gas charging and execution logic.
    #[instrument(name = "tx_execute_to_effects_inner", level = "debug", skip_all)]
    fn execute_transaction_to_effects_inner<Mode: ExecutionMode>(
        mut temporary_store: TemporaryStore,
        mut gas_charger: GasCharger,
        tx_ctx: Rc<RefCell<TxContext>>,
        mutable_inputs: &HashSet<ObjectId>,
        shared_object_refs: Vec<SharedInput>,
        mut transaction_dependencies: BTreeSet<TransactionDigest>,
        contains_deleted_input: bool,
        cancelled_objects: Option<(CancelledObjects, Version)>,
        transaction_kind: TransactionKind,
        transaction_signer: Address,
        transaction_digest: TransactionDigest,
        move_vm: &Arc<MoveVM>,
        epoch_id: &EpochId,
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
        enable_expensive_checks: bool,
        certificate_deny_set: &HashSet<TransactionDigest>,
        trace_builder_opt: &mut Option<MoveTraceBuilder>,
        pre_execution_result_opt: Option<
            Result<
                <execution_mode::Authentication as ExecutionMode>::ExecutionResults,
                ExecutionError,
            >,
        >,
    ) -> (
        InnerTemporaryStore,
        IotaGasStatus,
        TransactionEffects,
        Vec<ExecutionTiming>,
        Result<Mode::ExecutionResults, ExecutionError>,
    ) {
        let is_epoch_change = transaction_kind.is_end_of_epoch();
        let deny_cert = is_certificate_denied(&transaction_digest, certificate_deny_set);

        let (gas_cost_summary, execution_result, timings) = execute_transaction::<Mode>(
            &mut temporary_store,
            transaction_kind,
            &mut gas_charger,
            tx_ctx,
            move_vm,
            protocol_config,
            metrics,
            enable_expensive_checks,
            deny_cert,
            contains_deleted_input,
            cancelled_objects,
            trace_builder_opt,
            pre_execution_result_opt,
        );

        let status = if let Err(error) = &execution_result {
            elaborate_error_logs(error, transaction_digest)
        } else {
            ExecutionStatus::Success
        };

        #[skip_checked_arithmetic]
        trace!(
            tx_digest = ?transaction_digest,
            computation_gas_cost = gas_cost_summary.computation_cost,
            computation_gas_cost_burned = gas_cost_summary.computation_cost_burned,
            storage_gas_cost = gas_cost_summary.storage_cost,
            storage_gas_rebate = gas_cost_summary.storage_rebate,
            "Finished execution of transaction with status {:?}",
            status
        );

        // Genesis writes a special digest to indicate that an object was created during
        // genesis and not written by any normal transaction - remove that from the
        // dependencies
        transaction_dependencies.remove(&TransactionDigest::GENESIS_MARKER);

        if enable_expensive_checks && !Mode::allow_arbitrary_function_calls() {
            temporary_store
                .check_ownership_invariants(
                    &transaction_signer,
                    &mut gas_charger,
                    mutable_inputs,
                    is_epoch_change,
                )
                .unwrap()
        } // else, in dev inspect mode and anything goes--don't check

        let (inner, effects) = temporary_store.into_effects(
            shared_object_refs,
            &transaction_digest,
            transaction_dependencies,
            gas_cost_summary,
            status,
            &mut gas_charger,
            *epoch_id,
        );

        (
            inner,
            gas_charger.into_gas_status(),
            effects,
            timings,
            execution_result,
        )
    }

    /// This function produces transaction effects for a transaction that
    /// requires the Move authentication.
    /// It creates a temporary store, gas charger, and transaction context for
    /// the authentication execution and then reuses these for the normal
    /// transaction execution.
    /// When consensus cancelled the transaction, no authenticator runs and
    /// the effects carry the cancellation; with the P-COOL flow on, a gas
    /// owner that is a Move account is then not charged. Otherwise, running
    /// the Move authentication can have two outcomes:
    ///   - If it fails, then it charges gas for the failed execution of the authentication and
    ///     produces transaction effects with the appropriate error status. With the P-COOL flow on,
    ///     a gas owner that is a Move account and did not authorize the transaction is not charged;
    ///     see `execute_without_gas_charge_to_effects`. When `gas_owner_pays` is given, it decides
    ///     whether such a gas owner pays anyway, unless the failure is a cancellation or an
    ///     invariant violation. A gas owner that did authorize it is charged, and every owned input
    ///     moves to its next version.
    ///   - Else, if the authentication is successful, it continues with the normal transaction
    ///     execution.
    /// It combines the input objects from both the authentication and
    /// transaction.
    #[instrument(
        name = "tx_authenticate_then_execute_to_effects",
        level = "debug",
        skip_all
    )]
    pub fn authenticate_then_execute_transaction_to_effects<Mode: ExecutionMode>(
        store: &dyn BackingStore,
        // Configuration
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
        enable_expensive_checks: bool,
        certificate_deny_set: &HashSet<TransactionDigest>,
        // Epoch
        epoch_id: &EpochId,
        epoch_timestamp_ms: u64,
        // Gas related
        gas_data: GasPayment,
        gas_status: IotaGasStatus,
        // Authentication
        authenticators: MoveAuthenticatorsForExecution,
        authenticator_and_transaction_input_objects: CheckedInputObjects,
        gas_owner_pays: Option<&dyn Fn(&ExecutionErrorKind) -> bool>,
        // Transaction
        transaction_kind: TransactionKind,
        transaction_signer: Address,
        transaction_digest: TransactionDigest,
        auth_context_data: AuthContextData,
        // Tracing
        trace_builder_opt: &mut Option<MoveTraceBuilder>,
        // VM
        move_vm: &Arc<MoveVM>,
    ) -> AuthenticateThenExecuteOutput<Mode::ExecutionResults> {
        // Preparation
        // It involves setting up the TemporaryStore, GasCharger, and TxContext, that
        // will be common for both the authentication and transaction execution.

        // Input objects come from both authentication and transaction inputs
        let input_objects = authenticator_and_transaction_input_objects.into_inner();
        // Mutable inputs come only from the transaction inputs
        let mutable_inputs = if enable_expensive_checks {
            input_objects.mutable_inputs().keys().copied().collect()
        } else {
            HashSet::new()
        };
        // Shared object refs come from both authentication and transaction inputs
        let shared_object_refs = input_objects.filter_shared_objects();
        // Receiving objects can only come from the transaction inputs
        let transaction_receiving_objects = transaction_kind.receiving_objects();
        // Transaction dependencies come from both authentication and transaction inputs
        let transaction_dependencies = input_objects.transaction_dependencies();
        // Deleted and cancelled objects come from both authentication and transaction
        // inputs
        let contains_deleted_input = input_objects.contains_deleted_objects();
        let mut cancelled_objects = input_objects.get_cancelled_objects();

        // Prepare the temporary store.
        let mut temporary_store = TemporaryStore::new(
            store,
            input_objects,
            transaction_receiving_objects,
            transaction_digest,
            protocol_config,
            *epoch_id,
        );

        // Prepare the gas charger.
        let sponsor = resolve_sponsor(&gas_data, &transaction_signer);
        let gas_owner = gas_data.owner;
        let gas_price = gas_status.gas_price();
        let rgp = gas_status.reference_gas_price();
        let mut gas_charger = GasCharger::new(
            transaction_digest,
            gas_data.objects,
            gas_status,
            protocol_config,
        );

        // Prepare the transaction context.
        let tx_ctx = TxContext::new_from_components(
            &transaction_signer,
            &transaction_digest,
            epoch_id,
            epoch_timestamp_ms,
            rgp,
            gas_price,
            gas_data.budget,
            sponsor,
            protocol_config,
        );
        let tx_ctx = Rc::new(RefCell::new(tx_ctx));

        let enable_pcool = protocol_config.enable_pcool_flow();
        let run_authenticator =
            |temporary_store: &mut TemporaryStore<'_>,
             gas_charger: &mut GasCharger,
             trace_builder_opt: &mut Option<MoveTraceBuilder>,
             authenticator: MoveAuthenticator,
             authenticator_function_ref: AuthenticatorFunctionRef,
             authenticator_input_objects: CheckedInputObjects| {
                match authenticator_function_ref {
                    AuthenticatorFunctionRef::V1(authenticator_function_ref_v1) => {
                        authenticate_transaction_inner(
                            temporary_store,
                            protocol_config,
                            metrics.clone(),
                            gas_charger,
                            authenticator,
                            authenticator_function_ref_v1,
                            &authenticator_input_objects.into_inner(),
                            transaction_kind.clone(),
                            transaction_digest,
                            auth_context_data.clone(),
                            tx_ctx.clone(),
                            trace_builder_opt,
                            move_vm,
                        )
                    }
                }
            };

        // A cancelled transaction fails with its cancellation: its
        // authenticators are not run, and a failure to resolve them is not
        // reported. The cancellation is reported as is, not as an
        // authentication failure, and only once: the transaction execution
        // gets no cancelled objects to check.
        let cancellation_check =
            run_inputs_checks(protocol_config, false, false, cancelled_objects.take());

        // Next to the result, whether the gas owner authorized the transaction.
        // An owner that signed it did, as its signature is checked before
        // consensus. A Move account did only if its authenticator ran and
        // succeeded.
        //
        // Under the P-COOL flow the gas owner's authenticator runs first, and
        // also after another account failed to resolve, so whether
        // the gas owner authorized does not depend on the order of the
        // signatures. When it fails, its failure is the one reported.
        //
        // Otherwise a resolution failure skips the authenticators entirely, so
        // the objects holding their function references are neither recorded as
        // loaded nor charged for.
        let (authentication_execution_result, gas_owner_authorized) = match cancellation_check {
            // No authenticator ran, so a gas owner that is a Move account did
            // not authorize the transaction.
            Err(error) => {
                let gas_owner_authorized = match &authenticators {
                    MoveAuthenticatorsForExecution::ResolutionFailed { accounts, .. } => {
                        !accounts.contains(&gas_owner)
                    }
                    MoveAuthenticatorsForExecution::Resolved(authenticators) => !authenticators
                        .iter()
                        .any(|authenticator| authenticator.authenticator.address() == gas_owner),
                };
                (Err(error), gas_owner_authorized)
            }
            Ok(()) => {
                let (authentication_result, gas_owner_authorized) = match authenticators {
                    MoveAuthenticatorsForExecution::ResolutionFailed {
                        error,
                        accounts,
                        gas_owner: gas_owner_authenticator,
                    } => {
                        if !accounts.contains(&gas_owner) {
                            (Err(error), true)
                        } else {
                            match gas_owner_authenticator
                                .filter(|_| enable_pcool)
                                .map(|gas_owner_authenticator| *gas_owner_authenticator)
                            {
                                Some(MoveAuthenticatorForExecution {
                                    authenticator,
                                    function_ref,
                                    input_objects: authenticator_input_objects,
                                }) => {
                                    let AuthenticatorFunctionRefForExecution {
                                        authenticator_function_ref,
                                        loaded_object_id,
                                        loaded_object_metadata,
                                    } = function_ref;
                                    temporary_store.save_loaded_runtime_objects(BTreeMap::from([
                                        (loaded_object_id, loaded_object_metadata),
                                    ]));
                                    match run_authenticator(
                                        &mut temporary_store,
                                        &mut gas_charger,
                                        trace_builder_opt,
                                        authenticator,
                                        authenticator_function_ref,
                                        authenticator_input_objects,
                                    ) {
                                        Ok(()) => (Err(error), true),
                                        Err(gas_owner_error) => (Err(gas_owner_error), false),
                                    }
                                }
                                None => (Err(error), false),
                            }
                        }
                    }
                    MoveAuthenticatorsForExecution::Resolved(authenticators) => {
                        // Prepare the authenticators for execution.
                        // Store the loaded object metadata in the `TemporaryStore` before the
                        // authenticators are executed.
                        // The temporary store must contain all the required information at this
                        // point.
                        let mut authenticators = authenticators
                            .into_iter()
                            .map(
                                |MoveAuthenticatorForExecution {
                                     authenticator,
                                     function_ref,
                                     input_objects: authenticator_input_objects,
                                 }| {
                                    let AuthenticatorFunctionRefForExecution {
                                        authenticator_function_ref,
                                        loaded_object_id,
                                        loaded_object_metadata,
                                    } = function_ref;

                                    // Save the loaded object metadata, i.e., the field object
                                    // containing the AuthenticatorFunctionRef, in the temporary
                                    // store.
                                    temporary_store.save_loaded_runtime_objects(BTreeMap::from([
                                        (loaded_object_id, loaded_object_metadata),
                                    ]));

                                    (
                                        authenticator,
                                        authenticator_function_ref,
                                        authenticator_input_objects,
                                    )
                                },
                            )
                            .collect::<Vec<_>>();

                        if enable_pcool {
                            if let Some(position) =
                                authenticators.iter().position(|(authenticator, ..)| {
                                    authenticator.address() == gas_owner
                                })
                            {
                                let gas_owner_authenticator = authenticators.remove(position);
                                authenticators.insert(0, gas_owner_authenticator);
                            }
                        }

                        let mut gas_owner_authorized = !authenticators
                            .iter()
                            .any(|(authenticator, ..)| authenticator.address() == gas_owner);

                        // Authentication execution.
                        // It does not alter the state, if not for command execution gas charging,
                        // and produces no effects other than possible errors.

                        // Run each authenticator in sequence; the first failure aborts the chain.
                        let result = authenticators.into_iter().try_for_each(
                            |(
                                authenticator,
                                authenticator_function_ref,
                                authenticator_input_objects,
                            )| {
                                let account = authenticator.address();
                                let result = run_authenticator(
                                    &mut temporary_store,
                                    &mut gas_charger,
                                    trace_builder_opt,
                                    authenticator,
                                    authenticator_function_ref,
                                    authenticator_input_objects,
                                );
                                if result.is_ok() && account == gas_owner {
                                    gas_owner_authorized = true;
                                }
                                result
                            },
                        );
                        (result, gas_owner_authorized)
                    }
                };

                // A resolution failure goes through the same reporting as an
                // authenticator that fails, so a client sees `MoveAuthentication` for
                // both.
                (
                    report_authentication_error(authentication_result, protocol_config),
                    gas_owner_authorized,
                )
            }
        };

        // The body's own checks may replace this error in the effects, so its
        // kind is reported alongside.
        let authentication_error = authentication_execution_result
            .as_ref()
            .err()
            .map(|error| error.kind().clone());

        // Under the P-COOL flow, the gas owner's authenticator runs for the
        // first time here, so a transaction it did not authorize can reach
        // execution. Nobody pays for it, unless `gas_owner_pays` answers `true`.
        let authentication_execution_result = match authentication_execution_result {
            Err(error)
                if !gas_owner_authorized
                    && protocol_config.enable_pcool_flow()
                    && !charge_gas_owner(protocol_config, &error, gas_owner_pays) =>
            {
                let (inner_temp_store, gas_status, effects, timings, execution_result) =
                    execute_without_gas_charge_to_effects::<Mode>(
                        temporary_store,
                        gas_charger,
                        shared_object_refs,
                        transaction_dependencies,
                        contains_deleted_input,
                        cancelled_objects,
                        transaction_digest,
                        epoch_id,
                        protocol_config,
                        certificate_deny_set,
                        error,
                    );

                return (
                    inner_temp_store,
                    gas_status,
                    effects,
                    timings,
                    execution_result,
                    authentication_error,
                );
            }
            // Also a gas owner that `gas_owner_pays` charges: it pays like any
            // failed transaction its gas owner authorized.
            result => result,
        };
        // Transaction execution.
        // At this stage we arrive with gas charged for the execution of the
        // authenticate function and a result which is either empty or an error.
        // We can now start the creation of the transaction effects, either for an
        // authentication failure or for a normal execution of the transaction.

        // Run the transaction execution and return the effects.
        let (inner_temp_store, gas_status, effects, timings, execution_result) =
            execute_transaction_to_effects_inner::<Mode>(
                temporary_store,
                gas_charger,
                tx_ctx,
                &mutable_inputs,
                shared_object_refs,
                transaction_dependencies,
                contains_deleted_input,
                cancelled_objects,
                transaction_kind,
                transaction_signer,
                transaction_digest,
                move_vm,
                epoch_id,
                protocol_config,
                metrics,
                enable_expensive_checks,
                certificate_deny_set,
                trace_builder_opt,
                Some(authentication_execution_result),
            );
        (
            inner_temp_store,
            gas_status,
            effects,
            timings,
            execution_result,
            authentication_error,
        )
    }

    /// Whether a gas owner that is a Move account and did not authorize the
    /// transaction pays for its failed authentication, as `gas_owner_pays`
    /// decides under the protocol feature flag `enable_validator_attestation`.
    /// `gas_owner_pays` is not asked about a cancellation, decided at the
    /// consensus commit before any authenticator ran, nor about an invariant
    /// violation, an internal error: such a gas owner is not charged.
    fn charge_gas_owner(
        protocol_config: &ProtocolConfig,
        error: &ExecutionError,
        gas_owner_pays: Option<&dyn Fn(&ExecutionErrorKind) -> bool>,
    ) -> bool {
        let kind = unwrap_move_authentication_error(error.kind());

        protocol_config.enable_validator_attestation()
            && !is_cancellation(kind)
            && !is_any_invariant_violation(kind)
            && gas_owner_pays.is_some_and(|pays| pays(kind))
    }

    /// Produces the effects of a transaction whose gas owner is a Move account
    /// that did not authorize it: its authenticator failed, or did not run
    /// because resolution or an earlier authenticator failed. Nobody authorized
    /// paying for gas, so nobody is charged:
    ///   - owned inputs, gas coins included, move to their next versions with their contents,
    ///     owners and storage rebates unchanged;
    ///   - mutable shared inputs move to the version consensus assigned, with their contents and
    ///     storage rebates unchanged, so later transactions find them at the versions consensus
    ///     gave those transactions.
    ///
    /// The effects name the first gas coin, at its next version, as the gas
    /// object, with a zero gas cost; no other gas coin is merged into it.
    ///
    /// The checks every transaction runs on its inputs come first, as when gas
    /// is charged, so a deleted or cancelled input is reported the same way
    /// whoever pays.
    fn execute_without_gas_charge_to_effects<Mode: ExecutionMode>(
        mut temporary_store: TemporaryStore,
        mut gas_charger: GasCharger,
        shared_object_refs: Vec<SharedInput>,
        mut transaction_dependencies: BTreeSet<TransactionDigest>,
        contains_deleted_input: bool,
        cancelled_objects: Option<(CancelledObjects, Version)>,
        transaction_digest: TransactionDigest,
        epoch_id: &EpochId,
        protocol_config: &ProtocolConfig,
        certificate_deny_set: &HashSet<TransactionDigest>,
        authentication_error: ExecutionError,
    ) -> (
        InnerTemporaryStore,
        IotaGasStatus,
        TransactionEffects,
        Vec<ExecutionTiming>,
        Result<Mode::ExecutionResults, ExecutionError>,
    ) {
        let deny_cert = is_certificate_denied(&transaction_digest, certificate_deny_set);
        let error = run_inputs_checks(
            protocol_config,
            deny_cert,
            contains_deleted_input,
            cancelled_objects,
        )
        .err()
        .unwrap_or(authentication_error);
        let status = elaborate_error_logs(&error, transaction_digest);

        temporary_store.drop_writes();
        temporary_store.ensure_active_inputs_mutated();

        // Genesis writes a special digest to indicate that an object was created during
        // genesis and not written by any normal transaction - remove that from the
        // dependencies
        transaction_dependencies.remove(&TransactionDigest::GENESIS_MARKER);

        gas_charger.set_gas_coin_without_smashing();
        let (inner, effects) = temporary_store.into_effects(
            shared_object_refs,
            &transaction_digest,
            transaction_dependencies,
            GasCostSummary::default(),
            status,
            &mut gas_charger,
            *epoch_id,
        );

        (
            inner,
            gas_charger.into_gas_status(),
            effects,
            vec![],
            Err(error),
        )
    }

    /// This function checks the authentication of a transaction without
    /// returning effects. It executes an authenticate function using the
    /// information of an authenticator. If the execution fails, it returns
    /// an execution error; otherwise it returns an empty value. The gas
    /// status the authentication was metered on is returned alongside.
    #[instrument(name = "tx_validate", level = "debug", skip_all)]
    pub fn authenticate_transaction(
        store: &dyn BackingStore,
        // Configuration
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
        // Epoch
        epoch_id: &EpochId,
        epoch_timestamp_ms: u64,
        // Gas related
        gas_data: GasPayment,
        gas_status: IotaGasStatus,
        // Authentication
        authenticators: Vec<(
            MoveAuthenticator,
            AuthenticatorFunctionRef,
            CheckedInputObjects,
        )>,
        aggregated_authenticator_input_objects: CheckedInputObjects,
        // Transaction
        transaction_kind: TransactionKind,
        transaction_signer: Address,
        transaction_digest: TransactionDigest,
        auth_context_data: AuthContextData,
        // Tracing
        trace_builder_opt: &mut Option<MoveTraceBuilder>,
        // VM
        move_vm: &Arc<MoveVM>,
    ) -> (
        IotaGasStatus,
        Result<<execution_mode::Authentication as ExecutionMode>::ExecutionResults, ExecutionError>,
    ) {
        // Prepare the gas charger for authentication execution.
        let sponsor = resolve_sponsor(&gas_data, &transaction_signer);
        let gas_price = gas_status.gas_price();
        let rgp = gas_status.reference_gas_price();
        let mut gas_charger =
            GasCharger::new(transaction_digest, vec![], gas_status, protocol_config);

        // Prepare the transaction context, equal for both authentication and
        // transaction execution.
        let tx_ctx = TxContext::new_from_components(
            &transaction_signer,
            &transaction_digest,
            epoch_id,
            epoch_timestamp_ms,
            rgp,
            gas_price,
            gas_data.budget,
            sponsor,
            protocol_config,
        );
        let tx_ctx = Rc::new(RefCell::new(tx_ctx));

        let mut temporary_store = TemporaryStore::new(
            store,
            aggregated_authenticator_input_objects.into_inner(),
            vec![],
            transaction_digest,
            protocol_config,
            *epoch_id,
        );

        // Run each authenticator in sequence; return on first failure.
        let authentication_execution_result = authenticators.into_iter().try_for_each(
            |(authenticator, authenticator_function_ref, authenticator_input_objects)| {
                match authenticator_function_ref {
                    AuthenticatorFunctionRef::V1(authenticator_function_ref_v1) => {
                        authenticate_transaction_inner(
                            &mut temporary_store,
                            protocol_config,
                            metrics.clone(),
                            &mut gas_charger,
                            authenticator,
                            authenticator_function_ref_v1,
                            &authenticator_input_objects.into_inner(),
                            transaction_kind.clone(),
                            transaction_digest,
                            auth_context_data.clone(),
                            tx_ctx.clone(),
                            trace_builder_opt,
                            move_vm,
                        )
                    }
                }
            },
        );

        let result = report_authentication_error(authentication_execution_result, protocol_config);
        (gas_charger.into_gas_status(), result)
    }

    // This function implements the authentication execution. It checks that the
    // authentication method used by the authenticator is valid. It prepares a
    /// `MoveAuthenticator` PTB with a single move call for execution, then
    /// executes it through an inner execution method. The
    /// `MoveAuthenticator` provides the inputs to use for the
    /// authentication function found in `AuthenticatorFunctionRef`,
    /// that is retrieved from an account.
    /// If the execution fails, it returns an execution error; otherwise it
    /// returns an empty value.
    #[instrument(name = "tx_validate", level = "debug", skip_all)]
    pub fn authenticate_transaction_inner(
        temporary_store: &mut TemporaryStore<'_>,
        // Configuration
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
        // Gas related
        gas_charger: &mut GasCharger,
        // Authenticator
        authenticator: MoveAuthenticator,
        authenticator_function_ref: AuthenticatorFunctionRefV1,
        authenticator_input_objects: &InputObjects,
        // Transaction
        transaction_kind: TransactionKind,
        transaction_digest: TransactionDigest,
        auth_context_data: AuthContextData,
        tx_ctx: Rc<RefCell<TxContext>>,
        // Tracing
        trace_builder_opt: &mut Option<MoveTraceBuilder>,
        // VM
        move_vm: &Arc<MoveVM>,
    ) -> Result<<execution_mode::Authentication as ExecutionMode>::ExecutionResults, ExecutionError>
    {
        // Check the preconditions.
        debug_assert!(
            transaction_kind.is_programmable(),
            "Only programmable transactions are allowed"
        );
        debug_assert!(
            authenticator_input_objects
                .mutable_inputs()
                .keys()
                .copied()
                .collect::<HashSet<_>>()
                .is_empty(),
            "No mutable inputs are allowed"
        );
        debug_assert!(
            authenticator.receiving_objects().is_empty(),
            "No receiving inputs are allowed"
        );

        let contains_deleted_input = authenticator_input_objects.contains_deleted_objects();
        let cancelled_objects = authenticator_input_objects.get_cancelled_objects();

        // Prepare the authentication context.
        let auth_ctx = {
            let TransactionKind::Programmable(ptb) = &transaction_kind else {
                unreachable!("Only programmable transactions are allowed");
            };
            AuthContext::new_from_components(
                authenticator.digest().into(),
                auth_context_data.sender_auth_digest,
                auth_context_data.sponsor_auth_digest,
                auth_context_data
                    .sender_authenticator_function_ref
                    .and_then(Into::into),
                auth_context_data
                    .sponsor_authenticator_function_ref
                    .and_then(Into::into),
                ptb,
                auth_context_data.transaction_data_bytes,
            )
        };
        let auth_ctx = Rc::new(RefCell::new(auth_ctx));

        // Store the authentication context in the temporary store.
        // It will be added to the authentication's parameter list later, just before
        // execution.
        temporary_store.store_auth_context(auth_ctx);

        // Execute the authentication.
        let authentication_execution_result = execute_authenticator_move_call(
            temporary_store,
            authenticator,
            authenticator_function_ref,
            gas_charger,
            tx_ctx,
            move_vm,
            protocol_config,
            metrics,
            false,
            contains_deleted_input,
            cancelled_objects,
            trace_builder_opt,
        );

        // Check the authentication result.
        let authentication_execution_status = if let Err(error) = &authentication_execution_result {
            elaborate_error_logs(error, transaction_digest)
        } else {
            ExecutionStatus::Success
        };

        #[skip_checked_arithmetic]
        trace!(
            tx_digest = ?transaction_digest,
            computation_gas_cost = gas_charger.summary().gas_used(),
            "Finished authenticator execution of transaction with status {:?}",
            authentication_execution_status
        );

        authentication_execution_result
    }

    /// Executes an authentication move call by processing the specified
    /// `ProgrammableTransaction`, running the main execution logic.
    /// Similarly to `execute_transaction`, this function handles certain error
    /// conditions such as denied certificate, deleted input objects failed
    /// consistency checks.
    ///
    /// Gas costs are managed through the `GasCharger` argument and charged only
    /// for authentication move function execution.
    ///
    /// Returns only the execution results.
    #[instrument(name = "auth_execute", level = "debug", skip_all)]
    fn execute_authenticator_move_call(
        temporary_store: &mut TemporaryStore<'_>,
        authenticator: MoveAuthenticator,
        authenticator_function_ref: AuthenticatorFunctionRefV1,
        gas_charger: &mut GasCharger,
        tx_ctx: Rc<RefCell<TxContext>>,
        move_vm: &Arc<MoveVM>,
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
        deny_cert: bool,
        contains_deleted_input: bool,
        cancelled_objects: Option<(CancelledObjects, Version)>,
        trace_builder_opt: &mut Option<MoveTraceBuilder>,
    ) -> Result<<execution_mode::Authentication as ExecutionMode>::ExecutionResults, ExecutionError>
    {
        // It must NOT charge gas for reading the Move authenticator input objects from
        // the storage. It will be done later during the transaction execution.
        // Then execute the authentication.
        run_inputs_checks(
            protocol_config,
            deny_cert,
            contains_deleted_input,
            cancelled_objects,
        )
        .and_then(|()| {
            let authenticator_move_call =
                setup_authenticator_move_call(authenticator, authenticator_function_ref)?;
            programmable_transactions::execution::execute::<execution_mode::Authentication>(
                protocol_config,
                metrics.clone(),
                move_vm,
                temporary_store,
                tx_ctx,
                gas_charger,
                authenticator_move_call,
                trace_builder_opt,
            )
            .map_err(|(e, _)| e)
            .and_then(|(ok_result, _timings)| {
                temporary_store.check_move_authenticator_results_consistency()?;
                Ok(ok_result)
            })
        })
    }

    /// Function dedicated to the execution of a GenesisTransaction.
    /// The function creates an `InnerTemporaryStore`, processes the input
    /// objects, and executes the transaction in unmetered mode using the
    /// `Genesis` execution mode. It returns an inner temporary store that
    /// contains the objects found into the input `GenesisTransaction` by
    /// adding the data for `previous_transaction` and `storage_rebate` fields.
    pub fn execute_genesis_state_update(
        store: &dyn BackingStore,
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
        move_vm: &Arc<MoveVM>,
        tx_context: Rc<RefCell<TxContext>>,
        input_objects: CheckedInputObjects,
        pt: ProgrammableTransaction,
    ) -> Result<InnerTemporaryStore, ExecutionError> {
        let input_objects = input_objects.into_inner();
        let tx_digest = tx_context.borrow().digest();

        let mut temporary_store =
            TemporaryStore::new(store, input_objects, vec![], tx_digest, protocol_config, 0);
        let mut gas_charger = GasCharger::new_unmetered(tx_digest);
        programmable_transactions::execution::execute::<execution_mode::Genesis>(
            protocol_config,
            metrics,
            move_vm,
            &mut temporary_store,
            tx_context,
            &mut gas_charger,
            pt,
            &mut None,
        )
        .map_err(|(e, _)| e)?;
        temporary_store.update_object_version_and_prev_tx();
        Ok(temporary_store.into_inner())
    }

    /// Executes a transaction by processing the specified `TransactionKind`,
    /// applying the necessary gas charges and running the main execution logic.
    /// The function handles certain error conditions such as denied
    /// certificate, deleted input objects, exceeded execution meter limits,
    /// failed conservation checks. It also accounts for unmetered storage
    /// rebates and adjusts for special cases like epoch change
    /// transactions. Gas costs are managed through the `GasCharger`
    /// argument; gas is also charged in case of errors.
    #[instrument(name = "tx_execute", level = "debug", skip_all)]
    fn execute_transaction<Mode: ExecutionMode>(
        temporary_store: &mut TemporaryStore<'_>,
        transaction_kind: TransactionKind,
        gas_charger: &mut GasCharger,
        tx_ctx: Rc<RefCell<TxContext>>,
        move_vm: &Arc<MoveVM>,
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
        enable_expensive_checks: bool,
        deny_cert: bool,
        contains_deleted_input: bool,
        cancelled_objects: Option<(CancelledObjects, Version)>,
        trace_builder_opt: &mut Option<MoveTraceBuilder>,
        pre_execution_result_opt: Option<
            Result<
                <execution_mode::Authentication as ExecutionMode>::ExecutionResults,
                ExecutionError,
            >,
        >,
    ) -> (
        GasCostSummary,
        Result<Mode::ExecutionResults, ExecutionError>,
        Vec<ExecutionTiming>,
    ) {
        gas_charger.smash_gas(temporary_store);

        // At this point, either no charges have been applied yet or we have
        // already a pre execution result to handle.
        debug_assert!(
            pre_execution_result_opt.is_some() || gas_charger.no_charges(),
            "No gas charges must be applied yet"
        );

        let is_genesis_or_epoch_change_tx = matches!(transaction_kind, TransactionKind::Genesis(_))
            || transaction_kind.is_end_of_epoch();

        let advance_epoch_gas_summary = transaction_kind.get_advance_epoch_tx_gas_summary();

        let tx_digest = tx_ctx.borrow().digest();

        // We must charge object read here during transaction execution, because if this
        // fails we must still ensure an effect is committed and all objects
        // versions incremented
        let result = gas_charger.charge_input_objects(temporary_store);
        let result: ResultWithTimings<Mode::ExecutionResults, ExecutionError> =
            result.map_err(|e| (e, vec![])).and_then(
                |()| -> ResultWithTimings<Mode::ExecutionResults, ExecutionError> {
                    run_inputs_checks(
                        protocol_config,
                        deny_cert,
                        contains_deleted_input,
                        cancelled_objects,
                    )
                    .map_err(|e| (e, vec![]))?;

                    // If the pre-execution succeeded, proceed with the main execution loop
                    // else propagate the pre-execution error
                    let mut execution_result = pre_execution_result_opt
                        .unwrap_or(Ok(()))
                        .map_err(|e| (e, vec![]))
                        .and_then(|_| {
                            execution_loop::<Mode>(
                                temporary_store,
                                transaction_kind,
                                tx_ctx,
                                move_vm,
                                gas_charger,
                                protocol_config,
                                metrics.clone(),
                                trace_builder_opt,
                            )
                        });

                    let meter_check = check_meter_limit(
                        temporary_store,
                        gas_charger,
                        protocol_config,
                        metrics.clone(),
                    );
                    if let Err(e) = meter_check {
                        execution_result = Err((e, vec![]));
                    }

                    if execution_result.is_ok() {
                        let gas_check = check_written_objects_limit(
                            temporary_store,
                            gas_charger,
                            protocol_config,
                            metrics,
                        );
                        if let Err(e) = gas_check {
                            execution_result = Err((e, vec![]));
                        }
                    }

                    execution_result
                },
            );

        let (mut result, timings) = match result {
            Ok((r, t)) => (Ok(r), t),
            Err((e, t)) => (Err(e), t),
        };

        let cost_summary = gas_charger.charge_gas(temporary_store, &mut result);
        // For advance epoch transaction, we need to provide epoch rewards and rebates
        // as extra information provided to check_iota_conserved, because we
        // mint rewards, and burn the rebates. We also need to pass in the
        // unmetered_storage_rebate because storage rebate is not reflected in
        // the storage_rebate of gas summary. This is a bit confusing.
        // We could probably clean up the code a bit.
        // Put all the storage rebate accumulated in the system transaction
        // to the 0x5 object so that it's not lost.
        temporary_store.conserve_unmetered_storage_rebate(gas_charger.unmetered_storage_rebate());

        if let Err(e) = run_conservation_checks::<Mode>(
            temporary_store,
            gas_charger,
            tx_digest,
            move_vm,
            enable_expensive_checks,
            &cost_summary,
            is_genesis_or_epoch_change_tx,
            advance_epoch_gas_summary,
        ) {
            // FIXME: we cannot fail the transaction if this is an epoch change transaction.
            result = Err(e);
        }

        (cost_summary, result, timings)
    }

    /// When enabled by the protocol config, report a failure of the Move
    /// authentication as a distinct
    /// [`ExecutionErrorKind::MoveAuthentication`], dropping the
    /// authenticator's internal command index so it is not attributed to a
    /// command of the programmable transaction.
    fn report_authentication_error<T>(
        authentication_execution_result: Result<T, ExecutionError>,
        protocol_config: &ProtocolConfig,
    ) -> Result<T, ExecutionError> {
        if protocol_config.report_move_authentication_error() {
            authentication_execution_result.map_err(ExecutionError::into_move_authentication_error)
        } else {
            authentication_execution_result
        }
    }

    /// Elaborate errors in logs if they are unexpected or their status is
    /// terse.
    fn elaborate_error_logs(
        execution_error: &ExecutionError,
        transaction_digest: TransactionDigest,
    ) -> ExecutionStatus {
        use ExecutionErrorKind as K;
        match execution_error.kind() {
            K::InvariantViolation | K::VmInvariantViolation => {
                #[skip_checked_arithmetic]
                tracing::error!(
                    kind = ?execution_error.kind(),
                    tx_digest = ?transaction_digest,
                    "INVARIANT VIOLATION! Source: {:?}",
                    execution_error.source(),
                );
            }

            K::IotaMoveVerificationError | K::VmVerificationOrDeserializationError => {
                #[skip_checked_arithmetic]
                tracing::debug!(
                    kind = ?execution_error.kind(),
                    tx_digest = ?transaction_digest,
                    "Verification Error. Source: {:?}",
                    execution_error.source(),
                );
            }

            K::PublishUpgradeMissingDependency | K::PublishUpgradeDependencyDowngrade => {
                #[skip_checked_arithmetic]
                tracing::debug!(
                    kind = ?execution_error.kind(),
                    tx_digest = ?transaction_digest,
                    "Publish/Upgrade Error. Source: {:?}",
                    execution_error.source(),
                )
            }

            _ => (),
        };

        let (status, command) = execution_error.to_execution_status();
        ExecutionStatus::new_failure(status, command)
    }

    /// Performs IOTA conservation checks during transaction execution, ensuring
    /// that the transaction does not create or destroy IOTA. If
    /// conservation is violated, the function attempts to recover
    /// by resetting the gas charger, recharging gas, and rechecking
    /// conservation. If recovery fails, it panics to avoid IOTA creation or
    /// destruction. These checks include both simple and expensive
    /// checks based on the configuration and are skipped for genesis or epoch
    /// change transactions.
    #[instrument(name = "run_conservation_checks", level = "debug", skip_all)]
    fn run_conservation_checks<Mode: ExecutionMode>(
        temporary_store: &mut TemporaryStore<'_>,
        gas_charger: &mut GasCharger,
        tx_digest: TransactionDigest,
        move_vm: &Arc<MoveVM>,
        enable_expensive_checks: bool,
        cost_summary: &GasCostSummary,
        is_genesis_or_epoch_change_tx: bool,
        advance_epoch_gas_summary: Option<(u64, u64)>,
    ) -> Result<(), ExecutionError> {
        let mut result: std::result::Result<(), iota_types::error::ExecutionError> = Ok(());
        if !is_genesis_or_epoch_change_tx && !Mode::skip_conservation_checks() {
            // ensure that this transaction did not create or destroy IOTA, try to recover
            // if the check fails
            let conservation_result = {
                temporary_store
                    .check_iota_conserved(cost_summary)
                    .and_then(|()| {
                        if enable_expensive_checks {
                            // ensure that this transaction did not create or destroy IOTA, try to
                            // recover if the check fails
                            let mut layout_resolver =
                                TypeLayoutResolver::new(move_vm, Box::new(&*temporary_store));
                            temporary_store.check_iota_conserved_expensive(
                                cost_summary,
                                advance_epoch_gas_summary,
                                &mut layout_resolver,
                            )
                        } else {
                            Ok(())
                        }
                    })
            };
            if let Err(conservation_err) = conservation_result {
                // conservation violated. try to avoid panic by dumping all writes, charging for
                // gas, re-checking conservation, and surfacing an aborted
                // transaction with an invariant violation if all of that works
                result = Err(conservation_err);
                gas_charger.reset(temporary_store);
                gas_charger.charge_gas(temporary_store, &mut result);
                // check conservation once more
                if let Err(recovery_err) = temporary_store
                    .check_iota_conserved(cost_summary)
                    .and_then(|()| {
                        if enable_expensive_checks {
                            // ensure that this transaction did not create or destroy IOTA, try
                            // to recover if the check fails
                            let mut layout_resolver =
                                TypeLayoutResolver::new(move_vm, Box::new(&*temporary_store));
                            temporary_store.check_iota_conserved_expensive(
                                cost_summary,
                                advance_epoch_gas_summary,
                                &mut layout_resolver,
                            )
                        } else {
                            Ok(())
                        }
                    })
                {
                    // if we still fail, it's a problem with gas
                    // charging that happens even in the "aborted" case--no other option but panic.
                    // we will create or destroy IOTA otherwise
                    panic!(
                        "IOTA conservation fail in tx block {}: {}\nGas status is {}\nTx was ",
                        tx_digest,
                        recovery_err,
                        gas_charger.summary()
                    )
                }
            }
        } // else, we're in the genesis transaction which mints the IOTA supply, and hence
        // does not satisfy IOTA conservation, or we're in the non-production
        // dev inspect mode which allows us to violate conservation
        result
    }

    /// Runs checks on the input objects of a transaction to ensure that they
    /// meet the necessary conditions for execution.
    ///
    /// It checks for denied certificates, deleted input objects, and cancelled
    /// objects due to congestion or randomness unavailability. If any of
    /// these conditions are met, it returns an appropriate
    /// `ExecutionError`.
    ///
    /// If all checks pass, it returns `Ok(())`, indicating that the transaction
    /// can proceed with execution.
    #[instrument(name = "run_inputs_checks", level = "debug", skip_all)]
    fn run_inputs_checks(
        protocol_config: &ProtocolConfig,
        deny_cert: bool,
        contains_deleted_input: bool,
        cancelled_objects: Option<(CancelledObjects, Version)>,
    ) -> Result<(), ExecutionError> {
        if deny_cert {
            Err(ExecutionError::new(
                ExecutionErrorKind::CertificateDenied,
                None,
            ))
        } else if contains_deleted_input {
            Err(ExecutionError::new(
                ExecutionErrorKind::InputObjectDeleted,
                None,
            ))
        } else if let Some((cancelled_objects, reason)) = cancelled_objects {
            match reason {
                version if version.is_congested() => Err(ExecutionError::new(
                    match cancelled_objects {
                        // A transaction cancelled through its gas object has no shared
                        // inputs, so the execution workers are the congested resource
                        // and no individual object is responsible.
                        CancelledObjects::GasObject => {
                            ExecutionErrorKind::ExecutionCanceledDueToExecutionWorkerCongestion {
                                suggested_gas_price: version
                                    .get_congested_version_suggested_gas_price()
                                    .expect(
                                        "execution-worker congestion control requires the gas \
                                        price feedback mechanism",
                                    ),
                            }
                        }
                        CancelledObjects::SharedObjects(congested_objects) => {
                            if protocol_config.congestion_control_gas_price_feedback_mechanism() {
                                ExecutionErrorKind::ExecutionCanceledDueToSharedObjectCongestionV2 {
                                    congested_objects,
                                    suggested_gas_price: version
                                        .get_congested_version_suggested_gas_price()
                                        .unwrap(),
                                }
                            } else {
                                // WARN: do not remove this `else` branch even after
                                // `congestion_control_gas_price_feedback_mechanism` is enabled
                                // on the mainnet. It must be kept to be able to replay old
                                // transaction data.
                                ExecutionErrorKind::ExecutionCanceledDueToSharedObjectCongestion {
                                    congested_objects,
                                }
                            }
                        }
                    },
                    None,
                )),
                Version::RANDOMNESS_UNAVAILABLE => Err(ExecutionError::new(
                    ExecutionErrorKind::ExecutionCanceledDueToRandomnessUnavailable,
                    None,
                )),
                _ => panic!("invalid cancellation reason Version: {reason}"),
            }
        } else {
            Ok(())
        }
    }

    /// Checks if the estimated size of transaction effects exceeds predefined
    /// limits based on the protocol configuration. For metered
    /// transactions, it enforces hard limits, while for system transactions, it
    /// allows soft limits with warnings.
    #[instrument(name = "check_meter_limit", level = "debug", skip_all)]
    fn check_meter_limit(
        temporary_store: &mut TemporaryStore<'_>,
        gas_charger: &mut GasCharger,
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
    ) -> Result<(), ExecutionError> {
        let effects_estimated_size = temporary_store.estimate_effects_size_upperbound();

        // Check if a limit threshold was crossed.
        // For metered transactions, there is not soft limit.
        // For system transactions, we allow a soft limit with alerting, and a hard
        // limit where we terminate
        match check_limit_by_meter!(
            !gas_charger.is_unmetered(),
            effects_estimated_size,
            protocol_config.max_serialized_tx_effects_size_bytes(),
            protocol_config.max_serialized_tx_effects_size_bytes_system_tx(),
            metrics.excessive_estimated_effects_size
        ) {
            LimitThresholdCrossed::None => Ok(()),
            LimitThresholdCrossed::Soft(_, limit) => {
                warn!(
                    effects_estimated_size = effects_estimated_size,
                    soft_limit = limit,
                    "Estimated transaction effects size crossed soft limit",
                );
                Ok(())
            }
            LimitThresholdCrossed::Hard(_, lim) => Err(ExecutionError::new_with_source(
                ExecutionErrorKind::EffectsTooLarge {
                    current_size: effects_estimated_size as u64,
                    max_size: lim as u64,
                },
                "Transaction effects are too large",
            )),
        }
    }

    /// Checks if the total size of written objects in the transaction exceeds
    /// the limits defined in the protocol configuration. For metered
    /// transactions, it enforces a hard limit, while for system transactions,
    /// it allows a soft limit with warnings.
    #[instrument(name = "check_written_objects_limit", level = "debug", skip_all)]
    fn check_written_objects_limit(
        temporary_store: &mut TemporaryStore<'_>,
        gas_charger: &mut GasCharger,
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
    ) -> Result<(), ExecutionError> {
        if let (Some(normal_lim), Some(system_lim)) = (
            protocol_config.max_size_written_objects_as_option(),
            protocol_config.max_size_written_objects_system_tx_as_option(),
        ) {
            let written_objects_size = temporary_store.written_objects_size();

            match check_limit_by_meter!(
                !gas_charger.is_unmetered(),
                written_objects_size,
                normal_lim,
                system_lim,
                metrics.excessive_written_objects_size
            ) {
                LimitThresholdCrossed::None => (),
                LimitThresholdCrossed::Soft(_, limit) => {
                    warn!(
                        written_objects_size = written_objects_size,
                        soft_limit = limit,
                        "Written objects size crossed soft limit",
                    )
                }
                LimitThresholdCrossed::Hard(_, lim) => {
                    return Err(ExecutionError::new_with_source(
                        ExecutionErrorKind::WrittenObjectsTooLarge {
                            object_size: written_objects_size as u64,
                            max_object_size: lim as u64,
                        },
                        "Written objects size crossed hard limit",
                    ));
                }
            };
        }

        Ok(())
    }

    /// Executes the given transaction based on its `TransactionKind` by
    /// processing it through corresponding handlers such as epoch changes,
    /// genesis transactions, consensus commit prologues, and programmable
    /// transactions. For each type of transaction, the corresponding logic is
    /// invoked, such as advancing the epoch, setting up consensus commits, or
    /// executing a programmable transaction.
    #[instrument(level = "debug", skip_all)]
    fn execution_loop<Mode: ExecutionMode>(
        temporary_store: &mut TemporaryStore<'_>,
        transaction_kind: TransactionKind,
        tx_ctx: Rc<RefCell<TxContext>>,
        move_vm: &Arc<MoveVM>,
        gas_charger: &mut GasCharger,
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
        trace_builder_opt: &mut Option<MoveTraceBuilder>,
    ) -> ResultWithTimings<Mode::ExecutionResults, ExecutionError> {
        let result = match transaction_kind {
            TransactionKind::Genesis(GenesisTransaction { objects, events }) => {
                if tx_ctx.borrow().epoch() != 0 {
                    panic!("BUG: Genesis Transactions can only be executed in epoch 0");
                }

                for genesis_object in objects {
                    let object = ObjectInner {
                        data: genesis_object.data,
                        owner: genesis_object.owner,
                        previous_transaction: tx_ctx.borrow().digest(),
                        storage_rebate: 0,
                    };
                    temporary_store.create_object(object.into());
                }

                temporary_store.record_execution_results(ExecutionResults::V1(
                    ExecutionResultsV1 {
                        user_events: events,
                        ..Default::default()
                    },
                ));

                Ok((Mode::empty_results(), vec![]))
            }
            TransactionKind::ConsensusCommitPrologueV1(prologue) => {
                setup_consensus_commit(
                    prologue.commit_timestamp_ms,
                    temporary_store,
                    tx_ctx,
                    move_vm,
                    gas_charger,
                    protocol_config,
                    metrics,
                    trace_builder_opt,
                )
                .expect("ConsensusCommitPrologueV1 cannot fail");
                Ok((Mode::empty_results(), vec![]))
            }
            TransactionKind::Programmable(pt) => {
                programmable_transactions::execution::execute::<Mode>(
                    protocol_config,
                    metrics,
                    move_vm,
                    temporary_store,
                    tx_ctx,
                    gas_charger,
                    pt,
                    trace_builder_opt,
                )
            }
            TransactionKind::EndOfEpoch(txns) => {
                // Non-change-epoch kinds accumulate commands into the builder;
                // the change-epoch kind is always last and executes the built
                // transaction as part of advancing the epoch.
                let mut builder = ProgrammableTransactionBuilder::new();
                let len = txns.len();

                for (i, tx) in txns.into_iter().enumerate() {
                    match tx {
                        EndOfEpochTransactionKind::ChangeEpoch(change_epoch) => {
                            assert_eq!(i, len - 1);
                            advance_epoch_v1(
                                builder,
                                change_epoch,
                                temporary_store,
                                tx_ctx,
                                move_vm,
                                gas_charger,
                                protocol_config,
                                metrics,
                                trace_builder_opt,
                            )
                            .map_err(|e| (e, vec![]))?;
                            return Ok((Mode::empty_results(), vec![]));
                        }
                        EndOfEpochTransactionKind::ChangeEpochV2(change_epoch_v2) => {
                            assert_eq!(i, len - 1);
                            advance_epoch_v2(
                                builder,
                                change_epoch_v2,
                                temporary_store,
                                tx_ctx,
                                move_vm,
                                gas_charger,
                                protocol_config,
                                metrics,
                                trace_builder_opt,
                            )
                            .map_err(|e| (e, vec![]))?;
                            return Ok((Mode::empty_results(), vec![]));
                        }
                        EndOfEpochTransactionKind::ChangeEpochV3(change_epoch_v3) => {
                            assert_eq!(i, len - 1);
                            advance_epoch_v3(
                                builder,
                                change_epoch_v3,
                                temporary_store,
                                tx_ctx,
                                move_vm,
                                gas_charger,
                                protocol_config,
                                metrics,
                                trace_builder_opt,
                            )
                            .map_err(|e| (e, vec![]))?;
                            return Ok((Mode::empty_results(), vec![]));
                        }
                        EndOfEpochTransactionKind::ChangeEpochV4(change_epoch_v4) => {
                            assert_eq!(i, len - 1);
                            advance_epoch_v4(
                                builder,
                                change_epoch_v4,
                                temporary_store,
                                tx_ctx,
                                move_vm,
                                gas_charger,
                                protocol_config,
                                metrics,
                                trace_builder_opt,
                            )
                            .map_err(|e| (e, vec![]))?;
                            return Ok((Mode::empty_results(), vec![]));
                        }
                        EndOfEpochTransactionKind::TransactionDenyRulesCreate => {
                            assert!(
                                protocol_config.enable_pcool_flow(),
                                "unexpected TransactionDenyRulesCreate: on-chain deny rule governance is not enabled"
                            );
                            builder = setup_transaction_deny_rules_create(builder)
                                .map_err(|e| (e, vec![]))?;
                        }
                        _ => unimplemented!(
                            "a new EndOfEpochTransactionKind enum variant was added and needs to be handled"
                        ),
                    }
                }
                unreachable!(
                    "EndOfEpochTransactionKind::ChangeEpoch should be the last transaction in the list"
                )
            }
            #[allow(deprecated)]
            TransactionKind::AuthenticatorStateUpdateV1Deprecated => {
                // Deprecated: Authenticator state (JWK) is deprecated and
                // was never enabled. These transaction kinds are retained
                // only for BCS enum variant compatibility.
                return Err((
                    ExecutionError::new(
                        ExecutionErrorKind::VmInvariantViolation,
                        Some("AuthenticatorState transactions are deprecated and were never created on IOTA".into()),
                    ),
                    vec![],
                ));
            }
            TransactionKind::RandomnessStateUpdate(randomness_state_update) => {
                setup_randomness_state_update(
                    randomness_state_update,
                    temporary_store,
                    tx_ctx,
                    move_vm,
                    gas_charger,
                    protocol_config,
                    metrics,
                    trace_builder_opt,
                )
                .map_err(|e| (e, vec![]))?;
                Ok((Mode::empty_results(), vec![]))
            }
            TransactionKind::TransactionDenyRulesUpdate(update) => {
                assert!(
                    protocol_config.enable_pcool_flow(),
                    "unexpected TransactionDenyRulesUpdate: on-chain deny rule governance is not enabled"
                );
                setup_transaction_deny_rules_update(
                    update,
                    temporary_store,
                    tx_ctx,
                    move_vm,
                    gas_charger,
                    protocol_config,
                    metrics,
                    trace_builder_opt,
                )
                .map_err(|e| (e, vec![]))?;
                Ok((Mode::empty_results(), vec![]))
            }
            _ => unimplemented!(
                "a new TransactionKind enum variant was added and needs to be handled"
            ),
        }?;
        temporary_store
            .check_execution_results_consistency()
            .map_err(|e| (e, vec![]))?;
        Ok(result)
    }

    /// Mints epoch rewards by creating both storage and computation charges
    /// using a `ProgrammableTransactionBuilder`. The function takes in the
    /// `AdvanceEpochParams`, serializes the storage and computation
    /// charges, and invokes the reward creation function within the IOTA
    /// Prepares invocations for creating both storage and computation charges
    /// with a `ProgrammableTransactionBuilder` using the `AdvanceEpochParams`.
    /// The corresponding functions from the IOTA framework can be invoked later
    /// during execution of the programmable transaction.
    fn mint_epoch_rewards_in_pt(
        builder: &mut ProgrammableTransactionBuilder,
        params: &AdvanceEpochParams,
    ) -> (Argument, Argument) {
        // Create storage charges.
        let storage_charge_arg = builder
            .input(CallArg::pure(&params.storage_charge))
            .unwrap();
        let storage_charges = builder.programmable_move_call(
            ObjectId::FRAMEWORK,
            Identifier::BALANCE_MODULE,
            BALANCE_CREATE_REWARDS_FUNCTION_NAME,
            vec![TypeTag::from(StructTag::new_gas())],
            vec![storage_charge_arg],
        );

        // Create computation charges.
        let computation_charge_arg = builder
            .input(CallArg::pure(&params.computation_charge))
            .unwrap();
        let computation_charges = builder.programmable_move_call(
            ObjectId::FRAMEWORK,
            Identifier::BALANCE_MODULE,
            BALANCE_CREATE_REWARDS_FUNCTION_NAME,
            vec![TypeTag::from(StructTag::new_gas())],
            vec![computation_charge_arg],
        );
        (storage_charges, computation_charges)
    }

    /// Constructs a `ProgrammableTransaction` to advance the epoch. It creates
    /// storage charges and computation charges by invoking
    /// `mint_epoch_rewards_in_pt`, advances the epoch by setting up the
    /// necessary arguments, such as epoch number, protocol version, storage
    /// rebate, and slashing rate, and executing the `advance_epoch` function
    /// within the IOTA system. Then, it destroys the storage rebates to
    /// complete the transaction.
    pub fn construct_advance_epoch_pt_impl(
        mut builder: ProgrammableTransactionBuilder,
        params: &AdvanceEpochParams,
        call_arg_vec: Vec<CallArg>,
    ) -> Result<ProgrammableTransaction, ExecutionError> {
        // Create storage and computation charges and add them as arguments.
        let (storage_charges, computation_charges) = mint_epoch_rewards_in_pt(&mut builder, params);
        let mut arguments = vec![
            builder
                .pure(params.validator_subsidy)
                .expect("bcs encoding a u64 should not fail"),
            storage_charges,
            computation_charges,
        ];

        let call_arg_arguments = call_arg_vec
            .into_iter()
            .map(|a| builder.input(a))
            .collect::<Result<_, _>>();

        assert_invariant!(
            call_arg_arguments.is_ok(),
            "Unable to generate args for advance_epoch transaction!"
        );

        arguments.append(&mut call_arg_arguments.unwrap());

        info!("Call arguments to advance_epoch transaction: {:?}", params);

        let storage_rebates = builder.programmable_move_call(
            ObjectId::SYSTEM,
            Identifier::IOTA_SYSTEM_MODULE,
            ADVANCE_EPOCH_FUNCTION_NAME,
            vec![],
            arguments,
        );

        // Step 3: Destroy the storage rebates.
        builder.programmable_move_call(
            ObjectId::FRAMEWORK,
            Identifier::BALANCE_MODULE,
            BALANCE_DESTROY_REBATES_FUNCTION_NAME,
            vec![TypeTag::from(StructTag::new_gas())],
            vec![storage_rebates],
        );
        Ok(builder.finish())
    }

    pub fn construct_advance_epoch_pt_v1(
        builder: ProgrammableTransactionBuilder,
        params: &AdvanceEpochParams,
    ) -> Result<ProgrammableTransaction, ExecutionError> {
        // the first three arguments to the advance_epoch function, namely
        // validator_subsidy, storage_charges and computation_charges, are
        // common to both v1 and v2 and are added in `construct_advance_epoch_pt_impl`.
        // The remaining arguments are added here.
        let call_arg_vec = vec![
            CallArg::IOTA_SYSTEM_MUTABLE, // wrapper: &mut IotaSystemState
            CallArg::pure(&params.epoch), // new_epoch: u64
            CallArg::pure(&params.next_protocol_version.as_u64()), // next_protocol_version: u64
            CallArg::pure(&params.storage_rebate), // storage_rebate: u64
            CallArg::pure(&params.non_refundable_storage_fee), // non_refundable_storage_fee: u64
            CallArg::pure(&params.reward_slashing_rate), // reward_slashing_rate: u64
            CallArg::pure(&params.epoch_start_timestamp_ms), // epoch_start_timestamp_ms: u64
        ];
        construct_advance_epoch_pt_impl(builder, params, call_arg_vec)
    }

    pub fn construct_advance_epoch_pt_v2(
        builder: ProgrammableTransactionBuilder,
        params: &AdvanceEpochParams,
    ) -> Result<ProgrammableTransaction, ExecutionError> {
        // the first three arguments to the advance_epoch function, namely
        // validator_subsidy, storage_charges and computation_charges, are
        // common to both v1 and v2 and are added in `construct_advance_epoch_pt_impl`.
        // The remaining arguments are added here.
        let call_arg_vec = vec![
            CallArg::pure(&params.computation_charge_burned), // computation_charge_burned: u64
            CallArg::IOTA_SYSTEM_MUTABLE,                     // wrapper: &mut IotaSystemState
            CallArg::pure(&params.epoch),                     // new_epoch: u64
            CallArg::pure(&params.next_protocol_version.as_u64()), // next_protocol_version: u64
            CallArg::pure(&params.storage_rebate),            // storage_rebate: u64
            CallArg::pure(&params.non_refundable_storage_fee), // non_refundable_storage_fee: u64
            CallArg::pure(&params.reward_slashing_rate),      // reward_slashing_rate: u64
            CallArg::pure(&params.epoch_start_timestamp_ms),  // epoch_start_timestamp_ms: u64
            CallArg::pure(&params.max_committee_members_count), // max_committee_members_count: u64
        ];
        construct_advance_epoch_pt_impl(builder, params, call_arg_vec)
    }

    pub fn construct_advance_epoch_pt_v3(
        builder: ProgrammableTransactionBuilder,
        params: &AdvanceEpochParams,
    ) -> Result<ProgrammableTransaction, ExecutionError> {
        // the first three arguments to the advance_epoch function, namely
        // validator_subsidy, storage_charges and computation_charges, are
        // common to both v1, v2 and v3 and are added in
        // `construct_advance_epoch_pt_impl`. The remaining arguments are added
        // here.
        let call_arg_vec = vec![
            CallArg::pure(&params.computation_charge_burned), // computation_charge_burned: u64
            CallArg::IOTA_SYSTEM_MUTABLE,                     // wrapper: &mut IotaSystemState
            CallArg::pure(&params.epoch),                     // new_epoch: u64
            CallArg::pure(&params.next_protocol_version.as_u64()), // next_protocol_version: u64
            CallArg::pure(&params.storage_rebate),            // storage_rebate: u64
            CallArg::pure(&params.non_refundable_storage_fee), // non_refundable_storage_fee: u64
            CallArg::pure(&params.reward_slashing_rate),      // reward_slashing_rate: u64
            CallArg::pure(&params.epoch_start_timestamp_ms),  // epoch_start_timestamp_ms: u64
            CallArg::pure(&params.max_committee_members_count), // max_committee_members_count: u64
            CallArg::pure(&params.eligible_active_validators), /* eligible_active_validators:
                                                               * Vec<u64> */
        ];
        construct_advance_epoch_pt_impl(builder, params, call_arg_vec)
    }

    pub fn construct_advance_epoch_pt_v4(
        builder: ProgrammableTransactionBuilder,
        params: &AdvanceEpochParams,
    ) -> Result<ProgrammableTransaction, ExecutionError> {
        // the first three arguments to the advance_epoch function, namely
        // validator_subsidy, storage_charges and computation_charges, are
        // common to both v1, v2, v3 and v4 and are added in
        // `construct_advance_epoch_pt_impl`. The remaining arguments are added
        // here.
        let call_arg_vec = vec![
            CallArg::pure(&params.computation_charge_burned), // computation_charge_burned: u64
            CallArg::IOTA_SYSTEM_MUTABLE,                     // wrapper: &mut IotaSystemState
            CallArg::pure(&params.epoch),                     // new_epoch: u64
            CallArg::pure(&params.next_protocol_version.as_u64()), // next_protocol_version: u64
            CallArg::pure(&params.storage_rebate),            // storage_rebate: u64
            CallArg::pure(&params.non_refundable_storage_fee), // non_refundable_storage_fee: u64
            CallArg::pure(&params.reward_slashing_rate),      // reward_slashing_rate: u64
            CallArg::pure(&params.epoch_start_timestamp_ms),  // epoch_start_timestamp_ms: u64
            CallArg::pure(&params.max_committee_members_count), // max_committee_members_count: u64
            CallArg::pure(&params.eligible_active_validators), /* eligible_active_validators:
                                                               * Vec<u64> */
            CallArg::pure(&params.scores), // scores: Vec<u64>
            CallArg::pure(&params.adjust_rewards_by_score), // adjust_rewards_by_score: bool
        ];
        construct_advance_epoch_pt_impl(builder, params, call_arg_vec)
    }

    /// Advances the epoch by executing a `ProgrammableTransaction`. If the
    /// transaction fails, it switches to safe mode and retries the epoch
    /// advancement in a more controlled environment. The function also
    /// handles the publication and upgrade of system packages for the new
    /// epoch. If any system package is added or upgraded, it ensures the
    /// proper execution and storage of the changes.
    fn advance_epoch_impl(
        advance_epoch_pt: ProgrammableTransaction,
        params: AdvanceEpochParams,
        system_packages: Vec<SystemPackage>,
        temporary_store: &mut TemporaryStore<'_>,
        tx_ctx: Rc<RefCell<TxContext>>,
        move_vm: &Arc<MoveVM>,
        gas_charger: &mut GasCharger,
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
        trace_builder_opt: &mut Option<MoveTraceBuilder>,
    ) -> Result<(), ExecutionError> {
        let result = programmable_transactions::execution::execute::<execution_mode::System>(
            protocol_config,
            metrics.clone(),
            move_vm,
            temporary_store,
            tx_ctx.clone(),
            gas_charger,
            advance_epoch_pt,
            trace_builder_opt,
        );

        #[cfg(msim)]
        let result = maybe_modify_result(result, params.epoch);

        if let Err(err) = &result {
            tracing::error!(
                "Failed to execute advance epoch transaction. Switching to safe mode. Error: {:?}. Input objects: {:?}. Tx params: {:?}",
                err.0,
                temporary_store.objects(),
                params,
            );
            temporary_store.drop_writes();
            // Must reset the storage rebate since we are re-executing.
            gas_charger.reset_storage_cost_and_rebate();

            temporary_store.advance_epoch_safe_mode(&params, protocol_config);
        }

        let new_vm = new_move_vm(
            all_natives(/* silent */ true, protocol_config),
            protocol_config,
            // enable_profiler
            None,
        )
        .expect("Failed to create new MoveVM");
        process_system_packages(
            system_packages,
            temporary_store,
            tx_ctx,
            &new_vm,
            gas_charger,
            protocol_config,
            metrics,
            trace_builder_opt,
        );

        Ok(())
    }

    /// Advances the epoch for the given `ChangeEpoch` transaction kind by
    /// constructing a programmable transaction, executing it and processing the
    /// system packages.
    fn advance_epoch_v1(
        builder: ProgrammableTransactionBuilder,
        change_epoch: ChangeEpoch,
        temporary_store: &mut TemporaryStore<'_>,
        tx_ctx: Rc<RefCell<TxContext>>,
        move_vm: &Arc<MoveVM>,
        gas_charger: &mut GasCharger,
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
        trace_builder_opt: &mut Option<MoveTraceBuilder>,
    ) -> Result<(), ExecutionError> {
        let params = AdvanceEpochParams {
            epoch: change_epoch.epoch,
            next_protocol_version: change_epoch.protocol_version.into(),
            validator_subsidy: protocol_config.validator_target_reward(),
            storage_charge: change_epoch.storage_charge,
            computation_charge: change_epoch.computation_charge,
            // all computation charge is burned in v1
            computation_charge_burned: change_epoch.computation_charge,
            storage_rebate: change_epoch.storage_rebate,
            non_refundable_storage_fee: change_epoch.non_refundable_storage_fee,
            reward_slashing_rate: protocol_config.reward_slashing_rate(),
            epoch_start_timestamp_ms: change_epoch.epoch_start_timestamp_ms,
            // AdvanceEpochV1 does not use those fields, but keeping them to avoid creating a
            // separate AdvanceEpochParams struct.
            max_committee_members_count: 0,
            eligible_active_validators: vec![],
            scores: vec![],
            adjust_rewards_by_score: false,
        };
        let advance_epoch_pt = construct_advance_epoch_pt_v1(builder, &params)?;
        advance_epoch_impl(
            advance_epoch_pt,
            params,
            change_epoch.system_packages,
            temporary_store,
            tx_ctx,
            move_vm,
            gas_charger,
            protocol_config,
            metrics,
            trace_builder_opt,
        )
    }

    /// Advances the epoch for the given `ChangeEpochV2` transaction kind by
    /// constructing a programmable transaction, executing it and processing the
    /// system packages.
    fn advance_epoch_v2(
        builder: ProgrammableTransactionBuilder,
        change_epoch_v2: ChangeEpochV2,
        temporary_store: &mut TemporaryStore<'_>,
        tx_ctx: Rc<RefCell<TxContext>>,
        move_vm: &Arc<MoveVM>,
        gas_charger: &mut GasCharger,
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
        trace_builder_opt: &mut Option<MoveTraceBuilder>,
    ) -> Result<(), ExecutionError> {
        let params = AdvanceEpochParams {
            epoch: change_epoch_v2.epoch,
            next_protocol_version: change_epoch_v2.protocol_version.into(),
            validator_subsidy: protocol_config.validator_target_reward(),
            storage_charge: change_epoch_v2.storage_charge,
            computation_charge: change_epoch_v2.computation_charge,
            computation_charge_burned: change_epoch_v2.computation_charge_burned,
            storage_rebate: change_epoch_v2.storage_rebate,
            non_refundable_storage_fee: change_epoch_v2.non_refundable_storage_fee,
            reward_slashing_rate: protocol_config.reward_slashing_rate(),
            epoch_start_timestamp_ms: change_epoch_v2.epoch_start_timestamp_ms,
            max_committee_members_count: protocol_config.max_committee_members_count(),
            // AdvanceEpochV2 does not use these fields, but keeping them to avoid creating a
            // separate AdvanceEpochParams struct.
            eligible_active_validators: vec![],
            scores: vec![],
            adjust_rewards_by_score: false,
        };
        let advance_epoch_pt = construct_advance_epoch_pt_v2(builder, &params)?;
        advance_epoch_impl(
            advance_epoch_pt,
            params,
            change_epoch_v2.system_packages,
            temporary_store,
            tx_ctx,
            move_vm,
            gas_charger,
            protocol_config,
            metrics,
            trace_builder_opt,
        )
    }

    /// Advances the epoch for the given `ChangeEpochV3` transaction kind by
    /// constructing a programmable transaction, executing it and processing the
    /// system packages.
    fn advance_epoch_v3(
        builder: ProgrammableTransactionBuilder,
        change_epoch_v3: ChangeEpochV3,
        temporary_store: &mut TemporaryStore<'_>,
        tx_ctx: Rc<RefCell<TxContext>>,
        move_vm: &Arc<MoveVM>,
        gas_charger: &mut GasCharger,
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
        trace_builder_opt: &mut Option<MoveTraceBuilder>,
    ) -> Result<(), ExecutionError> {
        let params = AdvanceEpochParams {
            epoch: change_epoch_v3.epoch,
            next_protocol_version: change_epoch_v3.protocol_version.into(),
            validator_subsidy: protocol_config.validator_target_reward(),
            storage_charge: change_epoch_v3.storage_charge,
            computation_charge: change_epoch_v3.computation_charge,
            computation_charge_burned: change_epoch_v3.computation_charge_burned,
            storage_rebate: change_epoch_v3.storage_rebate,
            non_refundable_storage_fee: change_epoch_v3.non_refundable_storage_fee,
            reward_slashing_rate: protocol_config.reward_slashing_rate(),
            epoch_start_timestamp_ms: change_epoch_v3.epoch_start_timestamp_ms,
            max_committee_members_count: protocol_config.max_committee_members_count(),
            eligible_active_validators: change_epoch_v3.eligible_active_validators,
            // AdvanceEpochV3 does not use these fields, but keeping them to avoid creating a
            // separate AdvanceEpochParams struct.
            scores: vec![],
            adjust_rewards_by_score: false,
        };
        let advance_epoch_pt = construct_advance_epoch_pt_v3(builder, &params)?;
        advance_epoch_impl(
            advance_epoch_pt,
            params,
            change_epoch_v3.system_packages,
            temporary_store,
            tx_ctx,
            move_vm,
            gas_charger,
            protocol_config,
            metrics,
            trace_builder_opt,
        )
    }

    /// Advances the epoch for the given `ChangeEpochV4` transaction kind by
    /// constructing a programmable transaction, executing it and processing the
    /// system packages.
    fn advance_epoch_v4(
        builder: ProgrammableTransactionBuilder,
        change_epoch_v4: ChangeEpochV4,
        temporary_store: &mut TemporaryStore<'_>,
        tx_ctx: Rc<RefCell<TxContext>>,
        move_vm: &Arc<MoveVM>,
        gas_charger: &mut GasCharger,
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
        trace_builder_opt: &mut Option<MoveTraceBuilder>,
    ) -> Result<(), ExecutionError> {
        let params = AdvanceEpochParams {
            epoch: change_epoch_v4.epoch,
            next_protocol_version: change_epoch_v4.protocol_version.into(),
            validator_subsidy: protocol_config.validator_target_reward(),
            storage_charge: change_epoch_v4.storage_charge,
            computation_charge: change_epoch_v4.computation_charge,
            computation_charge_burned: change_epoch_v4.computation_charge_burned,
            storage_rebate: change_epoch_v4.storage_rebate,
            non_refundable_storage_fee: change_epoch_v4.non_refundable_storage_fee,
            reward_slashing_rate: protocol_config.reward_slashing_rate(),
            epoch_start_timestamp_ms: change_epoch_v4.epoch_start_timestamp_ms,
            max_committee_members_count: protocol_config.max_committee_members_count(),
            eligible_active_validators: change_epoch_v4.eligible_active_validators,
            scores: change_epoch_v4.scores,
            adjust_rewards_by_score: change_epoch_v4.adjust_rewards_by_score,
        };
        let advance_epoch_pt = construct_advance_epoch_pt_v4(builder, &params)?;
        advance_epoch_impl(
            advance_epoch_pt,
            params,
            change_epoch_v4.system_packages,
            temporary_store,
            tx_ctx,
            move_vm,
            gas_charger,
            protocol_config,
            metrics,
            trace_builder_opt,
        )
    }

    fn process_system_packages(
        system_packages: Vec<SystemPackage>,
        temporary_store: &mut TemporaryStore<'_>,
        tx_ctx: Rc<RefCell<TxContext>>,
        move_vm: &MoveVM,
        gas_charger: &mut GasCharger,
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
        trace_builder_opt: &mut Option<MoveTraceBuilder>,
    ) {
        let binary_config = to_binary_config(protocol_config, None);
        for SystemPackage {
            version,
            modules,
            dependencies,
        } in system_packages.into_iter()
        {
            let deserialized_modules: Vec<_> = modules
                .iter()
                .map(|m| CompiledModule::deserialize_with_config(m, &binary_config).unwrap())
                .collect();

            if version == OBJECT_START_VERSION {
                let package_id = deserialized_modules.first().unwrap().address();
                info!("adding new system package {package_id}");

                let publish_pt = {
                    let mut b = ProgrammableTransactionBuilder::new();
                    b.command(Command::new_publish(modules, dependencies));
                    b.finish()
                };

                programmable_transactions::execution::execute::<execution_mode::System>(
                    protocol_config,
                    metrics.clone(),
                    move_vm,
                    temporary_store,
                    tx_ctx.clone(),
                    gas_charger,
                    publish_pt,
                    trace_builder_opt,
                )
                .map_err(|(e, _)| e)
                .expect("System Package Publish must succeed");
            } else {
                let mut new_package = Object::new_system_package(
                    &deserialized_modules,
                    version,
                    dependencies,
                    tx_ctx.borrow().digest(),
                );

                info!("upgraded system package {:?}", new_package.object_ref());

                // Decrement the version before writing the package so that the store can record
                // the version growing by one in the effects.
                new_package
                    .data
                    .as_opt_mut_package()
                    .unwrap()
                    .decrement_version()
                    .expect("package version should never underflow");

                // upgrade of a previously existing framework module
                temporary_store.upgrade_system_package(new_package);
            }
        }
    }

    /// Perform metadata updates in preparation for the transactions in the
    /// upcoming checkpoint:
    ///
    /// - Set the timestamp for the `Clock` shared object from the timestamp in the header from
    ///   consensus.
    fn setup_consensus_commit(
        consensus_commit_timestamp_ms: CheckpointTimestamp,
        temporary_store: &mut TemporaryStore<'_>,
        tx_ctx: Rc<RefCell<TxContext>>,
        move_vm: &Arc<MoveVM>,
        gas_charger: &mut GasCharger,
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
        trace_builder_opt: &mut Option<MoveTraceBuilder>,
    ) -> Result<(), ExecutionError> {
        let pt = {
            let mut builder = ProgrammableTransactionBuilder::new();
            let res = builder.move_call(
                ObjectId::FRAMEWORK,
                Identifier::CLOCK_MODULE,
                CONSENSUS_COMMIT_PROLOGUE_FUNCTION_NAME,
                vec![],
                vec![
                    CallArg::CLOCK_MUTABLE,
                    CallArg::pure(&consensus_commit_timestamp_ms),
                ],
            );
            assert_invariant!(
                res.is_ok(),
                "Unable to generate consensus_commit_prologue transaction!"
            );
            builder.finish()
        };
        programmable_transactions::execution::execute::<execution_mode::System>(
            protocol_config,
            metrics,
            move_vm,
            temporary_store,
            tx_ctx,
            gas_charger,
            pt,
            trace_builder_opt,
        )
        .map_err(|(e, _)| e)?;
        Ok(())
    }

    /// The function constructs a transaction that invokes
    /// the `randomness_state_update` function from the IOTA framework,
    /// passing the randomness state object, the `randomness_round`,
    /// and the `random_bytes` as arguments. It then executes the transaction
    /// using the system execution mode.
    fn setup_randomness_state_update(
        update: RandomnessStateUpdate,
        temporary_store: &mut TemporaryStore<'_>,
        tx_ctx: Rc<RefCell<TxContext>>,
        move_vm: &Arc<MoveVM>,
        gas_charger: &mut GasCharger,
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
        trace_builder_opt: &mut Option<MoveTraceBuilder>,
    ) -> Result<(), ExecutionError> {
        let pt = {
            let mut builder = ProgrammableTransactionBuilder::new();
            let res = builder.move_call(
                ObjectId::FRAMEWORK,
                Identifier::RANDOM_MODULE,
                RANDOMNESS_STATE_UPDATE_FUNCTION_NAME,
                vec![],
                vec![
                    CallArg::Shared(SharedObjectReference::new(
                        ObjectId::RANDOMNESS_STATE,
                        update.randomness_obj_initial_shared_version,
                        true,
                    )),
                    CallArg::pure(&update.randomness_round),
                    CallArg::pure(&update.random_bytes),
                ],
            );
            assert_invariant!(
                res.is_ok(),
                "Unable to generate randomness_state_update transaction!"
            );
            builder.finish()
        };
        programmable_transactions::execution::execute::<execution_mode::System>(
            protocol_config,
            metrics,
            move_vm,
            temporary_store,
            tx_ctx,
            gas_charger,
            pt,
            trace_builder_opt,
        )
        .map_err(|(e, _)| e)?;
        Ok(())
    }

    /// Appends the `transaction_deny_rules::create` call to the end-of-epoch
    /// transaction being built. If the built transaction later fails and epoch
    /// advancement falls back to safe mode, the creation is dropped with it
    /// and must be re-injected at a later epoch end while the object is
    /// absent.
    fn setup_transaction_deny_rules_create(
        mut builder: ProgrammableTransactionBuilder,
    ) -> Result<ProgrammableTransactionBuilder, ExecutionError> {
        let res = builder.move_call(
            ObjectId::FRAMEWORK,
            TRANSACTION_DENY_RULES_MODULE,
            TRANSACTION_DENY_RULES_CREATE_FUNCTION_NAME,
            vec![],
            vec![],
        );
        assert_invariant!(
            res.is_ok(),
            "Unable to generate transaction_deny_rules create transaction!"
        );
        Ok(builder)
    }

    /// Executes a `TransactionDenyRulesUpdate` system transaction: a single
    /// call to `transaction_deny_rules::update` applying the payload's
    /// add/remove delta and switch states.
    fn setup_transaction_deny_rules_update(
        update: TransactionDenyRulesUpdate,
        temporary_store: &mut TemporaryStore<'_>,
        tx_ctx: Rc<RefCell<TxContext>>,
        move_vm: &Arc<MoveVM>,
        gas_charger: &mut GasCharger,
        protocol_config: &ProtocolConfig,
        metrics: Arc<LimitsMetrics>,
        trace_builder_opt: &mut Option<MoveTraceBuilder>,
    ) -> Result<(), ExecutionError> {
        let pt = {
            let mut builder = ProgrammableTransactionBuilder::new();
            // Argument order must match `transaction_deny_rules::update`. The
            // set-typed delta lists BCS-encode identically to the `vector`
            // parameters the Move function takes.
            let res = builder.move_call(
                ObjectId::FRAMEWORK,
                TRANSACTION_DENY_RULES_MODULE,
                TRANSACTION_DENY_RULES_UPDATE_FUNCTION_NAME,
                vec![],
                vec![
                    CallArg::Shared(SharedObjectReference::new(
                        ObjectId::TRANSACTION_DENY_RULES,
                        update.deny_rules_obj_initial_shared_version,
                        true,
                    )),
                    CallArg::pure(&update.added_addresses),
                    CallArg::pure(&update.removed_addresses),
                    CallArg::pure(&update.added_objects),
                    CallArg::pure(&update.removed_objects),
                    CallArg::pure(&update.added_packages),
                    CallArg::pure(&update.removed_packages),
                    CallArg::pure(&update.package_publish_disabled),
                    CallArg::pure(&update.package_upgrade_disabled),
                    CallArg::pure(&update.shared_object_disabled),
                    CallArg::pure(&update.user_transaction_disabled),
                    CallArg::pure(&update.receiving_objects_disabled),
                    CallArg::pure(&update.move_authenticator_disabled),
                ],
            );
            assert_invariant!(
                res.is_ok(),
                "Unable to generate transaction_deny_rules update transaction!"
            );
            builder.finish()
        };
        programmable_transactions::execution::execute::<execution_mode::System>(
            protocol_config,
            metrics,
            move_vm,
            temporary_store,
            tx_ctx,
            gas_charger,
            pt,
            trace_builder_opt,
        )
        .map(|(results, _timings)| results)
        .map_err(|(error, _timings)| error)
    }

    /// Construct a PTB with a single move call. This calls the authenticator
    /// function found in `AuthenticatorFunctionRef`. The inputs for the
    /// function are found in `MoveAuthenticator`.
    /// `MoveAuthenticator::object_to_authenticate` is added as the first
    /// argument to the created PTB, followed by all arguments in
    /// `MoveAuthenticator::call_args`.
    fn setup_authenticator_move_call(
        authenticator: MoveAuthenticator,
        authenticator_function_ref: AuthenticatorFunctionRefV1,
    ) -> Result<ProgrammableTransaction, ExecutionError> {
        let mut builder = ProgrammableTransactionBuilder::new();

        let mut args = vec![authenticator.object_to_authenticate().to_owned()];
        args.extend(authenticator.call_args().to_owned());

        let res = builder.move_call(
            authenticator_function_ref.package,
            Identifier::new(authenticator_function_ref.module.clone()).expect(
                "`AuthenticatorFunctionRefV1::module` is expected to be a valid `Identifier`",
            ),
            Identifier::new(authenticator_function_ref.function).expect(
                "`AuthenticatorFunctionRefV1::function` is expected to be a valid `Identifier`",
            ),
            authenticator.type_args().to_vec(),
            args,
        );

        assert_invariant!(
            res.is_ok(),
            "Unable to generate an account authenticator call transaction!"
        );

        Ok(builder.finish())
    }

    fn resolve_sponsor(gas_data: &GasPayment, transaction_signer: &Address) -> Option<Address> {
        let gas_owner = gas_data.owner;
        if &gas_owner == transaction_signer {
            None
        } else {
            Some(gas_owner)
        }
    }
}