@feelyourprotocol/block 8141.0.0

package/src/header/index.ts

@@ -0,0 +1,2 @@
+export * from './constructors.ts'
+export * from './header.ts'

package/src/helpers.ts

@@ -0,0 +1,223 @@
+import { MerklePatriciaTrie } from '@feelyourprotocol/mpt'
+import { RLP } from '@feelyourprotocol/rlp'
+import { Blob4844Tx } from '@feelyourprotocol/tx'
+import {
+  BIGINT_0,
+  BIGINT_1,
+  EthereumJSErrorWithoutCode,
+  TypeOutput,
+  concatBytes,
+  isHexString,
+  toType,
+} from '@feelyourprotocol/util'
+
+import { type Common } from '@feelyourprotocol/common'
+import type { TypedTransaction } from '@feelyourprotocol/tx'
+import type { CLRequest, CLRequestType, PrefixedHexString, Withdrawal } from '@feelyourprotocol/util'
+import type { BlockHeaderBytes, HeaderData } from './types.ts'
+/**
+ * Returns a 0x-prefixed hex number string from a hex string or string integer.
+ * @param {string} input string to check, convert, and return
+ */
+export const numberToHex = function (input?: string): PrefixedHexString | undefined {
+  if (input === undefined) return undefined
+  if (!isHexString(input)) {
+    const regex = new RegExp(/^\d+$/) // test to make sure input contains only digits
+    if (!regex.test(input)) {
+      const msg = `Cannot convert string to hex string. numberToHex only supports 0x-prefixed hex or integer strings but the given string was: ${input}`
+      throw EthereumJSErrorWithoutCode(msg)
+    }
+    return `0x${parseInt(input, 10).toString(16)}`
+  }
+  return input
+}
+
+/**
+ * Converts the canonical byte-array representation of a header into structured {@link HeaderData}.
+ * @param values Header field values in canonical order
+ * @returns Parsed header data
+ */
+export function valuesArrayToHeaderData(values: BlockHeaderBytes): HeaderData {
+  const [
+    parentHash,
+    uncleHash,
+    coinbase,
+    stateRoot,
+    transactionsTrie,
+    receiptTrie,
+    logsBloom,
+    difficulty,
+    number,
+    gasLimit,
+    gasUsed,
+    timestamp,
+    extraData,
+    mixHash,
+    nonce,
+    baseFeePerGas,
+    withdrawalsRoot,
+    blobGasUsed,
+    excessBlobGas,
+    parentBeaconBlockRoot,
+    requestsHash,
+    blockAccessListHash,
+    slotNumber,
+  ] = values
+
+  if (values.length > 23) {
+    throw EthereumJSErrorWithoutCode(
+      `invalid header. More values than expected were received. Max: 23, got: ${values.length}`,
+    )
+  }
+  if (values.length < 15) {
+    throw EthereumJSErrorWithoutCode(
+      `invalid header. Less values than expected were received. Min: 15, got: ${values.length}`,
+    )
+  }
+
+  return {
+    parentHash,
+    uncleHash,
+    coinbase,
+    stateRoot,
+    transactionsTrie,
+    receiptTrie,
+    logsBloom,
+    difficulty,
+    number,
+    gasLimit,
+    gasUsed,
+    timestamp,
+    extraData,
+    mixHash,
+    nonce,
+    baseFeePerGas,
+    withdrawalsRoot,
+    blobGasUsed,
+    excessBlobGas,
+    parentBeaconBlockRoot,
+    requestsHash,
+    blockAccessListHash,
+    slotNumber,
+  }
+}
+
+/**
+ * Retrieves the header difficulty as a bigint if the field is provided.
+ * @param headerData Header data potentially containing a difficulty value
+ * @returns Difficulty as bigint, or `null` when unset
+ */
+export function getDifficulty(headerData: HeaderData): bigint | null {
+  const { difficulty } = headerData
+  if (difficulty !== undefined) {
+    return toType(difficulty, TypeOutput.BigInt)
+  }
+  return null
+}
+
+/**
+ * Counts the total number of blob commitments contained in the provided transactions.
+ * @param transactions Transactions to inspect for blob data
+ * @returns Number of blob versioned hashes referenced
+ */
+export const getNumBlobs = (transactions: TypedTransaction[]) => {
+  let numBlobs = 0
+  for (const tx of transactions) {
+    if (tx instanceof Blob4844Tx) {
+      numBlobs += tx.blobVersionedHashes.length
+    }
+  }
+  return numBlobs
+}
+
+/**
+ * Approximates `factor * e ** (numerator / denominator)` using Taylor expansion
+ */
+export const fakeExponential = (factor: bigint, numerator: bigint, denominator: bigint) => {
+  let i = BIGINT_1
+  let output = BIGINT_0
+  let numerator_accumulator = factor * denominator
+  while (numerator_accumulator > BIGINT_0) {
+    output += numerator_accumulator
+    numerator_accumulator = (numerator_accumulator * numerator) / (denominator * i)
+    i++
+  }
+
+  return output / denominator
+}
+
+/**
+ * Returns the blob gas price depending upon the `excessBlobGas` value
+ * @param excessBlobGas
+ * @param common
+ */
+export const computeBlobGasPrice = (excessBlobGas: bigint, common: Common) => {
+  return fakeExponential(
+    common.param('minBlobGas'),
+    excessBlobGas,
+    common.param('blobGasPriceUpdateFraction'),
+  )
+}
+
+/**
+ * Returns the withdrawals trie root for array of Withdrawal.
+ * @param wts array of Withdrawal to compute the root of
+ * @param emptyTrie Optional trie used to generate the root
+ */
+export async function genWithdrawalsTrieRoot(wts: Withdrawal[], emptyTrie?: MerklePatriciaTrie) {
+  const trie = emptyTrie ?? new MerklePatriciaTrie()
+  for (const [i, wt] of wts.entries()) {
+    await trie.put(RLP.encode(i), RLP.encode(wt.raw()))
+  }
+  return trie.root()
+}
+
+/**
+ * Returns the txs trie root for array of TypedTransaction
+ * @param txs array of TypedTransaction to compute the root of
+ * @param emptyTrie Optional trie used to generate the root
+ */
+export async function genTransactionsTrieRoot(
+  txs: TypedTransaction[],
+  emptyTrie?: MerklePatriciaTrie,
+) {
+  const trie = emptyTrie ?? new MerklePatriciaTrie()
+  for (const [i, tx] of txs.entries()) {
+    await trie.put(RLP.encode(i), tx.serialize())
+  }
+  return trie.root()
+}
+
+/**
+ * Returns the requests trie root for an array of CLRequests
+ * @param requests - an array of CLRequests
+ * @param sha256Function Hash function used to derive the requests root
+ * @param emptyTrie optional empty trie used to generate the root
+ * @returns a 32 byte Uint8Array representing the requests trie root
+ */
+export function genRequestsRoot(
+  requests: CLRequest<CLRequestType>[],
+  sha256Function: (msg: Uint8Array) => Uint8Array,
+) {
+  // Requests should be sorted in monotonically ascending order based on type
+  // and whatever internal sorting logic is defined by each request type
+  if (requests.length > 1) {
+    for (let x = 1; x < requests.length; x++) {
+      if (requests[x].type < requests[x - 1].type)
+        throw EthereumJSErrorWithoutCode('requests are not sorted in ascending order')
+    }
+  }
+
+  // def compute_requests_hash(list):
+  //    return keccak_256(rlp.encode([rlp.encode(req) for req in list]))
+
+  let flatRequests = new Uint8Array()
+  for (const req of requests) {
+    if (req.bytes.length > 1) {
+      // Only append requests if they have content
+      flatRequests = concatBytes(flatRequests, sha256Function(req.bytes))
+    }
+  }
+
+  return sha256Function(flatRequests)
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from './block/index.ts'
+export * from './consensus/index.ts'
+export { type BeaconPayloadJSON, executionPayloadFromBeaconPayload } from './from-beacon-payload.ts'
+export * from './header/index.ts'
+export {
+  genRequestsRoot,
+  genTransactionsTrieRoot,
+  genWithdrawalsTrieRoot,
+  getDifficulty,
+  valuesArrayToHeaderData,
+} from './helpers.ts'
+export * from './params.ts'
+export * from './types.ts'

package/src/params.ts

@@ -0,0 +1,95 @@
+import type { ParamsDict } from '@feelyourprotocol/common'
+
+export const paramsBlock: ParamsDict = {
+  /**
+   * Frontier/Chainstart
+   */
+  1: {
+    // gasConfig
+    minGasLimit: 5000, // Minimum the gas limit may ever be
+    gasLimitBoundDivisor: 1024, // The bound divisor of the gas limit, used in update calculations
+    targetBlobGasPerBlock: 0, // Base value needed here since called pre-4844 in BlockHeader.calcNextExcessBlobGas()
+    blobGasPerBlob: 0,
+    maxBlobGasPerBlock: 0,
+    // format
+    maxExtraDataSize: 32, // Maximum size extra data may be after Genesis
+    // pow
+    minimumDifficulty: 131072, // The minimum that the difficulty may ever be
+    difficultyBoundDivisor: 2048, // The bound divisor of the difficulty, used in the update calculations
+    durationLimit: 13, // The decision boundary on the blocktime duration used to determine whether difficulty should go up or not
+    difficultyBombDelay: 0, // the amount of blocks to delay the difficulty bomb with
+  },
+  /**
+   * Byzantium HF Meta EIP
+   */
+  609: {
+    // pow
+    difficultyBombDelay: 3000000, // the amount of blocks to delay the difficulty bomb with
+  },
+  /**
+   * Constantinople HF Meta EIP
+   */
+  1013: {
+    // pow
+    difficultyBombDelay: 5000000, // the amount of blocks to delay the difficulty bomb with
+  },
+  /**
+   * MuirGlacier HF Meta EIP
+   */
+  2384: {
+    // pow
+    difficultyBombDelay: 9000000, // the amount of blocks to delay the difficulty bomb with
+  },
+  /**
+   * Fee market change for ETH 1.0 chain
+   */
+  1559: {
+    // gasConfig
+    baseFeeMaxChangeDenominator: 8, // Maximum base fee change denominator
+    elasticityMultiplier: 2, // Maximum block gas target elasticity
+    initialBaseFee: 1000000000, // Initial base fee on first EIP1559 block
+  },
+  /**
+   * Difficulty Bomb Delay to December 1st 2021
+   */
+  3554: {
+    // pow
+    difficultyBombDelay: 9500000, // the amount of blocks to delay the difficulty bomb with
+  },
+  /**
+   * Difficulty Bomb Delay to June 2022
+   */
+  4345: {
+    // pow
+    difficultyBombDelay: 10700000, // the amount of blocks to delay the difficulty bomb with
+  },
+  /**
+   * Shard Blob Transactions
+   */
+  4844: {
+    // gasConfig
+    targetBlobGasPerBlock: 393216, // The target blob gas consumed per block
+    blobGasPerBlob: 131072, // The base fee for blob gas per blob
+    maxBlobGasPerBlock: 786432, // The max blob gas allowable per block
+    blobGasPriceUpdateFraction: 3338477, // The denominator used in the exponential when calculating a blob gas price
+    // gasPrices
+    minBlobGas: 1, // The minimum fee per blob gas
+    blobBaseCost: 8192, // EIP-7918: Blob base fee bounded by execution cost (2^13)
+  },
+  /**
+   * Delaying Difficulty Bomb to mid-September 2022
+   */
+  5133: {
+    // pow
+    difficultyBombDelay: 11400000, // the amount of blocks to delay the difficulty bomb with
+  },
+  /**
+   * Blob throughput increase
+   */
+  7691: {
+    // gasConfig
+    targetBlobGasPerBlock: 786432, // The target blob gas consumed per block
+    maxBlobGasPerBlock: 1179648, // The max blob gas allowable per block
+    blobGasPriceUpdateFraction: 5007716, // The denominator used in the exponential when calculating a blob gas price
+  },
+}

package/src/types.ts

@@ -0,0 +1,254 @@
+import type { Common, ParamsDict } from '@feelyourprotocol/common'
+import type { JSONRPCTx, JSONTx, TransactionType, TxData } from '@feelyourprotocol/tx'
+import type {
+  AddressLike,
+  BigIntLike,
+  BytesLike,
+  JSONRPCWithdrawal,
+  NumericString,
+  PrefixedHexString,
+  WithdrawalBytes,
+  WithdrawalData,
+} from '@feelyourprotocol/util'
+import type { BlockHeader } from './index.ts'
+
+/**
+ * An object to set to which blockchain the blocks and their headers belong. This could be specified
+ * using a {@link Common} object, or `chain` and `hardfork`. Defaults to mainnet without specifying a
+ * hardfork.
+ */
+export interface BlockOptions {
+  /**
+   * A {@link Common} object defining the chain and the hardfork a block/block header belongs to.
+   *
+   * Object will be internally copied so that tx behavior don't incidentally
+   * change on future HF changes.
+   *
+   * Default: {@link Common} object set to `mainnet` and the HF currently defined as the default
+   * hardfork in the {@link Common} class.
+   *
+   * Current default hardfork: `merge`
+   */
+  common?: Common
+  /**
+   * Set the hardfork either by timestamp (for HFs from Shanghai onwards) or by block number
+   * for older Hfs.
+   *
+   * Default: `false` (HF is set to whatever default HF is set by the {@link Common} instance)
+   */
+  setHardfork?: boolean
+  /**
+   * Block parameters sorted by EIP can be found in the exported `paramsBlock` dictionary,
+   * which is internally passed to the associated `@feelyourprotocol/common` instance which
+   * manages parameter selection based on the hardfork and EIP settings.
+   *
+   * This option allows providing a custom set of parameters. Note that parameters
+   * get fully overwritten, so you need to extend the default parameter dict
+   * to provide the full parameter set.
+   *
+   * It is recommended to deep-clone the params object for this to avoid side effects:
+   *
+   * ```ts
+   * const params = JSON.parse(JSON.stringify(paramsBlock))
+   * params['1']['minGasLimit'] = 3000 // 5000
+   * ```
+   */
+  params?: ParamsDict
+  /**
+   * If a preceding {@link BlockHeader} (usually the parent header) is given the preceding
+   * header will be used to calculate the difficulty for this block and the calculated
+   * difficulty takes precedence over a provided static `difficulty` value.
+   *
+   * Note that this option has no effect on networks other than PoW/Ethash networks
+   * (respectively also deactivates on the Merge HF switching to PoS/Casper).
+   */
+  calcDifficultyFromHeader?: BlockHeader
+  /**
+   * A block object by default gets frozen along initialization. This gives you
+   * strong additional security guarantees on the consistency of the block parameters.
+   * It also enables block hash caching when the `hash()` method is called multiple times.
+   *
+   * If you need to deactivate the block freeze - e.g. because you want to subclass block and
+   * add additional properties - it is strongly encouraged that you do the freeze yourself
+   * within your code instead.
+   *
+   * Default: true
+   */
+  freeze?: boolean
+  /**
+   *  Skip consensus format validation checks on header if set. Defaults to false.
+   */
+  skipConsensusFormatValidation?: boolean
+}
+
+/**
+ * A block header's data.
+ */
+export interface HeaderData {
+  parentHash?: BytesLike
+  uncleHash?: BytesLike
+  coinbase?: AddressLike
+  stateRoot?: BytesLike
+  transactionsTrie?: BytesLike
+  receiptTrie?: BytesLike
+  logsBloom?: BytesLike
+  difficulty?: BigIntLike
+  number?: BigIntLike
+  gasLimit?: BigIntLike
+  gasUsed?: BigIntLike
+  timestamp?: BigIntLike
+  extraData?: BytesLike
+  mixHash?: BytesLike
+  nonce?: BytesLike
+  baseFeePerGas?: BigIntLike
+  withdrawalsRoot?: BytesLike
+  blobGasUsed?: BigIntLike
+  excessBlobGas?: BigIntLike
+  parentBeaconBlockRoot?: BytesLike
+  requestsHash?: BytesLike
+  /**
+   * 32 bytes hash of the block access list (EIP-7928)
+   */
+  blockAccessListHash?: BytesLike
+  /**
+   * Slot number (EIP-7843)
+   */
+  slotNumber?: BigIntLike
+}
+
+/**
+ * A block's data.
+ */
+export interface BlockData {
+  /**
+   * Header data for the block
+   */
+  header?: HeaderData
+  transactions?: Array<TxData[TransactionType]>
+  uncleHeaders?: Array<HeaderData>
+  withdrawals?: Array<WithdrawalData>
+}
+
+export type WithdrawalsBytes = WithdrawalBytes[]
+
+export type BlockBytes =
+  | [BlockHeaderBytes, TransactionsBytes, UncleHeadersBytes]
+  | [BlockHeaderBytes, TransactionsBytes, UncleHeadersBytes, WithdrawalsBytes]
+  | [BlockHeaderBytes, TransactionsBytes, UncleHeadersBytes, WithdrawalsBytes]
+
+export type BlockHeaderBytes = Uint8Array[]
+export type BlockBodyBytes = [TransactionsBytes, UncleHeadersBytes, WithdrawalsBytes?]
+/**
+ * TransactionsBytes can be an array of serialized txs for Typed Transactions or an array of Uint8Array Arrays for legacy transactions.
+ */
+export type TransactionsBytes = Uint8Array[][] | Uint8Array[]
+export type UncleHeadersBytes = Uint8Array[][]
+
+/**
+ * An object with the block's data represented as strings.
+ */
+export interface JSONBlock {
+  /**
+   * Header data for the block
+   */
+  header?: JSONHeader
+  transactions?: JSONTx[]
+  uncleHeaders?: JSONHeader[]
+  withdrawals?: JSONRPCWithdrawal[]
+}
+
+/**
+ * An object with the block header's data represented as 0x-prefixed hex strings.
+ */
+export interface JSONHeader {
+  parentHash?: PrefixedHexString
+  uncleHash?: PrefixedHexString
+  coinbase?: PrefixedHexString
+  stateRoot?: PrefixedHexString
+  transactionsTrie?: PrefixedHexString
+  receiptTrie?: PrefixedHexString
+  logsBloom?: PrefixedHexString
+  difficulty?: PrefixedHexString
+  number?: PrefixedHexString
+  gasLimit?: PrefixedHexString
+  gasUsed?: PrefixedHexString
+  timestamp?: PrefixedHexString
+  extraData?: PrefixedHexString
+  mixHash?: PrefixedHexString
+  nonce?: PrefixedHexString
+  baseFeePerGas?: PrefixedHexString
+  withdrawalsRoot?: PrefixedHexString
+  blobGasUsed?: PrefixedHexString
+  excessBlobGas?: PrefixedHexString
+  parentBeaconBlockRoot?: PrefixedHexString
+  requestsHash?: PrefixedHexString
+  blockAccessListHash?: PrefixedHexString
+  slotNumber?: PrefixedHexString
+}
+
+/*
+ * Based on https://ethereum.org/en/developers/docs/apis/json-rpc/
+ */
+export interface JSONRPCBlock {
+  number: PrefixedHexString // the block number.
+  hash: PrefixedHexString // hash of the block.
+  parentHash: PrefixedHexString // hash of the parent block.
+  mixHash?: PrefixedHexString // bit hash which proves combined with the nonce that a sufficient amount of computation has been carried out on this block.
+  nonce: PrefixedHexString // hash of the generated proof-of-work.
+  sha3Uncles: PrefixedHexString // SHA3 of the uncles data in the block.
+  logsBloom: PrefixedHexString // the bloom filter for the logs of the block.
+  transactionsRoot: PrefixedHexString // the root of the transaction trie of the block.
+  stateRoot: PrefixedHexString // the root of the final state trie of the block.
+  receiptsRoot: PrefixedHexString // the root of the receipts trie of the block.
+  miner: PrefixedHexString // the address of the beneficiary to whom the mining rewards were given.
+  difficulty: PrefixedHexString | NumericString // integer of the difficulty for this block. Can be a 0x-prefixed hex string or a string integer
+  totalDifficulty?: PrefixedHexString // integer of the total difficulty of the chain until this block.
+  extraData: PrefixedHexString // the “extra data” field of this block.
+  size: PrefixedHexString // integer the size of this block in bytes.
+  gasLimit: PrefixedHexString // the maximum gas allowed in this block.
+  gasUsed: PrefixedHexString // the total used gas by all transactions in this block.
+  timestamp: PrefixedHexString // the unix timestamp for when the block was collated.
+  transactions: Array<JSONRPCTx | PrefixedHexString> // Array of transaction objects, or 32 Bytes transaction hashes depending on the last given parameter.
+  uncles: PrefixedHexString[] // Array of uncle hashes
+  baseFeePerGas?: PrefixedHexString // If EIP-1559 is enabled for this block, returns the base fee per gas
+  withdrawals?: Array<JSONRPCWithdrawal> // If EIP-4895 is enabled for this block, array of withdrawals
+  withdrawalsRoot?: PrefixedHexString // If EIP-4895 is enabled for this block, the root of the withdrawal trie of the block.
+  blobGasUsed?: PrefixedHexString // If EIP-4844 is enabled for this block, returns the blob gas used for the block
+  excessBlobGas?: PrefixedHexString // If EIP-4844 is enabled for this block, returns the excess blob gas for the block
+  parentBeaconBlockRoot?: PrefixedHexString // If EIP-4788 is enabled for this block, returns parent beacon block root
+  requestsHash?: PrefixedHexString // If EIP-7685 is enabled for this block, returns the requests root
+  blockAccessListHash?: PrefixedHexString // If EIP-7928 is enabled for this block, returns the hash of the block access list
+  slotNumber?: PrefixedHexString // If EIP-7843 is enabled for this block, returns the slot number
+}
+
+export type WithdrawalV1 = {
+  index: PrefixedHexString // Quantity, 8 Bytes
+  validatorIndex: PrefixedHexString // Quantity, 8 bytes
+  address: PrefixedHexString // DATA, 20 bytes
+  amount: PrefixedHexString // Quantity, 32 bytes
+}
+
+// Note: all these strings are 0x-prefixed
+export type ExecutionPayload = {
+  parentHash: PrefixedHexString // DATA, 32 Bytes
+  feeRecipient: PrefixedHexString // DATA, 20 Bytes
+  stateRoot: PrefixedHexString // DATA, 32 Bytes
+  receiptsRoot: PrefixedHexString // DATA, 32 bytes
+  logsBloom: PrefixedHexString // DATA, 256 Bytes
+  prevRandao: PrefixedHexString // DATA, 32 Bytes
+  blockNumber: PrefixedHexString // QUANTITY, 64 Bits
+  gasLimit: PrefixedHexString // QUANTITY, 64 Bits
+  gasUsed: PrefixedHexString // QUANTITY, 64 Bits
+  timestamp: PrefixedHexString // QUANTITY, 64 Bits
+  extraData: PrefixedHexString // DATA, 0 to 32 Bytes
+  baseFeePerGas: PrefixedHexString // QUANTITY, 256 Bits
+  blockHash: PrefixedHexString // DATA, 32 Bytes
+  transactions: PrefixedHexString[] // Array of DATA - Array of transaction rlp strings,
+  withdrawals?: WithdrawalV1[] // Array of withdrawal objects
+  blobGasUsed?: PrefixedHexString // QUANTITY, 64 Bits
+  excessBlobGas?: PrefixedHexString // QUANTITY, 64 Bits
+  parentBeaconBlockRoot?: PrefixedHexString // QUANTITY, 64 Bits
+  requestsHash?: PrefixedHexString
+  blockAccessListHash?: PrefixedHexString // DATA, 32 Bytes
+  slotNumber?: PrefixedHexString // QUANTITY, 64 Bits (EIP-7843)
+}