TransactionProcessor.cs

// SPDX-FileCopyrightText: 2026 Demerzel Solutions Limited
// SPDX-License-Identifier: LGPL-3.0-only

using System;
using System.Diagnostics;
using System.Diagnostics.CodeAnalysis;
using System.IO;
using System.Runtime.CompilerServices;
using System.Threading;
using Nethermind.Core.BlockAccessLists;
using Nethermind.Core;
using Nethermind.Core.Collections;
using Nethermind.Core.Extensions;
using Nethermind.Core.Crypto;
using Nethermind.Core.Messages;
using Nethermind.Core.Specs;
using Nethermind.Crypto;
using Nethermind.Evm.CodeAnalysis;
using Nethermind.Evm.GasPolicy;
using Nethermind.Evm.Tracing;
using Nethermind.Int256;
using Nethermind.Logging;
using Nethermind.Evm.State;
using Nethermind.Evm.Tracing.State;

namespace Nethermind.Evm.TransactionProcessing
{
    public sealed class TransactionProcessor<TGasPolicy>(
        ITransactionProcessor.IBlobBaseFeeCalculator blobBaseFeeCalculator,
        ISpecProvider? specProvider,
        IWorldState? worldState,
        IVirtualMachine<TGasPolicy>? virtualMachine,
        ICodeInfoRepository? codeInfoRepository,
        ILogManager? logManager,
        bool parallel = false)
        : TransactionProcessorBase<TGasPolicy>(blobBaseFeeCalculator, specProvider, worldState, virtualMachine, codeInfoRepository, logManager, parallel)
        where TGasPolicy : struct, IGasPolicy<TGasPolicy>
    {
        public TransactionResult Process(Transaction transaction, ITxTracer txTracer, ExecutionOptions options, in IntrinsicGas<TGasPolicy> intrinsicGas)
            => ExecuteCore(transaction, txTracer, options, in intrinsicGas);
    }

    /// <summary>
    /// Non-generic TransactionProcessor for backward compatibility with EthereumGasPolicy.
    /// </summary>
    public sealed class EthereumTransactionProcessor(
        ITransactionProcessor.IBlobBaseFeeCalculator blobBaseFeeCalculator,
        ISpecProvider? specProvider,
        IWorldState? worldState,
        IVirtualMachine? virtualMachine,
        ICodeInfoRepository? codeInfoRepository,
        ILogManager? logManager)
        : EthereumTransactionProcessorBase(blobBaseFeeCalculator, specProvider, worldState, virtualMachine, codeInfoRepository, logManager);

    public class BlobBaseFeeCalculator : ITransactionProcessor.IBlobBaseFeeCalculator
    {
        public static BlobBaseFeeCalculator Instance { get; } = new BlobBaseFeeCalculator();

        public bool TryCalculateBlobBaseFee(BlockHeader header, Transaction transaction,
            UInt256 blobGasPriceUpdateFraction, out UInt256 blobBaseFee) =>
            BlobGasCalculator.TryCalculateBlobBaseFee(header, transaction, blobGasPriceUpdateFraction, out blobBaseFee);
    }

    public abstract class TransactionProcessorBase<TGasPolicy> : ITransactionProcessor
        where TGasPolicy : struct, IGasPolicy<TGasPolicy>
    {
        protected EthereumEcdsa Ecdsa { get; }
        protected ILogger Logger { get; }
        protected ISpecProvider SpecProvider { get; }
        protected IWorldState WorldState { get; }
        protected IVirtualMachine<TGasPolicy> VirtualMachine { get; }
        private readonly ICodeInfoRepository _codeInfoRepository;
        private SystemTransactionProcessor<TGasPolicy>? _systemTransactionProcessor;
        private readonly ITransactionProcessor.IBlobBaseFeeCalculator _blobBaseFeeCalculator;
        private readonly ILogManager _logManager;
        private readonly bool _parallel;
        private long _blockCumulativeReceiptGas;

        protected TransactionProcessorBase(
            ITransactionProcessor.IBlobBaseFeeCalculator? blobBaseFeeCalculator,
            ISpecProvider? specProvider,
            IWorldState? worldState,
            IVirtualMachine<TGasPolicy>? virtualMachine,
            ICodeInfoRepository? codeInfoRepository,
            ILogManager? logManager,
            bool parallel = false)
        {
            ArgumentNullException.ThrowIfNull(logManager);
            ArgumentNullException.ThrowIfNull(specProvider);
            ArgumentNullException.ThrowIfNull(worldState);
            ArgumentNullException.ThrowIfNull(virtualMachine);
            ArgumentNullException.ThrowIfNull(codeInfoRepository);
            ArgumentNullException.ThrowIfNull(blobBaseFeeCalculator);

            Logger = logManager.GetClassLogger(typeof(TransactionProcessorBase<>));
            SpecProvider = specProvider;
            WorldState = worldState;
            VirtualMachine = virtualMachine;
            _codeInfoRepository = codeInfoRepository;
            _blobBaseFeeCalculator = blobBaseFeeCalculator;

            Ecdsa = new EthereumEcdsa(specProvider.ChainId);
            _logManager = logManager;
            _parallel = parallel;
        }

        public void SetBlockExecutionContext(in BlockExecutionContext blockExecutionContext)
        {
            _blockCumulativeReceiptGas = 0;
            VirtualMachine.SetBlockExecutionContext(in blockExecutionContext);
        }

        public void SetBlockExecutionContext(BlockHeader header)
        {
            IReleaseSpec spec = SpecProvider.GetSpec(header);
            BlockExecutionContext blockExecutionContext = new(header, spec);
            SetBlockExecutionContext(in blockExecutionContext);
        }

        public TransactionResult Process(
            Transaction transaction,
            ITxTracer txTracer,
            ExecutionOptions options)
        {
            if (options == ExecutionOptions.BuildUp)
            {
                WorldState.TakeSnapshot(true);
            }

            return ExecuteCore(transaction, txTracer, options);
        }
        private TransactionResult ExecuteCore(Transaction tx, ITxTracer tracer, ExecutionOptions opts)
        {
            if (Logger.IsTrace) Logger.Trace($"Executing tx {tx.Hash}");
            if (tx.IsSystem() || (opts & ~ExecutionOptions.Warmup) == ExecutionOptions.SkipValidation)
            {
                if (_systemTransactionProcessor is null)
                {
                    Interlocked.CompareExchange(ref _systemTransactionProcessor,
                        new SystemTransactionProcessor<TGasPolicy>(_blobBaseFeeCalculator, SpecProvider, WorldState, VirtualMachine, _codeInfoRepository, _logManager),
                        null);
                }
                return _systemTransactionProcessor.Execute(tx, tracer, opts);
            }

            TransactionResult result = Execute(tx, tracer, opts);
            if (Logger.IsTrace) Logger.Trace($"Tx {tx.Hash} was executed, {result}");
            return result;
        }

        protected TransactionResult ExecuteCore(Transaction tx, ITxTracer tracer, ExecutionOptions opts, in IntrinsicGas<TGasPolicy> intrinsicGas)
        {
            if (Logger.IsTrace) Logger.Trace($"Executing tx {tx.Hash}");
            if (tx.IsSystem() || (opts & ~ExecutionOptions.Warmup) == ExecutionOptions.SkipValidation)
            {
                if (_systemTransactionProcessor is null)
                {
                    Interlocked.CompareExchange(ref _systemTransactionProcessor,
                        new SystemTransactionProcessor<TGasPolicy>(_blobBaseFeeCalculator, SpecProvider, WorldState, VirtualMachine, _codeInfoRepository, _logManager),
                        null);
                }
                return _systemTransactionProcessor.Execute(tx, tracer, opts);
            }

            TransactionResult result = Execute(tx, tracer, opts, in intrinsicGas);
            if (Logger.IsTrace) Logger.Trace($"Tx {tx.Hash} was executed, {result}");
            return result;
        }

        protected virtual TransactionResult Execute(Transaction tx, ITxTracer tracer, ExecutionOptions opts)
        {
            BlockHeader header = VirtualMachine.BlockExecutionContext.Header;
            IReleaseSpec spec = GetSpec(header);
            IntrinsicGas<TGasPolicy> intrinsicGas = CalculateIntrinsicGas(tx, spec, header.GasLimit);
            return Execute(tx, tracer, opts, header, spec, in intrinsicGas);
        }

        protected TransactionResult Execute(Transaction tx, ITxTracer tracer, ExecutionOptions opts, in IntrinsicGas<TGasPolicy> intrinsicGas)
        {
            BlockHeader header = VirtualMachine.BlockExecutionContext.Header;
            IReleaseSpec spec = GetSpec(header);
            return Execute(tx, tracer, opts, header, spec, in intrinsicGas);
        }

        private TransactionResult Execute(Transaction tx, ITxTracer tracer, ExecutionOptions opts, BlockHeader header, IReleaseSpec spec, in IntrinsicGas<TGasPolicy> intrinsicGas)
        {
            // restore is CallAndRestore - previous call, we will restore state after the execution
            bool restore = opts.HasFlag(ExecutionOptions.Restore);
            // commit - is for standard execute, we will commit the state after execution
            // !commit - is for build up during block production, we won't commit state after each transaction to support rollbacks
            // we commit only after all block is constructed
            bool commit = opts.HasFlag(ExecutionOptions.Commit) || (!opts.HasFlag(ExecutionOptions.SkipValidation) && !spec.IsEip658Enabled);

            TransactionResult result;
            if (!(result = ValidateStatic(tx, header, spec, opts, in intrinsicGas))) return result;

            UInt256 effectiveGasPrice = CalculateEffectiveGasPrice(tx, spec.IsEip1559Enabled, header.BaseFeePerGas, out UInt256 opcodeGasPrice);

            VirtualMachine.SetTxExecutionContext(new(tx.SenderAddress!, _codeInfoRepository, tx.BlobVersionedHashes, in opcodeGasPrice));

            UpdateMetrics(opts, effectiveGasPrice);

            bool deleteCallerAccount = RecoverSenderIfNeeded(tx, spec, opts, effectiveGasPrice);

            if (!(result = ValidateSender(tx, header, spec, tracer, opts)) ||
                !(result = BuyGas(tx, spec, tracer, opts, effectiveGasPrice, out UInt256 premiumPerGas, out UInt256 senderReservedGasPayment, out UInt256 blobBaseFee)) ||
                !(result = IncrementNonce(tx, header, spec, tracer, opts)))
            {
                if (restore)
                {
                    WorldState.Reset(resetBlockChanges: false);
                }
                return result;
            }

            if (commit) WorldState.Commit(spec, tracer.IsTracingState ? tracer : NullTxTracer.Instance, commitRoots: false);

            // substate.Logs contains a reference to accessTracker.Logs so we can't Dispose until end of the method
            using StackAccessTracker accessTracker = new(tracer.IsTracingAccess);

            int delegationRefunds = !spec.IsEip7702Enabled || !tx.HasAuthorizationList ? 0 : ProcessDelegations(tx, spec, accessTracker);

            if (!(result = CalculateAvailableGas(tx, spec, in intrinsicGas, out TGasPolicy gasAvailable))) return result;
            Apply8037DelegationRefunds(spec, in intrinsicGas, ref gasAvailable, ref delegationRefunds);

            if (!(result = BuildExecutionEnvironment(tx, spec, _codeInfoRepository, accessTracker, out ExecutionEnvironment e))) return result;
            using ExecutionEnvironment env = e;

            int statusCode = !tracer.IsTracingInstructions ?
                ExecuteEvmCall<OffFlag>(tx, header, spec, tracer, opts, delegationRefunds, intrinsicGas, accessTracker, gasAvailable, env, out TransactionSubstate substate, out GasConsumed spentGas) :
                ExecuteEvmCall<OnFlag>(tx, header, spec, tracer, opts, delegationRefunds, intrinsicGas, accessTracker, gasAvailable, env, out substate, out spentGas);

            PayFees(tx, header, spec, tracer, in substate, spentGas.SpentGas, premiumPerGas, blobBaseFee, statusCode);

            // EIP-8037+EIP-7708: process destroy list after PayFees so burn logs include
            // the priority fee in the destroyed account's balance.
            if (spec.IsEip8037Enabled && spec.IsEip7708Enabled && statusCode == StatusCode.Success)
            {
                JournalSet<Address> destroyList = substate.DestroyList;
                if (destroyList.Count > 1)
                {
                    Address[] orderedDestroyList = [.. destroyList];
                    Array.Sort(orderedDestroyList, GenericComparer.GetOptimized<Address>());
                    for (int i = 0; i < orderedDestroyList.Length; i++)
                    {
                        FinalizeDestroyedAccount(WorldState, in substate, orderedDestroyList[i]);
                    }
                }
                else
                {
                    foreach (Address toBeDestroyed in destroyList)
                    {
                        FinalizeDestroyedAccount(WorldState, in substate, toBeDestroyed);
                    }
                }

                static void FinalizeDestroyedAccount(IWorldState worldState, in TransactionSubstate substate, Address toBeDestroyed)
                {
                    UInt256 balance = worldState.GetBalance(toBeDestroyed);
                    if (!balance.IsZero)
                    {
                        substate.Logs.Add(TransferLog.CreateBurn(toBeDestroyed, balance));
                    }

                    worldState.ClearStorage(toBeDestroyed);
                    worldState.DeleteAccount(toBeDestroyed);
                }
            }

            if (!opts.HasFlag(ExecutionOptions.Warmup))
            {
                tx.BlockGasUsed = spentGas.EffectiveBlockGas;
            }

            if (!opts.HasFlag(ExecutionOptions.SkipValidation))
            {
                _blockCumulativeReceiptGas += spentGas.SpentGas;
            }

            //only main thread updates transaction
            if (!opts.HasFlag(ExecutionOptions.Warmup))
                tx.SpentGas = spentGas.SpentGas;

            // Finalize
            if (restore)
            {
                WorldState.Reset(resetBlockChanges: false);
                if (deleteCallerAccount)
                {
                    WorldState.DeleteAccount(tx.SenderAddress!);
                }
                else
                {
                    if (!senderReservedGasPayment.IsZero)
                    {
                        WorldState.AddToBalance(tx.SenderAddress!, senderReservedGasPayment, spec);
                    }

                    DecrementNonce(tx);

                    WorldState.Commit(spec, commitRoots: false);
                }
            }
            else if (commit)
            {
                WorldState.Commit(spec, tracer.IsTracingState ? tracer : NullStateTracer.Instance, commitRoots: !spec.IsEip658Enabled);
            }
            else
            {
                WorldState.ResetTransient();
            }

            if (tracer.IsTracingReceipt)
            {
                Hash256 stateRoot = null;
                if (!spec.IsEip658Enabled)
                {
                    WorldState.RecalculateStateRoot();
                    stateRoot = WorldState.StateRoot;
                }

                if (statusCode == StatusCode.Failure)
                {
                    byte[] output = substate.ShouldRevert ? substate.Output.ToArray() : [];
                    tracer.MarkAsFailed(env.ExecutingAccount, spentGas, output, substate.Error, stateRoot);
                }
                else
                {
                    LogEntry[] logs = substate.Logs.Count != 0 ? substate.Logs.ToArray() : [];
                    tracer.MarkAsSuccess(env.ExecutingAccount, spentGas, substate.Output.ToArray(), logs, stateRoot);
                }
            }

            return substate.EvmExceptionType != EvmExceptionType.None
                ? TransactionResult.EvmException(substate.EvmExceptionType, substate.SubstateError)
                : TransactionResult.Ok;
        }

        protected virtual TransactionResult CalculateAvailableGas(Transaction tx, IReleaseSpec spec, in IntrinsicGas<TGasPolicy> intrinsicGas, out TGasPolicy gasAvailable)
        {
            gasAvailable = TGasPolicy.CreateAvailableFromIntrinsic(tx.GasLimit, intrinsicGas.Standard, spec);
            return TransactionResult.Ok;
        }

        private static void Apply8037DelegationRefunds(IReleaseSpec spec, in IntrinsicGas<TGasPolicy> intrinsicGas, ref TGasPolicy gasAvailable, ref int delegationRefunds)
        {
            if (spec.IsEip8037Enabled && delegationRefunds > 0)
            {
                TGasPolicy intrinsicGasStandard = intrinsicGas.Standard;
                long stateGasFloor = TGasPolicy.GetStateReservoir(in intrinsicGasStandard);
                TGasPolicy.ApplyCodeInsertRefunds(ref gasAvailable, delegationRefunds, spec, stateGasFloor);
                delegationRefunds = 0;
            }
        }

        [MethodImpl(MethodImplOptions.NoInlining)]
        private int ProcessDelegations(Transaction tx, IReleaseSpec spec, in StackAccessTracker accessTracker)
        {
            Debug.Assert(spec.IsEip7702Enabled && tx.HasAuthorizationList);

            int refunds = 0;
            foreach (AuthorizationTuple authTuple in tx.AuthorizationList)
            {
                Address authority = (authTuple.Authority ??= Ecdsa.RecoverAddress(authTuple))!;

                AuthorizationTupleResult authorizationResult = IsValidForExecution(authTuple, accessTracker, spec, out string? error);
                if (authorizationResult != AuthorizationTupleResult.Valid)
                {
                    if (Logger.IsDebug) Logger.Debug($"Delegation {authTuple} is invalid with error: {error}");
                }
                else
                {
                    if (!WorldState.AccountExists(authority))
                    {
                        WorldState.CreateAccount(authority, 0, 1);
                    }
                    else
                    {
                        refunds++;
                        WorldState.IncrementNonce(authority);
                    }

                    _codeInfoRepository.SetDelegation(authTuple.CodeAddress, authority, spec);
                }
            }

            return refunds;
        }

        private enum AuthorizationTupleResult
        {
            Valid,
            IncorrectNonce,
            InvalidNonce,
            InvalidChainId,
            InvalidSignature,
            InvalidAsCodeDeployed
        }

        private AuthorizationTupleResult IsValidForExecution(
            AuthorizationTuple authorizationTuple,
            in StackAccessTracker accessTracker,
            IReleaseSpec spec,
            [NotNullWhen(false)] out string? error)
        {
            if (authorizationTuple.ChainId != 0 && SpecProvider.ChainId != authorizationTuple.ChainId)
            {
                error = $"Chain id ({authorizationTuple.ChainId}) does not match.";
                return AuthorizationTupleResult.InvalidChainId;
            }

            if (authorizationTuple.Nonce == ulong.MaxValue)
            {
                error = $"Nonce ({authorizationTuple.Nonce}) must be less than 2**64 - 1.";
                return AuthorizationTupleResult.InvalidNonce;
            }

            UInt256 s = new(authorizationTuple.AuthoritySignature.SAsSpan, isBigEndian: true);
            if (authorizationTuple.Authority is null
                || s > SecP256k1Curve.HalfN
                //V minus the offset can only be 1 or 0 since eip-155 does not apply to Setcode signatures
                || authorizationTuple.AuthoritySignature.V - Signature.VOffset > 1)
            {
                error = "Bad signature.";
                return AuthorizationTupleResult.InvalidSignature;
            }

            accessTracker.WarmUp(authorizationTuple.Authority);

            if (WorldState.HasCode(authorizationTuple.Authority) && !_codeInfoRepository.TryGetDelegation(authorizationTuple.Authority, spec, out _))
            {
                error = $"Authority ({authorizationTuple.Authority}) has code deployed.";
                return AuthorizationTupleResult.InvalidAsCodeDeployed;
            }

            UInt256 authNonce = WorldState.GetNonce(authorizationTuple.Authority);
            if (authNonce != authorizationTuple.Nonce)
            {
                error = $"Skipping tuple in authorization_list because nonce is set to {authorizationTuple.Nonce}, but authority ({authorizationTuple.Authority}) has {authNonce}.";
                return AuthorizationTupleResult.IncorrectNonce;
            }

            error = null;
            return AuthorizationTupleResult.Valid;
        }

        protected virtual IReleaseSpec GetSpec(BlockHeader header) => VirtualMachine.BlockExecutionContext.Spec;

        private static void UpdateMetrics(ExecutionOptions opts, UInt256 effectiveGasPrice)
        {
            if (opts is ExecutionOptions.Commit or ExecutionOptions.None or ExecutionOptions.BuildUp && (effectiveGasPrice[2] | effectiveGasPrice[3]) == 0)
            {
                float gasPrice = (float)((double)effectiveGasPrice / 1_000_000_000.0);

                Metrics.BlockMinGasPrice = Math.Min(gasPrice, Metrics.BlockMinGasPrice);
                Metrics.BlockMaxGasPrice = Math.Max(gasPrice, Metrics.BlockMaxGasPrice);

                Metrics.BlockAveGasPrice = (Metrics.BlockAveGasPrice * Metrics.BlockTransactions + gasPrice) / (Metrics.BlockTransactions + 1);
                Metrics.BlockEstMedianGasPrice += Metrics.BlockAveGasPrice * 0.01f * float.Sign(gasPrice - Metrics.BlockEstMedianGasPrice);
                Metrics.BlockTransactions++;
            }
        }

        /// <summary>
        /// Validates the transaction, in a static manner (i.e. without accessing state/storage).
        /// It basically ensures the transaction is well formed (i.e. no null values where not allowed, no overflows, etc).
        /// As a part of validating the transaction the premium per gas will be calculated, to save computation this
        /// is returned in an out parameter.
        /// </summary>
        /// <param name="tx">The transaction to validate</param>
        /// <param name="header">The block containing the transaction. Only BaseFee is being used from the block atm.</param>
        /// <param name="spec">The release spec with which the transaction will be executed</param>
        /// <param name="opts">Options (Flags) to use for execution</param>
        /// <param name="intrinsicGas">Calculated intrinsic gas</param>
        /// <returns></returns>
        protected virtual TransactionResult ValidateStatic(
            Transaction tx,
            BlockHeader header,
            IReleaseSpec spec,
            ExecutionOptions opts,
            in IntrinsicGas<TGasPolicy> intrinsicGas)
        {

            bool validate = !opts.HasFlag(ExecutionOptions.SkipValidation);

            if (tx.SenderAddress is null)
            {
                TraceLogInvalidTx(tx, "SENDER_NOT_SPECIFIED");
                return TransactionResult.SenderNotSpecified;
            }

            if (validate && tx.Nonce >= ulong.MaxValue - 1)
            {
                // we are here if nonce is at least (ulong.MaxValue - 1). If tx is contract creation,
                // it is max possible value. Otherwise, (ulong.MaxValue - 1) is allowed, but ulong.MaxValue not.
                if (tx.IsContractCreation || tx.Nonce == ulong.MaxValue)
                {
                    TraceLogInvalidTx(tx, "NONCE_OVERFLOW");
                    return TransactionResult.NonceOverflow;
                }
            }

            if (tx.IsAboveInitCode(spec))
            {
                TraceLogInvalidTx(tx, $"CREATE_TRANSACTION_SIZE_EXCEEDS_MAX_INIT_CODE_SIZE {tx.DataLength} > {spec.MaxInitCodeSize}");
                return TransactionResult.TransactionSizeOverMaxInitCodeSize;
            }

            TGasPolicy standard = intrinsicGas.Standard;
            TGasPolicy minimal = intrinsicGas.MinimalGas;
            long minGasRequired = spec.IsEip8037Enabled
                ? Math.Max(TGasPolicy.GetRemainingGas(in standard) + TGasPolicy.GetStateReservoir(in standard), TGasPolicy.GetRemainingGas(in minimal))
                : TGasPolicy.GetRemainingGas(in minimal);

            return ValidateGas(tx, header, spec, in standard, minGasRequired, validate);
        }

        protected virtual TransactionResult ValidateGas(Transaction tx, BlockHeader header, IReleaseSpec spec, in TGasPolicy intrinsicGas, long minGasRequired, bool validate)
        {
            if (tx.GasLimit < minGasRequired)
            {
                TraceLogInvalidTx(tx, $"GAS_LIMIT_BELOW_INTRINSIC_GAS {tx.GasLimit} < {minGasRequired}");
                return TransactionResult.ErrorType.GasLimitBelowIntrinsicGas.WithDetail(
                    $"intrinsic gas too low: have {tx.GasLimit}, want {minGasRequired}");
            }

            if (validate)
            {
                if (spec.IsEip8037Enabled)
                {
                    if (tx.GasLimit > header.GasLimit)
                    {
                        TraceLogInvalidTx(tx, $"BLOCK_GAS_LIMIT_EXCEEDED {tx.GasLimit} > {header.GasLimit}");
                        return TransactionResult.BlockGasLimitExceeded;
                    }

                    // Per-block EIP-8037 inclusion depends on cumulative regular/state gas,
                    // so block validation performs the 2D check in BlockAccessListManager
                    // where those accumulators are available. Direct Execute/BuildUp/estimator
                    // callers can only validate the tx-local allowance here.
                    return TransactionResult.Ok;
                }

                long gasUsedForAllowance = _parallel ? 0 : spec switch
                {
                    { IsEip7778Enabled: true } => _blockCumulativeReceiptGas,
                    _ => header.GasUsed,
                };

                long maxTransactionGasLimit = header.GasLimit - gasUsedForAllowance;
                if (tx.GasLimit > maxTransactionGasLimit)
                {
                    string limitDescription = _parallel
                        ? $"{header.GasLimit}"
                        : $"{header.GasLimit} - {gasUsedForAllowance}";
                    TraceLogInvalidTx(tx, $"BLOCK_GAS_LIMIT_EXCEEDED {tx.GasLimit} > {limitDescription}");
                    return TransactionResult.BlockGasLimitExceeded;
                }
            }

            return TransactionResult.Ok;
        }

        protected virtual bool RecoverSenderIfNeeded(Transaction tx, IReleaseSpec spec, ExecutionOptions opts, in UInt256 effectiveGasPrice)
        {
            bool deleteCallerAccount = false;
            Address? sender = tx.SenderAddress;
            if (sender is null || !WorldState.AccountExists(sender))
            {
                bool commit = opts.HasFlag(ExecutionOptions.Commit) || !spec.IsEip658Enabled;
                bool restore = opts.HasFlag(ExecutionOptions.Restore);
                bool noValidation = opts.HasFlag(ExecutionOptions.SkipValidation);

                if (Logger.IsDebug) Logger.Debug($"TX sender account does not exist {sender} - trying to recover it");

                // hacky fix for the potential recovery issue
                if (tx.Signature is not null)
                    tx.SenderAddress = Ecdsa.RecoverAddress(tx, !spec.ValidateChainId);

                if (sender != tx.SenderAddress)
                {
                    if (Logger.IsWarn) Logger.Warn($"TX recovery issue fixed - tx was coming with sender {sender} and the now it recovers to {tx.SenderAddress}");
                    sender = tx.SenderAddress;
                }
                else
                {
                    TraceLogInvalidTx(tx, $"SENDER_ACCOUNT_DOES_NOT_EXIST {sender}");
                    if (!commit || noValidation || effectiveGasPrice.IsZero)
                    {
                        deleteCallerAccount = !commit || restore;
                        WorldState.CreateAccount(sender!, in UInt256.Zero);
                    }
                }

                if (sender is null)
                {
                    ThrowInvalidDataException($"Failed to recover sender address on tx {tx.Hash} when previously recovered sender account did not exist.");
                }
            }

            return deleteCallerAccount;
        }

        protected virtual IntrinsicGas<TGasPolicy> CalculateIntrinsicGas(Transaction tx, IReleaseSpec spec, long blockGasLimit)
            => TGasPolicy.CalculateIntrinsicGas(tx, spec, blockGasLimit);

        protected virtual UInt256 CalculateEffectiveGasPrice(Transaction tx, bool eip1559Enabled, in UInt256 baseFee, out UInt256 opcodeGasPrice)
        {
            opcodeGasPrice = tx.CalculateEffectiveGasPrice(eip1559Enabled, in baseFee);
            return opcodeGasPrice;
        }

        protected virtual bool TryCalculatePremiumPerGas(Transaction tx, in UInt256 baseFee, out UInt256 premiumPerGas) =>
            tx.TryCalculatePremiumPerGas(baseFee, out premiumPerGas);

        protected virtual TransactionResult ValidateSender(Transaction tx, BlockHeader header, IReleaseSpec spec, ITxTracer tracer, ExecutionOptions opts)
        {
            bool validate = !opts.HasFlag(ExecutionOptions.SkipValidation);

            if (validate && WorldState.IsInvalidContractSender(spec, tx.SenderAddress!))
            {
                TraceLogInvalidTx(tx, "SENDER_IS_CONTRACT");
                return TransactionResult.SenderHasDeployedCode;
            }

            return TransactionResult.Ok;
        }

        protected static bool ShouldValidateGas(Transaction tx, ExecutionOptions opts)
            => !opts.HasFlag(ExecutionOptions.SkipValidation) || !tx.MaxFeePerGas.IsZero || !tx.MaxPriorityFeePerGas.IsZero;

        protected virtual TransactionResult BuyGas(Transaction tx, IReleaseSpec spec, ITxTracer tracer, ExecutionOptions opts,
                in UInt256 effectiveGasPrice, out UInt256 premiumPerGas, out UInt256 senderReservedGasPayment, out UInt256 blobBaseFee)
        {
            premiumPerGas = UInt256.Zero;
            senderReservedGasPayment = UInt256.Zero;
            blobBaseFee = UInt256.Zero;
            bool validate = ShouldValidateGas(tx, opts);

            BlockHeader header = VirtualMachine.BlockExecutionContext.Header;
            if (validate && !TryCalculatePremiumPerGas(tx, header.BaseFeePerGas, out premiumPerGas))
            {
                TraceLogInvalidTx(tx, "MINER_PREMIUM_IS_NEGATIVE");
                string errorDetail = $"max fee per gas less than block base fee: address {tx.SenderAddress?.ToString(withEip55Checksum: true) ?? "unknown"}, maxFeePerGas: {tx.MaxFeePerGas}, baseFee: {header.BaseFeePerGas}";
                return TransactionResult.ErrorType.MaxFeePerGasBelowBaseFee.WithDetail(errorDetail);
            }

            UInt256 senderBalance = WorldState.GetBalance(tx.SenderAddress!);
            if (UInt256.SubtractUnderflow(in senderBalance, in tx.ValueRef, out UInt256 balanceLeft))
            {
                TraceLogInvalidTx(tx, $"INSUFFICIENT_SENDER_BALANCE: ({tx.SenderAddress})_BALANCE = {senderBalance}");
                return InsufficientFundsForTransfer(tx, senderBalance);
            }

            bool overflows;
            if (spec.IsEip1559Enabled && !tx.IsFree())
            {
                overflows = UInt256.MultiplyOverflow((UInt256)tx.GasLimit, tx.MaxFeePerGas, out UInt256 maxGasFee);
                if (overflows || balanceLeft < maxGasFee)
                {
                    TraceLogInvalidTx(tx, $"INSUFFICIENT_MAX_FEE_PER_GAS_FOR_SENDER_BALANCE: ({tx.SenderAddress})_BALANCE = {senderBalance}, MAX_FEE_PER_GAS: {tx.MaxFeePerGas}");
                    return InsufficientFundsForGas(tx, senderBalance, tx.MaxFeePerGas);
                }

                if (tx.SupportsBlobs)
                {
                    overflows = UInt256.MultiplyOverflow(BlobGasCalculator.CalculateBlobGas(tx), (UInt256)tx.MaxFeePerBlobGas!, out UInt256 maxBlobGasFee);
                    if (overflows || UInt256.AddOverflow(maxGasFee, maxBlobGasFee, out UInt256 multidimGasFee) || multidimGasFee > balanceLeft)
                    {
                        TraceLogInvalidTx(tx, $"INSUFFICIENT_MAX_FEE_PER_BLOB_GAS_FOR_SENDER_BALANCE: ({tx.SenderAddress})_BALANCE = {senderBalance}");
                        return InsufficientFundsForGas(tx, senderBalance, effectiveGasPrice);
                    }
                }
            }

            overflows = UInt256.MultiplyOverflow((UInt256)tx.GasLimit, effectiveGasPrice, out senderReservedGasPayment);
            if (!overflows && tx.SupportsBlobs)
            {
                if (validate)
                {
                    if (!BlobGasCalculator.TryCalculateFeePerBlobGas(header, spec.BlobBaseFeeUpdateFraction, out UInt256 feePerBlobGas))
                    {
                        overflows = true;
                    }
                    else if (tx.MaxFeePerBlobGas < feePerBlobGas)
                    {
                        TraceLogInvalidTx(tx, "INSUFFICIENT_MAX_FEE_PER_BLOB_GAS");
                        return TransactionResult.WithDetail(TransactionResult.ErrorType.InsufficientSenderBalance, BlockErrorMessages.InsufficientMaxFeePerBlobGas);
                    }
                }

                if (!overflows)
                {
                    overflows = !_blobBaseFeeCalculator.TryCalculateBlobBaseFee(header, tx, spec.BlobBaseFeeUpdateFraction, out blobBaseFee);
                    if (!overflows)
                    {
                        overflows = UInt256.AddOverflow(senderReservedGasPayment, blobBaseFee, out senderReservedGasPayment);
                    }
                }
            }

            if (overflows || senderReservedGasPayment > balanceLeft)
            {
                TraceLogInvalidTx(tx, $"INSUFFICIENT_SENDER_BALANCE: ({tx.SenderAddress})_BALANCE = {senderBalance}");
                return InsufficientFundsForGas(tx, senderBalance, effectiveGasPrice);
            }

            if (!senderReservedGasPayment.IsZero) WorldState.SubtractFromBalance(tx.SenderAddress, senderReservedGasPayment, spec);

            return TransactionResult.Ok;
        }

        private static TransactionResult InsufficientFundsForTransfer(Transaction tx, UInt256 senderBalance) =>
            TransactionResult.ErrorType.InsufficientSenderBalance.WithDetail(
                $"insufficient funds for transfer: address {tx.SenderAddress?.ToString(withEip55Checksum: true)} have {senderBalance} want {tx.Value}");

        private static TransactionResult InsufficientFundsForGas(Transaction tx, UInt256 senderBalance, UInt256 gasPrice)
        {
            UInt256.MultiplyOverflow((UInt256)tx.GasLimit, gasPrice, out UInt256 gasCost);
            UInt256.AddOverflow(gasCost, tx.Value, out UInt256 want);
            return TransactionResult.ErrorType.InsufficientMaxFeePerGasForSenderBalance.WithDetail(
                $"insufficient sender balance for gas * price + value: address {tx.SenderAddress?.ToString(withEip55Checksum: true)} have {senderBalance} want {want}");
        }

        protected virtual TransactionResult IncrementNonce(Transaction tx, BlockHeader header, IReleaseSpec spec, ITxTracer tracer, ExecutionOptions opts)
        {
            bool validate = !opts.HasFlag(ExecutionOptions.SkipValidation);
            UInt256 nonce = WorldState.GetNonce(tx.SenderAddress!);
            if (validate && tx.Nonce != nonce)
            {
                TraceLogInvalidTx(tx, $"WRONG_TRANSACTION_NONCE: {tx.Nonce} (expected {nonce})");
                // Geth core/state_transition.go ErrNonceTooHigh / ErrNonceTooLow.
                string sender = tx.SenderAddress?.ToString(withEip55Checksum: true) ?? "unknown";
                return tx.Nonce > nonce
                    ? TransactionResult.ErrorType.TransactionNonceTooHigh.WithDetail(
                        $"nonce too high: address {sender}, tx: {tx.Nonce} state: {nonce}")
                    : TransactionResult.ErrorType.TransactionNonceTooLow.WithDetail(
                        $"nonce too low: address {sender}, tx: {tx.Nonce} state: {nonce}");
            }

            UInt256 newNonce = validate || nonce < ulong.MaxValue ? nonce + 1 : 0;
            WorldState.SetNonce(tx.SenderAddress, newNonce);

            return TransactionResult.Ok;
        }

        protected virtual void DecrementNonce(Transaction tx) => WorldState.DecrementNonce(tx.SenderAddress!);

        [SkipLocalsInit]
        private TransactionResult BuildExecutionEnvironment(
            Transaction tx,
            IReleaseSpec spec,
            ICodeInfoRepository codeInfoRepository,
            in StackAccessTracker accessTracker,
            out ExecutionEnvironment env)
        {
            Address recipient = tx.GetRecipient(tx.IsContractCreation ? WorldState.GetNonce(tx.SenderAddress!) : 0);
            if (recipient is null) ThrowInvalidDataException("Recipient has not been resolved properly before tx execution");
            CodeInfo? codeInfo;
            ReadOnlyMemory<byte> inputData = tx.IsMessageCall ? tx.Data : default;
            if (tx.IsContractCreation)
            {
                codeInfo = CodeInfoFactory.CreateCodeInfo(tx.Data);
            }
            else
            {
                codeInfo = codeInfoRepository.GetCachedCodeInfo(recipient, spec, out Address? delegationAddress);

                //We assume eip-7702 must be active if it is a delegation
                if (delegationAddress is not null)
                    accessTracker.WarmUp(delegationAddress);
            }

            if (spec.UseHotAndColdStorage)
            {
                if (spec.UseTxAccessLists)
                    accessTracker.WarmUp(tx.AccessList); // eip-2930

                if (spec.AddCoinbaseToTxAccessList)
                    accessTracker.WarmUp(VirtualMachine.BlockExecutionContext.Header.GasBeneficiary!);

                accessTracker.WarmUp(recipient);
                accessTracker.WarmUp(tx.SenderAddress!);
            }

            env = ExecutionEnvironment.Rent(
                codeInfo: codeInfo,
                executingAccount: recipient,
                caller: tx.SenderAddress!,
                codeSource: recipient,
                callDepth: 0,
                transferValue: in tx.ValueRef,
                value: in tx.ValueRef,
                inputData: in inputData);

            return TransactionResult.Ok;
        }

        protected virtual bool ShouldValidate(ExecutionOptions opts) => !opts.HasFlag(ExecutionOptions.SkipValidation);

        private int ExecuteEvmCall<TTracingInst>(
            Transaction tx,
            BlockHeader header,
            IReleaseSpec spec,
            ITxTracer tracer,
            ExecutionOptions opts,
            int delegationRefunds,
            IntrinsicGas<TGasPolicy> gas,
            in StackAccessTracker accessedItems,
            TGasPolicy gasAvailable,
            ExecutionEnvironment env,
            out TransactionSubstate substate,
            out GasConsumed gasConsumed)
            where TTracingInst : struct, IFlag
        {
            substate = default;
            gasConsumed = tx.GasLimit;
            byte statusCode = StatusCode.Failure;
            long selfDestructStateRefund = 0;

            // EIP-7702 + EIP-8037: capture the tx-start state reservoir (post-Apply8037DelegationRefunds).
            // The halt path needs this to correctly initialize the reservoir in ResetForHalt; the
            // intrinsicGasStandard-based formula misses the auth refund and would charge the sender
            // for unconsumed reservoir gas (1x AccountCreationCost = 131,488 per valid auth on
            // existing account).
            long postIntrinsicStateReservoir = TGasPolicy.GetStateReservoir(in gasAvailable);

            Snapshot snapshot = WorldState.TakeSnapshot();
            long floorGasLong = TGasPolicy.GetRemainingGas(gas.FloorGas);

            PayValue(tx, spec, opts);

            if (env.CodeInfo is not null)
            {
                if (tx.IsContractCreation)
                {
                    // if transaction is a contract creation then recipient address is the contract deployment address
                    if (!PrepareDeployment(env.ExecutingAccount))
                    {
                        if (Logger.IsTrace) Logger.Trace("Restoring state from before transaction");
                        WorldState.Restore(snapshot);
                        TGasPolicy collisionIntrinsicGasStandard = gas.Standard;
                        gasConsumed = RefundOnContractCollision(
                            tx,
                            spec,
                            opts,
                            in gasAvailable,
                            VirtualMachine.TxExecutionContext.GasPrice,
                            in collisionIntrinsicGasStandard,
                            floorGasLong);
                        goto Complete;
                    }
                }
            }
            else
            {
                // Gas for initcode execution is not consumed, only intrinsic creation transaction costs are charged.
                long minimalGasLong = TGasPolicy.GetRemainingGas(gas.MinimalGas);
                gasConsumed = minimalGasLong;
                // If noValidation we didn't charge for gas, so do not refund; otherwise return unspent gas
                if (!opts.HasFlag(ExecutionOptions.SkipValidation))
                    WorldState.AddToBalance(tx.SenderAddress!, (ulong)(tx.GasLimit - minimalGasLong) * VirtualMachine.TxExecutionContext.GasPrice, spec);
                goto Complete;
            }

            ExecutionType executionType = tx.IsContractCreation ? ExecutionType.CREATE : ExecutionType.TRANSACTION;

            using (VmState<TGasPolicy> state = VmState<TGasPolicy>.RentTopLevel(gasAvailable, executionType, env, in accessedItems, in snapshot))
            {
                substate = !TTracingInst.IsActive
                    ? VirtualMachine.ExecuteTransaction(state, WorldState, tracer) // no GVM trick for ZK
                    : VirtualMachine.ExecuteTransaction<OnFlag>(state, WorldState, tracer);

                Metrics.IncrementOpCodes(VirtualMachine.OpCodeCount);
                gasAvailable = state.Gas;

                if (tracer.IsTracingAccess)
                {
                    tracer.ReportAccess(accessedItems.AccessedAddresses, accessedItems.AccessedStorageCells);
                }

                if (substate.ShouldRevert || substate.IsError)
                {
                    if (Logger.IsTrace) Logger.Trace("Restoring state from before transaction");
                    WorldState.Restore(snapshot);
                }
                else
                {
                    if (tx.IsContractCreation)
                    {
                        if (!DeployContract(spec, env.ExecutingAccount, in substate, in accessedItems, ref gasAvailable))
                        {
                            goto FailContractCreate;
                        }
                    }

                    selfDestructStateRefund = CalculateSelfDestructStateRefund(spec, in substate, in accessedItems, in gasAvailable);

                    // EIP-8037: defer destroy list processing to after PayFees so that
                    // burn logs include the priority fee in the balance.
                    bool deferFinalization = spec.IsEip7708Enabled && spec.IsEip8037Enabled;
                    if (!deferFinalization)
                    {
                        bool eip7708Enabled = spec.IsEip7708Enabled;
                        bool tracingRefunds = tracer.IsTracingRefunds;
                        foreach (Address toBeDestroyed in substate.DestroyList)
                        {
                            if (Logger.IsTrace) Logger.Trace($"Destroying account {toBeDestroyed}");

                            if (eip7708Enabled)
                            {
                                UInt256 balance = WorldState.GetBalance(toBeDestroyed);
                                if (!balance.IsZero)
                                {
                                    substate.Logs.Add(TransferLog.CreateSelfDestruct(toBeDestroyed, balance));
                                }
                            }

                            WorldState.ClearStorage(toBeDestroyed);
                            WorldState.DeleteAccount(toBeDestroyed);

                            if (tracingRefunds)
                            {
                                tracer.ReportRefund(spec.GasCosts.DestroyRefund);
                            }
                        }
                    }

                    statusCode = StatusCode.Success;
                }
            }

            gasConsumed = Refund(tx, header, spec, opts, in substate, gasAvailable, VirtualMachine.TxExecutionContext.GasPrice, delegationRefunds, selfDestructStateRefund, gas.FloorGas, gas.Standard, postIntrinsicStateReservoir);
            goto Complete;
        FailContractCreate:
            if (Logger.IsTrace) Logger.Trace("Restoring state from before transaction");
            if (spec.ChargeForTopLevelCreate)
            {
                TGasPolicy.SetOutOfGas(ref gasAvailable);
            }
            WorldState.Restore(snapshot);
            TGasPolicy intrinsicGasStandard = gas.Standard;
            if (spec.IsEip8037Enabled)
            {
                // Use postIntrinsicStateReservoir captured before EVM execution so any
                // EIP-7702 auth refund applied via Apply8037DelegationRefunds is preserved
                // (otherwise the sender pays AccountCreationCost per refunded auth even
                // though no account was created).
                gasConsumed = CompleteEip8037Halt(tx, spec, opts, ref gasAvailable, VirtualMachine.TxExecutionContext.GasPrice, in intrinsicGasStandard, floorGasLong, postIntrinsicStateReservoir);
            }
            else
            {
                gasConsumed = RefundOnFail(tx, spec, opts, in gasAvailable, VirtualMachine.TxExecutionContext.GasPrice, in intrinsicGasStandard, floorGasLong);
            }
        Complete:
            if (!opts.HasFlag(ExecutionOptions.SkipValidation) && !_parallel)
            {
                header.GasUsed += gasConsumed.EffectiveBlockGas;
            }

            return statusCode;
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        static void RefundRevertedExecutionStateGas(IReleaseSpec spec, in TGasPolicy intrinsicGas, ref TGasPolicy gas)
        {
            if (!spec.IsEip8037Enabled)
            {
                return;
            }

            long stateGasFloor = TGasPolicy.GetStateReservoir(in intrinsicGas);
            long revertedStateGas = TGasPolicy.GetStateGasUsed(in gas);
            if (revertedStateGas > stateGasFloor)
            {
                TGasPolicy.RefundStateGas(ref gas, revertedStateGas, stateGasFloor);
            }
        }

        // Common EIP-8037 halt-prepare-then-restore sequence shared by FailContractCreate
        // and the substate.IsError branch of Refund. AggressiveInlining keeps codegen
        // identical to the prior inline form on both hot paths.
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        private GasConsumed CompleteEip8037Halt(
            Transaction tx,
            IReleaseSpec spec,
            ExecutionOptions opts,
            ref TGasPolicy gas,
            in UInt256 gasPrice,
            in TGasPolicy intrinsicGasStandard,
            long floorGas,
            long postIntrinsicStateReservoir)
        {
            RefundRevertedExecutionStateGas(spec, in intrinsicGasStandard, ref gas);
            long refundedCreateStateSpillForHalt = CalculateRefundedCreateStateSpillForHalt(in gas);
            long intrinsicStateGas = TGasPolicy.GetStateReservoir(in intrinsicGasStandard);
            TGasPolicy.ResetForHalt(ref gas, postIntrinsicStateReservoir, intrinsicStateGas);
            return RefundOnTopLevelHalt(tx, spec, opts, in gas, in gasPrice, in intrinsicGasStandard, floorGas, refundedCreateStateSpillForHalt);
        }

        protected virtual GasConsumed RefundOnFail(
            Transaction tx,
            IReleaseSpec spec,
            ExecutionOptions opts,
            in TGasPolicy gas,
            in UInt256 gasPrice,
            in TGasPolicy intrinsicGasStandard,
            long floorGas = 0)
        {
            if (!spec.IsEip8037Enabled)
                return tx.GasLimit;

            long remainingRegularGas = TGasPolicy.GetRemainingGas(in gas);
            long stateReservoir = TGasPolicy.GetStateReservoir(in gas);
            long spentGas = Math.Max(tx.GasLimit - remainingRegularGas - stateReservoir, floorGas);
            long blockGas = Calculate8037BlockRegularGas(in gas, in intrinsicGasStandard, tx.GasLimit, floorGas, remainingRegularGas);
            long blockStateGas = TGasPolicy.GetStateGasUsed(in gas);

            return RefundFailedEip8037Gas(tx, spec, opts, in gasPrice, spentGas, blockGas, blockStateGas);
        }

        protected virtual GasConsumed RefundOnContractCollision(
            Transaction tx,
            IReleaseSpec spec,
            ExecutionOptions opts,
            in TGasPolicy gas,
            in UInt256 gasPrice,
            in TGasPolicy intrinsicGasStandard,
            long floorGas)
        {
            if (!spec.IsEip8037Enabled)
                return tx.GasLimit;

            long remainingRegularGas = TGasPolicy.GetRemainingGas(in gas);
            long blockGas = Calculate8037BlockRegularGas(in gas, in intrinsicGasStandard, tx.GasLimit, floorGas, remainingRegularGas);
            long blockStateGas = TGasPolicy.GetStateGasUsed(in gas);

            return RefundFailedEip8037Gas(tx, spec, opts, in gasPrice, tx.GasLimit, blockGas, blockStateGas);
        }

        private GasConsumed RefundOnTopLevelHalt(
            Transaction tx,
            IReleaseSpec spec,
            ExecutionOptions opts,
            in TGasPolicy gas,
            in UInt256 gasPrice,
            in TGasPolicy intrinsicGasStandard,
            long floorGas,
            long refundedCreateStateSpillForHalt)
        {
            if (!spec.IsEip8037Enabled)
                return tx.GasLimit;

            long stateReservoir = TGasPolicy.GetStateReservoir(in gas);
            long spentGas = Math.Max(tx.GasLimit - stateReservoir, floorGas);
            long intrinsicStateGas = TGasPolicy.GetStateReservoir(in intrinsicGasStandard);
            long initialReservoir = Math.Max(0, tx.GasLimit - intrinsicStateGas - Eip7825Constants.DefaultTxGasLimitCap);
            long spillBurned = TGasPolicy.GetStateGasSpillBurned(in gas);
            long effectiveStateGas = Math.Max(0, intrinsicStateGas - spillBurned) + refundedCreateStateSpillForHalt;
            long blockGas = Math.Max(tx.GasLimit - effectiveStateGas - initialReservoir, floorGas);

            return RefundFailedEip8037Gas(tx, spec, opts, in gasPrice, spentGas, blockGas, effectiveStateGas);
        }

        private GasConsumed RefundFailedEip8037Gas(
            Transaction tx,
            IReleaseSpec spec,
            ExecutionOptions opts,
            in UInt256 gasPrice,
            long spentGas,
            long blockGas,
            long blockStateGas)
        {
            if (ShouldRefundGas(tx, opts, in gasPrice) && spentGas < tx.GasLimit)
                PayRefund(tx, (ulong)(tx.GasLimit - spentGas) * gasPrice, spec);

            return new GasConsumed(spentGas, spentGas, blockGas, blockStateGas, spentGas);
        }

        protected virtual bool DeployContract(IReleaseSpec spec, Address codeOwner, in TransactionSubstate substate, in StackAccessTracker accessedItems, ref TGasPolicy unspentGas)
        {
            if (!CodeDepositHandler.CalculateCost(spec, substate.Output.Length, in unspentGas, out long regularDepositCost, out long stateDepositCost))
                return false;

            if (CodeDepositHandler.CodeIsInvalid(spec, substate.Output))
                return false;

            // Copy the bytes so it's not live memory that will be used in another tx.
            return TryChargeCodeDeposit(spec, codeOwner, in accessedItems, ref unspentGas, regularDepositCost, stateDepositCost, substate.Output.ToArray());
        }

        private bool TryChargeCodeDeposit(
            IReleaseSpec spec,
            Address codeOwner,
            in StackAccessTracker accessedItems,
            ref TGasPolicy unspentGas,
            long regularDepositCost,
            long stateDepositCost,
            byte[] code)
        {
            long remainingGas = TGasPolicy.GetRemainingGas(in unspentGas);
            bool hasEnoughGas = remainingGas >= regularDepositCost && remainingGas + TGasPolicy.GetStateReservoir(in unspentGas) >= stateDepositCost;

            if (!hasEnoughGas)
                return !spec.ChargeForTopLevelCreate;

            TGasPolicy gasAfterCodeDeposit = unspentGas;
            if (!TGasPolicy.TryConsumeStateAndRegularGas(ref gasAfterCodeDeposit, stateDepositCost, regularDepositCost))
                return false;

            _codeInfoRepository.InsertCode(code, codeOwner, spec);

            unspentGas = gasAfterCodeDeposit;
            return true;
        }

        protected virtual void PayValue(Transaction tx, IReleaseSpec spec, ExecutionOptions opts) => WorldState.SubtractFromBalance(tx.SenderAddress!, in tx.ValueRef, spec);

        protected virtual void PayFees(Transaction tx, BlockHeader header, IReleaseSpec spec, ITxTracer tracer, in TransactionSubstate substate, long spentGas, in UInt256 premiumPerGas, in UInt256 blobBaseFee, int statusCode)
        {
            UInt256 fees = premiumPerGas * (ulong)spentGas;

            // n.b. destroyed accounts already set to zero balance
            // EIP-8037: always pay coinbase — deferred finalization will burn the balance
            bool gasBeneficiaryNotDestroyed = !substate.DestroyList.Contains(header.GasBeneficiary);
            if (statusCode == StatusCode.Failure || gasBeneficiaryNotDestroyed || spec.IsEip8037Enabled)
            {
                WorldState.AddToBalanceAndCreateIfNotExists(header.GasBeneficiary!, fees, spec);
            }

            UInt256 eip1559Fees = !tx.IsFree() ? header.BaseFeePerGas * (ulong)spentGas : UInt256.Zero;
            UInt256 collectedFees = spec.IsEip1559Enabled ? eip1559Fees : UInt256.Zero;

            if (tx.SupportsBlobs && spec.IsEip4844FeeCollectorEnabled)
            {
                collectedFees += blobBaseFee;
            }

            if (spec.FeeCollector is not null && !collectedFees.IsZero)
            {
                WorldState.AddToBalanceAndCreateIfNotExists(spec.FeeCollector, collectedFees, spec);
            }

            if (tracer.IsTracingFees)
            {
                tracer.ReportFees(fees, eip1559Fees + blobBaseFee);
            }
        }

        private long CalculateSelfDestructStateRefund(
            IReleaseSpec spec,
            in TransactionSubstate substate,
            in StackAccessTracker accessedItems,
            in TGasPolicy gasAfterExecution)
        {
            if (!spec.IsEip8037Enabled || substate.ShouldRevert || substate.IsError)
                return 0;

            BlockAccessList? generatedBlockAccessList = WorldState is IBlockAccessListSource blockAccessListSource
                ? blockAccessListSource.GeneratedBlockAccessList
                : null;

            long selfDestructStateRefund = 0;
            foreach (Address toBeDestroyed in substate.DestroyList)
            {
                if (!accessedItems.CreateList.Contains(toBeDestroyed))
                    continue;

                selfDestructStateRefund = checked(selfDestructStateRefund + TGasPolicy.GetNewAccountStateCost(in gasAfterExecution));
                selfDestructStateRefund = checked(selfDestructStateRefund + TGasPolicy.GetCodeDepositStateCost(in gasAfterExecution, WorldState.GetCode(toBeDestroyed)?.Length ?? 0));
                selfDestructStateRefund = checked(selfDestructStateRefund + GetCreatedStorageStateRefund(in gasAfterExecution, generatedBlockAccessList, in accessedItems, toBeDestroyed));
            }

            return selfDestructStateRefund;
        }

        private long GetCreatedStorageStateRefund(
            in TGasPolicy gasAfterExecution,
            BlockAccessList? generatedBlockAccessList,
            in StackAccessTracker accessedItems,
            Address address)
        {
            int createdSlots = 0;
            if (generatedBlockAccessList?.GetAccountChanges(address) is { } accountChanges)
            {
                foreach (SlotChanges slotChanges in accountChanges.StorageChanges)
                {
                    if (slotChanges.Changes.Count > 0 && slotChanges.Changes.Values[^1].Value != default)
                    {
                        createdSlots++;
                    }
                }
            }
            else
            {
                // Non-BAL callers only expose the flat access tracker, so this fallback scans
                // all touched storage cells. Keep the BAL source path preferred for block
                // execution; optimize this if selfdestruct refunds become hot outside BAL.
                foreach (StorageCell storageCell in accessedItems.AccessedStorageCells)
                {
                    if (storageCell.Address == address && !WorldState.Get(in storageCell).IsZero())
                    {
                        createdSlots++;
                    }
                }
            }

            return checked((long)createdSlots * TGasPolicy.GetStorageSetStateCost(in gasAfterExecution));
        }

        protected bool PrepareDeployment(Address contractAddress)
        {
            if (!WorldState.IsNonZeroAccount(contractAddress, out _))
                return true;

            if (Logger.IsTrace) Logger.Trace($"Contract collision at {contractAddress}");
            return false;
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        protected void TraceLogInvalidTx(Transaction transaction, string reason)
        {
            if (Logger.IsTrace) Logger.Trace($"Invalid tx {transaction.Hash} ({reason})");
        }

        protected virtual GasConsumed Refund(Transaction tx, BlockHeader header, IReleaseSpec spec, ExecutionOptions opts,
            in TransactionSubstate substate, in TGasPolicy unspentGas, in UInt256 gasPrice, int codeInsertRefunds, long selfDestructStateRefund, in TGasPolicy floorGas, in TGasPolicy intrinsicGasStandard, long postIntrinsicStateReservoir)
        {
            TGasPolicy gasAfterExecution = unspentGas;
            long stateGasFloor = TGasPolicy.GetStateReservoir(in intrinsicGasStandard);
            if (selfDestructStateRefund > 0)
            {
                TGasPolicy.RefundStateGas(ref gasAfterExecution, selfDestructStateRefund, stateGasFloor);
            }

            long codeInsertRegularRefund = TGasPolicy.ApplyCodeInsertRefunds(ref gasAfterExecution, codeInsertRefunds, spec, stateGasFloor);
            long floorGasLong = TGasPolicy.GetRemainingGas(floorGas);

            if (substate.IsError && spec.IsEip8037Enabled)
            {
                // Use postIntrinsicStateReservoir captured before EVM execution so any
                // EIP-7702 auth refund applied via Apply8037DelegationRefunds is preserved
                // through the halt-reset; otherwise we'd charge the sender for unconsumed
                // auth-refund reservoir gas (1x AccountCreationCost = 131,488 per refund).
                return CompleteEip8037Halt(tx, spec, opts, ref gasAfterExecution, in gasPrice, in intrinsicGasStandard, floorGasLong, postIntrinsicStateReservoir);
            }

            (long spentGas, long refund) = CalculateSpentGasAndRefund(tx, spec, in substate, in gasAfterExecution, codeInsertRegularRefund);
            (long blockGas, long blockStateGas) = CalculateBlockGas(spec, in substate, in gasAfterExecution, in intrinsicGasStandard, spentGas, floorGasLong, tx.GasLimit);

            long operationGas = spentGas - refund;
            long spentGasAfterFloor = Math.Max(operationGas, floorGasLong);

            if (ShouldRefundGas(tx, opts, in gasPrice))
                PayRefund(tx, (ulong)(tx.GasLimit - spentGasAfterFloor) * gasPrice, spec);

            return new GasConsumed(spentGasAfterFloor, operationGas, blockGas, blockStateGas, Math.Max(spentGas, floorGasLong));
        }

        private (long spentGas, long refund) CalculateSpentGasAndRefund(
            Transaction tx,
            IReleaseSpec spec,
            in TransactionSubstate substate,
            in TGasPolicy gasAfterExecution,
            long codeInsertRegularRefund)
        {
            long spentGas = substate.IsError
                ? tx.GasLimit
                : tx.GasLimit - TGasPolicy.GetRemainingGas(in gasAfterExecution) - TGasPolicy.GetStateReservoir(in gasAfterExecution);

            long totalToRefund = codeInsertRegularRefund;
            if (!substate.IsError && !substate.ShouldRevert)
                totalToRefund += substate.Refund + substate.DestroyList.Count * spec.GasCosts.DestroyRefund;

            return (spentGas, CalculateClaimableRefund(spentGas, totalToRefund, spec));
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        private static long CalculateRefundedCreateStateSpillForHalt(in TGasPolicy gas)
        {
            long returnedSpillNotInReservoir =
                TGasPolicy.GetStateGasSpill(in gas) -
                TGasPolicy.GetStateReservoir(in gas) -
                TGasPolicy.GetStateGasSpillBurned(in gas);
            long refundedSpill = TGasPolicy.GetStateGasSpillRefunded(in gas);
            long refundedSpillNotInReservoir = Math.Min(returnedSpillNotInReservoir, refundedSpill);
            long createStateGas = TGasPolicy.GetCreateStateCost(in gas);
            if (createStateGas <= 0)
            {
                return 0;
            }

            // Only whole CREATE-state units are restored to state on halt; partial spill remains regular.
            return Math.Max(0, (refundedSpillNotInReservoir / createStateGas) * createStateGas);
        }

        private static (long blockGas, long blockStateGas) CalculateBlockGas(
            IReleaseSpec spec,
            in TransactionSubstate substate,
            in TGasPolicy gasAfterExecution,
            in TGasPolicy intrinsicGasStandard,
            long preRefundGas,
            long floorGas,
            long txGasLimit)
        {
            if (!spec.IsEip8037Enabled)
                return (spec.IsEip7778Enabled ? Math.Max(preRefundGas, floorGas) : 0, 0);

            long blockStateGas = TGasPolicy.GetStateGasUsed(in gasAfterExecution);
            long blockGas = Calculate8037BlockRegularGas(
                in gasAfterExecution,
                in intrinsicGasStandard,
                txGasLimit,
                floorGas,
                TGasPolicy.GetRemainingGas(in gasAfterExecution));

            return (blockGas, blockStateGas);
        }

        private static long Calculate8037BlockRegularGas(
            in TGasPolicy gasAfterExecution,
            in TGasPolicy intrinsicGasStandard,
            long txGasLimit,
            long floorGas,
            long remainingRegularGas)
        {
            long intrinsicRegularGas = TGasPolicy.GetRemainingGas(in intrinsicGasStandard);
            long intrinsicStateGas = TGasPolicy.GetStateReservoir(in intrinsicGasStandard);
            long initialReservoir = Math.Max(0, txGasLimit - intrinsicStateGas - Eip7825Constants.DefaultTxGasLimitCap);
            long initialRegularGas = txGasLimit - intrinsicRegularGas - intrinsicStateGas - initialReservoir;
            long stateGasSpill = TGasPolicy.GetStateGasSpill(in gasAfterExecution);
            long stateGasSpillReclassified = TGasPolicy.GetStateGasSpillReclassified(in gasAfterExecution);
            return Eip8037BlockGasInclusionCheck.CalculateBlockRegularGas(
                intrinsicRegularGas,
                initialRegularGas,
                remainingRegularGas,
                stateGasSpill,
                stateGasSpillReclassified,
                floorGas);
        }

        protected virtual void PayRefund(Transaction tx, UInt256 refundAmount, IReleaseSpec spec)
        {
            if (!refundAmount.IsZero)
                WorldState.AddToBalance(tx.SenderAddress!, refundAmount, spec);
        }

        private static bool ShouldRefundGas(Transaction tx, ExecutionOptions opts, in UInt256 gasPrice) =>
            !gasPrice.IsZero && ShouldValidateGas(tx, opts);

        protected virtual long CalculateClaimableRefund(long spentGas, long totalRefund, IReleaseSpec spec)
            => RefundHelper.CalculateClaimableRefund(spentGas, totalRefund, spec);

        [DoesNotReturn, StackTraceHidden]
        private static void ThrowInvalidDataException(string message) => throw new InvalidDataException(message);
    }

    /// <summary>
    /// Non-generic TransactionProcessorBase for backward compatibility with EthereumGasPolicy.
    /// </summary>
    public abstract class EthereumTransactionProcessorBase(
        ITransactionProcessor.IBlobBaseFeeCalculator? blobBaseFeeCalculator,
        ISpecProvider? specProvider,
        IWorldState? worldState,
        IVirtualMachine? virtualMachine,
        ICodeInfoRepository? codeInfoRepository,
        ILogManager? logManager)
        : TransactionProcessorBase<EthereumGasPolicy>(blobBaseFeeCalculator, specProvider, worldState, virtualMachine, codeInfoRepository, logManager);

    public readonly struct TransactionResult : IEquatable<TransactionResult>
    {
        private TransactionResult(ErrorType error = ErrorType.None, EvmExceptionType evmException = EvmExceptionType.None, string errorDescription = "")
        {
            Error = error;
            EvmExceptionType = evmException;
            ErrorDescription = errorDescription;
        }

        public ErrorType Error { get; }
        public bool TransactionExecuted => Error is ErrorType.None;
        public EvmExceptionType EvmExceptionType { get; }
        public string ErrorDescription { get; }

        public static implicit operator TransactionResult(ErrorType error) => new(error);
        public static implicit operator bool(TransactionResult result) => result.TransactionExecuted;
        public bool Equals(TransactionResult other) => (TransactionExecuted && other.TransactionExecuted) || (Error == other.Error);
        public static bool operator ==(TransactionResult obj1, TransactionResult obj2) => obj1.Equals(obj2);
        public static bool operator !=(TransactionResult obj1, TransactionResult obj2) => !obj1.Equals(obj2);
        public override bool Equals(object? obj) => obj is TransactionResult result && Equals(result);
        public override int GetHashCode() => TransactionExecuted ? 1 : Error.GetHashCode();
        public override string ToString() => Error is not ErrorType.None ? $"Fail : {ErrorDescription}" : "Success";

        public static TransactionResult EvmException(EvmExceptionType evmExceptionType, string? description = null) =>
            new(evmException: evmExceptionType, errorDescription: description ?? "");

        public static TransactionResult WithDetail(ErrorType errorType, string detail) => new(errorType, errorDescription: detail);

        public static readonly TransactionResult Ok = new();
        public static readonly TransactionResult BlockGasLimitExceeded = new(ErrorType.BlockGasLimitExceeded, errorDescription: "Block gas limit exceeded");
        public static readonly TransactionResult GasLimitBelowIntrinsicGas = new(ErrorType.GasLimitBelowIntrinsicGas, errorDescription: "intrinsic gas too low");
        public static readonly TransactionResult InsufficientMaxFeePerGasForSenderBalance = new(ErrorType.InsufficientMaxFeePerGasForSenderBalance, errorDescription: "insufficient sender balance for gas * price + value");
        public static readonly TransactionResult InsufficientSenderBalance = new(ErrorType.InsufficientSenderBalance, errorDescription: "insufficient funds for transfer");
        public static readonly TransactionResult MalformedTransaction = new(ErrorType.MalformedTransaction, errorDescription: "malformed");
        public static readonly TransactionResult MinerPremiumNegative = new(ErrorType.MinerPremiumNegative, errorDescription: "miner premium is negative");
        public static readonly TransactionResult NonceOverflow = new(ErrorType.NonceOverflow, errorDescription: "nonce overflow");
        public static readonly TransactionResult SenderHasDeployedCode = new(ErrorType.SenderHasDeployedCode, errorDescription: "sender has deployed code");
        public static readonly TransactionResult SenderNotSpecified = new(ErrorType.SenderNotSpecified, errorDescription: "sender not specified");
        public static readonly TransactionResult TransactionSizeOverMaxInitCodeSize = new(ErrorType.TransactionSizeOverMaxInitCodeSize, errorDescription: "EIP-3860 - transaction size over max init code size");
        public static readonly TransactionResult TransactionNonceTooHigh = new(ErrorType.TransactionNonceTooHigh, errorDescription: "nonce too high");
        public static readonly TransactionResult TransactionNonceTooLow = new(ErrorType.TransactionNonceTooLow, errorDescription: "nonce too low");

        public enum ErrorType
        {
            None,
            BlockGasLimitExceeded,
            GasLimitBelowIntrinsicGas,
            InsufficientMaxFeePerGasForSenderBalance,
            InsufficientSenderBalance,
            MalformedTransaction,
            MaxFeePerGasBelowBaseFee,
            MinerPremiumNegative,
            NonceOverflow,
            SenderHasDeployedCode,
            SenderNotSpecified,
            TransactionSizeOverMaxInitCodeSize,
            TransactionNonceTooHigh,
            TransactionNonceTooLow,
        }
    }

    public static class TransactionResultExtensions
    {
        public static TransactionResult WithDetail(this TransactionResult.ErrorType errorType, string detail) =>
            TransactionResult.WithDetail(errorType, detail);
    }
}