using Nethereum.EVM;
using Nethereum.Hex.HexConvertors.Extensions;

// Execute PUSH1 0xA0 (pushes 0xA0 onto stack)
var vm = new EVMSimulator();
var program = new Program("60A0".HexToByteArray());
await vm.StepAsync(program, 0);

var result = program.StackPeek(); // Returns: 0x00000000...0000A0

// Execute: PUSH1 0x04, PUSH1 0x04, ADD (4 + 4 = 8)
var vm = new EVMSimulator();
var bytecode = "6004600401".HexToByteArray(); // PUSH1 0x04, PUSH1 0x04, ADD
var program = new Program(bytecode);

// Step through each instruction
await vm.StepAsync(program, 0); // PUSH1 0x04
await vm.StepAsync(program, 1); // PUSH1 0x04
await vm.StepAsync(program, 2); // ADD

var result = program.StackPeek(); // Returns: 0x0000...0008

// Stack operations (32-byte values, stack grows downward)
program.StackPush(value);          // Push 32-byte value
var top = program.StackPeek();     // Peek at top
var item = program.StackPeekAt(2); // Peek at position 2
program.StackPop();                // Remove top
program.StackSwap(1);              // Swap positions

// Memory expands automatically (32-byte increments)
program.WriteToMemory(index, totalSize, data, extend: true);
// Memory is accessed directly via the Memory property (List<byte>)
var memorySize = program.Memory.Count;

var callInput = new CallInput
{
    From = "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    To = "0x1234567890123456789012345678901234567890",
    Value = new HexBigInteger(1000000000000000000), // 1 ETH
    Gas = new HexBigInteger(21000),
    ChainId = 1
};

var executionStateService = new ExecutionStateService(nodeDataService);
var context = new ProgramContext(callInput, executionStateService);

// Common static costs
ADD = 3
MUL = 5
PUSH1-PUSH32 = 3
DUP1-DUP16 = 3
SWAP1-SWAP16 = 3
SELFDESTRUCT = -1 (dynamic)
TLOAD, TSTORE = 100 (transient storage)

// SSTORE has complex gas calculation:
// - Cold access: +2100 gas
// - Setting from zero: 20000 gas
// - Setting from non-zero to different non-zero: 2900 gas (if original value)
// - Setting to same value: 100 gas
// - Dirty slot (already modified): 100 gas

// CALL gas includes:
// - Cold account access: 2600 gas (warm: 100 gas)
// - Memory expansion cost
// - Value transfer: +9000 gas
// - Account creation (if empty): +25000 gas

using Nethereum.EVM.BlockchainState;
using Nethereum.Web3;

var web3 = new Web3("https://mainnet.infura.io/v3/YOUR_KEY");
var nodeDataService = new RpcNodeDataService(
    web3.Eth,
    BlockParameter.CreateLatest()
);

var stateService = new ExecutionStateService(nodeDataService);

// Fetch and cache account data
var code = await stateService.GetCodeAsync("0x1234...");
var storage = await stateService.GetFromStorageAsync("0x1234...", BigInteger.Zero);
var balance = await stateService.GetTotalBalanceAsync("0x1234...");

await vm.ExecuteAsync(program);

var result = program.ProgramResult;

if (result.IsRevert)
{
    // Decode revert message (ABI-encoded Error(string))
    var message = result.GetRevertMessage();
    Console.WriteLine($"Reverted: {message}");
}
else
{
    var returnData = result.Result;
    foreach (var log in result.Logs)
    {
        Console.WriteLine($"Log: {log.Topics[0]}");
    }
}

var vm = new EVMSimulator();
var program = new Program(bytecode, context);

await vm.ExecuteAsync(program, traceEnabled: true);

foreach (var trace in program.Trace)
{
    Console.WriteLine(trace.ToString());
    // Output includes:
    // - Address, VMTraceStep, Depth, Gas
    // - Instruction with arguments
    // - Stack contents
    // - Memory contents
    // - Storage changes
}

using Nethereum.EVM;

var bytecode = "0x60806040526004361060...";

// Parse into instructions
var instructions = ProgramInstructionsUtils.GetProgramInstructions(bytecode);

// Full disassembly
var disassembly = ProgramInstructionsUtils.DisassembleToString(bytecode);
// Output format: "0000   60   PUSH1  0x80"

// Simplified disassembly
var simplified = ProgramInstructionsUtils.DisassembleSimplifiedToString(bytecode);
// Output format: "PUSH1 0x80 PUSH1 0x40 MSTORE"

var instructions = ProgramInstructionsUtils.GetProgramInstructions(contractCode);

// Check for specific function signature
bool hasTransfer = ProgramInstructionsUtils.ContainsFunctionSignature(
    instructions,
    "0xa9059cbb" // transfer(address,uint256)
);

// Check for multiple signatures
var signatures = new[] { "0xa9059cbb", "0x70a08231" }; // transfer, balanceOf
bool hasAll = ProgramInstructionsUtils.ContainsFunctionSignatures(instructions, signatures);

using Nethereum.EVM;
using Nethereum.Hex.HexConvertors.Extensions;
using System.Numerics;

// Test: 2 + 2 with ADDMOD 3 (should equal 1)
var bytecode = "60036002600208"; // PUSH1 0x03, PUSH1 0x02, PUSH1 0x02, ADDMOD

var vm = new EVMSimulator();
var program = new Program(bytecode.HexToByteArray());

// Execute all instructions
await vm.ExecuteAsync(program, traceEnabled: false);

var result = program.StackPeek();
// result = 0x0000...0001 (4 % 3 = 1)

using Nethereum.EVM;
using Nethereum.Hex.HexConvertors.Extensions;

// Store 0x01 at memory[0], then hash 1 byte starting at memory[0]
// PUSH1 0x01, PUSH1 0x00, MSTORE8, PUSH1 0x01, PUSH1 0x00, KECCAK256
var bytecode = "6001600053600160002016".HexToByteArray();

var vm = new EVMSimulator();
var program = new Program(bytecode);

await vm.ExecuteAsync(program);

var hash = program.StackPeek().ToHex();
// hash = keccak256(0x01) = "5fe7f977e71dba2ea1a68e21057beebb9be2ac30c6410aa38d4f3fbe41dcffd2"

using Nethereum.EVM;
using Nethereum.Hex.HexConvertors.Extensions;

// PUSH1 0x01 (condition=true), PUSH1 0x05 (jump target), JUMPI, JUMPDEST, PUSH1 0xCC
// If condition is true, jump to JUMPDEST at position 5, then push 0xCC
var bytecode = "60016005575B60CC".HexToByteArray();

var vm = new EVMSimulator();
var program = new Program(bytecode);

await vm.ExecuteAsync(program);

var result = program.StackPeek();
// result = 0xCC (jump was taken)

using Nethereum.EVM;
using Nethereum.EVM.BlockchainState;
using Nethereum.Web3;
using Nethereum.RPC.Eth.DTOs;
using Nethereum.Hex.HexTypes;

// Connect to Ethereum node
var web3 = new Web3("https://mainnet.infura.io/v3/YOUR_KEY");

// Create node data service for fetching blockchain state
var nodeDataService = new RpcNodeDataService(
    web3.Eth,
    BlockParameter.CreateLatest()
);

var stateService = new ExecutionStateService(nodeDataService);

// Create call input
var callInput = new CallInput
{
    From = "0x0000000000000000000000000000000000000001",
    To = "0xContractAddress",
    Gas = new HexBigInteger(1000000),
    ChainId = 1,
    Data = "0x" // Function call data
};

// Create program context
var context = new ProgramContext(callInput, stateService);

// Get contract bytecode from blockchain
var contractCode = await stateService.GetCodeAsync(callInput.To);

// Execute contract code
var vm = new EVMSimulator();
var program = new Program(contractCode, context);

await vm.ExecuteAsync(program, traceEnabled: true);

// Check results
if (program.ProgramResult.IsRevert)
{
    Console.WriteLine($"Reverted: {program.ProgramResult.GetRevertMessage()}");
}
else
{
    var returnData = program.ProgramResult.Result;
    Console.WriteLine($"Success: {returnData.ToHex()}");
}

// Analyze gas usage
var totalGas = program.Trace.Sum(t => t.GasCost);
Console.WriteLine($"Gas used: {totalGas}");

using Nethereum.EVM;
using Nethereum.Web3;

var web3 = new Web3("https://mainnet.infura.io/v3/YOUR_KEY");

// Fetch USDC contract bytecode
var usdcAddress = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
var bytecode = await web3.Eth.GetCode.SendRequestAsync(usdcAddress);

// Parse into instructions
var instructions = ProgramInstructionsUtils.GetProgramInstructions(bytecode);

Console.WriteLine($"Total instructions: {instructions.Count}");

// Check for specific functions
bool hasTransfer = ProgramInstructionsUtils.ContainsFunctionSignature(
    instructions,
    "0xa9059cbb" // transfer(address,uint256) signature
);

Console.WriteLine($"Has transfer function: {hasTransfer}");

// Full disassembly
var disassembly = ProgramInstructionsUtils.DisassembleToString(bytecode);
Console.WriteLine(disassembly);

// Output format:
// 0000   60   PUSH1  0x80
// 0002   60   PUSH1  0x40
// 0004   52   MSTORE
// ...

using Nethereum.EVM;
using Nethereum.Hex.HexConvertors.Extensions;

// Bytecode: PUSH1 0xF0, PUSH1 0x0F, OR (0xF0 | 0x0F = 0xFF)
var bytecode = "60F0600F17".HexToByteArray();

var vm = new EVMSimulator();
var program = new Program(bytecode);

// Step through each instruction
int step = 0;

// Step 1: PUSH1 0xF0
await vm.StepAsync(program, step++);
Console.WriteLine($"After PUSH1 0xF0: Stack top = {program.StackPeek().ToHex()}");
// Stack: [0xF0]

// Step 2: PUSH1 0x0F
await vm.StepAsync(program, step++);
Console.WriteLine($"After PUSH1 0x0F: Stack has {program.GetCurrentStackAsHex().Count} items");
// Stack: [0x0F, 0xF0]

// Step 3: OR
await vm.StepAsync(program, step++);
Console.WriteLine($"After OR: Stack top = {program.StackPeek().ToHex()}");
// Stack: [0xFF]

// Check traces
foreach (var trace in program.Trace)
{
    Console.WriteLine($"Step {trace.VMTraceStep}: {trace.Instruction?.Instruction} - Gas: {trace.GasCost}");
}

// Cold storage access: +2100 gas (first time)
// Warm storage access: 0 gas (already accessed)

// Value changes:
// 1. Setting from zero to non-zero: 20000 gas (new slot)
// 2. Setting from non-zero to different non-zero: 2900 gas (if original value)
// 3. Setting to same value: 100 gas (no-op)
// 4. Dirty slot (already modified in transaction): 100 gas

// Gas cost = memory_size_word * 3 + floor(memory_size_word^2 / 512)
// where memory_size_word = ceil(memory_size_byte / 32)

// Base costs:
// - Account access (warm: 100, cold: 2600)
// - Memory expansion (input + output)
// - Value transfer: +9000 gas (if value > 0)
// - Account creation: +25000 gas (if target is empty account and value > 0)

public class CustomStateProvider : INodeDataService
{
    public async Task<BigInteger> GetBalanceAsync(string address)
    {
        // Custom balance logic
        return BigInteger.Zero;
    }

    public async Task<byte[]> GetCodeAsync(string address)
    {
        // Custom code retrieval
        return new byte[0];
    }

    public async Task<byte[]> GetStorageAtAsync(string address, BigInteger position)
    {
        // Custom storage logic
        return new byte[32];
    }

    // Implement other INodeDataService methods...
}

var nodeDataService = new RpcNodeDataService(
    web3.Eth,
    BlockParameter.CreateLatest(),
    web3.DebugApiService,
    blockHash: "0xabc123...",
    transactionIndex: 5,
    useDebugStorageAt: true
);

// Storage reads will use debug_storageRangeAt for transaction-level precision

public class TransactionExecutor
{
    public TransactionExecutor(
        HardforkConfig config = null,
        EVMSimulator evmSimulator = null,
        IPrecompileProvider customPrecompileProvider = null);

    public async Task<TransactionExecutionResult> ExecuteAsync(TransactionExecutionContext ctx);
}

public enum ExecutionMode
{
    Transaction,  // Full transaction execution with gas payment
    Call           // eth_call mode - skips gas price validation
}

public class TransactionExecutionResult
{
    public bool Success { get; set; }
    public BigInteger GasUsed { get; set; }
    public BigInteger GasRefund { get; set; }
    public BigInteger EffectiveGasUsed { get; set; }
    public byte[] ReturnData { get; set; }
    public string RevertReason { get; set; }
    public List<FilterLog> Logs { get; set; }
    public byte[] StateRoot { get; set; }
    public string ContractAddress { get; set; }
    public string Error { get; set; }
    public bool IsValidationError { get; set; }
    public List<ProgramTrace> Traces { get; set; }
    public List<string> CreatedAccounts { get; set; }
    public List<string> DeletedAccounts { get; set; }
    public List<CallInput> InnerCalls { get; set; }
    public Dictionary<string, List<ProgramInstruction>> InnerContractCodeCalls { get; set; }
    public ProgramResult ProgramResult { get; set; }
}

public enum TransactionError
{
    None,
    InsufficientMaxFeePerGas,
    PriorityGreaterThanMaxFee,
    InsufficientBalance,
    GasAllowanceExceeded,
    IntrinsicGasTooLow,
    NonceIsMax,
    SenderNotEOA,
    InitcodeSizeExceeded,
    Type3TxContractCreation,
    Type3TxZeroBlobs,
    Type3TxBlobCountExceeded,
    Type3TxInvalidBlobVersionedHash,
    AddressCollision,
    InvalidEFPrefix,
    MaxCodeSizeExceeded,
    OutOfGas,
    Reverted,
}

public class HardforkConfig
{
    public bool EnableEIP4844 { get; set; }     // Blob transactions (Cancun)
    public bool EnableEIP7623 { get; set; }     // Calldata gas floor (Prague)
    public bool EnableEIP7702 { get; set; }     // Authorization lists (Prague)
    public int MaxBlobsPerBlock { get; set; }
    public IPrecompileProvider PrecompileProvider { get; set; }

    public static HardforkConfig Cancun { get; }   // EIP-4844 only, 6 blobs, Cancun precompiles (1-10)
    public static HardforkConfig Prague { get; }    // All EIPs, 9 blobs, Prague precompiles (1-17)
    public static HardforkConfig Default { get; }   // Same as Prague

    public static HardforkConfig FromName(string hardfork); // "cancun" or "prague"
}

var nodeDataService = new RpcNodeDataService(web3.Eth, new BlockParameter(blockNumber));
var executionStateService = new ExecutionStateService(nodeDataService);

var ctx = new TransactionExecutionContext
{
    Mode = ExecutionMode.Call,
    Sender = callInput.From,
    To = callInput.To,
    Data = callInput.Data?.HexToByteArray(),
    GasLimit = 10_000_000,
    Value = callInput.Value?.Value ?? BigInteger.Zero,
    GasPrice = baseFee + 1_000_000_000,
    MaxFeePerGas = callInput.MaxFeePerGas?.Value ?? baseFee + 1_000_000_000,
    MaxPriorityFeePerGas = callInput.MaxPriorityFeePerGas?.Value ?? 1_000_000_000,
    Nonce = BigInteger.Zero,
    IsEip1559 = callInput.MaxFeePerGas != null,
    IsContractCreation = string.IsNullOrEmpty(callInput.To),
    BlockNumber = (long)blockNumber.Value,
    Timestamp = timestamp,
    BaseFee = baseFee,
    Coinbase = "0x0000000000000000000000000000000000000000",
    BlockGasLimit = 30_000_000,
    ExecutionState = executionStateService,
    TraceEnabled = true
};

var config = HardforkConfig.Default;
var executor = new TransactionExecutor(config);
var execResult = await executor.ExecuteAsync(ctx);

if (execResult.Success)
{
    // Decode and extract state changes
    var decoder = new ProgramResultDecoder(abiStorage);
    var decodedResult = decoder.Decode(execResult, callInput, chainId);

    var extractor = new StateChangesExtractor();
    var stateChanges = extractor.ExtractFromDecodedResult(
        decodedResult, executionStateService, currentUserAddress);
}

public class ProgramResultDecoder
{
    public ProgramResultDecoder(IABIInfoStorage abiStorage);

    public DecodedProgramResult Decode(
        Program program, CallInput initialCall, BigInteger chainId);

    public DecodedProgramResult Decode(
        TransactionExecutionResult executionResult, CallInput initialCall, BigInteger chainId);

    public DecodedProgramResult Decode(
        ProgramResult programResult, List<ProgramTrace> trace,
        CallInput initialCall, BigInteger chainId);

    public DecodedCall DecodeCall(CallInput call, BigInteger chainId, int depth);

    public DecodedLog DecodeLog(FilterLog log, BigInteger chainId);

    public DecodedError DecodeRevert(byte[] revertData, BigInteger chainId, string contractAddress);

    public List<ParameterOutput> DecodeReturnValue(FunctionABI functionABI, string output);
}

public class DecodedProgramResult
{
    public DecodedCall RootCall { get; set; }
    public List<DecodedLog> DecodedLogs { get; set; }
    public List<ParameterOutput> ReturnValue { get; set; }
    public DecodedError RevertReason { get; set; }
    public bool IsRevert { get; set; }
    public bool IsSuccess { get; }              // !IsRevert
    public ProgramResult OriginalResult { get; set; }
    public CallInput OriginalCall { get; set; }
    public BigInteger ChainId { get; set; }

    public string ToHumanReadableString();       // Formatted call tree, events, and result
}

public enum CallType
{
    Call, DelegateCall, StaticCall, CallCode, Create, Create2
}

public class DecodedCall
{
    public string From { get; set; }
    public string To { get; set; }
    public string ContractName { get; set; }
    public FunctionABI Function { get; set; }
    public List<ParameterOutput> InputParameters { get; set; }
    public List<ParameterOutput> OutputParameters { get; set; }
    public List<DecodedCall> InnerCalls { get; set; }
    public List<DecodedLog> Logs { get; set; }
    public CallType CallType { get; set; }
    public int Depth { get; set; }
    public bool IsDecoded { get; set; }
    public string RawInput { get; set; }
    public string RawOutput { get; set; }
    public BigInteger Value { get; set; }
    public BigInteger GasUsed { get; set; }
    public bool IsRevert { get; set; }
    public DecodedError Error { get; set; }
    public CallInput OriginalCall { get; set; }

    public string GetFunctionSignature();  // Returns Function.Sha3Signature
    public string GetFunctionName();       // Returns Function.Name
    public string GetDisplayName();        // "ContractName.FunctionName" or fallback
}

public class DecodedLog
{
    public string ContractAddress { get; set; }
    public string ContractName { get; set; }
    public EventABI Event { get; set; }
    public List<ParameterOutput> Parameters { get; set; }
    public bool IsDecoded { get; set; }
    public FilterLog OriginalLog { get; set; }
    public int LogIndex { get; set; }
    public int CallDepth { get; set; }

    public string GetEventSignature();  // Returns Event.Sha3Signature
    public string GetEventName();       // Returns Event.Name
    public string GetDisplayName();     // "ContractName.EventName" or fallback
}

public class DecodedError
{
    public ErrorABI Error { get; set; }
    public List<ParameterOutput> Parameters { get; set; }
    public string Message { get; set; }
    public bool IsStandardError { get; set; }
    public bool IsDecoded { get; set; }
    public string RawData { get; set; }

    public string GetErrorSignature();     // Returns Error.Sha3Signature
    public string GetErrorName();          // Returns Error.Name
    public string GetDisplayMessage();     // Message, Error.Name, or RawData fallback

    public static DecodedError FromStandardError(string message, string rawData = null);
    public static DecodedError FromUnknownError(string rawData);
}

// After executing a transaction
var executor = new TransactionExecutor(HardforkConfig.Default);
var execResult = await executor.ExecuteAsync(ctx);

// Decode the result using ABI storage
var decoder = new ProgramResultDecoder(abiStorage);
var decoded = decoder.Decode(execResult, callInput, chainId);

// Inspect the decoded result
Console.WriteLine(decoded.ToHumanReadableString());

// Access individual parts
if (decoded.IsSuccess)
{
    foreach (var param in decoded.ReturnValue)
    {
        Console.WriteLine($"{param.Parameter.Name}: {param.Result}");
    }
}
else
{
    Console.WriteLine($"Reverted: {decoded.RevertReason?.GetDisplayMessage()}");
}

// Walk the call tree
Console.WriteLine($"Root: {decoded.RootCall.GetDisplayName()}");
foreach (var inner in decoded.RootCall.InnerCalls)
{
    Console.WriteLine($"  -> {inner.GetDisplayName()}");
}

// Inspect events
foreach (var log in decoded.DecodedLogs)
{
    Console.WriteLine($"Event: {log.GetDisplayName()}");
}

public class StateChangesExtractor : IStateChangesExtractor
{
    public StateChangesResult ExtractFromDecodedResult(
        DecodedProgramResult decodedResult,
        ExecutionStateService stateService = null,
        string currentUserAddress = null);

    public StateChangesResult ExtractFromDecodedResult(
        DecodedProgramResult decodedResult,
        ExecutionStateService stateService,
        string currentUserAddress,
        Func<string, TokenInfo> tokenResolver);

    public async Task<StateChangesResult> ExtractFromDecodedResultAsync(
        DecodedProgramResult decodedResult,
        ExecutionStateService stateService = null,
        string currentUserAddress = null,
        Func<string, Task<TokenInfo>> tokenResolverAsync = null,
        CancellationToken cancellationToken = default);

    public void ValidateTokenBalances(
        StateChangesResult result,
        Program program,
        ExecutionStateService stateService,
        Func<string, string, BigInteger> getErc20Balance = null,
        Func<string, BigInteger, string> getErc721Owner = null,
        Func<string, string, BigInteger, BigInteger> getErc1155Balance = null);
}

public class StateChangesResult
{
    public List<BalanceChange> BalanceChanges { get; set; }
    public DecodedCall RootCall { get; set; }
    public List<DecodedLog> DecodedLogs { get; set; }
    public DecodedProgramResult DecodedResult { get; set; }
    public string Error { get; set; }
    public List<ProgramTrace> Traces { get; set; }
    public BigInteger GasUsed { get; set; }

    public bool HasError { get; }             // !string.IsNullOrEmpty(Error)
    public bool HasBalanceChanges { get; }
    public bool HasDecodedLogs { get; }
    public bool HasTraces { get; }

    public string ToSummaryString();           // Formatted balance changes, call tree, and events
}

public enum BalanceChangeType
{
    Native,   // ETH transfers
    ERC20,    // ERC20 token transfers
    ERC721,   // ERC721 NFT transfers
    ERC1155   // ERC1155 multi-token transfers
}

public enum BalanceValidationStatus
{
    NotValidated,    // Not yet validated against actual state
    Verified,        // Change matches actual state
    FeeOnTransfer,   // Actual change < expected (fee-on-transfer token)
    Rebasing,        // Actual change > expected (rebasing token)
    OwnerMismatch,   // ERC721 owner doesn't match expected
    Mismatch         // General mismatch
}

public class BalanceChange
{
    // Identity
    public string Address { get; set; }
    public string AddressLabel { get; set; }
    public bool IsCurrentUser { get; set; }

    // Token info
    public BalanceChangeType Type { get; set; }
    public string TokenAddress { get; set; }
    public string TokenSymbol { get; set; }
    public int TokenDecimals { get; set; }
    public BigInteger? TokenId { get; set; }        // For ERC721/ERC1155

    // Change amount
    public BigInteger Change { get; set; }           // Positive = received, negative = sent
    public BigInteger? BalanceBefore { get; set; }
    public BigInteger? BalanceAfter { get; set; }

    // Validation
    public BigInteger? ActualChange { get; set; }
    public string ActualOwner { get; set; }          // For ERC721 validation
    public BalanceValidationStatus ValidationStatus { get; set; }
    public bool HasDiscrepancy { get; }

    // Display helpers
    public string GetTokenIdentifier();    // "ETH", token address, or "address:tokenId"
    public string GetDisplaySymbol();      // "ETH", "USDC", "NFT #42", etc.
    public string GetAddressDisplay();     // Label or truncated address "0x1234...abcd"
}

public class TokenInfo
{
    public string Symbol { get; set; }
    public int Decimals { get; set; }

    public TokenInfo();
    public TokenInfo(string symbol, int decimals);
}

// After decoding a transaction execution result
var decoder = new ProgramResultDecoder(abiStorage);
var decoded = decoder.Decode(execResult, callInput, chainId);

// Extract state changes
var extractor = new StateChangesExtractor();
var stateChanges = extractor.ExtractFromDecodedResult(
    decoded,
    executionStateService,
    currentUserAddress: "0xYourAddress");

// Print summary
Console.WriteLine(stateChanges.ToSummaryString());

// Inspect individual balance changes
foreach (var change in stateChanges.BalanceChanges)
{
    var sign = change.Change >= 0 ? "+" : "";
    Console.WriteLine(
        $"{change.GetAddressDisplay()}: {sign}{change.Change} {change.GetDisplaySymbol()}" +
        (change.IsCurrentUser ? " (you)" : ""));
}

// Async version with token metadata resolution
var stateChangesWithMetadata = await extractor.ExtractFromDecodedResultAsync(
    decoded,
    executionStateService,
    currentUserAddress: "0xYourAddress",
    tokenResolverAsync: async (address) =>
    {
        var info = await tokenService.GetTokenAsync(chainId, address);
        return info != null ? new TokenInfo(info.Symbol, info.Decimals) : null;
    });

public class EVMDebuggerSession
{
    public EVMDebuggerSession(IABIInfoStorage abiStorage);

    // Loading
    public void LoadFromProgram(Program executedProgram, BigInteger chainId);
    public async Task LoadFromProgramAsync(Program executedProgram, BigInteger chainId);
    public void LoadFromTrace(List<ProgramTrace> trace, BigInteger chainId);
    public async Task LoadFromTraceAsync(List<ProgramTrace> trace, BigInteger chainId);
    public void SetContractDebugInfo(string address, ABIInfo abiInfo);

    // Navigation
    public void StepForward();
    public void StepBack();
    public void GoToStep(int step);
    public void GoToStart();
    public void GoToEnd();

    // State properties
    public List<ProgramTrace> Trace { get; }
    public int CurrentStep { get; }
    public bool CanStepForward { get; }
    public bool CanStepBack { get; }
    public int TotalSteps { get; }

    // Current step inspection
    public ProgramTrace CurrentTrace { get; }
    public ProgramInstruction CurrentInstruction { get; }
    public List<string> CurrentStack { get; }
    public string CurrentMemory { get; }
    public Dictionary<string, string> CurrentStorage { get; }
    public int CurrentDepth { get; }
    public BigInteger CurrentGasCost { get; }
    public string CurrentCodeAddress { get; }
    public string CurrentProgramAddress { get; }

    // Source mapping
    public SourceLocation GetCurrentSourceLocation();
    public SourceLocation GetSourceLocationForStep(int stepIndex);
    public SourceLocation GetNearestSourceLocation(int stepIndex, int maxLookahead = 20);
    public SourceLocation GetFunctionDeclarationLocation(string functionName, string codeAddress);
    public List<int> FindStepsForSourceLine(string filePath, int lineNumber);

    // Function/contract resolution
    public string GetFunctionNameForStep(int stepIndex);
    public string GetCurrentContractName();
    public string GetContractNameForAddress(string address);
    public ABIInfo GetABIInfoForAddress(string address);

    // Call decoding
    public CallStepInfo GetCallInfoForStep(int stepIndex);

    // Source file access
    public IEnumerable<string> GetSourceFiles();
    public Dictionary<string, string> GetAllSourceFileContents();

    // Display
    public string ToDebugString();       // Full debug view (step, address, source, stack, storage)
    public string ToSummaryString();     // One-line summary: "[step/total] OPCODE | file:line"
}

public class CallStepInfo
{
    public string TargetAddress { get; set; }
    public string ContractName { get; set; }
    public string CallType { get; set; }          // "CALL", "STATICCALL", etc.
    public string Selector { get; set; }           // "0x70a08231" etc.
    public string FunctionName { get; set; }
    public string FunctionSignature { get; set; }
    public List<ParameterOutput> DecodedInputs { get; set; }
    public string RawCalldata { get; set; }
}

public static class EVMDebuggerExtensions
{
    // Create from Program
    public static EVMDebuggerSession CreateDebugSession(
        this Program program, IABIInfoStorage abiStorage, long chainId);
    public static async Task<EVMDebuggerSession> CreateDebugSessionAsync(
        this Program program, IABIInfoStorage abiStorage, long chainId);

    // Create from trace list
    public static EVMDebuggerSession CreateDebugSession(
        this List<ProgramTrace> trace, IABIInfoStorage abiStorage, long chainId);
    public static async Task<EVMDebuggerSession> CreateDebugSessionAsync(
        this List<ProgramTrace> trace, IABIInfoStorage abiStorage, long chainId);

    // Trace generation
    public static string GenerateFullTraceString(this EVMDebuggerSession session);
    public static string GenerateSourceAnnotatedTrace(this EVMDebuggerSession session);

    // Source navigation
    public static List<SourceLocation> GetUniqueSourceLocations(this EVMDebuggerSession session);
    public static bool HasDebugInfo(this EVMDebuggerSession session);
    public static IEnumerable<DebugStepInfo> EnumerateWithSource(this EVMDebuggerSession session);
    public static void StepToNextSourceLine(this EVMDebuggerSession session);
    public static void StepToPreviousSourceLine(this EVMDebuggerSession session);
}

public class SourceLocation
{
    public string FilePath { get; set; }
    public int Position { get; set; }           // Byte offset in source
    public int Length { get; set; }             // Length of source range
    public string SourceCode { get; set; }      // The source snippet
    public string FullFileContent { get; set; }
    public int LineNumber { get; set; }
    public int ColumnNumber { get; set; }
    public int SourceFileIndex { get; set; }
    public string JumpType { get; set; }
    public int ModifierDepth { get; set; }

    public static SourceLocation FromSourceMap(SourceMap sourceMap, string filePath, string fileContent);

    public string GetContextLines(int linesBefore = 2, int linesAfter = 2);
    // Returns surrounding source lines with ">>> " marker on the current line

    public override string ToString();  // "FilePath:LineNumber:ColumnNumber"
}

// Create a debug session from a Program after EVM execution
var session = program.CreateDebugSession(abiStorage, chainId);

// Or from a TransactionExecutionResult's traces
// var session = execResult.Traces.CreateDebugSession(abiStorage, chainId);

// Step through the execution
while (session.CanStepForward)
{
    var source = session.GetCurrentSourceLocation();
    if (source != null)
    {
        Console.WriteLine($"Step {session.CurrentStep}: {source}");
        Console.WriteLine(source.GetContextLines());
    }

    // Inspect call opcodes
    var callInfo = session.GetCallInfoForStep(session.CurrentStep);
    if (callInfo != null)
    {
        Console.WriteLine($"  CALL -> {callInfo.ContractName ?? callInfo.TargetAddress}");
        Console.WriteLine($"  Function: {callInfo.FunctionName ?? callInfo.Selector}");
    }

    session.StepForward();
}

// Or step by source line (skips opcodes that map to the same line)
session.GoToStart();
while (session.CanStepForward)
{
    session.StepToNextSourceLine();
    Console.WriteLine(session.ToSummaryString());
}

// Generate a full annotated trace
Console.WriteLine(session.GenerateSourceAnnotatedTrace());

// Full debug view at current step
Console.WriteLine(session.ToDebugString());

public static class IntrinsicGasCalculator
{
    // Constants
    public const int G_TRANSACTION = 21000;
    public const int G_TXDATAZERO = 4;
    public const int G_TXDATANONZERO = 16;
    public const int G_TXCREATE = 32000;
    public const int G_CODEDEPOSIT = 200;
    public const int G_ACCESS_LIST_ADDRESS = 2400;
    public const int G_ACCESS_LIST_STORAGE = 1900;
    public const int G_INITCODE_WORD = 2;
    public const int G_FLOOR_PER_TOKEN = 10;
    public const int G_TOKENS_PER_NONZERO = 4;
    public const int GAS_PER_BLOB = 131072;
    public const int MIN_BASE_FEE_PER_BLOB_GAS = 1;
    public const int BLOB_BASE_FEE_UPDATE_FRACTION = 3338477;

    // Intrinsic gas: base 21000 + calldata costs + access list + create + initcode words
    public static BigInteger CalculateIntrinsicGas(
        byte[] data, bool isContractCreation, IList<AccessListEntry> accessList);

    // EIP-7623: Floor gas limit based on calldata token count
    public static BigInteger CalculateFloorGasLimit(byte[] data, bool isContractCreation);

    // Calldata token count: zero_bytes + (nonzero_bytes * 4)
    public static BigInteger CalculateTokensInCalldata(byte[] data);

    // EIP-4844 blob gas
    public static BigInteger CalculateBlobBaseFee(BigInteger excessBlobGas);
    public static BigInteger CalculateBlobGasCost(int blobCount, BigInteger blobBaseFee);

    // Contract creation helpers
    public static BigInteger CalculateCodeDepositGas(int codeLength);  // codeLength * 200
    public static BigInteger CalculateMaxRefund(BigInteger gasUsed);   // gasUsed / 5
}

// Calculate intrinsic gas for a transaction
var calldata = "0xa9059cbb000000000000000000000000...".HexToByteArray();
var intrinsicGas = IntrinsicGasCalculator.CalculateIntrinsicGas(
    calldata,
    isContractCreation: false,
    accessList: null);
// Result: 21000 + (4 * zeroBytes) + (16 * nonZeroBytes)

// EIP-7623 floor gas check
var floorGas = IntrinsicGasCalculator.CalculateFloorGasLimit(calldata, isContractCreation: false);
var minGasRequired = BigInteger.Max(intrinsicGas, floorGas);

// Blob gas calculation (EIP-4844)
var blobBaseFee = IntrinsicGasCalculator.CalculateBlobBaseFee(excessBlobGas);
var blobGasCost = IntrinsicGasCalculator.CalculateBlobGasCost(blobCount: 3, blobBaseFee);

public interface IPrecompileProvider
{
    IEnumerable<string> GetHandledAddresses();
    bool CanHandle(string address);
    BigInteger GetGasCost(string address, byte[] data);
    byte[] Execute(string address, byte[] data);
}

public class BuiltInPrecompileProvider : IPrecompileProvider
{
    public static BuiltInPrecompileProvider Cancun();   // Addresses 0x01-0x0a (1-10)
    public static BuiltInPrecompileProvider Prague();    // Addresses 0x01-0x11 (1-17, includes BLS)

    public BuiltInPrecompileProvider(int start, int end);
}

public class CompositePrecompileProvider : IPrecompileProvider
{
    public CompositePrecompileProvider(params IPrecompileProvider[] providers);
}

public static class HardforkConfigExtensions
{
    public static HardforkConfig WithPrecompileProviders(
        this HardforkConfig config,
        params IPrecompileProvider[] additionalProviders);
}

// Implement a custom precompile
public class MyCustomPrecompile : IPrecompileProvider
{
    private const string ADDRESS = "0x0000000000000000000000000000000000000100";

    public IEnumerable<string> GetHandledAddresses() => new[] { ADDRESS };
    public bool CanHandle(string address) => address.Equals(ADDRESS, StringComparison.OrdinalIgnoreCase);
    public BigInteger GetGasCost(string address, byte[] data) => 1000;
    public byte[] Execute(string address, byte[] data)
    {
        // Custom precompile logic
        return data;
    }
}

// Use with TransactionExecutor
var config = HardforkConfig.Prague.WithPrecompileProviders(new MyCustomPrecompile());
var executor = new TransactionExecutor(config);

// Or pass directly to the constructor
var executor2 = new TransactionExecutor(
    config: HardforkConfig.Prague,
    customPrecompileProvider: new MyCustomPrecompile());

[Fact]
public async Task TestEVMOperation()
{
    var bytecode = "..."; // Hex bytecode
    var expected = "..."; // Expected stack top result

    var vm = new EVMSimulator();
    var program = new Program(bytecode.HexToByteArray());

    // Execute N steps
    for (var i = 0; i < numberOfSteps; i++)
    {
        await vm.StepAsync(program, i);
    }

    Assert.Equal(expected.ToUpper(), program.StackPeek().ToHex().ToUpper());
}