Block Lookup Reporter

A small utility for summarizing block headers and drilling into transactions from an Ethereum JSON-RPC endpoint.

Capabilities

Summarizes block headers

• Given "latest" as the block reference with default options, resolves block number, block hash, miner address, returns only transaction hashes, and reports the transaction count. @test
• Given a specific block number and includeTransactions: true, returns at least the first transaction object (hash, from, to, value) and a transaction count that matches the number of returned transactions. @test

Retrieves transaction by hash

• Given a known transaction hash, returns block number, from/to/value, and whether the receipt status indicates success; returns null when the transaction hash cannot be found. @test

Retrieves transaction by block index

• Given a block identifier and transaction index, returns the transaction hash and receipt status corresponding to that position in the block; aligns with the same transaction when the block is hydrated with transactions. @test

Implementation

@generates

API

export interface BlockSummaryOptions {
  includeTransactions?: boolean;
}

export interface TransactionDetails {
  hash: string;
  from: string;
  to?: string | null;
  value: bigint;
}

export interface BlockSummary {
  blockNumber: bigint;
  blockHash: string;
  miner: string;
  transactionCount: number;
  transactions: (string | TransactionDetails)[];
}

export interface TransactionLookup {
  hash: string;
  blockNumber: bigint;
  from: string;
  to?: string | null;
  value: bigint;
  receiptStatus: boolean;
}

export interface BlockTransactionRef {
  block: number | string;
  index: number;
}

export class BlockLookupService {
  constructor(endpointOrClient: unknown);
  fetchBlockSummary(blockRef?: number | string, options?: BlockSummaryOptions): Promise<BlockSummary>;
  fetchTransactionByHash(hash: string): Promise<TransactionLookup | null>;
  fetchTransactionFromBlock(ref: BlockTransactionRef): Promise<TransactionLookup | null>;
}

Dependencies { .dependencies }

web3-eth { .dependency }

Provides Ethereum JSON-RPC access for block and transaction queries.