How to Read Blocks on VeChain

After deploying your smart contract, the next skill you’ll need is reading real on-chain data.

Understanding blocks allows your application to monitor transactions, events, and changes happening across the VeChain network.

What can you do with this?

Here’s what devs usually track from blocks:

  • Gas used vs gas limit

  • Who the signer/beneficiary is

  • When it was finalized

  • Which transactions ran, and what events were emitted

  • Which smart contracts were triggered

This data is vital for:

  • Building explorers

  • Monitoring app activity

  • Validating actions

  • Creating analytics dashboards

Whether you're tracking transactions, monitoring gas usage, or powering dashboards, this is how it starts.

What is a block?

On VeChain, a new block is produced every ~10 seconds even if there are zero transactions.

Each block represents a snapshot of state changes and contains:

  • number: The block number

  • id: A unique hash for the block

  • parentID: The block it builds on

  • timestamp: When the block was created

  • isFinalized: Whether the block is finalized

  • transactions: A list of transaction IDs or full transaction data

Querying a block

Using ThorClient from the VeChain SDK, you can retrieve two types of block data:

  • Compressed block: Basic metadata + list of transaction IDs (no full transaction details).

  • Expanded block: Full transaction information, execution outputs, events, and fees.

Example:

const blockNumber = 12345678;

// Get compressed block (only metadata and transaction IDs)
const compressed = await thor.blocks.getBlockCompressed(blockNumber);
console.log(compressed);

// Get expanded block (full transactions and receipts)
const expanded = await thor.blocks.getBlockExpanded(blockNumber);
console.log(expanded);

Use compressed when you just want an overview. Use expanded for analytics or app logic.

  • You can pass a block number

  • A block ID

  • Or use reserved words like:

"best" – the latest block

"finalized" – the last finalized block

Example for the latest block:

const latestBlock = await thor.blocks.getBlockCompressed('best');

⛓️ Special block types to know

  • "genesis" – the first block ever (block 0)

  • "best" – the most recent block (~10s old)

  • "final" – the latest block that cannot be reverted (checkpointed & finalized)

Finalized blocks are important for state proofs, off-chain indexing, and cross-chain integrations.

Tip: Use WebSockets for real-time event subscriptions (like VET transfers or smart contract events) and the Testnet is recommended to avoid expenses during development stages.

Use RPC methods to read one-off block and transaction data from the Testnet (https://testnet.vechain.org) or a local Solo node.