@feelyourprotocol/common 8141.0.0

package/src/enums.ts

@@ -0,0 +1,104 @@
+import { BIGINT_0, hexToBytes } from '@feelyourprotocol/util'
+
+export type Chain = (typeof Chain)[keyof typeof Chain]
+
+export const Chain = {
+  Mainnet: 1,
+  Sepolia: 11155111,
+  Holesky: 17000,
+  Hoodi: 560048,
+} as const
+
+// Reverse mapping: from numeric value back to the key name
+export const ChainNameFromNumber: { [key in Chain]: string } = Object.entries(Chain).reduce(
+  (acc, [key, value]) => {
+    acc[value as Chain] = key
+    return acc
+  },
+  {} as { [key in Chain]: string },
+)
+
+/**
+ * Genesis state meta info which is decoupled from common's genesis params
+ */
+type GenesisState = {
+  name: string
+  /* blockNumber that can be used to update and track the regenesis marker */
+  blockNumber: bigint
+  /* stateRoot of the chain at the blockNumber */
+  stateRoot: Uint8Array
+}
+
+// Having this info as record will force typescript to make sure no chain is missed
+/**
+ * GenesisState info about well known ethereum chains
+ */
+export const ChainGenesis: Record<Chain, GenesisState> = {
+  [Chain.Mainnet]: {
+    name: 'mainnet',
+    blockNumber: BIGINT_0,
+    stateRoot: hexToBytes('0xd7f8974fb5ac78d9ac099b9ad5018bedc2ce0a72dad1827a1709da30580f0544'),
+  },
+  [Chain.Sepolia]: {
+    name: 'sepolia',
+    blockNumber: BIGINT_0,
+    stateRoot: hexToBytes('0x5eb6e371a698b8d68f665192350ffcecbbbf322916f4b51bd79bb6887da3f494'),
+  },
+  [Chain.Holesky]: {
+    name: 'holesky',
+    blockNumber: BIGINT_0,
+    stateRoot: hexToBytes('0x69d8c9d72f6fa4ad42d4702b433707212f90db395eb54dc20bc85de253788783'),
+  },
+  [Chain.Hoodi]: {
+    name: 'hoodi',
+    blockNumber: BIGINT_0,
+    stateRoot: hexToBytes('0xda87d7f5f91c51508791bbcbd4aa5baf04917830b86985eeb9ad3d5bfb657576'),
+  },
+}
+
+export type Hardfork = (typeof Hardfork)[keyof typeof Hardfork]
+
+export const Hardfork = {
+  Chainstart: 'chainstart',
+  Homestead: 'homestead',
+  Dao: 'dao',
+  TangerineWhistle: 'tangerineWhistle',
+  SpuriousDragon: 'spuriousDragon',
+  Byzantium: 'byzantium',
+  Constantinople: 'constantinople',
+  Petersburg: 'petersburg',
+  Istanbul: 'istanbul',
+  MuirGlacier: 'muirGlacier',
+  Berlin: 'berlin',
+  London: 'london',
+  ArrowGlacier: 'arrowGlacier',
+  GrayGlacier: 'grayGlacier',
+  MergeNetsplitBlock: 'mergeNetsplitBlock',
+  Paris: 'paris',
+  Shanghai: 'shanghai',
+  Cancun: 'cancun',
+  Prague: 'prague',
+  Osaka: 'osaka',
+  Bpo1: 'bpo1',
+  Bpo2: 'bpo2',
+  Bpo3: 'bpo3',
+  Bpo4: 'bpo4',
+  Bpo5: 'bpo5',
+  Amsterdam: 'amsterdam',
+} as const
+
+export type ConsensusType = (typeof ConsensusType)[keyof typeof ConsensusType]
+
+export const ConsensusType = {
+  ProofOfStake: 'pos',
+  ProofOfWork: 'pow',
+  ProofOfAuthority: 'poa',
+} as const
+
+export type ConsensusAlgorithm = (typeof ConsensusAlgorithm)[keyof typeof ConsensusAlgorithm]
+
+export const ConsensusAlgorithm = {
+  Ethash: 'ethash',
+  Clique: 'clique',
+  Casper: 'casper',
+} as const

package/src/gethGenesis.ts

@@ -0,0 +1,175 @@
+import { type PrefixedHexString, addHexPrefix, bigIntToHex, isHexString } from '@feelyourprotocol/util'
+
+/**
+ * Interface for Geth Genesis Config
+ */
+export interface GethGenesisConfig {
+  chainId: number
+  depositContractAddress?: string
+  homesteadBlock?: number
+  daoForkBlock?: number
+  daoForkSupport?: boolean
+  eip150Block?: number
+  eip150Hash?: string
+  eip155Block?: number
+  eip158Block?: number
+  byzantiumBlock?: number
+  constantinopleBlock?: number
+  petersburgBlock?: number
+  istanbulBlock?: number
+  muirGlacierBlock?: number
+  berlinBlock?: number
+  londonBlock?: number
+  mergeForkBlock?: number
+  cancunBlock?: number
+  arrowGlacierBlock?: number
+  grayGlacierBlock?: number
+  mergeNetsplitBlock?: number
+  shanghaiTime?: number
+  cancunTime?: number
+  pragueTime?: number
+  terminalTotalDifficulty?: number
+  terminalTotalDifficultyPassed?: boolean
+  ethash?: {}
+  clique?: {
+    period?: number
+    epoch?: number
+    blockperiodseconds?: number
+    epochlength?: number
+  }
+  trustedCheckpoint?: {
+    sectionIndex: number
+    sectionHead: string
+    chtRoot: string
+    bloomRoot: string
+  }
+  trustedCheckpointOracle?: {
+    address: string
+    signers: string[]
+    threshold: number
+  }
+  blobSchedule?: GethGenesisBlobSchedule
+  proofInBlocks?: boolean
+}
+
+/**
+ * Interface for account allocation in Geth Genesis
+ */
+export interface GethGenesisAlloc {
+  [address: string]: {
+    balance: string
+    code?: string
+    storage?: { [key: string]: string }
+    nonce?: string
+  }
+}
+
+/**
+ * Interface for blob schedule in Geth Genesis (EIP-7840)
+ */
+export interface GethGenesisBlobSchedule {
+  [fork: string]: {
+    target?: number
+    max?: number
+    baseFeeUpdateFraction?: number
+  }
+}
+
+/**
+ * Interface for Geth Genesis object
+ */
+export interface GethGenesis {
+  config: GethGenesisConfig
+  name?: string
+  excessBlobGas?: string
+  requestsHash?: string
+  nonce: string
+  timestamp: string
+  extraData?: string
+  gasLimit: PrefixedHexString
+  difficulty?: PrefixedHexString
+  mixHash?: PrefixedHexString
+  coinbase?: PrefixedHexString
+  alloc: GethGenesisAlloc
+  number?: PrefixedHexString
+  gasUsed?: PrefixedHexString
+  parentHash?: PrefixedHexString
+  baseFeePerGas?: PrefixedHexString | number | null
+}
+
+/**
+ * Type for the options passed to createCommonFromGethGenesis
+ */
+export interface CreateCommonFromGethGenesisOpts {
+  chain?: string
+  genesisHash?: string
+  mergeForkIdPostMerge?: boolean
+}
+
+export type StoragePair = [key: PrefixedHexString, value: PrefixedHexString]
+
+export type AccountState = [
+  balance: PrefixedHexString,
+  code?: PrefixedHexString,
+  storage?: Array<StoragePair>,
+  nonce?: PrefixedHexString,
+]
+
+/**
+ * If you are using a custom chain {@link Common}, pass the genesis state.
+ *
+ * Pattern 1 (with genesis state see {@link GenesisState} for format):
+ *
+ * ```javascript
+ * {
+ *   '0x0...01': '0x100', // For EoA
+ * }
+ * ```
+ *
+ * Pattern 2 (with complex genesis state, containing contract accounts and storage).
+ * Note that in {@link AccountState} there are two
+ * accepted types. This allows to easily insert accounts in the genesis state:
+ *
+ * A complex genesis state with Contract and EoA states would have the following format:
+ *
+ * ```javascript
+ * {
+ *   '0x0...01': '0x100', // For EoA
+ *   '0x0...02': ['0x1', '0xRUNTIME_BYTECODE', [[storageKey1, storageValue1], [storageKey2, storageValue2]]] // For contracts
+ * }
+ * ```
+ */
+export interface GenesisState {
+  [key: PrefixedHexString]: PrefixedHexString | AccountState
+}
+
+/**
+ * Parses the geth genesis state into Blockchain {@link GenesisState}
+ * @param gethGenesis GethGenesis object
+ * @returns Parsed {@link GenesisState}
+ */
+export function parseGethGenesisState(gethGenesis: GethGenesis): GenesisState {
+  const state: GenesisState = {}
+
+  for (const address of Object.keys(gethGenesis.alloc)) {
+    const {
+      balance: rawBalance,
+      code: rawCode,
+      nonce: rawNonce,
+      storage: rawStorage,
+    } = gethGenesis.alloc[address]
+    // create a map with lowercase for easy lookups
+    const prefixedAddress = addHexPrefix(address.toLowerCase())
+    const balance = isHexString(rawBalance) ? rawBalance : bigIntToHex(BigInt(rawBalance))
+    const code = rawCode !== undefined ? addHexPrefix(rawCode) : undefined
+    const storage =
+      rawStorage !== undefined
+        ? (Object.entries(rawStorage).map((storagePair) =>
+            storagePair.map(addHexPrefix),
+          ) as StoragePair[])
+        : undefined
+    const nonce = rawNonce !== undefined ? addHexPrefix(rawNonce) : undefined
+    state[prefixedAddress] = [balance, code, storage, nonce]
+  }
+  return state
+}

package/src/hardforks.ts

@@ -0,0 +1,205 @@
+import type { HardforksDict } from './types.ts'
+
+export const hardforksDict: HardforksDict = {
+  /**
+   * Description: Start of the Ethereum main chain
+   * URL        : -
+   * Status     : Final
+   */
+  chainstart: {
+    eips: [1],
+  },
+  /**
+   * Description: Homestead hardfork with protocol and network changes
+   * URL        : https://eips.ethereum.org/EIPS/eip-606
+   * Status     : Final
+   */
+  homestead: {
+    eips: [606],
+  },
+  /**
+   * Description: DAO rescue hardfork
+   * URL        : https://eips.ethereum.org/EIPS/eip-779
+   * Status     : Final
+   */
+  dao: {
+    eips: [],
+  },
+  /**
+   * Description: Hardfork with gas cost changes for IO-heavy operations
+   * URL        : https://eips.ethereum.org/EIPS/eip-608
+   * Status     : Final
+   */
+  tangerineWhistle: {
+    eips: [608],
+  },
+  /**
+   * Description: HF with EIPs for simple replay attack protection, EXP cost increase, state trie clearing, contract code size limit
+   * URL        : https://eips.ethereum.org/EIPS/eip-607
+   * Status     : Final
+   */
+  spuriousDragon: {
+    eips: [607],
+  },
+  /**
+   * Description: Hardfork with new precompiles, instructions and other protocol changes
+   * URL        : https://eips.ethereum.org/EIPS/eip-609
+   * Status     : Final
+   */
+  byzantium: {
+    eips: [609],
+  },
+  /**
+   * Description: Postponed hardfork including EIP-1283 (SSTORE gas metering changes)
+   * URL        : https://eips.ethereum.org/EIPS/eip-1013
+   * Status     : Final
+   */
+  constantinople: {
+    eips: [1013],
+  },
+  /**
+   * Description: Aka constantinopleFix, removes EIP-1283, activate together with or after constantinople
+   * URL        : https://eips.ethereum.org/EIPS/eip-1716
+   * Status     : Final
+   */
+  petersburg: {
+    eips: [1716],
+  },
+  /**
+   * Description: HF targeted for December 2019 following the Constantinople/Petersburg HF
+   * URL        : https://eips.ethereum.org/EIPS/eip-1679
+   * Status     : Final
+   */
+  istanbul: {
+    eips: [1679],
+  },
+  /**
+   * Description: HF to delay the difficulty bomb
+   * URL        : https://eips.ethereum.org/EIPS/eip-2384
+   * Status     : Final
+   */
+  muirGlacier: {
+    eips: [2384],
+  },
+  /**
+   * Description: HF targeted for July 2020 following the Muir Glacier HF
+   * URL        : https://eips.ethereum.org/EIPS/eip-2070
+   * Status     : Final
+   */
+  berlin: {
+    eips: [2565, 2929, 2718, 2930],
+  },
+  /**
+   * Description: HF targeted for July 2021 following the Berlin fork
+   * URL        : https://github.com/ethereum/eth1.0-specs/blob/master/network-upgrades/mainnet-upgrades/london.md
+   * Status     : Final
+   */
+  london: {
+    eips: [1559, 3198, 3529, 3541],
+  },
+  /**
+   * Description: HF to delay the difficulty bomb
+   * URL        : https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/arrow-glacier.md
+   * Status     : Final
+   */
+  arrowGlacier: {
+    eips: [4345],
+  },
+  /**
+   * Description: Delaying the difficulty bomb to Mid September 2022
+   * URL        : https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/gray-glacier.md
+   * Status     : Final
+   */
+  grayGlacier: {
+    eips: [5133],
+  },
+  /**
+   * Description: Hardfork to upgrade the consensus mechanism to Proof-of-Stake
+   * URL        : https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/merge.md
+   * Status     : Final
+   */
+  paris: {
+    consensus: {
+      type: 'pos',
+      algorithm: 'casper',
+      casper: {},
+    },
+    eips: [3675, 4399],
+  },
+  /**
+   * Description: Pre-merge hardfork to fork off non-upgraded clients
+   * URL        : https://eips.ethereum.org/EIPS/eip-3675
+   * Status     : Final
+   */
+  mergeNetsplitBlock: {
+    eips: [],
+  },
+  /**
+   * Description: Next feature hardfork after the merge hardfork having withdrawals, warm coinbase, push0, limit/meter initcode
+   * URL        : https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/shanghai.md
+   * Status     : Final
+   */
+  shanghai: {
+    eips: [3651, 3855, 3860, 4895],
+  },
+  /**
+   * Description: Next feature hardfork after shanghai, includes proto-danksharding EIP 4844 blobs,
+   * transient storage opcodes, parent beacon block root availability in EVM, selfdestruct only in
+   * same transaction, and blob base fee opcode
+   * URL        : https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/cancun.md
+   * Status     : Final
+   */
+  cancun: {
+    eips: [1153, 4844, 4788, 5656, 6780, 7516],
+  },
+  /**
+   * Description: Next feature hardfork after cancun including EIP-7702 account abstraction + other EIPs
+   * URL        : https://eips.ethereum.org/EIPS/eip-7600
+   * Status     : Final
+   */
+  prague: {
+    eips: [2537, 2935, 6110, 7002, 7251, 7623, 7685, 7691, 7702],
+  },
+  /**
+   * Description: Next feature hardfork after prague (headliner: PeerDAS)
+   * URL        : https://eips.ethereum.org/EIPS/eip-7607
+   * Status     : Final
+   */
+  osaka: {
+    eips: [7594, 7823, 7825, 7883, 7892, 7939, 7951, 7918],
+  },
+  /**
+   * Description: HF to update the blob target, max and updateFraction (see also EIP-7892)
+   * URL        : TBD
+   * Status     : Final
+   */
+  bpo1: {
+    eips: [],
+    params: {
+      target: 10,
+      max: 15,
+      blobGasPriceUpdateFraction: 8346193,
+    },
+  },
+  /**
+   * Description: HF to update the blob target, max and updateFraction (see also EIP-7892)
+   * URL        : TBD
+   * Status     : Final
+   */
+  bpo2: {
+    eips: [],
+    params: {
+      target: 14,
+      max: 21,
+      blobGasPriceUpdateFraction: 11684671,
+    },
+  },
+  /**
+   * Description: Feature hardfork after osaka (headliner: EIP-7928 Block Level Access Lists (BAL))
+   * URL        : https://eips.ethereum.org/EIPS/eip-7773
+   * Status     : Draft (implementation incomplete + spec still moving!)
+   */
+  amsterdam: {
+    eips: [7708, 7843, 7778, 7928, 8024],
+  },
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './chains.ts'
+export * from './common.ts'
+export * from './constructors.ts'
+export * from './enums.ts'
+export * from './gethGenesis.ts'
+export * from './interfaces.ts'
+export * from './types.ts'
+export * from './utils.ts'

package/src/interfaces.ts

@@ -0,0 +1,191 @@
+/**
+ * External Interfaces for other EthereumJS libraries
+ */
+
+import type {
+  Account,
+  Address,
+  BinaryTreeExecutionWitness,
+  PrefixedHexString,
+} from '@feelyourprotocol/util'
+
+export interface StorageDump {
+  [key: string]: string
+}
+
+/**
+ * Object that can contain a set of storage keys associated with an account.
+ */
+export interface StorageRange {
+  /**
+   * A dictionary where the keys are hashed storage keys, and the values are
+   * objects containing the preimage of the hashed key (in `key`) and the
+   * storage key (in `value`). Currently, there is no way to retrieve preimages,
+   * so they are always `null`.
+   */
+  storage: {
+    [key: string]: {
+      key: string | null
+      value: string
+    }
+  }
+  /**
+   * The next (hashed) storage key after the greatest storage key
+   * contained in `storage`.
+   */
+  nextKey: string | null
+}
+
+export type AccountFields = Partial<
+  Pick<Account, 'nonce' | 'balance' | 'storageRoot' | 'codeHash' | 'codeSize'>
+>
+
+export type StorageProof = {
+  key: PrefixedHexString
+  proof: PrefixedHexString[]
+  value: PrefixedHexString
+}
+
+export type Proof = {
+  address: PrefixedHexString
+  balance: PrefixedHexString
+  codeHash: PrefixedHexString
+  nonce: PrefixedHexString
+  storageHash: PrefixedHexString
+  accountProof: PrefixedHexString[]
+  storageProof: StorageProof[]
+}
+
+/**
+ * Binary tree related
+ *
+ * Experimental (do not implement)
+ */
+export type AccessEventFlags = {
+  stemRead: boolean
+  stemWrite: boolean
+  chunkRead: boolean
+  chunkWrite: boolean
+  chunkFill: boolean
+}
+
+export type BinaryTreeAccessedStateType =
+  (typeof BinaryTreeAccessedStateType)[keyof typeof BinaryTreeAccessedStateType]
+
+export const BinaryTreeAccessedStateType = {
+  BasicData: 'basicData',
+  CodeHash: 'codeHash',
+  Code: 'code',
+  Storage: 'storage',
+} as const
+
+export type RawBinaryTreeAccessedState = {
+  address: Address
+  treeIndex: number | bigint
+  chunkIndex: number
+  chunkKey: PrefixedHexString
+}
+
+export type BinaryTreeAccessedState =
+  | {
+      type: Exclude<
+        BinaryTreeAccessedStateType,
+        typeof BinaryTreeAccessedStateType.Code | typeof BinaryTreeAccessedStateType.Storage
+      >
+    }
+  | { type: typeof BinaryTreeAccessedStateType.Code; codeOffset: number }
+  | { type: typeof BinaryTreeAccessedStateType.Storage; slot: bigint }
+
+export type BinaryTreeAccessedStateWithAddress = BinaryTreeAccessedState & {
+  address: Address
+  chunkKey: PrefixedHexString
+}
+export interface BinaryTreeAccessWitnessInterface {
+  accesses(): Generator<BinaryTreeAccessedStateWithAddress>
+  rawAccesses(): Generator<RawBinaryTreeAccessedState>
+  debugWitnessCost(): void
+  readAccountBasicData(address: Address): bigint
+  writeAccountBasicData(address: Address): bigint
+  readAccountCodeHash(address: Address): bigint
+  writeAccountCodeHash(address: Address): bigint
+  readAccountHeader(address: Address): bigint
+  writeAccountHeader(address: Address): bigint
+  readAccountCodeChunks(contract: Address, startPc: number, endPc: number): bigint
+  writeAccountCodeChunks(contract: Address, startPc: number, endPc: number): bigint
+  readAccountStorage(contract: Address, storageSlot: bigint): bigint
+  writeAccountStorage(contract: Address, storageSlot: bigint): bigint
+  merge(accessWitness: BinaryTreeAccessWitnessInterface): void
+  commit(): void
+  revert(): void
+}
+
+/*
+ * Generic StateManager interface corresponding with the @feelyourprotocol/statemanager package
+ *
+ */
+export interface StateManagerInterface {
+  /*
+   * Core Access Functionality
+   */
+  // Account methods
+  getAccount(address: Address): Promise<Account | undefined>
+  putAccount(address: Address, account?: Account): Promise<void>
+  deleteAccount(address: Address): Promise<void>
+  modifyAccountFields(address: Address, accountFields: AccountFields): Promise<void>
+
+  // Code methods
+  putCode(address: Address, value: Uint8Array): Promise<void>
+  getCode(address: Address): Promise<Uint8Array>
+  getCodeSize(address: Address): Promise<number>
+
+  // Storage methods
+  getStorage(address: Address, key: Uint8Array): Promise<Uint8Array>
+  putStorage(address: Address, key: Uint8Array, value: Uint8Array): Promise<void>
+  clearStorage(address: Address): Promise<void>
+
+  /*
+   * Checkpointing Functionality
+   */
+  checkpoint(): Promise<void>
+  commit(): Promise<void>
+  revert(): Promise<void>
+
+  /*
+   * State Root Functionality
+   */
+  getStateRoot(): Promise<Uint8Array>
+  setStateRoot(stateRoot: Uint8Array, clearCache?: boolean): Promise<void>
+  hasStateRoot(root: Uint8Array): Promise<boolean> // only used in client
+
+  /*
+   * Extra Functionality
+   *
+   * Optional non-essential methods, these methods should always be guarded
+   * on usage (check for existence)
+   */
+  // Client RPC
+  dumpStorage?(address: Address): Promise<StorageDump>
+  dumpStorageRange?(address: Address, startKey: bigint, limit: number): Promise<StorageRange>
+
+  /*
+   * EVM/VM Specific Functionality
+   */
+  originalStorageCache: {
+    get(address: Address, key: Uint8Array): Promise<Uint8Array>
+    clear(): void
+  }
+  generateCanonicalGenesis?(initState: any): Promise<void> // TODO make input more typesafe
+  initBinaryTreeExecutionWitness?(
+    blockNum: bigint,
+    executionWitness?: BinaryTreeExecutionWitness | null,
+  ): void
+  verifyBinaryTreePostState?(accessWitness: BinaryTreeAccessWitnessInterface): Promise<boolean>
+  checkChunkWitnessPresent?(contract: Address, programCounter: number): Promise<boolean>
+  getAppliedKey?(address: Uint8Array): Uint8Array // only for preimages
+
+  /*
+   * Utility
+   */
+  clearCaches(): void
+  shallowCopy(downlevelCaches?: boolean): StateManagerInterface
+}