@feelyourprotocol/blockchain 8141.0.0

package/src/consensus/ethash.ts

@@ -0,0 +1,69 @@
+import { ConsensusAlgorithm } from '@feelyourprotocol/common'
+import { EthereumJSErrorWithoutCode, bytesToHex, isDebugEnabled } from '@feelyourprotocol/util'
+import debugDefault from 'debug'
+
+import type { Block, BlockHeader } from '@feelyourprotocol/block'
+import type { Debugger } from 'debug'
+import type { Blockchain } from '../index.ts'
+import type { Consensus, ConsensusOptions } from '../types.ts'
+
+export type MinimalEthashInterface = {
+  cacheDB?: any
+  verifyPOW(block: Block): Promise<boolean>
+}
+
+/**
+ * This class encapsulates Ethash-related consensus functionality when used with the Blockchain class.
+ */
+export class EthashConsensus implements Consensus {
+  blockchain: Blockchain | undefined
+  algorithm: ConsensusAlgorithm
+  _ethash: MinimalEthashInterface
+
+  private DEBUG: boolean // Guard for debug logs
+  private _debug: Debugger
+
+  constructor(ethash: MinimalEthashInterface) {
+    this.DEBUG = isDebugEnabled('ethjs')
+    this._debug = debugDefault('blockchain:ethash')
+
+    this.algorithm = ConsensusAlgorithm.Ethash
+    this._ethash = ethash
+  }
+
+  async validateConsensus(block: Block): Promise<void> {
+    const valid = await this._ethash.verifyPOW(block)
+    if (!valid) {
+      throw EthereumJSErrorWithoutCode('invalid POW')
+    }
+    this.DEBUG &&
+      this._debug(
+        `valid PoW consensus block: number ${block.header.number} hash ${bytesToHex(block.hash())}`,
+      )
+  }
+
+  /**
+   * Checks that the block's `difficulty` matches the canonical difficulty of the parent header.
+   * @param header - header of block to be checked
+   */
+  async validateDifficulty(header: BlockHeader) {
+    if (!this.blockchain) {
+      throw EthereumJSErrorWithoutCode('blockchain not provided')
+    }
+    const parentHeader = await this.blockchain['_getHeader'](header.parentHash)
+    if (header.ethashCanonicalDifficulty(parentHeader) !== header.difficulty) {
+      throw EthereumJSErrorWithoutCode(`invalid difficulty ${header.errorStr()}`)
+    }
+    this.DEBUG &&
+      this._debug(
+        `valid difficulty header: number ${header.number} difficulty ${header.difficulty} parentHash ${bytesToHex(header.parentHash)}`,
+      )
+  }
+
+  public async genesisInit(): Promise<void> {}
+  public async setup({ blockchain }: ConsensusOptions): Promise<void> {
+    this.blockchain = blockchain
+    this._ethash.cacheDB = this.blockchain.db
+  }
+  public async newBlock(): Promise<void> {}
+}

package/src/consensus/index.ts

@@ -0,0 +1,5 @@
+import { CasperConsensus } from './casper.ts'
+import { CliqueConsensus } from './clique.ts'
+import { EthashConsensus } from './ethash.ts'
+
+export { CasperConsensus, CliqueConsensus, EthashConsensus }

package/src/constructors.ts

@@ -0,0 +1,119 @@
+import { createBlock } from '@feelyourprotocol/block'
+import {
+  BIGINT_0,
+  EthereumJSErrorWithoutCode,
+  bytesToHex,
+  equalsBytes,
+  isDebugEnabled,
+} from '@feelyourprotocol/util'
+import debugDefault from 'debug'
+
+import {
+  Blockchain,
+  DBSaveLookups,
+  DBSetBlockOrHeader,
+  DBSetTD,
+  genGenesisStateRoot,
+  getGenesisStateRoot,
+} from './index.ts'
+
+import type { BlockData } from '@feelyourprotocol/block'
+import type { Chain } from '@feelyourprotocol/common'
+import type { BlockchainOptions, DBOp } from './index.ts'
+
+const DEBUG = isDebugEnabled('ethjs')
+const debug = debugDefault('blockchain:#')
+
+export async function createBlockchain(opts: BlockchainOptions = {}) {
+  const blockchain = new Blockchain(opts)
+
+  await blockchain.consensus?.setup({ blockchain })
+
+  let stateRoot = opts.genesisBlock?.header.stateRoot ?? opts.genesisStateRoot
+  if (stateRoot === undefined) {
+    if (blockchain['_customGenesisState'] !== undefined) {
+      stateRoot = await genGenesisStateRoot(blockchain['_customGenesisState'], blockchain.common)
+    } else {
+      stateRoot = await getGenesisStateRoot(
+        Number(blockchain.common.chainId()) as Chain,
+        blockchain.common,
+      )
+    }
+  }
+
+  const genesisBlock = opts.genesisBlock ?? blockchain.createGenesisBlock(stateRoot)
+
+  let genesisHash = await blockchain.dbManager.numberToHash(BIGINT_0)
+
+  const dbGenesisBlock =
+    genesisHash !== undefined ? await blockchain.dbManager.getBlock(genesisHash) : undefined
+
+  // If the DB has a genesis block, then verify that the genesis block in the
+  // DB is indeed the Genesis block generated or assigned.
+  if (dbGenesisBlock !== undefined && !equalsBytes(genesisBlock.hash(), dbGenesisBlock.hash())) {
+    throw EthereumJSErrorWithoutCode(
+      'The genesis block in the DB has a different hash than the provided genesis block.',
+    )
+  }
+
+  genesisHash = genesisBlock.hash()
+
+  if (!dbGenesisBlock) {
+    // If there is no genesis block put the genesis block in the DB.
+    // For that TD, the BlockOrHeader, and the Lookups have to be saved.
+    const dbOps: DBOp[] = []
+    dbOps.push(DBSetTD(genesisBlock.header.difficulty, BIGINT_0, genesisHash))
+    DBSetBlockOrHeader(genesisBlock).map((op) => dbOps.push(op))
+    DBSaveLookups(genesisHash, BIGINT_0).map((op) => dbOps.push(op))
+    await blockchain.dbManager.batch(dbOps)
+    await blockchain.consensus?.genesisInit(genesisBlock)
+  }
+
+  // At this point, we can safely set the genesis:
+  // it is either the one we put in the DB, or it is equal to the one
+  // which we read from the DB.
+  blockchain['_genesisBlock'] = genesisBlock
+
+  // load verified iterator heads
+  const heads = await blockchain.dbManager.getHeads()
+  blockchain['_heads'] = heads ?? {}
+
+  // load headerchain head
+  let hash = await blockchain.dbManager.getHeadHeader()
+  blockchain['_headHeaderHash'] = hash ?? genesisHash
+
+  // load blockchain head
+  hash = await blockchain.dbManager.getHeadBlock()
+  blockchain['_headBlockHash'] = hash ?? genesisHash
+
+  if (blockchain['_hardforkByHeadBlockNumber']) {
+    const latestHeader = await blockchain['_getHeader'](blockchain['_headHeaderHash'])
+    await blockchain.checkAndTransitionHardForkByNumber(latestHeader.number, latestHeader.timestamp)
+  }
+
+  DEBUG && debug(`genesis block initialized with hash ${bytesToHex(genesisHash!)}`)
+
+  return blockchain
+}
+
+/**
+ * Creates a blockchain from a list of block objects,
+ * objects must be readable by {@link createBlock}
+ *
+ * @param blockData List of block objects
+ * @param opts Constructor options, see {@link BlockchainOptions}
+ */
+export async function createBlockchainFromBlocksData(
+  blocksData: BlockData[],
+  opts: BlockchainOptions = {},
+) {
+  const blockchain = await createBlockchain(opts)
+  for (const blockData of blocksData) {
+    const block = createBlock(blockData, {
+      common: blockchain.common,
+      setHardfork: true,
+    })
+    await blockchain.putBlock(block)
+  }
+  return blockchain
+}

package/src/db/cache.ts

@@ -0,0 +1,39 @@
+import { bytesToUnprefixedHex } from '@feelyourprotocol/util'
+import { LRUCache } from 'lru-cache'
+
+/**
+ * Simple LRU Cache that allows for keys of type Uint8Array
+ * @hidden
+ */
+export class Cache<V> {
+  _cache: LRUCache<string, { value: V }, void>
+
+  constructor(opts: LRUCache.Options<string, { value: V }, void>) {
+    this._cache = new LRUCache(opts)
+  }
+
+  set(key: string | Uint8Array, value: V): void {
+    if (key instanceof Uint8Array) {
+      // Using deprecated bytesToUnprefixedHex for performance: used as LRU cache keys (string encoding).
+      key = bytesToUnprefixedHex(key)
+    }
+    this._cache.set(key, { value })
+  }
+
+  get(key: string | Uint8Array): V | undefined {
+    if (key instanceof Uint8Array) {
+      // Using deprecated bytesToUnprefixedHex for performance: used as LRU cache keys (string encoding).
+      key = bytesToUnprefixedHex(key)
+    }
+    const elem = this._cache.get(key)
+    return elem !== undefined ? elem.value : undefined
+  }
+
+  del(key: string | Uint8Array): void {
+    if (key instanceof Uint8Array) {
+      // Using deprecated bytesToUnprefixedHex for performance: used as LRU cache keys (string encoding).
+      key = bytesToUnprefixedHex(key)
+    }
+    this._cache.delete(key)
+  }
+}

package/src/db/constants.ts

@@ -0,0 +1,73 @@
+import { bigIntToBytes, concatBytes, utf8ToBytes } from '@feelyourprotocol/util'
+
+// Geth compatible DB keys
+
+const HEADS_KEY = 'heads'
+
+/**
+ * Current canonical head for light sync
+ */
+const HEAD_HEADER_KEY = 'LastHeader'
+
+/**
+ * Current canonical head for full sync
+ */
+const HEAD_BLOCK_KEY = 'LastBlock'
+
+/**
+ * headerPrefix + number + hash -> header
+ */
+const HEADER_PREFIX = utf8ToBytes('h')
+
+/**
+ * headerPrefix + number + hash + tdSuffix -> td
+ */
+const TD_SUFFIX = utf8ToBytes('t')
+
+/**
+ * headerPrefix + number + numSuffix -> hash
+ */
+const NUM_SUFFIX = utf8ToBytes('n')
+
+/**
+ * blockHashPrefix + hash -> number
+ */
+const BLOCK_HASH_PREFIX = utf8ToBytes('H')
+
+/**
+ * bodyPrefix + number + hash -> block body
+ */
+const BODY_PREFIX = utf8ToBytes('b')
+
+// Utility functions
+
+/**
+ * Convert bigint to big endian Uint8Array
+ */
+const bytesBE8 = (n: bigint) => bigIntToBytes(BigInt.asUintN(64, n))
+
+const tdKey = (n: bigint, hash: Uint8Array) =>
+  concatBytes(HEADER_PREFIX, bytesBE8(n), hash, TD_SUFFIX)
+
+const headerKey = (n: bigint, hash: Uint8Array) => concatBytes(HEADER_PREFIX, bytesBE8(n), hash)
+
+const bodyKey = (n: bigint, hash: Uint8Array) => concatBytes(BODY_PREFIX, bytesBE8(n), hash)
+
+const numberToHashKey = (n: bigint) => concatBytes(HEADER_PREFIX, bytesBE8(n), NUM_SUFFIX)
+
+const hashToNumberKey = (hash: Uint8Array) => concatBytes(BLOCK_HASH_PREFIX, hash)
+
+/**
+ * @hidden
+ */
+export {
+  bodyKey,
+  bytesBE8,
+  hashToNumberKey,
+  HEAD_BLOCK_KEY,
+  HEAD_HEADER_KEY,
+  headerKey,
+  HEADS_KEY,
+  numberToHashKey,
+  tdKey,
+}

package/src/db/helpers.ts

@@ -0,0 +1,81 @@
+import { Block } from '@feelyourprotocol/block'
+import { RLP } from '@feelyourprotocol/rlp'
+import { BIGINT_0 } from '@feelyourprotocol/util'
+
+import { bytesBE8 } from './constants.ts'
+import { DBOp, DBTarget } from './operation.ts'
+
+import type { BlockHeader } from '@feelyourprotocol/block'
+
+/*
+ * This extra helper file serves as an interface between the blockchain API functionality
+ * and the DB operations from `db/operation.ts` and also handles the right encoding of the keys
+ */
+
+function DBSetTD(TD: bigint, blockNumber: bigint, blockHash: Uint8Array): DBOp {
+  return DBOp.set(DBTarget.TotalDifficulty, RLP.encode(TD), {
+    blockNumber,
+    blockHash,
+  })
+}
+
+/*
+ * This method accepts either a BlockHeader or a Block and returns a list of DatabaseOperation instances
+ *
+ * - A "Set Header Operation" is always added
+ * - A "Set Body Operation" is only added if the body is not empty (it has transactions/uncles) or if the block is the genesis block
+ * (if there is a header but no block saved the DB will implicitly assume the block to be empty)
+ */
+function DBSetBlockOrHeader(blockBody: Block | BlockHeader): DBOp[] {
+  const header: BlockHeader = blockBody instanceof Block ? blockBody.header : blockBody
+  const dbOps = []
+
+  const blockNumber = header.number
+  const blockHash = header.hash()
+
+  const headerValue = header.serialize()
+  dbOps.push(
+    DBOp.set(DBTarget.Header, headerValue, {
+      blockNumber,
+      blockHash,
+    }),
+  )
+
+  const isGenesis = header.number === BIGINT_0
+
+  if (isGenesis || blockBody instanceof Block) {
+    const bodyValue = RLP.encode(blockBody.raw().slice(1))
+    dbOps.push(
+      DBOp.set(DBTarget.Body, bodyValue, {
+        blockNumber,
+        blockHash,
+      }),
+    )
+  }
+
+  return dbOps
+}
+
+function DBSetHashToNumber(blockHash: Uint8Array, blockNumber: bigint): DBOp {
+  const blockNumber8Byte = bytesBE8(blockNumber)
+  return DBOp.set(DBTarget.HashToNumber, blockNumber8Byte, {
+    blockHash,
+  })
+}
+
+function DBSaveLookups(blockHash: Uint8Array, blockNumber: bigint, skipNumIndex?: boolean): DBOp[] {
+  const ops = []
+  if (skipNumIndex !== true) {
+    ops.push(DBOp.set(DBTarget.NumberToHash, blockHash, { blockNumber }))
+  }
+
+  const blockNumber8Bytes = bytesBE8(blockNumber)
+  ops.push(
+    DBOp.set(DBTarget.HashToNumber, blockNumber8Bytes, {
+      blockHash,
+    }),
+  )
+  return ops
+}
+
+export { DBOp, DBSaveLookups, DBSetBlockOrHeader, DBSetHashToNumber, DBSetTD }

package/src/db/manager.ts

@@ -0,0 +1,243 @@
+import { createBlockFromBytesArray, createBlockHeaderFromBytesArray } from '@feelyourprotocol/block'
+import { RLP } from '@feelyourprotocol/rlp'
+import {
+  EthereumJSErrorWithoutCode,
+  KECCAK256_RLP,
+  KECCAK256_RLP_ARRAY,
+  bytesToBigInt,
+  bytesToHex,
+  equalsBytes,
+  unprefixedHexToBytes,
+} from '@feelyourprotocol/util'
+
+import { Cache } from './cache.ts'
+import { DBOp, DBTarget } from './operation.ts'
+
+import type { Block, BlockBodyBytes, BlockBytes, BlockOptions } from '@feelyourprotocol/block'
+import type { Common } from '@feelyourprotocol/common'
+import type { BatchDBOp, DB, DBObject, DelBatch, PutBatch } from '@feelyourprotocol/util'
+import type { DatabaseKey } from './operation.ts'
+
+/**
+ * @hidden
+ */
+export interface GetOpts {
+  keyEncoding?: string
+  valueEncoding?: string
+  cache?: string
+}
+
+export type CacheMap = { [key: string]: Cache<Uint8Array> }
+
+/**
+ * Abstraction over a DB to facilitate storing/fetching blockchain-related
+ * data, such as blocks and headers, indices, and the head block.
+ * @hidden
+ */
+export class DBManager {
+  private _cache: CacheMap
+  public readonly common: Common
+  private _db: DB<Uint8Array | string, Uint8Array | string | DBObject>
+
+  constructor(db: DB<Uint8Array | string, Uint8Array | string | DBObject>, common: Common) {
+    this._db = db
+    this.common = common
+    this._cache = {
+      td: new Cache({ max: 1024 }),
+      header: new Cache({ max: 512 }),
+      body: new Cache({ max: 256 }),
+      numberToHash: new Cache({ max: 2048 }),
+      hashToNumber: new Cache({ max: 2048 }),
+    }
+  }
+
+  /**
+   * Fetches iterator heads from the db.
+   */
+  async getHeads(): Promise<{ [key: string]: Uint8Array }> {
+    const heads = (await this.get(DBTarget.Heads)) as DBObject
+    if (heads === undefined) return heads
+    const decodedHeads: { [key: string]: Uint8Array } = {}
+    for (const key of Object.keys(heads)) {
+      // Heads are stored in DB as hex strings since Level converts Uint8Arrays
+      // to nested JSON objects when they are included in a value being stored
+      // in the DB
+      decodedHeads[key] = unprefixedHexToBytes(heads[key] as string)
+    }
+    return decodedHeads
+  }
+
+  /**
+   * Fetches header of the head block.
+   */
+  async getHeadHeader(): Promise<Uint8Array | undefined> {
+    return this.get(DBTarget.HeadHeader)
+  }
+
+  /**
+   * Fetches head block.
+   */
+  async getHeadBlock(): Promise<Uint8Array | undefined> {
+    return this.get(DBTarget.HeadBlock)
+  }
+
+  /**
+   * Fetches a block (header and body) given a block id,
+   * which can be either its hash or its number.
+   */
+  async getBlock(blockId: Uint8Array | bigint | number): Promise<Block | undefined> {
+    if (typeof blockId === 'number' && Number.isInteger(blockId)) {
+      blockId = BigInt(blockId)
+    }
+
+    let number
+    let hash
+    if (blockId === undefined) return undefined
+    if (blockId instanceof Uint8Array) {
+      hash = blockId
+      number = await this.hashToNumber(blockId)
+    } else if (typeof blockId === 'bigint') {
+      number = blockId
+      hash = await this.numberToHash(blockId)
+    } else {
+      throw EthereumJSErrorWithoutCode('Unknown blockId type')
+    }
+
+    if (hash === undefined || number === undefined) return undefined
+    const header = await this.getHeader(hash, number)
+    let body = await this.getBody(hash, number)
+
+    // be backward compatible where we didn't use to store a body with no txs, uncles, withdrawals
+    // otherwise the body is never partially stored and if we have some body, its in entirety
+    if (body === undefined) {
+      body = [[], []] as BlockBodyBytes
+      // Do extra validations on the header since we are assuming empty transactions and uncles
+      if (!equalsBytes(header.transactionsTrie, KECCAK256_RLP)) {
+        throw EthereumJSErrorWithoutCode('transactionsTrie root should be equal to hash of null')
+      }
+
+      if (!equalsBytes(header.uncleHash, KECCAK256_RLP_ARRAY)) {
+        throw EthereumJSErrorWithoutCode('uncle hash should be equal to hash of empty array')
+      }
+
+      // If this block had empty withdrawals push an empty array in body
+      if (header.withdrawalsRoot !== undefined) {
+        // Do extra validations for withdrawal before assuming empty withdrawals
+        if (!equalsBytes(header.withdrawalsRoot, KECCAK256_RLP)) {
+          throw EthereumJSErrorWithoutCode(
+            'withdrawals root shoot be equal to hash of null when no withdrawals',
+          )
+        } else {
+          body.push([])
+        }
+      }
+    }
+
+    const blockData = [header.raw(), ...body] as BlockBytes
+    const opts: BlockOptions = { common: this.common, setHardfork: true }
+    return createBlockFromBytesArray(blockData, opts)
+  }
+
+  /**
+   * Fetches body of a block given its hash and number.
+   */
+  async getBody(blockHash: Uint8Array, blockNumber: bigint): Promise<BlockBodyBytes | undefined> {
+    const body = await this.get(DBTarget.Body, { blockHash, blockNumber })
+    return body !== undefined ? (RLP.decode(body) as BlockBodyBytes) : undefined
+  }
+
+  /**
+   * Fetches header of a block given its hash and number.
+   */
+  async getHeader(blockHash: Uint8Array, blockNumber: bigint) {
+    const encodedHeader = await this.get(DBTarget.Header, { blockHash, blockNumber })
+    const headerValues = RLP.decode(encodedHeader)
+
+    const opts: BlockOptions = { common: this.common, setHardfork: true }
+    return createBlockHeaderFromBytesArray(headerValues as Uint8Array[], opts)
+  }
+
+  /**
+   * Fetches total difficulty for a block given its hash and number.
+   */
+  async getTotalDifficulty(blockHash: Uint8Array, blockNumber: bigint): Promise<bigint> {
+    const td = await this.get(DBTarget.TotalDifficulty, { blockHash, blockNumber })
+    return bytesToBigInt(RLP.decode(td) as Uint8Array)
+  }
+
+  /**
+   * Performs a block hash to block number lookup.
+   */
+  async hashToNumber(blockHash: Uint8Array): Promise<bigint | undefined> {
+    const value = await this.get(DBTarget.HashToNumber, { blockHash })
+    if (value === undefined) {
+      throw EthereumJSErrorWithoutCode(`value for ${bytesToHex(blockHash)} not found in DB`)
+    }
+    return value !== undefined ? bytesToBigInt(value) : undefined
+  }
+
+  /**
+   * Performs a block number to block hash lookup.
+   */
+  async numberToHash(blockNumber: bigint): Promise<Uint8Array | undefined> {
+    const value = await this.get(DBTarget.NumberToHash, { blockNumber })
+    return value
+  }
+
+  /**
+   * Fetches a key from the db. If `opts.cache` is specified
+   * it first tries to load from cache, and on cache miss will
+   * try to put the fetched item on cache afterwards.
+   */
+  async get(dbOperationTarget: DBTarget, key?: DatabaseKey): Promise<any> {
+    const dbGetOperation = DBOp.get(dbOperationTarget, key)
+
+    const cacheString = dbGetOperation.cacheString
+    const dbKey = dbGetOperation.baseDBOp.key
+
+    if (cacheString !== undefined) {
+      if (this._cache[cacheString] === undefined) {
+        throw EthereumJSErrorWithoutCode(`Invalid cache: ${cacheString}`)
+      }
+      let value = this._cache[cacheString].get(dbKey)
+      if (value === undefined) {
+        value = (await this._db.get(dbKey, {
+          keyEncoding: dbGetOperation.baseDBOp.keyEncoding,
+          valueEncoding: dbGetOperation.baseDBOp.valueEncoding,
+        })) as Uint8Array | undefined
+        if (value !== undefined) {
+          this._cache[cacheString].set(dbKey, value)
+        }
+      }
+
+      return value
+    }
+    return this._db.get(dbKey, {
+      keyEncoding: dbGetOperation.baseDBOp.keyEncoding,
+      valueEncoding: dbGetOperation.baseDBOp.valueEncoding,
+    })
+  }
+
+  /**
+   * Performs a batch operation on db.
+   */
+  async batch(ops: DBOp[]) {
+    const convertedOps: BatchDBOp[] = ops.map((op) => {
+      const type = op.baseDBOp.type ?? (op.baseDBOp.value !== undefined ? 'put' : 'del')
+      const convertedOp = {
+        key: op.baseDBOp.key,
+        value: op.baseDBOp.value,
+        type,
+        opts: {
+          keyEncoding: op.baseDBOp.keyEncoding,
+          valueEncoding: op.baseDBOp.valueEncoding,
+        },
+      }
+      if (type === 'put') return convertedOp as PutBatch
+      else return convertedOp as DelBatch
+    })
+    // update the current cache for each operation
+    ops.map((op) => op.updateCache(this._cache))
+    return this._db.batch(convertedOps)
+  }
+}