Add tracing to t8n

packages/evm/src/eof/container.ts

@@ -1,4 +1,4 @@
-import { EthereumJSErrorWithoutCode } from '@ethereumjs/util'
+import { EthereumJSError, EthereumJSErrorWithoutCode } from '@ethereumjs/util'
 
 import {
   CODE_MIN,
@@ -269,6 +269,27 @@
     }
     return offset
   }
+
+  // Returns the code section for a given program counter position
+  getSectionFromProgramCounter(programCounter: number) {
+    if (
+      programCounter < 0 ||
+      programCounter >
+        this.codeStartPos[this.codeStartPos.lastIndex] + this.codeSizes[this.codeSizes.lastIndex]
+    ) {
+      // If code position is outside the beginning or end of the code sections, return 0
+      throw EthereumJSErrorWithoutCode('program counter out of bounds')
+    }
+
+    for (let i = 0; i < this.codeSizes.length; i++) {
+      if (programCounter < this.codeStartPos[i] + this.codeSizes[i]) {
+        // We've found our section if the code position is less than the end of the current code section
+        return i
+      }
+    }
+    // This shouldn't happen so just error
+    throw EthereumJSErrorWithoutCode(`Invalid program counter value: ${programCounter}`)
+  }
 }
 
 export interface TypeSection {

packages/evm/src/interpreter.ts

@@ -6,10 +6,12 @@
   BIGINT_2,
   EthereumJSErrorWithoutCode,
   MAX_UINT64,
+  bigIntToBytes,
   bigIntToHex,
   bytesToBigInt,
   bytesToHex,
   equalsBytes,
+  setLengthLeft,
   setLengthRight,
 } from '@ethereumjs/util'
 import debugDefault from 'debug'
@@ -32,6 +34,7 @@
   VerkleAccessWitnessInterface,
 } from '@ethereumjs/common'
 import type { Address, PrefixedHexString } from '@ethereumjs/util'
+import { stackDelta } from './eof/stackDelta.ts'
 import type { EVM } from './evm.ts'
 import type { Journal } from './journal.ts'
 import type { AsyncOpHandler, Opcode, OpcodeMapEntry } from './opcodes/index.ts'
@@ -108,6 +111,7 @@
   gasRefund: bigint // Tracks the current refund
   gasLeft: bigint // Current gas left
   returnBytes: Uint8Array /* Current bytes in the return Uint8Array. Cleared each time a CALL/CREATE is made in the current frame. */
+  accessedStorage: Map<PrefixedHexString, PrefixedHexString>
 }
 
 export interface InterpreterResult {
@@ -127,12 +131,18 @@
     fee: number
     dynamicFee?: bigint
     isAsync: boolean
+    code: number // The hexadecimal representation of the opcode (e.g. 0x60 for PUSH1)
   }
   account: Account
   address: Address
   memory: Uint8Array
   memoryWordCount: bigint
   codeAddress: Address
+  eofSection?: number // Current EOF section being executed
+  immediate?: Uint8Array // Immediate argument of the opcode
+  eofFunctionDepth?: number // Depth of CALLF return stack
+  error?: Uint8Array // Error bytes returned if revert occurs
+  storage?: [PrefixedHexString, PrefixedHexString][]
 }
 
 /**
@@ -198,6 +208,7 @@
       gasRefund: env.gasRefund,
       gasLeft,
       returnBytes: new Uint8Array(0),
+      accessedStorage: new Map(), // Maps accessed storage keys to their values (i.e. SSTOREd and SLOADed values)
     }
     this.journal = journal
     this._env = env
@@ -283,7 +294,7 @@
     while (this._runState.programCounter < this._runState.code.length) {
       const programCounter = this._runState.programCounter
       let opCode: number
-      let opCodeObj: OpcodeMapEntry
+      let opCodeObj: OpcodeMapEntry | undefined
       if (doJumpAnalysis) {
         opCode = this._runState.code[programCounter]
         // Only run the jump destination analysis if `code` actually contains a JUMP/JUMPI/JUMPSUB opcode
@@ -319,13 +330,13 @@
         }
       }
 
-      this._runState.opCode = opCode!
+      this._runState.opCode = opCode
 
       try {
         if (overheadTimer !== undefined) {
           this.performanceLogger.pauseTimer()
         }
-        await this.runStep(opCodeObj!)
+        await this.runStep(opCodeObj)
         if (overheadTimer !== undefined) {
           this.performanceLogger.unpauseTimer(overheadTimer)
         }
@@ -374,6 +385,9 @@
 
     let gas = opInfo.feeBigInt
 
+    // Cache pre-gas memory size if doing tracing (EIP-7756)
+    const memorySizeCache = this._runState.memoryWordCount
+
     try {
       if (opInfo.dynamicGas) {
         // This function updates the gas in-place.
@@ -384,7 +398,7 @@
       if (this._evm.events.listenerCount('step') > 0 || this._evm.DEBUG) {
         // Only run this stepHook function if there is an event listener (e.g. test runner)
         // or if the vm is running in debug mode (to display opcode debug logs)
-        await this._runStepHook(gas, this.getGasLeft())
+        await this._runStepHook(gas, this.getGasLeft(), memorySizeCache)
       }
 
       if (
@@ -441,27 +455,69 @@
     return this._evm['_opcodeMap'][op]
   }
 
-  async _runStepHook(dynamicFee: bigint, gasLeft: bigint): Promise<void> {
-    const opcodeInfo = this.lookupOpInfo(this._runState.opCode)
-    const opcode = opcodeInfo.opcodeInfo
+  async _runStepHook(dynamicFee: bigint, gasLeft: bigint, memorySize: bigint): Promise<void> {
+    const opcodeInfo = this.lookupOpInfo(this._runState.opCode).opcodeInfo
+    const section = this._env.eof?.container.header.getSectionFromProgramCounter(
+      this._runState.programCounter,
+    )
+    let error = undefined
+    let immediate = undefined
+    if (opcodeInfo.code === 0xfd) {
+      // If opcode is REVERT, read error data and return in trace
+      const [offset, length] = this._runState.stack.peek(2)
+      error = new Uint8Array(0)
+      if (length !== BIGINT_0) {
+        error = this._runState.memory.read(Number(offset), Number(length))
+      }
+    }
+
+    // Add immediate if present (i.e. bytecode parameter for a preceding opcode like (RJUMP 01 - jumps to PC 1))
+    if (stackDelta[opcodeInfo.code].intermediates > 0) {
+      immediate = this._runState.code.slice(
+        this._runState.programCounter,
+        this._runState.programCounter + stackDelta[opcodeInfo.code].intermediates,
+      )
+    }
+
+    if (opcodeInfo.name === 'SLOAD') {
+      // Store SLOADed values for recording in trace
+      const key = this._runState.stack.peek(1)
+      const value = await this.storageLoad(setLengthLeft(bigIntToBytes(key[0]), 32))
+      this._runState.accessedStorage.set(`0x${key[0].toString(16)}`, bytesToHex(value))
+    }
+
+    if (opcodeInfo.name === 'SSTORE') {
+      // Store SSTOREed values for recording in trace
+      const [key, value] = this._runState.stack.peek(2)
+      this._runState.accessedStorage.set(`0x${key.toString(16)}`, `0x${value.toString(16)}`)
+    }
+
+    // Create event object for step
     const eventObj: InterpreterStep = {
       pc: this._runState.programCounter,
       gasLeft,
       gasRefund: this._runState.gasRefund,
       opcode: {
-        name: opcode.fullName,
-        fee: opcode.fee,
+        name: opcodeInfo.fullName,
+        fee: opcodeInfo.fee,
         dynamicFee,
-        isAsync: opcode.isAsync,
+        isAsync: opcodeInfo.isAsync,
+        code: opcodeInfo.code,
       },
       stack: this._runState.stack.getStack(),
       depth: this._env.depth,
       address: this._env.address,
       account: this._env.contract,
-      memory: this._runState.memory._store.subarray(0, Number(this._runState.memoryWordCount) * 32),
-      memoryWordCount: this._runState.memoryWordCount,
+      memory: this._runState.memory._store.subarray(0, Number(memorySize) * 32),
+      memoryWordCount: memorySize,
       codeAddress: this._env.codeAddress,
       stateManager: this._runState.stateManager,
+      eofSection: section,
+      immediate,
+      error,
+      eofFunctionDepth:
+        this._env.eof !== undefined ? this._env.eof?.eofRunState.returnStack.length + 1 : undefined,
+      storage: Array.from(this._runState.accessedStorage.entries()),
     }
 
     if (this._evm.DEBUG) {
@@ -499,6 +555,7 @@
      * @property {fee}        opcode.number Base fee of the opcode
      * @property {dynamicFee} opcode.dynamicFee Dynamic opcode fee
      * @property {boolean}    opcode.isAsync opcode is async
+     * @property {number}     opcode.code opcode code
      * @property {BigInt} gasLeft amount of gasLeft
      * @property {BigInt} gasRefund gas refund
      * @property {StateManager} stateManager a {@link StateManager} instance
@@ -510,6 +567,11 @@
      * @property {Uint8Array} memory the memory of the EVM as a `Uint8Array`
      * @property {BigInt} memoryWordCount current size of memory in words
      * @property {Address} codeAddress the address of the code which is currently being ran (this differs from `address` in a `DELEGATECALL` and `CALLCODE` call)
+     * @property {number} eofSection the current EOF code section referenced by the PC
+     * @property {Uint8Array} immediate the immediate argument of the opcode
+     * @property {Uint8Array} error the error data of the opcode (only present for REVERT)
+     * @property {number} eofFunctionDepth the depth of the function call (only present for EOF)
+     * @property {Array} storage an array of tuples, where each tuple contains a storage key and value
      */
     await this._evm['_emit']('step', eventObj)
   }

packages/evm/test/runCall.spec.ts

@@ -22,6 +22,7 @@
 import { createEVM } from '../src/index.ts'
 
 import type { EVMRunCallOpts } from '../src/types.ts'
+import { eip4844Data } from './testdata/eip4844.ts'
 
 // Non-protected Create2Address generator. Does not check if Uint8Arrays have the right padding.
 function create2address(sourceAddress: Address, codeHash: Uint8Array, salt: Uint8Array): Address {

packages/vm/test/api/t8ntool/t8ntool.spec.ts

@@ -1,10 +1,15 @@
 import { readFileSync } from 'fs'
-import { assert, describe, it } from 'vitest'
+import { assert, describe, expect, it } from 'vitest'
 
 import { TransitionTool } from '../../t8n/t8ntool.ts'
 
+import { Common, Hardfork, Mainnet } from '@ethereumjs/common'
+import { MerkleStateManager } from '@ethereumjs/statemanager'
+import { createTx } from '@ethereumjs/tx'
+import { Account, createAddressFromPrivateKey, hexToBytes, randomBytes } from '@ethereumjs/util'
+import { createVM, runTx } from '../../../src/index.ts'
+import { stepTraceJSON, summaryTraceJSON } from '../../t8n/helpers.ts'
 import type { T8NOptions } from '../../t8n/types.ts'
-
 const t8nDir = 'test/t8n/testdata/'
 
 const args: T8NOptions = {
@@ -24,6 +29,7 @@ const args: T8NOptions = {
     alloc: `output/allocTEST.json`,
   },
   log: false,
+  trace: false,
 }
 
 // This test is generated using `execution-spec-tests` commit 88cab2521322191b2ec7ef7d548740c0b0a264fc, running:
@@ -34,11 +40,110 @@ const args: T8NOptions = {
 describe('test runner config tests', () => {
   it('should run t8ntool with inputs and report the expected output', async () => {
     await TransitionTool.run(args)
-    const expectedResult = JSON.parse(readFileSync(`${t8nDir}/output/result.json`).toString())
-    const expectedAlloc = JSON.parse(readFileSync(`${t8nDir}/output/alloc.json`).toString())
-    const reportedResult = JSON.parse(readFileSync(`${t8nDir}/output/resultTEST.json`).toString())
-    const reportedAlloc = JSON.parse(readFileSync(`${t8nDir}/output/allocTEST.json`).toString())
+    const expectedResult = JSON.parse(readFileSync(`${t8nDir}output/result.json`).toString())
+    const expectedAlloc = JSON.parse(readFileSync(`${t8nDir}output/alloc.json`).toString())
+    const reportedResult = JSON.parse(readFileSync(`${t8nDir}output/resultTEST.json`).toString())
+    const reportedAlloc = JSON.parse(readFileSync(`${t8nDir}output/allocTEST.json`).toString())
     assert.deepStrictEqual(reportedResult, expectedResult, 'result matches expected result')
     assert.deepStrictEqual(reportedAlloc, expectedAlloc, 'alloc matches expected alloc')
   })
 })
+describe('trace tests', async () => {
+  it('should produce a valid step trace for a legacy contract', async () => {
+    const common = new Common({ chain: Mainnet, hardfork: Hardfork.Cancun })
+    const sm = new MerkleStateManager({ common })
+    const vm = await createVM({ common, stateManager: sm })
+    const bytecode = hexToBytes('0x604260005260206000F3') // PUSH1 42 PUSH1 00 MSTORE PUSH1 20 PUSH1 00 RETURN
+    const contractAddress = createAddressFromPrivateKey(randomBytes(32))
+    await vm.stateManager.putAccount(contractAddress)
+    await vm.stateManager.putCode(contractAddress, bytecode)
+    const trace: string[] = []
+    vm.evm.events!.on('step', (step) => {
+      trace.push(JSON.stringify(stepTraceJSON(step, true)))
+    })
+    vm.events!.on('afterTx', async (event) => {
+      trace.push(JSON.stringify(await summaryTraceJSON(event, vm)))
+    })
+    const tx = await createTx({
+      to: contractAddress,
+      data: bytecode,
+      gasLimit: 0xffffffff,
+      gasPrice: 0xf,
+    }).sign(randomBytes(32))
+    await runTx(vm, { tx, skipBalance: true, skipBlockGasLimitValidation: true, skipNonce: true })
+    assert.equal(trace.length, 7, 'trace length is 7')
+    assert.equal(JSON.parse(trace[6]).gasUsed, 21154)
+  })
+  it('should produce a trace of the correct length', async () => {
+    const common = new Common({
+      hardfork: Hardfork.Prague,
+      eips: [663, 3540, 3670, 4200, 4750, 5450, 6206, 7069, 7480, 7620, 7692, 7698],
+      chain: Mainnet,
+    })
+    const sm = new MerkleStateManager({ common })
+    const vm = await createVM({ common, stateManager: sm })
+    const code = hexToBytes('0xef000101000402000100030400010000800001305000ef')
+
+    const pk = randomBytes(32)
+    const caller = createAddressFromPrivateKey(pk) // caller address
+    const contractAddress = createAddressFromPrivateKey(randomBytes(32)) // contract address
+
+    await vm.stateManager.putCode(contractAddress, code)
+    await vm.stateManager.putAccount(caller, new Account(BigInt(0), BigInt(0x11111111)))
+
+    const tx = await createTx({
+      gasLimit: BigInt(0xffff),
+      gasPrice: 0x7,
+      to: contractAddress,
+    }).sign(pk)
+    const trace: string[] = []
+    vm.evm.events!.on('step', (step) => {
+      trace.push(JSON.stringify(stepTraceJSON(step, true)))
+    })
+    vm.events!.on('afterTx', async (event) => {
+      trace.push(JSON.stringify(await summaryTraceJSON(event, vm)))
+    })
+    const result = await runTx(vm, {
+      tx,
+      skipBalance: true,
+      skipNonce: true,
+      skipBlockGasLimitValidation: true,
+    })
+    assert.equal(result.execResult.executionGasUsed, BigInt(4))
+    assert.equal(trace.length, 4)
+  })
+  it('should produce a trace with storage activates', async () => {
+    const bytecode = hexToBytes('0x604260005560206000f3') // PUSH1 42 PUSH1 00 MSTORE PUSH1 20 PUSH1 00 RETURN
+    const common = new Common({ chain: Mainnet, hardfork: Hardfork.Cancun })
+    const sm = new MerkleStateManager({ common })
+    const vm = await createVM({ common, stateManager: sm })
+    const contractAddress = createAddressFromPrivateKey(randomBytes(32))
+    await vm.stateManager.putAccount(contractAddress)
+    await vm.stateManager.putCode(contractAddress, bytecode)
+    const trace: string[] = []
+    vm.evm.events!.on('step', (step) => {
+      trace.push(JSON.stringify(stepTraceJSON(step, false, true)))
+    })
+    vm.events!.on('afterTx', async (event) => {
+      trace.push(JSON.stringify(await summaryTraceJSON(event, vm)))
+    })
+    const tx = await createTx({
+      to: contractAddress,
+      gasLimit: 0xffffffff,
+      gasPrice: 0xf,
+    }).sign(randomBytes(32))
+
+    await runTx(vm, { tx, skipBalance: true, skipBlockGasLimitValidation: true, skipNonce: true })
+    assert.equal(trace.length, 7, 'trace length is 7')
+
+    // First step trace should have empty storage
+    const traceStepWithoutStorage = JSON.parse(trace[0])
+    expect(traceStepWithoutStorage.storage.length).toBe(0)
+
+    // Last step trace should have storage with actual value
+    const traceStepWithStorage = JSON.parse(trace[5])
+    assert.exists(traceStepWithStorage.storage)
+    expect(traceStepWithStorage.storage).toMatchObject([['0x0', '0x42']])
+    assert.equal(JSON.parse(trace[6]).gasUsed, 43115)
+  })
+})

packages/vm/test/t8n/ethereumjs-t8ntool.sh

@@ -5,4 +5,4 @@ if [[ "$1" == "--version" ]]; then
 fi
 SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
 export NODE_OPTIONS="--max-old-space-size=4096" 
-npx tsx "$SCRIPT_DIR/launchT8N.ts" "$@"
+npx tsx --conditions=typescript "$SCRIPT_DIR/launchT8N.ts" "$@"