Bitcoin Core getblock RPC: Block Inspection Guide

This guide explains Bitcoin Core getblock RPC in plain English. It shows what the command does, what its result means and what it cannot prove.

Hash and verbosity contract

Validate the 32-byte hexadecimal block hash and choose numeric verbosity explicitly. Client schemas must not assume the tx field has one type: verbosity one returns transaction IDs, while verbosity two returns objects. A caller that accepts either silently can misparse data or expose unexpectedly large responses.

Raw block mode

Verbosity zero returns consensus serialisation as hex. Bound response size, authenticate its transport and hash the decoded header to confirm the requested identity. A successful fetch does not guarantee the block belongs to the active chain. Raw parsing should use a version-pinned library and reject trailing, truncated or excessive data.

Confirmations and chain membership

Positive confirmations describe active-chain depth at query time, while minus one means the block is not on the active chain. Record best-block context with the response because a reorganisation can change the value. Never mark payments final from a cached block object without rechecking active ancestry.

Size, stripped size and weight

size includes witness data, strippedsize excludes it and weight applies the BIP 141 weighting rule. Mining and fee analysis must use the correct measure and explicit units. Compare decoded transaction weights with the block total and reject arithmetic that treats ordinary bytes as virtual bytes.

Chainwork and neighbours

chainwork is cumulative expected work encoded in hexadecimal. Previousblockhash and nextblockhash describe known active-chain adjacency where available, not an immutable global sequence. Verify ancestry and compare chainwork across nodes during an incident instead of selecting a branch by height or timestamp alone.

Pruning and availability

A pruned node may know a header but lack old block data, causing getblock retrieval to fail. Plan archive and pruned roles explicitly and distinguish absent local data from an invalid block. Do not trigger broad redownloads automatically because one historical RPC request lacks stored bytes.

How specialists test it

Operators test the command on a non-production node first. They check a normal reply, an invalid request, a timeout and a restart. This shows what the response means and prevents one local result from being mistaken for a network-wide outcome.

Conclusion

getblock is a layered inspection API whose shape and meaning depend on verbosity and current chain state. Reliable use validates identity, membership, weight and ancestry while handling pruning and reorganisations explicitly.