@feelyourprotocol/evm 8141.0.0

package/src/journal.ts

@@ -0,0 +1,317 @@
+import { Hardfork } from '@feelyourprotocol/common'
+import {
+  Address,
+  EthereumJSErrorWithoutCode,
+  RIPEMD160_ADDRESS_STRING,
+  bytesToHex,
+  bytesToUnprefixedHex,
+  hexToBytes,
+  isDebugEnabled,
+  stripHexPrefix,
+  unprefixedHexToBytes,
+} from '@feelyourprotocol/util'
+import debugDefault from 'debug'
+
+import type { Common, StateManagerInterface } from '@feelyourprotocol/common'
+import type { Account, PrefixedHexString } from '@feelyourprotocol/util'
+import type { Debugger } from 'debug'
+
+type AddressString = string
+type SlotString = string
+type WarmSlots = Set<SlotString>
+
+type JournalType = Map<AddressString, WarmSlots>
+
+/**
+ * Journal Diff Item:
+ * Index 0: remove warm address
+ * Index 1: remove warm slots for this warm address
+ * Index 2: remove touched
+ */
+
+type JournalDiffItem = [Set<AddressString>, Map<AddressString, Set<SlotString>>, Set<AddressString>]
+
+type JournalHeight = number
+
+export class Journal {
+  private stateManager: StateManagerInterface
+  private common: Common
+  private DEBUG: boolean
+  private _debug: Debugger
+
+  private journal!: JournalType
+  private alwaysWarmJournal!: Map<AddressString, Set<SlotString>>
+  private touched!: Set<AddressString>
+  private journalDiff!: [JournalHeight, JournalDiffItem][]
+
+  private journalHeight: JournalHeight
+
+  public accessList?: Map<AddressString, Set<SlotString>>
+  public preimages?: Map<PrefixedHexString, Uint8Array>
+
+  constructor(stateManager: StateManagerInterface, common: Common) {
+    // Skip DEBUG calls unless 'ethjs' included in environmental DEBUG variables
+    this.DEBUG = isDebugEnabled('ethjs')
+
+    this._debug = debugDefault('evm:journal')
+
+    // TODO maybe call into this.clearJournal
+    this.cleanJournal()
+    this.journalHeight = 0
+
+    this.stateManager = stateManager
+    this.common = common
+  }
+
+  /**
+   * Clears the internal `accessList` map, and mark this journal to start reporting
+   * which addresses and storages have been accessed
+   */
+  startReportingAccessList() {
+    this.accessList = new Map()
+  }
+
+  /**
+   * Clears the internal `preimages` map, and marks this journal to start reporting
+   * the images (hashed addresses) of the accounts that have been accessed
+   */
+  startReportingPreimages() {
+    this.preimages = new Map()
+  }
+
+  async putAccount(address: Address, account: Account | undefined) {
+    this.touchAddress(address)
+    return this.stateManager.putAccount(address, account)
+  }
+
+  async deleteAccount(address: Address) {
+    this.touchAddress(address)
+    await this.stateManager.deleteAccount(address)
+  }
+
+  private touchAddress(address: Address): void {
+    const str = address.toString().slice(2)
+    this.touchAccount(str)
+  }
+
+  private touchAccount(address: string) {
+    // If preimages are being reported, add the address to the preimages map
+    if (this.preimages !== undefined) {
+      const bytesAddress = unprefixedHexToBytes(address)
+      if (this.stateManager.getAppliedKey === undefined) {
+        throw EthereumJSErrorWithoutCode(
+          'touchAccount: stateManager.getAppliedKey can not be undefined if preimage storing is enabled',
+        )
+      }
+      const hashedKey = this.stateManager.getAppliedKey(bytesAddress)
+      this.preimages.set(bytesToHex(hashedKey), bytesAddress)
+    }
+
+    if (!this.touched.has(address)) {
+      this.touched.add(address)
+      const diffArr = this.journalDiff[this.journalDiff.length - 1][1]
+      diffArr[2].add(address)
+    }
+  }
+  async commit() {
+    this.journalHeight--
+    this.journalDiff.push([this.journalHeight, [new Set(), new Map(), new Set()]])
+    await this.stateManager.commit()
+  }
+
+  async checkpoint() {
+    this.journalHeight++
+    this.journalDiff.push([this.journalHeight, [new Set(), new Map(), new Set()]])
+    await this.stateManager.checkpoint()
+  }
+
+  async revert() {
+    // Loop backwards over the journal diff and stop if we are at a lower height than current journal height
+    // During this process, delete all items.
+    // TODO check this logic, if there is this array: height [4,3,4] and we revert height 4, then the final
+    // diff arr will be reverted, but it will stop at height 3, so [4,3] are both not reverted..?
+    let finalI: number
+    for (let i = this.journalDiff.length - 1; i >= 0; i--) {
+      finalI = i
+      const [height, diff] = this.journalDiff[i]
+      if (height < this.journalHeight) {
+        break
+      }
+
+      const addressSet = diff[0]
+      const slotsMap = diff[1]
+      const touchedSet = diff[2]
+
+      for (const address of addressSet) {
+        // Sanity check, journal should have the item
+        if (this.journal.has(address)) {
+          this.journal.delete(address)
+        }
+      }
+
+      for (const [address, delSlots] of slotsMap) {
+        // Sanity check, the address SHOULD be in the journal
+        if (this.journal.has(address)) {
+          const slots = this.journal.get(address)!
+          for (const delSlot of delSlots) {
+            slots.delete(delSlot)
+          }
+        }
+      }
+
+      for (const address of touchedSet) {
+        // Delete the address from the journal
+        if (address !== RIPEMD160_ADDRESS_STRING) {
+          // If RIPEMD160 is touched, keep it touched.
+          // Default behavior for others.
+          this.touched.delete(address)
+        }
+      }
+    }
+
+    // the final diffs are reverted and we can dispose those
+    this.journalDiff = this.journalDiff.slice(0, finalI! + 1)
+
+    this.journalHeight--
+
+    await this.stateManager.revert()
+  }
+
+  public cleanJournal() {
+    this.journalHeight = 0
+    this.journal = new Map()
+    this.alwaysWarmJournal = new Map()
+    this.touched = new Set()
+    this.journalDiff = [[0, [new Set(), new Map(), new Set()]]]
+  }
+
+  /**
+   * Removes accounts from the state trie that have been touched,
+   * as defined in EIP-161 (https://eips.ethereum.org/EIPS/eip-161).
+   * Also cleanups any other internal fields
+   */
+  async cleanup(): Promise<void> {
+    if (this.common.gteHardfork(Hardfork.SpuriousDragon)) {
+      for (const addressHex of this.touched) {
+        const address = new Address(hexToBytes(`0x${addressHex}`))
+        const account = await this.stateManager.getAccount(address)
+        if (account === undefined || account.isEmpty()) {
+          await this.deleteAccount(address)
+          if (this.DEBUG) {
+            this._debug(`Cleanup touched account address=${address} (>= SpuriousDragon)`)
+          }
+        }
+      }
+    }
+    this.cleanJournal()
+    delete this.accessList
+    delete this.preimages
+  }
+
+  addAlwaysWarmAddress(addressStr: string, addToAccessList: boolean = false) {
+    const address = stripHexPrefix(addressStr)
+    if (!this.alwaysWarmJournal.has(address)) {
+      this.alwaysWarmJournal.set(address, new Set())
+    }
+    if (addToAccessList && this.accessList !== undefined) {
+      if (!this.accessList.has(address)) {
+        this.accessList.set(address, new Set())
+      }
+    }
+  }
+
+  addAlwaysWarmSlot(addressStr: string, slotStr: string, addToAccessList: boolean = false) {
+    const address = stripHexPrefix(addressStr)
+    this.addAlwaysWarmAddress(address, addToAccessList)
+    const slotsSet = this.alwaysWarmJournal.get(address)!
+    const slot = stripHexPrefix(slotStr)
+    slotsSet.add(slot)
+    if (addToAccessList && this.accessList !== undefined) {
+      this.accessList.get(address)!.add(slot)
+    }
+  }
+
+  /**
+   * Returns true if the address is warm in the current context
+   * @param address - The address (as a Uint8Array) to check
+   */
+  isWarmedAddress(address: Uint8Array): boolean {
+    // Using deprecated bytesToUnprefixedHex for performance: this is a hot path used in Map/Set lookups.
+    const addressHex = bytesToUnprefixedHex(address)
+    const warm = this.journal.has(addressHex) || this.alwaysWarmJournal.has(addressHex)
+    return warm
+  }
+
+  /**
+   * Add a warm address in the current context
+   * @param addressArr - The address (as a Uint8Array) to check
+   */
+  addWarmedAddress(addressArr: Uint8Array): void {
+    // Using deprecated bytesToUnprefixedHex for performance: this is a hot path used in Map/Set operations.
+    const address = bytesToUnprefixedHex(addressArr)
+    if (!this.journal.has(address)) {
+      this.journal.set(address, new Set())
+      const diffArr = this.journalDiff[this.journalDiff.length - 1][1]
+      diffArr[0].add(address)
+    }
+    if (this.accessList !== undefined) {
+      if (!this.accessList.has(address)) {
+        this.accessList.set(address, new Set())
+      }
+    }
+  }
+
+  /**
+   * Returns true if the slot of the address is warm
+   * @param address - The address (as a Uint8Array) to check
+   * @param slot - The slot (as a Uint8Array) to check
+   */
+  isWarmedStorage(address: Uint8Array, slot: Uint8Array): boolean {
+    // Using deprecated bytesToUnprefixedHex for performance: this is a hot path used in Map/Set lookups.
+    const addressHex = bytesToUnprefixedHex(address)
+    const slots = this.journal.get(addressHex)
+    if (slots === undefined) {
+      if (this.alwaysWarmJournal.has(addressHex)) {
+        return this.alwaysWarmJournal.get(addressHex)!.has(bytesToUnprefixedHex(slot))
+      }
+      return false
+    }
+    if (slots.has(bytesToUnprefixedHex(slot))) {
+      return true
+    } else if (this.alwaysWarmJournal.has(addressHex)) {
+      return this.alwaysWarmJournal.get(addressHex)!.has(bytesToUnprefixedHex(slot))
+    }
+    return false
+  }
+
+  /**
+   * Mark the storage slot in the address as warm in the current context
+   * @param address - The address (as a Uint8Array) to check
+   * @param slot - The slot (as a Uint8Array) to check
+   */
+  addWarmedStorage(address: Uint8Array, slot: Uint8Array): void {
+    // Using deprecated bytesToUnprefixedHex for performance: this is a hot path used in Map/Set operations.
+    const addressHex = bytesToUnprefixedHex(address)
+    let slots = this.journal.get(addressHex)
+    if (slots === undefined) {
+      this.addWarmedAddress(address)
+      slots = this.journal.get(addressHex)
+    }
+    const slotStr = bytesToUnprefixedHex(slot)
+    if (!slots!.has(slotStr)) {
+      slots!.add(slotStr)
+      const diff = this.journalDiff[this.journalDiff.length - 1][1]
+      const addressSlotMap = diff[1]
+      if (!addressSlotMap.has(addressHex)) {
+        addressSlotMap.set(addressHex, new Set())
+      }
+      const slotsSet = addressSlotMap.get(addressHex)!
+      slotsSet.add(slotStr)
+    }
+    if (this.accessList !== undefined) {
+      // Note: in `addWarmedAddress` the address is added to warm addresses
+      const addrSet = this.accessList.get(addressHex)!
+      addrSet.add(slotStr)
+    }
+  }
+}

package/src/logger.ts

@@ -0,0 +1,180 @@
+import { EthereumJSErrorWithoutCode } from '@feelyourprotocol/util'
+
+type EVMPerformanceLogEntry = {
+  calls: number
+  time: number
+  gasUsed: number
+  staticGas?: number
+  dynamicGasUsed?: number
+}
+
+export type EVMPerformanceLogOutput = {
+  calls: number // Amount this opcode/precompile was called
+  totalTime: number // Amount of seconds taken for this opcode/precompile (rounded to 3 digits)
+  avgTimePerCall: number // Avg time per call of this opcode/precompile (rounded to 3 digits)
+  gasUsed: number // Total amount of gas used by this opcode/precompile
+  millionGasPerSecond: number // How much million gas is executed per second (rounded to 3 digits)
+  blocksPerSlot: number // How many blocks is executed per beacon chain slot (rounded to 3 digits)
+  tag: string // opcode/precompile tag
+  staticGasUsed?: number // total static gas units spent
+  dynamicGasUsed?: number // total dynamic gas units spent
+  staticGas?: number // static gas of the opcode
+}
+
+type EVMPerformanceLogs = {
+  [tag: string]: EVMPerformanceLogEntry
+}
+
+const blockGasLimit = 30_000_000 // Block gas limit
+const slotTime = 12 // Time in seconds per slot
+
+// Normalize constant to check if execution time is above one block per slot (>=1) or not (<1)
+const bpsNormalizer = blockGasLimit / slotTime
+
+export class Timer {
+  private startTime: number
+  private runTime = 0
+  tag: string
+
+  constructor(tag: string) {
+    this.tag = tag
+    this.startTime = performance.now()
+  }
+
+  pause() {
+    this.runTime = this.runTime + performance.now() - this.startTime
+  }
+
+  unpause() {
+    this.startTime = performance.now()
+  }
+
+  time() {
+    return (performance.now() - this.startTime + this.runTime) / 1000
+  }
+}
+
+export class EVMPerformanceLogger {
+  private opcodes!: EVMPerformanceLogs
+  private precompiles!: EVMPerformanceLogs
+
+  private currentTimer?: Timer
+
+  constructor() {
+    this.clear()
+  }
+
+  clear() {
+    this.opcodes = {}
+    this.precompiles = {}
+  }
+
+  getLogs() {
+    // Return nicely formatted logs
+    function getLogsFor(obj: EVMPerformanceLogs) {
+      const output: EVMPerformanceLogOutput[] = []
+      for (const key in obj) {
+        const field = obj[key]
+        const gasPerSecond = field.gasUsed / field.time
+        const entry: EVMPerformanceLogOutput = {
+          calls: field.calls,
+          totalTime: Math.round(field.time * 1e6) / 1e3,
+          avgTimePerCall: Math.round((field.time / field.calls) * 1e6) / 1e3,
+          gasUsed: field.gasUsed,
+          millionGasPerSecond: Math.round(gasPerSecond / 1e3) / 1e3,
+          blocksPerSlot: Math.round((gasPerSecond / bpsNormalizer) * 1e3) / 1e3,
+          tag: key,
+        }
+        if (field.dynamicGasUsed !== undefined) {
+          // This is an opcode entry
+          entry.staticGas = field.staticGas
+          entry.staticGasUsed = field.staticGas! * field.calls
+          entry.dynamicGasUsed = field.dynamicGasUsed
+        }
+        output.push(entry)
+      }
+
+      output.sort((a, b) => {
+        return b.millionGasPerSecond - a.millionGasPerSecond
+      })
+
+      return output
+    }
+
+    return {
+      opcodes: getLogsFor(this.opcodes),
+      precompiles: getLogsFor(this.precompiles),
+    }
+  }
+
+  hasTimer() {
+    return this.currentTimer !== undefined
+  }
+
+  // Start a new timer
+  // Only one timer can be timing at the same time
+  startTimer(tag: string) {
+    if (this.currentTimer !== undefined) {
+      throw EthereumJSErrorWithoutCode('Cannot have two timers running at the same time')
+    }
+
+    this.currentTimer = new Timer(tag)
+    return this.currentTimer
+  }
+
+  // Pauses current timer and returns that timer
+  pauseTimer() {
+    const timer = this.currentTimer
+    if (timer === undefined) {
+      throw EthereumJSErrorWithoutCode('No timer to pause')
+    }
+    timer.pause()
+    this.currentTimer = undefined
+    return timer
+  }
+
+  // Unpauses current timer and returns that timer
+  unpauseTimer(timer: Timer) {
+    if (this.currentTimer !== undefined) {
+      throw EthereumJSErrorWithoutCode('Cannot unpause timer: another timer is already running')
+    }
+    timer.unpause()
+    this.currentTimer = timer
+  }
+
+  // Stops a timer from running
+  stopTimer(
+    timer: Timer,
+    gasUsed: number,
+    targetTimer: 'precompiles' | 'opcodes' = 'opcodes',
+    staticGas?: number,
+    dynamicGas?: number,
+  ) {
+    if (this.currentTimer === undefined || this.currentTimer !== timer) {
+      throw EthereumJSErrorWithoutCode('Cannot stop timer: another timer is already running')
+    }
+    const time = timer.time()
+    const tag = timer.tag
+    this.currentTimer = undefined
+
+    // Update the fields
+    const target = this[targetTimer]
+    if (target[tag] === undefined) {
+      target[tag] = {
+        calls: 0,
+        time: 0,
+        gasUsed: 0,
+      }
+    }
+    const obj = target[tag]
+
+    obj.calls++
+    obj.time += time
+    obj.gasUsed += gasUsed
+
+    if (targetTimer === 'opcodes') {
+      obj.staticGas = staticGas
+      obj.dynamicGasUsed = (obj.dynamicGasUsed ?? 0) + dynamicGas!
+    }
+  }
+}

package/src/memory.ts

@@ -0,0 +1,82 @@
+import { EthereumJSErrorWithoutCode, concatBytes } from '@feelyourprotocol/util'
+
+const ceil = (value: number, ceiling: number): number => {
+  const r = value % ceiling
+  if (r === 0) {
+    return value
+  } else {
+    return value + ceiling - r
+  }
+}
+
+const CONTAINER_SIZE = 8192
+
+/**
+ * Memory implements a simple memory model
+ * for the ethereum virtual machine.
+ */
+export class Memory {
+  _store: Uint8Array
+
+  constructor() {
+    this._store = new Uint8Array(CONTAINER_SIZE)
+  }
+
+  /**
+   * Extends the memory given an offset and size. Rounds extended
+   * memory to word-size.
+   */
+  extend(offset: number, size: number) {
+    if (size === 0) {
+      return
+    }
+
+    const newSize = ceil(offset + size, 32)
+    const sizeDiff = newSize - this._store.length
+    if (sizeDiff > 0) {
+      const expandBy = Math.ceil(sizeDiff / CONTAINER_SIZE) * CONTAINER_SIZE
+      this._store = concatBytes(this._store, new Uint8Array(expandBy))
+    }
+  }
+
+  /**
+   * Writes a byte array with length `size` to memory, starting from `offset`.
+   * @param offset - Starting position
+   * @param size - How many bytes to write
+   * @param value - Value
+   */
+  write(offset: number, size: number, value: Uint8Array) {
+    if (size === 0) {
+      return
+    }
+
+    this.extend(offset, size)
+
+    if (value.length !== size) throw EthereumJSErrorWithoutCode('Invalid value size')
+    if (offset + size > this._store.length)
+      throw EthereumJSErrorWithoutCode('Value exceeds memory capacity')
+
+    this._store.set(value, offset)
+  }
+
+  /**
+   * Reads a slice of memory from `offset` till `offset + size` as a `Uint8Array`.
+   * It fills up the difference between memory's length and `offset + size` with zeros.
+   * @param offset - Starting position
+   * @param size - How many bytes to read
+   * @param avoidCopy - Avoid memory copy if possible for performance reasons (optional)
+   */
+  read(offset: number, size: number, avoidCopy?: boolean): Uint8Array<ArrayBuffer> {
+    this.extend(offset, size)
+
+    const loaded = this._store.subarray(offset, offset + size) as Uint8Array<ArrayBuffer>
+    if (avoidCopy === true) {
+      return loaded
+    }
+    const returnBytes = new Uint8Array(size)
+    // Copy the stored "buffer" from memory into the return Uint8Array
+    returnBytes.set(loaded)
+
+    return returnBytes
+  }
+}

package/src/message.ts

@@ -0,0 +1,114 @@
+import { BIGINT_0, EthereumJSErrorWithoutCode, createZeroAddress } from '@feelyourprotocol/util'
+
+import type { BinaryTreeAccessWitnessInterface } from '@feelyourprotocol/common'
+import type { Address, PrefixedHexString } from '@feelyourprotocol/util'
+import type { PrecompileFunc } from './precompiles/index.ts'
+import type { EOFEnv, SelfdestructMap } from './types.ts'
+
+const defaults = {
+  value: BIGINT_0,
+  caller: createZeroAddress(),
+  data: new Uint8Array(0),
+  depth: 0,
+  isStatic: false,
+  isCompiled: false,
+  delegatecall: false,
+  gasRefund: BIGINT_0,
+}
+
+interface MessageOpts {
+  to?: Address
+  value?: bigint
+  caller?: Address
+  gasLimit: bigint
+  data?: Uint8Array
+  eofCallData?: Uint8Array
+  depth?: number
+  code?: Uint8Array | PrecompileFunc
+  codeAddress?: Address
+  isStatic?: boolean
+  isCompiled?: boolean
+  salt?: Uint8Array
+  /**
+   * Selfdestructed addresses mapped to their beneficiary, see {@link Message.selfdestruct}
+   */
+  selfdestruct?: SelfdestructMap
+  /**
+   * Map of addresses which were created (used in EIP 6780)
+   */
+  createdAddresses?: Set<PrefixedHexString>
+  delegatecall?: boolean
+  gasRefund?: bigint
+  blobVersionedHashes?: PrefixedHexString[]
+  accessWitness?: BinaryTreeAccessWitnessInterface
+}
+
+export class Message {
+  to?: Address
+  value: bigint
+  caller: Address
+  gasLimit: bigint
+  data: Uint8Array
+  eofCallData?: Uint8Array // Only used in EOFCreate to signal an EOF contract to be created with this calldata (via EOFCreate)
+  isCreate?: boolean
+  depth: number
+  code?: Uint8Array | PrecompileFunc
+  _codeAddress?: Address
+  isStatic: boolean
+  isCompiled: boolean
+  salt?: Uint8Array
+  eof?: EOFEnv
+  chargeCodeAccesses?: boolean
+  /**
+   * Selfdestructed addresses mapped to their beneficiary.
+   */
+  selfdestruct?: SelfdestructMap
+  /**
+   * Map of addresses which were created (used in EIP 6780)
+   */
+  createdAddresses?: Set<PrefixedHexString>
+  delegatecall: boolean
+  gasRefund: bigint // Keeps track of the gasRefund at the start of the frame (used for journaling purposes)
+  /**
+   * List of versioned hashes if message is a blob transaction in the outer VM
+   */
+  blobVersionedHashes?: PrefixedHexString[]
+  accessWitness?: BinaryTreeAccessWitnessInterface
+
+  constructor(opts: MessageOpts) {
+    this.to = opts.to
+    this.value = opts.value ?? defaults.value
+    this.caller = opts.caller ?? defaults.caller
+    this.gasLimit = opts.gasLimit
+    this.data = opts.data ?? defaults.data
+    this.eofCallData = opts.eofCallData
+    this.depth = opts.depth ?? defaults.depth
+    this.code = opts.code
+    this._codeAddress = opts.codeAddress
+    this.isStatic = opts.isStatic ?? defaults.isStatic
+    this.isCompiled = opts.isCompiled ?? defaults.isCompiled
+    this.salt = opts.salt
+    this.selfdestruct = opts.selfdestruct
+    this.createdAddresses = opts.createdAddresses
+    this.delegatecall = opts.delegatecall ?? defaults.delegatecall
+    this.gasRefund = opts.gasRefund ?? defaults.gasRefund
+    this.blobVersionedHashes = opts.blobVersionedHashes
+    this.accessWitness = opts.accessWitness
+    if (this.value < 0) {
+      throw EthereumJSErrorWithoutCode(`value field cannot be negative, received ${this.value}`)
+    }
+  }
+
+  /**
+   * Note: should only be called in instances where `_codeAddress` or `to` is defined.
+   */
+  get codeAddress(): Address {
+    const codeAddress = this._codeAddress ?? this.to
+    if (!codeAddress) {
+      throw EthereumJSErrorWithoutCode('Missing codeAddress')
+    }
+    return codeAddress
+  }
+}
+
+export type MessageWithTo = Message & Pick<Required<MessageOpts>, 'to'>