Block Operations

/**
 * Class representing a block in the Ethereum network
 */
class Block {
  readonly header: BlockHeader;
  readonly transactions: TypedTransaction[];
  readonly uncleHeaders: BlockHeader[];
  readonly withdrawals?: Withdrawal[];
  readonly common: Common;
  readonly executionWitness?: VerkleExecutionWitness | null;

  /**
   * Returns the hash of the block
   * @returns Block hash as Uint8Array
   */
  hash(): Uint8Array;

  /**
   * Returns the RLP serialization of the block
   * @returns RLP-encoded block as Uint8Array
   */
  serialize(): Uint8Array;

  /**
   * Checks if the block is the genesis block
   * @returns True if this is the genesis block
   */
  isGenesis(): boolean;

  /**
   * Returns raw bytes array representation of the block
   * @returns Array of raw bytes arrays
   */
  raw(): BlockBytes;

  /**
   * Validates the entire block including header and transactions
   * @param onlyHeader - Only validate header if true
   * @param verifyTxs - Verify transaction signatures if true
   */
  async validateData(onlyHeader?: boolean, verifyTxs?: boolean): Promise<void>;

  /**
   * Validates all transactions in the block
   * @returns True if all transactions are valid
   */
  transactionsAreValid(): boolean;

  /**
   * Gets detailed validation errors for transactions
   * @returns Array of validation error strings
   */
  getTransactionsValidationErrors(): string[];

  /**
   * Generates the transaction trie root for this block
   * @returns Transaction trie root hash
   */
  async genTxTrie(): Promise<Uint8Array>;

  /**
   * Validates that the transaction trie root matches the calculated value
   * @returns True if transaction trie is valid
   */
  async transactionsTrieIsValid(): Promise<boolean>;

  /**
   * Validates uncle hash against calculated value
   * @returns True if uncle hash is valid
   */
  uncleHashIsValid(): boolean;

  /**
   * Validates uncle headers
   */
  validateUncles(): void;

  /**
   * Validates withdrawals trie root (EIP-4895)
   * @returns True if withdrawals trie is valid
   */
  async withdrawalsTrieIsValid(): Promise<boolean>;

  /**
   * Validates gas limit against parent block
   * @param parentBlock - Parent block for validation
   */
  validateGasLimit(parentBlock: Block): void;

  /**
   * Validates blob transactions against parent header (EIP-4844)
   * @param parentHeader - Parent block header
   */
  validateBlobTransactions(parentHeader: BlockHeader): void;

  /**
   * Returns JSON representation of the block
   * @returns Block as JSON object
   */
  toJSON(): JSONBlock;

  /**
   * Converts block to execution payload format
   * @returns ExecutionPayload structure
   */
  toExecutionPayload(): ExecutionPayload;

  /**
   * Returns compact error string representation
   * @returns Error string
   */
  errorStr(): string;
}

/**
 * Creates a block from block data dictionary
 * @param blockData - Block data object
 * @param opts - Block options
 * @returns Block instance
 */
function createBlock(blockData?: BlockData, opts?: BlockOptions): Block;

/**
 * Creates an empty block with only header data (optimized for tree shaking)
 * @param headerData - Header data for the empty block
 * @param opts - Block options
 * @returns Block instance with no transactions or uncles
 */
function createEmptyBlock(headerData: HeaderData, opts?: BlockOptions): Block;

/**
 * Creates a block from raw bytes array
 * @param values - Block bytes array
 * @param opts - Block options
 * @returns Block instance
 */
function createBlockFromBytesArray(values: BlockBytes, opts?: BlockOptions): Block;

/**
 * Creates a block from RLP-serialized data
 * @param serialized - RLP-encoded block data
 * @param opts - Block options
 * @returns Block instance
 */
function createBlockFromRLP(serialized: Uint8Array, opts?: BlockOptions): Block;

/**
 * Creates a block from JSON-RPC response format
 * @param blockParams - JSON-RPC block object
 * @param uncles - Optional uncle headers
 * @param options - Block options
 * @returns Block instance
 */
function createBlockFromRPC(
  blockParams: JSONRPCBlock, 
  uncles?: JSONHeader[], 
  options?: BlockOptions
): Block;

/**
 * Creates a block from JSON-RPC provider by fetching block data
 * @param provider - JSON-RPC provider URL or EthersProvider instance
 * @param blockTag - Block number or tag ("latest", "pending", etc.)
 * @param opts - Block options
 * @returns Promise resolving to Block instance
 */
async function createBlockFromJSONRPCProvider(
  provider: string | EthersProvider, 
  blockTag: string | bigint, 
  opts: BlockOptions
): Promise<Block>;

/**
 * Creates a block from execution payload (Engine API)
 * @param payload - Execution payload object
 * @param opts - Block options
 * @returns Promise resolving to Block instance
 */
async function createBlockFromExecutionPayload(
  payload: ExecutionPayload, 
  opts?: BlockOptions
): Promise<Block>;

/**
 * Creates a block from beacon payload JSON format
 * @param payload - Beacon payload JSON object
 * @param opts - Block options
 * @returns Promise resolving to Block instance
 */
async function createBlockFromBeaconPayloadJSON(
  payload: BeaconPayloadJSON, 
  opts?: BlockOptions
): Promise<Block>;

/**
 * Creates a sealed Clique PoA block with signature
 * @param blockData - Block data object
 * @param cliqueSigner - Signer private key (32 bytes)
 * @param opts - Block options
 * @returns Sealed Block instance
 */
function createSealedCliqueBlock(
  blockData?: BlockData, 
  cliqueSigner: Uint8Array, 
  opts?: BlockOptions
): Block;

import { 
  createBlock, 
  createBlockFromRLP, 
  createBlockFromRPC,
  createBlockFromExecutionPayload 
} from "@ethereumjs/block";

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

// Create from RLP data
const rlpData = new Uint8Array([/* RLP bytes */]);
const blockFromRLP = createBlockFromRLP(rlpData);

// Create from JSON-RPC response
const jsonRpcBlock = {
  number: "0x1",
  hash: "0x...",
  parentHash: "0x...",
  // ... other JSON-RPC fields
};
const blockFromRPC = createBlockFromRPC(jsonRpcBlock);

// Create from execution payload (Engine API)
const payload = {
  parentHash: "0x...",
  feeRecipient: "0x...",
  stateRoot: "0x...",
  // ... other payload fields
};
const blockFromPayload = await createBlockFromExecutionPayload(payload);

// Validate the created block
await block.validateData();
console.log("Block hash:", block.hash());
console.log("Is genesis:", block.isGenesis());
console.log("Transactions valid:", block.transactionsAreValid());

/**
 * Validates the entire block
 * Checks header validity, transaction trie, uncle hash, and withdrawals trie
 */
async function validateBlockData(
  block: Block, 
  onlyHeader?: boolean, 
  verifyTxs?: boolean
): Promise<void>;

/**
 * Validates all transactions in the block
 * Returns detailed error information if any transaction is invalid
 */
function validateBlockTransactions(block: Block): {
  valid: boolean;
  errors: string[];
};

/**
 * Validates blob transactions against parent header (EIP-4844)
 * Ensures blob gas usage and pricing compliance
 */
function validateBlobTransactions(
  block: Block, 
  parentHeader: BlockHeader
): void;

import { createBlock } from "@ethereumjs/block";

const block = createBlock(blockData);

try {
  // Full validation including transaction signatures
  await block.validateData(false, true);
  console.log("Block is valid");
} catch (error) {
  console.error("Validation failed:", error.message);
}

// Check specific validation aspects
const transactionsValid = block.transactionsAreValid();
const uncleHashValid = block.uncleHashIsValid();
const txTrieValid = await block.transactionsTrieIsValid();

if (!transactionsValid) {
  const errors = block.getTransactionsValidationErrors();
  console.log("Transaction errors:", errors);
}

/**
 * Block serialization methods
 */
interface BlockSerialization {
  /** Returns RLP-encoded block as Uint8Array */
  serialize(): Uint8Array;
  
  /** Returns raw bytes array representation */
  raw(): BlockBytes;
  
  /** Returns JSON representation */
  toJSON(): JSONBlock;
  
  /** Converts to execution payload format (Engine API) */
  toExecutionPayload(): ExecutionPayload;
}

import { createBlock } from "@ethereumjs/block";

const block = createBlock(blockData);

// Get different serialization formats
const rlpBytes = block.serialize();
const rawBytes = block.raw();
const jsonFormat = block.toJSON();
const executionPayload = block.toExecutionPayload();

// Block hash and basic info
const blockHash = block.hash();
const isGenesis = block.isGenesis();

console.log("Block hash:", blockHash);
console.log("RLP size:", rlpBytes.length);
console.log("JSON format:", JSON.stringify(jsonFormat, null, 2));