Implement t8ntool to use for execution-spec-tests / VM Block Builder Adjustments

config/cspell-md.json

@@ -2,6 +2,8 @@
   "language": "en-US",
   "ignoreRegExpList": ["/0x[0-9A-Fa-f]+/"],
   "words": [
+    "t8ntool",
+    "calldatasize",
     "Dencun",
     "Hardfork",
     "acolytec",

config/cspell-ts.json

@@ -12,6 +12,7 @@
     }
   ],
   "words": [
+    "t8ntool",
     "!Json",
     "!Rpc",
     "Hardfork",

packages/vm/.gitignore

@@ -1,2 +1,4 @@
 .cachedb
 benchmarks/*.js
+test/t8n/testdata/output/allocTEST.json
+test/t8n/testdata/output/resultTEST.json

packages/vm/src/buildBlock.ts

@@ -90,7 +90,7 @@ export class BlockBuilder {
 
     this.headerData = {
       ...opts.headerData,
-      parentHash: opts.parentBlock.hash(),
+      parentHash: opts.headerData?.parentHash ?? opts.parentBlock.hash(),
       number: opts.headerData?.number ?? opts.parentBlock.header.number + BIGINT_1,
       gasLimit: opts.headerData?.gasLimit ?? opts.parentBlock.header.gasLimit,
       timestamp: opts.headerData?.timestamp ?? Math.round(Date.now() / 1000),
@@ -213,7 +213,10 @@ export class BlockBuilder {
    */
   async addTransaction(
     tx: TypedTransaction,
-    { skipHardForkValidation }: { skipHardForkValidation?: boolean } = {},
+    {
+      skipHardForkValidation,
+      allowNoBlobs,
+    }: { skipHardForkValidation?: boolean; allowNoBlobs?: boolean } = {},
   ) {
     this.checkStatus()
 
@@ -242,7 +245,11 @@ export class BlockBuilder {
 
       // Guard against the case if a tx came into the pool without blobs i.e. network wrapper payload
       if (blobTx.blobs === undefined) {
-        throw new Error('blobs missing for 4844 transaction')
+        // TODO: verify if we want this, do we want to allow the block builder to accept blob txs without the actual blobs?
+        // (these must have at least one `blobVersionedHashes`, this is verified at tx-level)
+        if (allowNoBlobs !== true) {
+          throw new Error('blobs missing for 4844 transaction')
+        }
       }
 
       if (this.blobGasUsed + BigInt(blobTx.numBlobs()) * blobGasPerBlob > blobGasLimit) {

packages/vm/src/runBlock.ts

@@ -494,14 +494,12 @@ export async function accumulateParentBlockHash(
 
   // getAccount with historyAddress will throw error as witnesses are not bundled
   // but we need to put account so as to query later for slot
-  try {
-    if ((await vm.stateManager.getAccount(historyAddress)) === undefined) {
-      const emptyHistoryAcc = new Account(BigInt(1))
-      await vm.evm.journal.putAccount(historyAddress, emptyHistoryAcc)
-    }
-  } catch (_e) {
-    const emptyHistoryAcc = new Account(BigInt(1))
-    await vm.evm.journal.putAccount(historyAddress, emptyHistoryAcc)
+  const code = await vm.stateManager.getCode(historyAddress)
+
+  if (code.length === 0) {
+    // Exit early, system contract has no code so no storage is written
+    // TODO: verify with Gabriel that this is fine regarding verkle (should we put an empty account?)
+    return
   }
 
   async function putBlockHash(vm: VM, hash: Uint8Array, number: bigint) {
@@ -536,24 +534,17 @@ export async function accumulateParentBeaconBlockRoot(vm: VM, root: Uint8Array,
   const timestampIndex = timestamp % historicalRootsLength
   const timestampExtended = timestampIndex + historicalRootsLength
 
-  /**
-   * Note: (by Jochem)
-   * If we don't do vm (put account if undefined / non-existent), block runner crashes because the beacon root address does not exist
-   * vm is hence (for me) again a reason why it should /not/ throw if the address does not exist
-   * All ethereum accounts have empty storage by default
-   */
-
   /**
    * Note: (by Gabriel)
    * Get account will throw an error in stateless execution b/c witnesses are not bundled
    * But we do need an account so we are able to put the storage
    */
-  try {
-    if ((await vm.stateManager.getAccount(parentBeaconBlockRootAddress)) === undefined) {
-      await vm.evm.journal.putAccount(parentBeaconBlockRootAddress, new Account())
-    }
-  } catch (_) {
-    await vm.evm.journal.putAccount(parentBeaconBlockRootAddress, new Account())
+  const code = await vm.stateManager.getCode(parentBeaconBlockRootAddress)
+
+  if (code.length === 0) {
+    // Exit early, system contract has no code so no storage is written
+    // TODO: verify with Gabriel that this is fine regarding verkle (should we put an empty account?)
+    return
   }
 
   await vm.stateManager.putStorage(

packages/vm/test/api/EIPs/eip-2935-historical-block-hashes.spec.ts

@@ -178,6 +178,8 @@ describe('EIP 2935: historical block hashes', () => {
         validateConsensus: false,
       })
       const vm = await createVM({ common: commonGenesis, blockchain })
+      // Ensure 2935 system code exists
+      await vm.stateManager.putCode(historyAddress, contract2935Code)
       commonGenesis.setHardforkBy({
         timestamp: 1,
       })
@@ -216,6 +218,8 @@ describe('EIP 2935: historical block hashes', () => {
         validateConsensus: false,
       })
       const vm = await createVM({ common, blockchain })
+      // Ensure 2935 system code exists
+      await vm.stateManager.putCode(historyAddress, contract2935Code)
       let lastBlock = (await vm.blockchain.getBlock(0)) as Block
       for (let i = 1; i <= blocksToBuild; i++) {
         lastBlock = await (

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

@@ -0,0 +1,44 @@
+import { readFileSync } from 'fs'
+import { assert, describe, it } from 'vitest'
+
+import { TransitionTool } from '../../t8n/t8ntool.js'
+
+import type { T8NOptions } from '../../t8n/types.js'
+
+const t8nDir = 'test/t8n/testdata/'
+
+const args: T8NOptions = {
+  state: {
+    fork: 'shanghai',
+    reward: BigInt(0),
+    chainid: BigInt(1),
+  },
+  input: {
+    alloc: `${t8nDir}input/alloc.json`,
+    txs: `${t8nDir}input/txs.json`,
+    env: `${t8nDir}input/env.json`,
+  },
+  output: {
+    basedir: t8nDir,
+    result: `output/resultTEST.json`,
+    alloc: `output/allocTEST.json`,
+  },
+  log: false,
+}
+
+// This test is generated using `execution-spec-tests` commit 88cab2521322191b2ec7ef7d548740c0b0a264fc, running:
+// fill -k test_push0_contracts[fork_Shanghai-blockchain_test-key_sstore] --fork Shanghai tests/shanghai/eip3855_push0 --evm-bin=<ETHEREUMJS_T8NTOOL_LAUNCHER.sh>
+
+// The test will run the TransitionTool using the inputs, and then compare if the output matches
+
+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())
+    assert.deepStrictEqual(reportedResult, expectedResult, 'result matches expected result')
+    assert.deepStrictEqual(reportedAlloc, expectedAlloc, 'alloc matches expected alloc')
+  })
+})

packages/vm/test/t8n/README.md

@@ -0,0 +1,40 @@
+# EVM T8NTool
+
+T8NTool, or Transition Tool, is a tool used to "fill tests" by test runners, for instance <https://github.com/ethereum/execution-spec-tests/>. These files take an input allocation (the pre-state), which contains the accounts (their balances, nonces, storage and code). It also provides an environment, which holds relevant data as current timestamp, previous block hashes, current gas limit, etc. Finally, it also provides a transactions file, which are the transactions to run on top of this pre-state and environment. It outputs the post-state and relevant other artifacts, such as tx receipts and their logs. Test fillers will take this output to generate relevant tests, such as Blockchain tests or State tests, which can then be directly ran in other clients, or using EthereumJS `npm run test:blockchain` or `npm run test:state`.
+
+## Using T8Ntool to fill `execution-spec-tests`
+
+To fill `execution-spec-tests` (or write own tests, and test those against the monorepo), follow these steps:
+
+1. Clone <https://github.com/ethereum/execution-spec-tests/>.
+2. Follow the installation steps: <https://github.com/ethereum/execution-spec-tests?tab=readme-ov-file#quick-start>.
+
+To fill tests, such as the EIP-1153 TSTORE/TLOAD tests, run:
+
+- `fill -vv -x --fork Cancun tests/cancun/eip1153_tstore/ --evm-bin=../ethereumjs-monorepo/packages/vm/test/t8n/ethereumjs-t8ntool.sh`
+
+Breaking down these arguments:
+
+- `-vv`: Verbose output
+- `-x`: Fail early if any of the test fillers fails
+- `--fork`: Fork to fill for
+- `--evm-bin`: relative/absolute path to t8ns `ethereumjs-t8ntool.sh`
+
+Optionally, it is also possible to add the `-k <TEST>` option which will only fill this certain test.
+
+## Debugging T8NTool with `execution-spec-tests`
+
+Sometimes it is unclear why a test fails, and one wants more verbose output (from the EthereumJS side). To do so, raw output from `execution-spec-tests` can be dumped by adding the `evm-dump-dir=<DIR>` flag to the `fill` command above. This will output `stdout`, `stderr`, the raw output allocation and the raw results (logs, receipts, etc.) to the `evm-dump-dir`. Additionally, if traces are wanted in `stdout`, add the `--log` flag to `ethereumjs-t8ntool.sh`, i.e. `tsx "$SCRIPT_DIR/launchT8N.ts" "$@" --log`.
+
+This will produce small EVM traces, like this:
+
+```typescript
+Processing new transaction...
+{
+  gasLeft: '9976184',
+  stack: [],
+  opName: 'CALLDATASIZE',
+  depth: 0,
+  address: '0x0000000000000000000000000000000000001000'
+}
+```

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

@@ -0,0 +1,8 @@
+#!/bin/bash
+if [[ "$1" == "--version" ]]; then
+    echo "ethereumjs t8n v1"
+    exit 0
+fi
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+export NODE_OPTIONS="--max-old-space-size=4096" 
+tsx "$SCRIPT_DIR/launchT8N.ts" "$@"

packages/vm/test/t8n/helpers.ts

@@ -0,0 +1,126 @@
+import yargs from 'yargs'
+import { hideBin } from 'yargs/helpers'
+
+import type { T8NOptions } from './types.js'
+
+export function getArguments() {
+  const argsParsed = yargs(hideBin(process.argv))
+    .parserConfiguration({
+      'dot-notation': false,
+    })
+    .option('state.fork', {
+      describe: 'Fork to use',
+      type: 'string',
+      demandOption: true,
+    })
+    .option('state.chainid', {
+      describe: 'ChainID to use',
+      type: 'string',
+      default: '1',
+    })
+    .option('state.reward', {
+      describe:
+        'Coinbase reward after running txs. If 0: coinbase account is touched and rewarded 0 wei. If -1, the coinbase account is not touched (default)',
+      type: 'string',
+      default: '-1',
+    })
+    .option('input.alloc', {
+      describe: 'Initial state allocation',
+      type: 'string',
+      demandOption: true,
+    })
+    .option('input.txs', {
+      describe: 'JSON input of txs to run on top of the initial state allocation',
+      type: 'string',
+      demandOption: true,
+    })
+    .option('input.env', {
+      describe: 'Input environment (coinbase, difficulty, etc.)',
+      type: 'string',
+      demandOption: true,
+    })
+    .option('output.basedir', {
+      describe: 'Base directory to write output to',
+      type: 'string',
+      demandOption: true,
+    })
+    .option('output.result', {
+      describe: 'File to write output results to (relative to `output.basedir`)',
+      type: 'string',
+      demandOption: true,
+    })
+    .option('output.alloc', {
+      describe: 'File to write output allocation to (after running the transactions)',
+      type: 'string',
+      demandOption: true,
+    })
+    .option('output.body', {
+      deprecate: true,
+      description: 'File to write transaction RLPs to (currently unused)',
+      type: 'string',
+    })
+    .option('log', {
+      describe: 'Optionally write light-trace logs to stdout',
+      type: 'boolean',
+      default: false,
+    })
+    .strict()
+    .help().argv
+
+  const args = argsParsed as any as T8NOptions
+
+  args.input = {
+    alloc: (<any>args)['input.alloc'],
+    txs: (<any>args)['input.txs'],
+    env: (<any>args)['input.env'],
+  }
+  args.output = {
+    basedir: (<any>args)['output.basedir'],
+    result: (<any>args)['output.result'],
+    alloc: (<any>args)['output.alloc'],
+  }
+  args.state = {
+    fork: (<any>args)['state.fork'],
+    reward: BigInt((<any>args)['state.reward']),
+    chainid: BigInt((<any>args)['state.chainid']),
+  }
+
+  return args
+}
+
+/**
+ * This function accepts an `inputs.env` which converts non-hex-prefixed numbers
+ * to a BigInt value, to avoid errors when converting non-prefixed hex strings to
+ * numbers
+ * @param input
+ * @returns converted input
+ */
+export function normalizeNumbers(input: any) {
+  const keys = [
+    'currentGasLimit',
+    'currentNumber',
+    'currentTimestamp',
+    'currentRandom',
+    'currentDifficulty',
+    'currentBaseFee',
+    'currentBlobGasUsed',
+    'currentExcessBlobGas',
+    'parentDifficulty',
+    'parentTimestamp',
+    'parentBaseFee',
+    'parentGasUsed',
+    'parentGasLimit',
+    'parentBlobGasUsed',
+    'parentExcessBlobGas',
+  ]
+
+  for (const key of keys) {
+    const value = input[key]
+    if (value !== undefined) {
+      if (value.substring(0, 2) !== '0x') {
+        input[key] = BigInt(value)
+      }
+    }
+  }
+  return input
+}

packages/vm/test/t8n/launchT8N.ts

@@ -0,0 +1,4 @@
+import { getArguments } from './helpers.js'
+import { TransitionTool } from './t8ntool.js'
+
+await TransitionTool.run(getArguments())