client: save preimages feature

packages/block/test/testdata/payload-kaustinen.json

@@ -242,9 +242,7 @@
       }
     ],
     "verkleProof": {
-      "otherStems": [
-        "0x9444524c2261a7086dd332bb05d79b1c63e74913a97b7b85c680368b19db0e"
-      ],
+      "otherStems": ["0x9444524c2261a7086dd332bb05d79b1c63e74913a97b7b85c680368b19db0e"],
       "depthExtensionPresent": "0x0a101209120808",
       "commitmentsByPath": [
         "0x1ba24c38c9aff43cf2793ed22a2fdd04282d558bcfad33589b5e4697c0662e45",
@@ -284,4 +282,4 @@
       }
     }
   }
-}
+}

packages/client/src/config.ts

@@ -327,6 +327,14 @@ export interface ConfigOptions {
   snapAvailabilityDepth?: bigint
   snapTransitionSafeDepth?: bigint
 
+  /**
+   * Save account keys preimages in the meta db (default: false)
+   */
+  savePreimages?: boolean
+
+  /**
+   * Enables stateless verkle block execution (default: false)
+   */
   statelessVerkle?: boolean
 }
 
@@ -431,6 +439,7 @@ export class Config {
   // Defaulting to false as experimental as of now
   public readonly enableSnapSync: boolean
   public readonly useStringValueTrieDB: boolean
+  public readonly savePreimages: boolean
 
   public readonly statelessVerkle: boolean
 
@@ -477,6 +486,7 @@ export class Config {
     this.debugCode = options.debugCode ?? Config.DEBUGCODE_DEFAULT
     this.mine = options.mine ?? false
     this.isSingleNode = options.isSingleNode ?? false
+    this.savePreimages = options.savePreimages ?? false
 
     if (options.vmProfileBlocks !== undefined || options.vmProfileTxs !== undefined) {
       this.vmProfilerOpts = {

packages/client/src/execution/preimage.ts

@@ -0,0 +1,27 @@
+import { DBKey, MetaDBManager } from '../util/metaDBManager'
+
+/**
+ * The `PreImagesManager` saves the preimages of hashed keys. This is necessary for the Verkle transition.
+ * A "PreImage" of a hash is whatever the input is to the hashed function. So, if one calls `keccak256(X)` with
+ * output `Y` then `X` is the preimage of `Y`. It thus serves to recover the input to the trapdoor hash function,
+ * which would otherwise not be feasible.
+ */
+export class PreimagesManager extends MetaDBManager {
+  /**
+   * Returns the preimage for a given hashed key
+   * @param key the hashed key
+   * @returns the preimage of the hashed key
+   */
+  async getPreimage(key: Uint8Array): Promise<Uint8Array | null> {
+    return this.get(DBKey.Preimage, key)
+  }
+
+  /**
+   * Saves a preimage to the db for a given hashed key.
+   * @param key The hashed key
+   * @param preimage The preimage to save
+   */
+  async savePreimage(key: Uint8Array, preimage: Uint8Array) {
+    await this.put(DBKey.Preimage, key, preimage)
+  }
+}

packages/client/src/execution/vmexecution.ts

@@ -12,7 +12,15 @@
   StatelessVerkleStateManager,
 } from '@ethereumjs/statemanager'
 import { Trie } from '@ethereumjs/trie'
-import { BIGINT_0, BIGINT_1, Lock, ValueEncoding, bytesToHex, equalsBytes } from '@ethereumjs/util'
+import {
+  BIGINT_0,
+  BIGINT_1,
+  Lock,
+  ValueEncoding,
+  bytesToHex,
+  equalsBytes,
+  hexToBytes,
+} from '@ethereumjs/util'
 import { VM } from '@ethereumjs/vm'
 
 import { Event } from '../types'
@@ -21,6 +29,7 @@
 
 import { Execution } from './execution'
 import { LevelDB } from './level'
+import { PreimagesManager } from './preimage'
 import { ReceiptsManager } from './receipt'
 
 import type { ExecutionOptions } from './execution'
@@ -50,6 +59,7 @@
   public chainStatus: ChainStatus | null = null
 
   public receiptsManager?: ReceiptsManager
+  public preimagesManager?: PreimagesManager
   private pendingReceipts?: Map<string, TxReceipt[]>
   private vmPromise?: Promise<number | null>
 
@@ -94,25 +104,34 @@
       ;(this.vm as any).blockchain = this.chain.blockchain
     }
 
-    if (this.metaDB && this.config.saveReceipts) {
-      this.receiptsManager = new ReceiptsManager({
-        chain: this.chain,
-        config: this.config,
-        metaDB: this.metaDB,
-      })
-      this.pendingReceipts = new Map()
-      this.chain.blockchain.events.addListener(
-        'deletedCanonicalBlocks',
-        async (blocks, resolve) => {
-          // Once a block gets deleted from the chain, delete the receipts also
-          for (const block of blocks) {
-            await this.receiptsManager?.deleteReceipts(block)
-          }
-          if (resolve !== undefined) {
-            resolve()
+    if (this.metaDB) {
+      if (this.config.saveReceipts) {
+        this.receiptsManager = new ReceiptsManager({
+          chain: this.chain,
+          config: this.config,
+          metaDB: this.metaDB,
+        })
+        this.pendingReceipts = new Map()
+        this.chain.blockchain.events.addListener(
+          'deletedCanonicalBlocks',
+          async (blocks, resolve) => {
+            // Once a block gets deleted from the chain, delete the receipts also
+            for (const block of blocks) {
+              await this.receiptsManager?.deleteReceipts(block)
+            }
+            if (resolve !== undefined) {
+              resolve()
+            }
           }
-        }
-      )
+        )
+      }
+      if (this.config.savePreimages) {
+        this.preimagesManager = new PreimagesManager({
+          chain: this.chain,
+          config: this.config,
+          metaDB: this.metaDB,
+        })
+      }
     }
   }
 
@@ -407,8 +426,18 @@
           if (skipHeaderValidation) {
             skipBlockchain = true
           }
+          const reportPreimages = this.config.savePreimages
 
-          const result = await vm.runBlock({ clearCache, ...opts, skipHeaderValidation })
+          const result = await vm.runBlock({
+            clearCache,
+            ...opts,
+            skipHeaderValidation,
+            reportPreimages,
+          })
+
+          if (this.config.savePreimages && result.preimages !== undefined) {
+            await this.savePreimages(result.preimages)
+          }
           receipts = result.receipts
         }
         if (receipts !== undefined) {
@@ -438,6 +467,14 @@
     return true
   }
 
+  async savePreimages(preimages: Map<string, Uint8Array>) {
+    if (this.preimagesManager !== undefined) {
+      for (const [key, preimage] of preimages) {
+        await this.preimagesManager.savePreimage(hexToBytes(key), preimage)
+      }
+    }
+  }
+
   /**
    * Sets the chain to a new head block.
    * Should only be used after {@link VMExecution.runWithoutSetHead}
@@ -677,6 +714,7 @@
                     clearCache,
                     skipBlockValidation,
                     skipHeaderValidation: true,
+                    reportPreimages: this.config.savePreimages,
                   })
                   const afterTS = Date.now()
                   const diffSec = Math.round((afterTS - beforeTS) / 1000)
@@ -691,6 +729,9 @@
                   }
 
                   await this.receiptsManager?.saveReceipts(block, result.receipts)
+                  if (this.config.savePreimages && result.preimages !== undefined) {
+                    await this.savePreimages(result.preimages)
+                  }
 
                   txCounter += block.transactions.length
                   // set as new head block

packages/client/src/types.ts

@@ -163,6 +163,7 @@ export interface ClientOpts {
   vmProfileTxs?: boolean
   loadBlocksFromRlp?: string
   pruneEngineCache?: boolean
+  savePreimages?: boolean
   verkleGenesisStateRoot?: Uint8Array
   statelessVerkle?: boolean
   engineNewpayloadMaxExecute?: number

packages/client/src/util/metaDBManager.ts

@@ -20,6 +20,7 @@ export enum DBKey {
   SkeletonBlockHashToNumber,
   SkeletonStatus,
   SkeletonUnfinalizedBlockByHash,
+  Preimage,
 }
 
 export interface MetaDBManagerOptions {