or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

block-operations.mdconsensus-operations.mdheader-operations.mdindex.mdutility-functions.md
tile.json

tessl/npm-ethereumjs--block

Provides Block serialization and help functions for Ethereum blockchain operations

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@ethereumjs/block@10.0.x

To install, run

npx @tessl/cli install tessl/npm-ethereumjs--block@10.0.0

index.mddocs/

@ethereumjs/block

@ethereumjs/block provides comprehensive Ethereum block handling and serialization functionality for the EthereumJS ecosystem. It implements schema and functions for creating, validating, and manipulating Ethereum blocks and block headers with support for all major Ethereum improvements including EIP-1559 fee markets, EIP-4844 shard blob transactions, EIP-4895 beacon chain withdrawals, and EIP-7685 consensus layer requests.

Package Information

  • Package Name: @ethereumjs/block
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @ethereumjs/block

Core Imports

import { createBlock, createBlockHeader, Block, BlockHeader } from "@ethereumjs/block";

For CommonJS:

const { createBlock, createBlockHeader, Block, BlockHeader } = require("@ethereumjs/block");

Basic Usage

import { createBlock, createBlockHeader } from "@ethereumjs/block";
import { Common } from "@ethereumjs/common";

// Create a block header
const header = createBlockHeader({
  number: 1n,
  gasLimit: 8000000n,
  timestamp: Math.floor(Date.now() / 1000),
});

// Create a complete block
const block = createBlock({
  header: {
    number: 1n,
    gasLimit: 8000000n,
    timestamp: Math.floor(Date.now() / 1000),
  },
  transactions: [],
});

// Validate and serialize
await block.validateData();
const serialized = block.serialize();
const hash = block.hash();

Architecture

@ethereumjs/block is built around several key components:

  • Block Class: Complete Ethereum block representation with header, transactions, uncles, and withdrawals
  • BlockHeader Class: Block header with all consensus-critical fields and validation methods
  • Constructor Functions: Tree-shakeable factory methods for creating blocks and headers from various data sources
  • Consensus Support: Functions for Ethash (PoW) and Clique (PoA) consensus mechanisms
  • EIP Compatibility: Full support for major Ethereum improvements including fee markets, blob transactions, and withdrawals
  • Serialization: Complete RLP encoding/decoding and JSON conversion capabilities

Capabilities

Block Operations

Core block functionality for creating, validating, and manipulating complete Ethereum blocks with transactions, uncles, and withdrawals.

class Block {
  readonly header: BlockHeader;
  readonly transactions: TypedTransaction[];
  readonly uncleHeaders: BlockHeader[];
  readonly withdrawals?: Withdrawal[];
  readonly common: Common;
  readonly executionWitness?: VerkleExecutionWitness | null;

  hash(): Uint8Array;
  serialize(): Uint8Array;
  isGenesis(): boolean;
  async validateData(onlyHeader?: boolean, verifyTxs?: boolean): Promise<void>;
  transactionsAreValid(): boolean;
  toJSON(): JSONBlock;
}

function createBlock(blockData?: BlockData, opts?: BlockOptions): Block;
function createBlockFromRLP(serialized: Uint8Array, opts?: BlockOptions): Block;
function createBlockFromRPC(blockParams: JSONRPCBlock, uncles?: JSONHeader[], options?: BlockOptions): Block;

Block Operations

Block Header Operations

Block header functionality with all consensus-critical fields, validation methods, and EIP-specific calculations.

class BlockHeader {
  readonly parentHash: Uint8Array;
  readonly coinbase: Address;
  readonly stateRoot: Uint8Array;
  readonly number: bigint;
  readonly gasLimit: bigint;
  readonly timestamp: bigint;
  readonly baseFeePerGas?: bigint;
  readonly withdrawalsRoot?: Uint8Array;
  readonly blobGasUsed?: bigint;
  readonly common: Common;

  hash(): Uint8Array;
  serialize(): Uint8Array;
  isGenesis(): boolean;
  calcNextBaseFee(): bigint;
  getBlobGasPrice(): bigint;
  validateGasLimit(parentBlockHeader: BlockHeader): void;
}

function createBlockHeader(headerData?: HeaderData, opts?: BlockOptions): BlockHeader;
function createBlockHeaderFromRLP(serializedHeaderData: Uint8Array, opts?: BlockOptions): BlockHeader;

Header Operations

Consensus Algorithms

Support for Ethereum consensus mechanisms including Ethash Proof-of-Work and Clique Proof-of-Authority.

// Clique PoA functions
function cliqueSigner(header: BlockHeader): Address;
function cliqueVerifySignature(header: BlockHeader, signerList: Address[]): boolean;
function cliqueIsEpochTransition(header: BlockHeader): boolean;

// Ethash PoW functions
function ethashCanonicalDifficulty(block: Block, parentBlock: Block): bigint;

// Constants
const CLIQUE_EXTRA_VANITY: number;
const CLIQUE_EXTRA_SEAL: number;

Consensus Operations

Utility Functions

Helper functions for trie root calculations, data conversions, and blockchain-specific operations.

function genTransactionsTrieRoot(txs: TypedTransaction[], emptyTrie?: MerklePatriciaTrie): Promise<Uint8Array>;
function genWithdrawalsTrieRoot(wts: Withdrawal[], emptyTrie?: MerklePatriciaTrie): Promise<Uint8Array>;
function genRequestsRoot(requests: CLRequest<CLRequestType>[], sha256Function: Function): Uint8Array;
function valuesArrayToHeaderData(values: BlockHeaderBytes): HeaderData;
function executionPayloadFromBeaconPayload(payload: BeaconPayloadJSON): ExecutionPayload;

Utility Functions

Types

Core Configuration Types

interface BlockOptions {
  common?: Common;
  setHardfork?: boolean;
  params?: ParamsDict;
  calcDifficultyFromHeader?: BlockHeader;
  freeze?: boolean;
  skipConsensusFormatValidation?: boolean;
  executionWitness?: VerkleExecutionWitness;
}

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;
}

interface BlockData {
  header?: HeaderData;
  transactions?: Array<TxData[TransactionType]>;
  uncleHeaders?: Array<HeaderData>;
  withdrawals?: Array<WithdrawalData>;
  executionWitness?: VerkleExecutionWitness | null;
}

Serialization Types

type BlockBytes = 
  | [BlockHeaderBytes, TransactionsBytes, UncleHeadersBytes]
  | [BlockHeaderBytes, TransactionsBytes, UncleHeadersBytes, WithdrawalsBytes]
  | [BlockHeaderBytes, TransactionsBytes, UncleHeadersBytes, WithdrawalsBytes, ExecutionWitnessBytes];

type BlockHeaderBytes = Uint8Array[];
type TransactionsBytes = Uint8Array[][] | Uint8Array[];
type UncleHeadersBytes = Uint8Array[][];
type WithdrawalsBytes = WithdrawalBytes[];
type ExecutionWitnessBytes = Uint8Array;

JSON Representation Types

interface JSONBlock {
  header?: JSONHeader;
  transactions?: JSONTx[];
  uncleHeaders?: JSONHeader[];
  withdrawals?: JSONRPCWithdrawal[];
  executionWitness?: VerkleExecutionWitness | null;
}

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;
}

interface JSONRPCBlock {
  number: PrefixedHexString;
  hash: PrefixedHexString;
  parentHash: PrefixedHexString;
  nonce: PrefixedHexString;
  sha3Uncles: PrefixedHexString;
  logsBloom: PrefixedHexString;
  transactionsRoot: PrefixedHexString;
  stateRoot: PrefixedHexString;
  receiptsRoot: PrefixedHexString;
  miner: PrefixedHexString;
  difficulty: PrefixedHexString | NumericString;
  extraData: PrefixedHexString;
  gasLimit: PrefixedHexString;
  gasUsed: PrefixedHexString;
  timestamp: PrefixedHexString;
  transactions: Array<JSONRPCTx | PrefixedHexString>;
  uncles: PrefixedHexString[];
  baseFeePerGas?: PrefixedHexString;
  withdrawals?: Array<JSONRPCWithdrawal>;
  withdrawalsRoot?: PrefixedHexString;
  blobGasUsed?: PrefixedHexString;
  excessBlobGas?: PrefixedHexString;
  parentBeaconBlockRoot?: PrefixedHexString;
  requestsHash?: PrefixedHexString;
}

Engine API Types

interface ExecutionPayload {
  parentHash: PrefixedHexString;
  feeRecipient: PrefixedHexString;
  stateRoot: PrefixedHexString;
  receiptsRoot: PrefixedHexString;
  logsBloom: PrefixedHexString;
  prevRandao: PrefixedHexString;
  blockNumber: PrefixedHexString;
  gasLimit: PrefixedHexString;
  gasUsed: PrefixedHexString;
  timestamp: PrefixedHexString;
  extraData: PrefixedHexString;
  baseFeePerGas: PrefixedHexString;
  blockHash: PrefixedHexString;
  transactions: PrefixedHexString[];
  withdrawals?: WithdrawalV1[];
  blobGasUsed?: PrefixedHexString;
  excessBlobGas?: PrefixedHexString;
  parentBeaconBlockRoot?: PrefixedHexString;
  requestsHash?: PrefixedHexString;
  executionWitness?: VerkleExecutionWitness | null;
}

type WithdrawalV1 = {
  index: PrefixedHexString;
  validatorIndex: PrefixedHexString;
  address: PrefixedHexString;
  amount: PrefixedHexString;
};

type BeaconPayloadJSON = ExecutionPayload;

interface EthersProvider {
  // Interface for Ethers.js provider instances
  // Allows using Ethers provider objects instead of URL strings
}