@feelyourprotocol/evm 8141.0.0

package/src/precompiles/index.ts

@@ -0,0 +1,344 @@
+import { Hardfork } from '@feelyourprotocol/common'
+import { type Address, type PrefixedHexString, bytesToUnprefixedHex } from '@feelyourprotocol/util'
+
+import { precompile0a } from './0a-kzg-point-evaluation.ts'
+import { precompile0b } from './0b-bls12-g1add.ts'
+import { precompile0c } from './0c-bls12-g1msm.ts'
+import { precompile0d } from './0d-bls12-g2add.ts'
+import { precompile0e } from './0e-bls12-g2msm.ts'
+import { precompile0f } from './0f-bls12-pairing.ts'
+import { precompile01 } from './01-ecrecover.ts'
+import { precompile02 } from './02-sha256.ts'
+import { precompile03 } from './03-ripemd160.ts'
+import { precompile04 } from './04-identity.ts'
+import { precompile05 } from './05-modexp.ts'
+import { precompile06 } from './06-bn254-add.ts'
+import { precompile07 } from './07-bn254-mul.ts'
+import { precompile08 } from './08-bn254-pairing.ts'
+import { precompile09 } from './09-blake2f.ts'
+import { precompile10 } from './10-bls12-map-fp-to-g1.ts'
+import { precompile11 } from './11-bls12-map-fp2-to-g2.ts'
+import { precompile100 } from './100-p256verify.ts'
+import { MCLBLS, NobleBLS } from './bls12_381/index.ts'
+import { NobleBN254, RustBN254 } from './bn254/index.ts'
+
+import type { Common } from '@feelyourprotocol/common'
+import type { PrecompileFunc, PrecompileInput } from './types.ts'
+
+interface PrecompileEntry {
+  address: string
+  check: PrecompileAvailabilityCheckType
+  precompile: PrecompileFunc
+  name: string
+}
+
+interface Precompiles {
+  [key: string]: PrecompileFunc
+}
+
+type PrecompileAvailabilityCheckType =
+  | PrecompileAvailabilityCheckTypeHardfork
+  | PrecompileAvailabilityCheckTypeEIP
+
+export type PrecompileAvailabilityCheck =
+  (typeof PrecompileAvailabilityCheck)[keyof typeof PrecompileAvailabilityCheck]
+
+export const PrecompileAvailabilityCheck = {
+  EIP: 'eip',
+  Hardfork: 'hardfork',
+} as const
+
+interface PrecompileAvailabilityCheckTypeHardfork {
+  type: typeof PrecompileAvailabilityCheck.Hardfork
+  param: string
+}
+
+interface PrecompileAvailabilityCheckTypeEIP {
+  type: typeof PrecompileAvailabilityCheck.EIP
+  param: number
+}
+const BYTES_19 = '00000000000000000000000000000000000000'
+const ripemdPrecompileAddress = BYTES_19 + '03'
+
+const precompileEntries: PrecompileEntry[] = [
+  {
+    address: BYTES_19 + '01',
+    check: {
+      type: PrecompileAvailabilityCheck.Hardfork,
+      param: Hardfork.Chainstart,
+    },
+    precompile: precompile01,
+    name: 'ECRECOVER (0x01)',
+  },
+  {
+    address: BYTES_19 + '02',
+    check: {
+      type: PrecompileAvailabilityCheck.Hardfork,
+      param: Hardfork.Chainstart,
+    },
+    precompile: precompile02,
+    name: 'SHA256 (0x02)',
+  },
+  {
+    address: BYTES_19 + '03',
+    check: {
+      type: PrecompileAvailabilityCheck.Hardfork,
+      param: Hardfork.Chainstart,
+    },
+    precompile: precompile03,
+    name: 'RIPEMD160 (0x03)',
+  },
+  {
+    address: BYTES_19 + '04',
+    check: {
+      type: PrecompileAvailabilityCheck.Hardfork,
+      param: Hardfork.Chainstart,
+    },
+    precompile: precompile04,
+    name: 'IDENTITY (0x04)',
+  },
+  {
+    address: BYTES_19 + '05',
+    check: {
+      type: PrecompileAvailabilityCheck.Hardfork,
+      param: Hardfork.Byzantium,
+    },
+    precompile: precompile05,
+    name: 'MODEXP (0x05)',
+  },
+  {
+    address: BYTES_19 + '06',
+    check: {
+      type: PrecompileAvailabilityCheck.Hardfork,
+      param: Hardfork.Byzantium,
+    },
+    precompile: precompile06,
+    name: 'BN254_ADD (0x06)',
+  },
+  {
+    address: BYTES_19 + '07',
+    check: {
+      type: PrecompileAvailabilityCheck.Hardfork,
+      param: Hardfork.Byzantium,
+    },
+    precompile: precompile07,
+    name: 'BN254_MUL (0x07)',
+  },
+  {
+    address: BYTES_19 + '08',
+    check: {
+      type: PrecompileAvailabilityCheck.Hardfork,
+      param: Hardfork.Byzantium,
+    },
+    precompile: precompile08,
+    name: 'BN254_PAIRING (0x08)',
+  },
+  {
+    address: BYTES_19 + '09',
+    check: {
+      type: PrecompileAvailabilityCheck.Hardfork,
+      param: Hardfork.Istanbul,
+    },
+    precompile: precompile09,
+    name: 'BLAKE2f (0x09)',
+  },
+  {
+    address: BYTES_19 + '0a',
+    check: {
+      type: PrecompileAvailabilityCheck.EIP,
+      param: 4844,
+    },
+    precompile: precompile0a,
+    name: 'KZG_POINT_EVALUATION (0x0a)',
+  },
+  {
+    address: BYTES_19 + '0b',
+    check: {
+      type: PrecompileAvailabilityCheck.EIP,
+      param: 2537,
+    },
+    precompile: precompile0b,
+    name: 'BLS12_G1ADD (0x0b)',
+  },
+  {
+    address: BYTES_19 + '0c',
+    check: {
+      type: PrecompileAvailabilityCheck.EIP,
+      param: 2537,
+    },
+    precompile: precompile0c,
+    name: 'BLS12_G1MSM (0x0c)',
+  },
+  {
+    address: BYTES_19 + '0d',
+    check: {
+      type: PrecompileAvailabilityCheck.EIP,
+      param: 2537,
+    },
+    precompile: precompile0d,
+    name: 'BLS12_G2ADD (0x0d)',
+  },
+  {
+    address: BYTES_19 + '0e',
+    check: {
+      type: PrecompileAvailabilityCheck.EIP,
+      param: 2537,
+    },
+    precompile: precompile0e,
+    name: 'BLS12_G2MSM (0x0e)',
+  },
+  {
+    address: BYTES_19 + '0f',
+    check: {
+      type: PrecompileAvailabilityCheck.EIP,
+      param: 2537,
+    },
+    precompile: precompile0f,
+    name: 'BLS12_PAIRING (0x0f)',
+  },
+  {
+    address: BYTES_19 + '10',
+    check: {
+      type: PrecompileAvailabilityCheck.EIP,
+      param: 2537,
+    },
+    precompile: precompile10,
+    name: 'BLS12_MAP_FP_TO_G1 (0x10)',
+  },
+  {
+    address: BYTES_19 + '11',
+    check: {
+      type: PrecompileAvailabilityCheck.EIP,
+      param: 2537,
+    },
+    precompile: precompile11,
+    name: 'BLS12_MAP_FP_TO_G2 (0x11)',
+  },
+  {
+    address: '0000000000000000000000000000000000000100',
+    check: {
+      type: PrecompileAvailabilityCheck.EIP,
+      param: 7951,
+    },
+    precompile: precompile100,
+    name: 'P256VERIFY (0x100)',
+  },
+]
+
+const precompiles: Precompiles = {
+  [BYTES_19 + '01']: precompile01,
+  [BYTES_19 + '02']: precompile02,
+  [ripemdPrecompileAddress]: precompile03,
+  [BYTES_19 + '04']: precompile04,
+  [BYTES_19 + '05']: precompile05,
+  [BYTES_19 + '06']: precompile06,
+  [BYTES_19 + '07']: precompile07,
+  [BYTES_19 + '08']: precompile08,
+  [BYTES_19 + '09']: precompile09,
+  [BYTES_19 + '0a']: precompile0a,
+  [BYTES_19 + '0b']: precompile0b,
+  [BYTES_19 + '0c']: precompile0c,
+  [BYTES_19 + '0d']: precompile0d,
+  [BYTES_19 + '0e']: precompile0e,
+  [BYTES_19 + '0f']: precompile0f,
+  [BYTES_19 + '10']: precompile10,
+  [BYTES_19 + '11']: precompile11,
+  '0000000000000000000000000000000000000100': precompile100,
+}
+
+/**
+ * Specifies a precompile to remove from the EVM.
+ * The address can be an `Address` instance or a `0x`-prefixed hex string.
+ */
+type DeletePrecompile = {
+  address: Address | PrefixedHexString
+}
+
+/**
+ * Specifies a precompile to add to (or override in) the EVM.
+ * The address can be an `Address` instance or a `0x`-prefixed hex string.
+ */
+type AddPrecompile = {
+  address: Address | PrefixedHexString
+  function: PrecompileFunc
+}
+
+/**
+ * A custom precompile entry: either an addition/override or a deletion.
+ *
+ * ```ts
+ * // Add a custom precompile at a new address
+ * const add: CustomPrecompile = {
+ *   address: '0x0000000000000000000000000000000000ff0001',
+ *   function: myPrecompileImpl,
+ * }
+ * // Delete an existing precompile
+ * const del: CustomPrecompile = {
+ *   address: '0x0000000000000000000000000000000000000002',
+ * }
+ * ```
+ */
+type CustomPrecompile = AddPrecompile | DeletePrecompile
+
+function resolvePrecompileAddress(address: Address | PrefixedHexString): string {
+  if (typeof address === 'string') {
+    return address.slice(2).padStart(40, '0').toLowerCase()
+  }
+  return bytesToUnprefixedHex(address.bytes)
+}
+
+function getActivePrecompiles(
+  common: Common,
+  customPrecompiles?: CustomPrecompile[],
+): Map<string, PrecompileFunc> {
+  const precompileMap = new Map()
+  if (customPrecompiles) {
+    for (const precompile of customPrecompiles) {
+      precompileMap.set(
+        resolvePrecompileAddress(precompile.address),
+        'function' in precompile ? precompile.function : undefined,
+      )
+    }
+  }
+  for (const entry of precompileEntries) {
+    if (precompileMap.has(entry.address)) {
+      continue
+    }
+    const type = entry.check.type
+
+    if (
+      (type === PrecompileAvailabilityCheck.Hardfork && common.gteHardfork(entry.check.param)) ||
+      (entry.check.type === PrecompileAvailabilityCheck.EIP &&
+        common.isActivatedEIP(entry.check.param))
+    ) {
+      precompileMap.set(entry.address, entry.precompile)
+    }
+  }
+  return precompileMap
+}
+
+function getPrecompileName(addressUnprefixedStr: string) {
+  if (addressUnprefixedStr.length < 40) {
+    addressUnprefixedStr = addressUnprefixedStr.padStart(40, '0')
+  }
+  for (const entry of precompileEntries) {
+    if (entry.address === addressUnprefixedStr) {
+      return entry.name
+    }
+  }
+  return ''
+}
+
+export {
+  getActivePrecompiles,
+  getPrecompileName,
+  MCLBLS,
+  NobleBLS,
+  NobleBN254,
+  precompileEntries,
+  precompiles,
+  ripemdPrecompileAddress,
+  RustBN254,
+}
+
+export type { AddPrecompile, CustomPrecompile, DeletePrecompile, PrecompileFunc, PrecompileInput }

package/src/precompiles/types.ts

@@ -0,0 +1,15 @@
+import type { Common } from '@feelyourprotocol/common'
+import type { debug } from 'debug'
+import type { EVMInterface, ExecResult } from '../types.ts'
+
+export interface PrecompileFunc {
+  (input: PrecompileInput): Promise<ExecResult> | ExecResult
+}
+
+export interface PrecompileInput {
+  data: Uint8Array
+  gasLimit: bigint
+  common: Common
+  _EVM: EVMInterface
+  _debug?: debug.Debugger
+}

package/src/precompiles/util.ts

@@ -0,0 +1,70 @@
+import { short } from '@feelyourprotocol/util'
+
+import type { PrecompileInput } from './index.ts'
+
+/**
+ * Checks that the gas used remain under the gas limit.
+ *
+ * @param opts - Precompile input wrapper
+ * @param gasUsed - Amount of gas consumed by the precompile
+ * @param pName - Human readable precompile name for logging
+ * @returns `true` if the gas usage is within the provided limit
+ */
+export const gasLimitCheck = (opts: PrecompileInput, gasUsed: bigint, pName: string) => {
+  if (opts._debug !== undefined) {
+    opts._debug(
+      `Run ${pName} precompile data=${short(opts.data)} length=${
+        opts.data.length
+      } gasLimit=${opts.gasLimit} gasUsed=${gasUsed}`,
+    )
+  }
+
+  if (opts.gasLimit < gasUsed) {
+    if (opts._debug !== undefined) {
+      opts._debug(`${pName} failed: OOG`)
+    }
+    return false
+  }
+  return true
+}
+
+/**
+ * Checks that the length of the provided data is equal to `length`.
+ *
+ * @param opts - Precompile input wrapper
+ * @param length - Required data length in bytes
+ * @param pName - Human readable precompile name for logging
+ * @returns `true` if the provided data matches the required length
+ */
+export const equalityLengthCheck = (opts: PrecompileInput, length: number, pName: string) => {
+  if (opts.data.length !== length) {
+    if (opts._debug !== undefined) {
+      opts._debug(
+        `${pName} failed: Invalid input length length=${opts.data.length} (expected: ${length})`,
+      )
+    }
+    return false
+  }
+  return true
+}
+
+/**
+ * Checks that the total length of the provided data input can be subdivided into k equal parts
+ * with `length` (without leaving some remainder bytes).
+ *
+ * @param opts - Precompile input wrapper
+ * @param length - Required chunk size
+ * @param pName - Human readable precompile name for logging
+ * @returns `true` if the length is divisible by the chunk size
+ */
+export const moduloLengthCheck = (opts: PrecompileInput, length: number, pName: string) => {
+  if (opts.data.length % length !== 0) {
+    if (opts._debug !== undefined) {
+      opts._debug(
+        `${pName} failed: Invalid input length length=${opts.data.length} (expected: ${length}*k bytes)`,
+      )
+    }
+    return false
+  }
+  return true
+}

package/src/stack.ts

@@ -0,0 +1,166 @@
+import { EVMError } from './errors.ts'
+
+/**
+ * Implementation of the stack used in evm.
+ */
+export class Stack {
+  // This array is initialized as an empty array. Once values are pushed, the array size will never decrease.
+  private _store: bigint[]
+  private _maxHeight: number
+
+  private _len: number = 0
+
+  constructor(maxHeight?: number) {
+    // It is possible to initialize the array with `maxHeight` items. However,
+    // this makes the constructor 10x slower and there do not seem to be any observable performance gains
+    this._store = []
+    this._maxHeight = maxHeight ?? 1024
+  }
+
+  get length() {
+    return this._len
+  }
+
+  /**
+   * Pushes a new bigint onto the stack.
+   * @param value - Value to push (must fit within the configured max height)
+   */
+  push(value: bigint) {
+    if (this._len >= this._maxHeight) {
+      throw new EVMError(EVMError.errorMessages.STACK_OVERFLOW)
+    }
+
+    // Read current length, set `_store` to value, and then increase the length
+    this._store[this._len++] = value
+  }
+
+  /**
+   * Pops the top value from the stack.
+   * @returns The value removed from the stack
+   */
+  pop(): bigint {
+    if (this._len < 1) {
+      throw new EVMError(EVMError.errorMessages.STACK_UNDERFLOW)
+    }
+
+    // Length is checked above, so pop shouldn't return undefined
+    // First decrease current length, then read the item and return it
+    // Note: this does thus not delete the item from the internal array
+    // However, the length is decreased, so it is not accessible to external observers
+    return this._store[--this._len]
+  }
+
+  /**
+   * Pops multiple items from the stack with the top-most item returned first.
+   * @param num - Number of items to pop (defaults to 1)
+   * @returns Array containing the popped values
+   */
+  popN(num: number = 1): bigint[] {
+    if (this._len < num) {
+      throw new EVMError(EVMError.errorMessages.STACK_UNDERFLOW)
+    }
+
+    if (num === 0) {
+      return []
+    }
+
+    const arr = Array(num)
+    const cache = this._store
+
+    for (let pop = 0; pop < num; pop++) {
+      // Note: this thus also (correctly) reduces the length of the internal array (without deleting items)
+      arr[pop] = cache[--this._len]
+    }
+
+    return arr
+  }
+
+  /**
+   * Returns items from the stack without removing them.
+   * @param num - Number of items to return (defaults to 1)
+   * @returns Array of items, with index 0 representing the top of the stack
+   * @throws {@link EVMError} with code STACK_UNDERFLOW if there are not enough items on the stack
+   */
+  peek(num: number = 1): bigint[] {
+    const peekArray: bigint[] = Array(num)
+    let start = this._len
+
+    for (let peek = 0; peek < num; peek++) {
+      const index = --start
+      if (index < 0) {
+        throw new EVMError(EVMError.errorMessages.STACK_UNDERFLOW)
+      }
+      peekArray[peek] = this._store[index]
+    }
+    return peekArray
+  }
+
+  /**
+   * Swaps the top of the stack with another item.
+   * @param position - Zero-based index from the top of the stack (0 swaps with the top itself)
+   */
+  swap(position: number) {
+    if (this._len <= position) {
+      throw new EVMError(EVMError.errorMessages.STACK_UNDERFLOW)
+    }
+
+    const head = this._len - 1
+    const i = head - position
+    const storageCached = this._store
+
+    const tmp = storageCached[head]
+    storageCached[head] = storageCached[i]
+    storageCached[i] = tmp
+  }
+
+  // I would say that we do not need this method any more
+  // since you can't copy a primitive data type
+  // Nevertheless not sure if we "loose" something here?
+  // Will keep commented out for now
+  /**
+   * Pushes a copy of an item deeper in the stack.
+   * @param position - One-based index of the item to duplicate
+   */
+  dup(position: number) {
+    const len = this._len
+    if (len < position) {
+      throw new EVMError(EVMError.errorMessages.STACK_UNDERFLOW)
+    }
+
+    // Note: this code is borrowed from `push()` (avoids a call)
+    if (len >= this._maxHeight) {
+      throw new EVMError(EVMError.errorMessages.STACK_OVERFLOW)
+    }
+
+    const i = len - position
+    this._store[this._len++] = this._store[i]
+  }
+
+  /**
+   * Swaps two arbitrary entries relative to the top of the stack.
+   * @param swap1 - Distance from the top (0 = top element) for the first entry
+   * @param swap2 - Distance from the top for the second entry
+   */
+  exchange(swap1: number, swap2: number) {
+    const headIndex = this._len - 1
+    const exchangeIndex1 = headIndex - swap1
+    const exchangeIndex2 = headIndex - swap2
+
+    // Stack underflow is not possible in EOF
+    if (exchangeIndex1 < 0 || exchangeIndex2 < 0) {
+      throw new EVMError(EVMError.errorMessages.STACK_UNDERFLOW)
+    }
+
+    const cache = this._store[exchangeIndex2]
+    this._store[exchangeIndex2] = this._store[exchangeIndex1]
+    this._store[exchangeIndex1] = cache
+  }
+
+  /**
+   * Returns a copy of the current stack. This represents the actual state of the stack
+   * (not the internal state of the stack, which might have unreachable elements in it)
+   */
+  getStack() {
+    return this._store.slice(0, this._len)
+  }
+}

package/src/stemCache.ts

@@ -0,0 +1,45 @@
+import type { PrefixedHexString } from '@feelyourprotocol/util'
+import type { BinaryStemAccessEvent, BinaryStemMeta } from './binaryTreeAccessWitness.ts'
+
+export class StemCache {
+  cache: Map<PrefixedHexString, BinaryStemAccessEvent & BinaryStemMeta>
+
+  constructor() {
+    this.cache = new Map<PrefixedHexString, BinaryStemAccessEvent & BinaryStemMeta>()
+  }
+
+  set(stemKey: PrefixedHexString, accessedStem: BinaryStemAccessEvent & BinaryStemMeta) {
+    this.cache.set(stemKey, accessedStem)
+  }
+
+  get(stemHex: PrefixedHexString): (BinaryStemAccessEvent & BinaryStemMeta) | undefined {
+    return this.cache.get(stemHex)
+  }
+
+  del(stemHex: PrefixedHexString): void {
+    this.cache.delete(stemHex)
+  }
+
+  commit(): [PrefixedHexString, BinaryStemAccessEvent & BinaryStemMeta][] {
+    const items: [PrefixedHexString, BinaryStemAccessEvent & BinaryStemMeta][] = Array.from(
+      this.cache.entries(),
+    )
+    this.clear()
+    return items
+  }
+
+  /**
+   * Clear cache
+   */
+  clear(): void {
+    this.cache.clear()
+  }
+
+  /**
+   * Returns the size of the cache
+   * @returns Number of cached stems currently stored
+   */
+  size() {
+    return this.cache.size
+  }
+}