@feelyourprotocol/blockchain 8141.0.0

package/src/db/operation.ts

@@ -0,0 +1,152 @@
+import { EthereumJSErrorWithoutCode, KeyEncoding, ValueEncoding } from '@feelyourprotocol/util'
+
+import {
+  HEADS_KEY,
+  HEAD_BLOCK_KEY,
+  HEAD_HEADER_KEY,
+  bodyKey,
+  hashToNumberKey,
+  headerKey,
+  numberToHashKey,
+  tdKey,
+} from './constants.ts'
+
+import type { CacheMap } from './manager.ts'
+
+export type DBTarget = (typeof DBTarget)[keyof typeof DBTarget]
+
+export const DBTarget = {
+  Heads: 0,
+  HeadHeader: 1,
+  HeadBlock: 2,
+  HashToNumber: 3,
+  NumberToHash: 4,
+  TotalDifficulty: 5,
+  Body: 6,
+  Header: 7,
+  CliqueSignerStates: 8,
+  CliqueVotes: 9,
+  CliqueBlockSigners: 10,
+} as const
+
+/**
+ * DBOpData is a type which has the purpose of holding the actual data of the Database Operation.
+ * @hidden
+ */
+export interface DBOpData {
+  type?: 'put' | 'del'
+  key: Uint8Array | string
+  keyEncoding: KeyEncoding
+  valueEncoding?: ValueEncoding
+  value?: Uint8Array | object
+}
+
+// a Database Key is identified by a block hash, a block number, or both
+export type DatabaseKey = {
+  blockNumber?: bigint
+  blockHash?: Uint8Array
+}
+
+/**
+ * The DBOp class aids creating database operations which is used by `level` using a more high-level interface
+ */
+export class DBOp {
+  public operationTarget: DBTarget
+  public baseDBOp: DBOpData
+  public cacheString: string | undefined
+
+  private constructor(operationTarget: DBTarget, key?: DatabaseKey) {
+    this.operationTarget = operationTarget
+
+    this.baseDBOp = {
+      key: '',
+      keyEncoding: KeyEncoding.Bytes,
+      valueEncoding: ValueEncoding.Bytes,
+    }
+
+    switch (operationTarget) {
+      case DBTarget.Heads: {
+        this.baseDBOp.key = HEADS_KEY
+        this.baseDBOp.valueEncoding = ValueEncoding.JSON
+        break
+      }
+      case DBTarget.HeadHeader: {
+        this.baseDBOp.key = HEAD_HEADER_KEY
+        this.baseDBOp.keyEncoding = KeyEncoding.String
+        break
+      }
+      case DBTarget.HeadBlock: {
+        this.baseDBOp.key = HEAD_BLOCK_KEY
+        this.baseDBOp.keyEncoding = KeyEncoding.String
+        break
+      }
+      case DBTarget.HashToNumber: {
+        this.baseDBOp.key = hashToNumberKey(key!.blockHash!)
+        this.cacheString = 'hashToNumber'
+        break
+      }
+      case DBTarget.NumberToHash: {
+        this.baseDBOp.key = numberToHashKey(key!.blockNumber!)
+        this.cacheString = 'numberToHash'
+        break
+      }
+      case DBTarget.TotalDifficulty: {
+        this.baseDBOp.key = tdKey(key!.blockNumber!, key!.blockHash!)
+        this.cacheString = 'td'
+        break
+      }
+      case DBTarget.Body: {
+        this.baseDBOp.key = bodyKey(key!.blockNumber!, key!.blockHash!)
+        this.cacheString = 'body'
+        break
+      }
+      case DBTarget.Header: {
+        this.baseDBOp.key = headerKey(key!.blockNumber!, key!.blockHash!)
+        this.cacheString = 'header'
+        break
+      }
+    }
+  }
+
+  public static get(operationTarget: DBTarget, key?: DatabaseKey): DBOp {
+    return new DBOp(operationTarget, key)
+  }
+
+  // set operation: note: value/key is not in default order
+  public static set(
+    operationTarget: DBTarget,
+    value: Uint8Array | object,
+    key?: DatabaseKey,
+  ): DBOp {
+    const dbOperation = new DBOp(operationTarget, key)
+    dbOperation.baseDBOp.value = value
+    dbOperation.baseDBOp.type = 'put'
+
+    if (operationTarget === DBTarget.Heads) {
+      dbOperation.baseDBOp.valueEncoding = ValueEncoding.JSON
+    } else {
+      dbOperation.baseDBOp.valueEncoding = ValueEncoding.Bytes
+    }
+
+    return dbOperation
+  }
+
+  public static del(operationTarget: DBTarget, key?: DatabaseKey): DBOp {
+    const dbOperation = new DBOp(operationTarget, key)
+    dbOperation.baseDBOp.type = 'del'
+    return dbOperation
+  }
+
+  public updateCache(cacheMap: CacheMap) {
+    if (this.cacheString !== undefined && cacheMap[this.cacheString] !== undefined) {
+      if (this.baseDBOp.type === 'put') {
+        this.baseDBOp.value instanceof Uint8Array &&
+          cacheMap[this.cacheString].set(this.baseDBOp.key, this.baseDBOp.value)
+      } else if (this.baseDBOp.type === 'del') {
+        cacheMap[this.cacheString].del(this.baseDBOp.key)
+      } else {
+        throw EthereumJSErrorWithoutCode('unsupported db operation on cache')
+      }
+    }
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,37 @@
+import { ChainGenesis } from '@feelyourprotocol/common'
+import { genesisMPTStateRoot } from '@feelyourprotocol/mpt'
+
+import type { Chain, Common, GenesisState } from '@feelyourprotocol/common'
+
+/**
+ * Safe creation of a new Blockchain object awaiting the initialization function,
+ * encouraged method to use when creating a blockchain object.
+ *
+ * @param opts Constructor options, see {@link BlockchainOptions}
+ */
+
+/**
+ * Merkle genesis root
+ * @param genesisState
+ * @param common
+ * @returns
+ */
+export async function genGenesisStateRoot(
+  genesisState: GenesisState,
+  common: Common,
+): Promise<Uint8Array> {
+  const genCommon = common.copy()
+  genCommon.setHardforkBy({
+    blockNumber: 0,
+    timestamp: genCommon.genesis().timestamp,
+  })
+  return genesisMPTStateRoot(genesisState)
+}
+
+/**
+ * Returns the genesis state root if chain is well known or an empty state's root otherwise
+ */
+export async function getGenesisStateRoot(chainId: Chain, common: Common): Promise<Uint8Array> {
+  const chainGenesis = ChainGenesis[chainId]
+  return chainGenesis !== undefined ? chainGenesis.stateRoot : genGenesisStateRoot({}, common)
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { Blockchain } from './blockchain.ts'
+export { CasperConsensus, CliqueConsensus, EthashConsensus } from './consensus/index.ts'
+export * from './constructors.ts'
+export {
+  DBOp,
+  DBSaveLookups,
+  DBSetBlockOrHeader,
+  DBSetHashToNumber,
+  DBSetTD,
+} from './db/helpers.ts'
+export * from './helpers.ts'
+export * from './types.ts'

package/src/types.ts

@@ -0,0 +1,256 @@
+import type { Block, BlockHeader } from '@feelyourprotocol/block'
+import type { Common, ConsensusAlgorithm, GenesisState } from '@feelyourprotocol/common'
+import type { DB, DBObject } from '@feelyourprotocol/util'
+import type { EventEmitter } from 'eventemitter3'
+import type { Blockchain } from './index.ts'
+
+export type OnBlock = (block: Block, reorg: boolean) => Promise<void> | void
+
+export type BlockchainEvent = {
+  deletedCanonicalBlocks: (data: Block[], resolve?: (result?: any) => void) => void
+}
+
+export interface BlockchainInterface {
+  consensus: Consensus | undefined
+  /**
+   * Adds a block to the blockchain.
+   *
+   * @param block - The block to be added to the blockchain.
+   */
+  putBlock(block: Block): Promise<void>
+
+  /**
+   * Deletes a block from the blockchain. All child blocks in the chain are
+   * deleted and any encountered heads are set to the parent block.
+   *
+   * @param blockHash - The hash of the block to be deleted
+   */
+  delBlock(blockHash: Uint8Array): Promise<void>
+
+  /**
+   * Returns a block by its hash or number.
+   */
+  getBlock(blockId: Uint8Array | number | bigint): Promise<Block>
+
+  /**
+   * Iterates through blocks starting at the specified iterator head and calls
+   * the onBlock function on each block.
+   *
+   * @param name - Name of the state root head
+   * @param onBlock - Function called on each block with params (block: Block,
+   * @param maxBlocks - optional maximum number of blocks to iterate through
+   * reorg: boolean)
+   */
+  iterator(
+    name: string,
+    onBlock: OnBlock,
+    maxBlocks?: number,
+    releaseLockOnCallback?: boolean,
+  ): Promise<number>
+
+  /**
+   * Returns a shallow copy of the blockchain that may share state with the original
+   */
+  shallowCopy(): BlockchainInterface
+
+  /**
+   * Validates a block header, throwing if invalid. It is being validated against the reported `parentHash`.
+   * @param header - header to be validated
+   * @param height - If this is an uncle header, this is the height of the block that is including it
+   */
+  validateHeader(header: BlockHeader, height?: bigint): Promise<void>
+
+  /**
+   * Returns the specified iterator head.
+   *
+   * @param name - Optional name of the iterator head (default: 'vm')
+   */
+  getIteratorHead(name?: string): Promise<Block>
+
+  /**
+   * Set header hash of a certain `tag`.
+   * When calling the iterator, the iterator will start running the first child block after the header hash currently stored.
+   * @param tag - The tag to save the headHash to
+   * @param headHash - The head hash to save
+   */
+  setIteratorHead(tag: string, headHash: Uint8Array): Promise<void>
+
+  /**
+   * Gets total difficulty for a block specified by hash and number
+   */
+  getTotalDifficulty?(hash: Uint8Array, number?: bigint): Promise<bigint>
+
+  /**
+   * Returns the latest full block in the canonical chain.
+   */
+  getCanonicalHeadBlock(): Promise<Block>
+
+  /**
+   * Optional events emitter
+   */
+  events?: EventEmitter<BlockchainEvent>
+}
+
+export interface GenesisOptions {
+  /**
+   * The blockchain only initializes successfully if it has a genesis block. If
+   * there is no block available in the DB and a `genesisBlock` is provided,
+   * then the provided `genesisBlock` will be used as genesis. If no block is
+   * present in the DB and no block is provided, then the genesis block as
+   * provided from the `common` will be used.
+   */
+  genesisBlock?: Block
+
+  /**
+   * 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
+   * }
+   * ```
+   */
+  genesisState?: GenesisState
+
+  /**
+   * State root of the genesis state
+   */
+  genesisStateRoot?: Uint8Array
+}
+
+export type ConsensusDict = {
+  [consensusAlgorithm: ConsensusAlgorithm | string]: Consensus
+}
+
+/**
+ * This are the options that the Blockchain constructor can receive.
+ */
+export interface BlockchainOptions extends GenesisOptions {
+  /**
+   * Specify the chain and hardfork by passing a {@link Common} instance.
+   *
+   * If not provided this defaults to chain `mainnet` and hardfork `chainstart`
+   *
+   */
+  common?: Common
+
+  /**
+   * Set the HF to the fork determined by the head block and update on head updates.
+   *
+   * Note: for HFs where the transition is also determined by a total difficulty
+   * threshold (merge HF) the calculated TD is additionally taken into account
+   * for HF determination.
+   *
+   * Default: `false` (HF is set to whatever default HF is set by the {@link Common} instance)
+   */
+  hardforkByHeadBlockNumber?: boolean
+
+  /**
+   * Database to store blocks and metadata.
+   * Can be any database implementation that adheres to the `DB` interface
+   */
+  db?: DB<Uint8Array | string | number, Uint8Array | string | DBObject>
+
+  /**
+   * This flag indicates if protocol-given consistency checks on
+   * block headers and included uncles and transactions should be performed,
+   * see Block#validate for details.
+   *
+   */
+  validateBlocks?: boolean
+
+  /**
+   * Validate the consensus with the respective consensus implementation passed
+   * to `consensusDict` (see respective option) `CasperConsensus` (which effectively
+   * does nothing) is available by default.
+   *
+   * For the build-in validation classes the following validations take place.
+   * - 'pow' with 'ethash' algorithm (validates the proof-of-work)
+   * - 'poa' with 'clique' algorithm (verifies the block signatures)
+   * Default: `false`.
+   */
+  validateConsensus?: boolean
+
+  /**
+   * Optional dictionary with consensus objects (adhering to the {@link Consensus} interface)
+   * if consensus validation is wished for certain consensus algorithms.
+   *
+   * Since consensus validation moved to the Ethereum consensus layer with Proof-of-Stake
+   * consensus is not validated by default. For `ConsensusAlgorithm.Ethash` and
+   * `ConsensusAlgorithm.Clique` consensus validation can be activated by passing in the
+   * respective consensus validation objects `EthashConsensus` or `CliqueConsensus`.
+   *
+   * ```ts
+   * import { CliqueConsensus, createBlockchain } from '@feelyourprotocol/blockchain'
+   * import type { ConsensusDict } from '@feelyourprotocol/blockchain'
+   *
+   * const consensusDict: ConsensusDict = {}
+   * consensusDict[ConsensusAlgorithm.Clique] = new CliqueConsensus()
+   * const blockchain = await createBlockchain({ common, consensusDict })
+   * ```
+   *
+   * Additionally it is possible to provide a fully custom consensus implementation.
+   * Note that this needs a custom `Common` object passed to the blockchain where
+   * the `ConsensusAlgorithm` string matches the string used here.
+   */
+  consensusDict?: ConsensusDict
+}
+
+/**
+ * Interface that a consensus class needs to implement.
+ */
+export interface Consensus {
+  algorithm: ConsensusAlgorithm | string
+  /**
+   * Initialize genesis for consensus mechanism
+   * @param genesisBlock genesis block
+   */
+  genesisInit(genesisBlock: Block): Promise<void>
+
+  /**
+   * Set up consensus mechanism
+   */
+  setup({ blockchain }: ConsensusOptions): Promise<void>
+
+  /**
+   * Validate block consensus parameters
+   * @param block block to be validated
+   */
+  validateConsensus(block: Block): Promise<void>
+
+  validateDifficulty(header: BlockHeader): Promise<void>
+
+  /**
+   * Update consensus on new block
+   * @param block new block
+   * @param commonAncestor common ancestor block header (optional)
+   * @param ancientHeaders array of ancestor block headers (optional)
+   */
+  newBlock(
+    block: Block,
+    commonAncestor?: BlockHeader,
+    ancientHeaders?: BlockHeader[],
+  ): Promise<void>
+}
+
+/**
+ * Options when initializing a class that implements the Consensus interface.
+ */
+export interface ConsensusOptions {
+  blockchain: Blockchain
+}