Add tracing to t8n (#3953)

* Add json traces to t8n tool support

* Update trace output to be one step per line

* move tracing to correct spot

* address feedback

* Clean up traces

* Cache pre-gas computation memory size for 3155

* Add jsonifyTrace helper and test

* more fixes

* Have t8n use typescript where available

* Partially fix gas calculation

* Implicitly call STOP if end of bytecode is reached

* spellcheck

* fix tests and opcode function lookup logic

* more fixes

* address feedback

* fix tests

* fix test

* Remove unneeded test data

* where is the outlog?

* REmove extra slash

* lint

* t8ntool: fix test

* remove Nify from whitelist

* client: remove console.log in test

* evm/vm: lowercase stepTraceJSON

* Move helpers to vm. Update tests.  Add eip7756 formatted fields

* Add test

* Comment bytecode

* Revert changes related to adding STOP code

* spellcheck

* Add remaining fields for eip 7756

* spellcheck

* fix functionDepth reference

* update comments

* Add logic to track storage in step hook

* memory is not optional

* pad keys to 32 bytes for storage

* Address feedback

* Simplify immediates computation

* Add eof test

* Revise bytecode

* Fix definition and presentation of immediates

* fix intermediates issue

* spellcheck

* address feedback

---------

Co-authored-by: Jochem Brouwer <[email protected]>
Co-authored-by: Holger Drewes <[email protected]>

Author: 3 people

config/cspell-ts.json

@@ -24,6 +24,7 @@
     }
   ],
   "words": [
+    "immediates",
     "unerasable",
     "bytelist",
     "bytestring",

packages/evm/src/eof/container.ts

@@ -246,6 +246,7 @@ class EOFHeader {
     // Write the start of the first code section into `codeStartPos`
     // Note: in EVM, if one would set the Program Counter to this byte, it would start executing the bytecode of the first code section
     this.codeStartPos = [relativeOffset]
+    this.getCodePosition(this.codeSizes.length - 1) // initialize code positions
   }
 
   sections() {
@@ -269,6 +270,27 @@ class EOFHeader {
     }
     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 @@ import {
   BIGINT_2,
   EthereumJSErrorWithoutCode,
   MAX_UINT64,
+  bigIntToBytes,
   bigIntToHex,
   bytesToBigInt,
   bytesToHex,
   equalsBytes,
+  setLengthLeft,
   setLengthRight,
 } from '@ethereumjs/util'
 import debugDefault from 'debug'
@@ -32,6 +34,7 @@ import type {
   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 @@ export interface RunState {
   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 @@ export interface InterpreterStep {
     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 @@ export class Interpreter {
       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 @@ export class Interpreter {
     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 @@ export class Interpreter {
         }
       }
 
-      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 @@ export class Interpreter {
 
     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 @@ export class Interpreter {
       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,72 @@ export class Interpreter {
     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] !== undefined &&
+      stackDelta[opcodeInfo.code].intermediates > 0
+    ) {
+      immediate = this._runState.code.slice(
+        this._runState.programCounter + 1, // immediates start "immediately" following current opcode
+        this._runState.programCounter + 1 + 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 +558,7 @@ export class Interpreter {
      * @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 +570,11 @@ export class Interpreter {
      * @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/eips/eof-runner.spec.ts

@@ -1,7 +1,7 @@
-import { Account, Address, hexToBytes } from '@ethereumjs/util'
+import { Account, Address, type PrefixedHexString, hexToBytes } from '@ethereumjs/util'
 import { assert, describe, it } from 'vitest'
 
-import { createEVM } from '../../src/index.ts'
+import { EOFContainer, createEVM } from '../../src/index.ts'
 
 import { getCommon } from './eof-utils.ts'
 
@@ -38,4 +38,19 @@ describe('EOF: should run a simple contract', async () => {
     // This costs 4 gas
     assert.equal(result.execResult.executionGasUsed, BigInt(4))
   })
+  it('should initialize code positions correctly', async () => {
+    const code = hexToBytes(
+      ('0xef0001' +
+        '010008' +
+        '02' +
+        '000200080003' +
+        '040000' +
+        '00' +
+        '0080000100000001' + // Section 1
+        '3050e30001600100' + // Section 2
+        '3050e4') as PrefixedHexString,
+    )
+    const eofContainer = new EOFContainer(code)
+    assert.doesNotThrow(() => eofContainer.header.getSectionFromProgramCounter(33))
+  })
 })

packages/evm/test/verkle.spec.ts

@@ -112,7 +112,7 @@ describe('verkle tests', () => {
     assert.equal(writtenChunks.length, 1)
     assert.equal(res.execResult.exceptionError?.error, undefined)
   })
-})
+}, 20000)
 describe('generate an execution witness', () => {
   it('should generate the correct execution witness from a prestate and changes', async () => {
     const preStateVKT: Record<PrefixedHexString, PrefixedHexString> = {
@@ -188,4 +188,4 @@ describe('generate an execution witness', () => {
     // Ensure sender account nonce is 1 in execution witness
     assert.equal(decodeVerkleLeafBasicData(hexToBytes(suffixDiff!.newValue!)).nonce, 1n)
   })
-})
+}, 20000)

packages/vm/test/api/EIPs/eip-4844-blobs.spec.ts

@@ -100,4 +100,4 @@ describe('EIP4844 tests', () => {
     assert.deepEqual(result.stateRoot, block.header.stateRoot)
     assert.deepEqual(result.logsBloom, block.header.logsBloom)
   })
-})
+}, 20000)

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

@@ -926,4 +926,4 @@ describe('EIP 4844 transaction tests', () => {
     assert.equal(res.blobGasUsed, 131072n, 'returns correct blob gas used for 1 blob')
     Blockchain.prototype.getBlock = oldGetBlockFunction
   })
-})
+}, 20000)