blockinspector

README

Block Inspector

A command-line tool for parsing and inspecting Hyperledger Fabric block files generated by either a peer or an orderer, providing detailed summary information about blocks, transactions, and read-write sets.

Overview

Block Inspector analyzes Hyperledger Fabric ledger data and provides insights into:

• Block metadata (block number, hash, transaction count, size)
• Transaction details (validation status, chaincode ID, events)
• Read-write sets for transactions
• Transaction and event sizes

This tool is designed to calculate metrics on transaction sizes and RW sets, making it useful for performance analysis and debugging Hyperledger Fabric networks.

Installation

From Source

git clone https://github.com/luthersystems/blockinspector.git
cd blockinspector
make install

Or build locally:

make build

The binary will be created at ./build/blockinspector.

Requirements

• Go 1.25 or later
• Access to Hyperledger Fabric ledger data directory

Usage

Block Inspector provides two main commands for inspecting block data:

Inspect Peer Ledger

blockinspector range-peer <LEDGERDIR> <CHANNEL> <START> <END>

Example:

blockinspector range-peer ./ledgersData/chains mychannel 0 10

Inspect Orderer Ledger

blockinspector range-orderer <LEDGERDIR> <CHANNEL> <START> <END>

Example:

blockinspector range-orderer ./orderer/chains mychannel 0 10

Inspect Luther Snapshot Ledger

blockinspector snapshot <SNAPSHOTFILE>

Example:

blockinspector snapshot ./test_snapshot.bak

This command loads and inspects a Luther snapshot ledger file (Badger DB backup format). Snapshots are created when running Go tests with the Luther platform and plugin, allowing developers to quickly resume from a ledger state without running a full Fabric network.

The snapshot inspector shows:

• Summary statistics (total keys, sizes)
• Namespace and collection breakdowns
• All state keys grouped by namespace
• All private data keys grouped by collection

List Private Data Keys

blockinspector pvtdata-keys <LEDGERPATH> <CHANNEL> [--collection NAME] [--sort-by-version] [--limit N] [--output-csv]

Example — find the earliest private data key across all collections:

blockinspector pvtdata-keys /var/hyperledger/production mychannel --sort-by-version --limit 1

Example — list all keys in a specific collection:

blockinspector pvtdata-keys /var/hyperledger/production mychannel --collection private --sort-by-version

This command reads the peer's LevelDB state database offline and lists private data collection keys with their version (block number, transaction number). This is useful for discovering the oldest private data key after a snapshot restore, to verify that gossip-based private data reconciliation has completed.

Important: The peer process must be stopped before running this command, as LevelDB holds a file lock.

Parameters

• LEDGERDIR: Directory containing ledger data (for peers: ledgersData/chains, for orderers: orderer/chains)
• CHANNEL: Name of the channel to inspect
• START: Start block number (inclusive)
• END: End block number (exclusive). Use 0 to iterate through all blocks
• SNAPSHOTFILE: Path to a Luther snapshot file (Badger DB backup format)
• LEDGERPATH: Path to the peer's ledger data directory (e.g., /var/hyperledger/production)

Output Formats

Table Format (default)

The default output displays blocks and transactions in a formatted table showing:

• Block summary with block number, hash, transaction count, and size
• Transaction details with validation status, chaincode ID, and event information
• Read-write sets with keys and versions

Example Output:

┌───────────┬───────────┬─────────┬─────────────────┐
│ BLOCK NUM │   HASH    │ NUM TXS │ SIZE  ( BYTES ) │
├───────────┼───────────┼─────────┼─────────────────┤
│ 1         │ f38eb8... │ 1       │ 4834            │
└───────────┴───────────┴─────────┴─────────────────┘
                    Block Summary                    

┌───────────┬────────────┬──────────────┬──────────────┬───────────────────────┬─────────────────┐
│    ID     │ VALIDATION │ CHAINCODE ID │ LUTHER EVENT │ EVENT SIZE  ( BYTES ) │ SIZE  ( BYTES ) │
├───────────┼────────────┼──────────────┼──────────────┼───────────────────────┼─────────────────┤
│ 8d4dbd... │ VALID      │              │ <none>       │ 0                     │ 3755            │
└───────────┴────────────┴──────────────┴──────────────┴───────────────────────┴─────────────────┘
                                     Transactions (block=[1])                                     

┌─────────┬─────────┐
│   KEY   │ VERSION │
├─────────┼─────────┤
│ marbles │ (0:0)   │
└─────────┴─────────┘
Read Set (namespace=[lscc], txid=[8d4dbd2d73f6d78a0716ae72baabe97521642931ae3483b2e78e477b0298a642])

┌─────┬───────────────┐
│ KEY │ VAL  ( SIZE ) │
└─────┴───────────────┘
    Write Set [lscc]   


┌───────────┬───────────┬─────────┬─────────────────┐
│ BLOCK NUM │   HASH    │ NUM TXS │ SIZE  ( BYTES ) │
├───────────┼───────────┼─────────┼─────────────────┤
│ 4         │ 28bb5b... │ 1       │ 4783            │
└───────────┴───────────┴─────────┴─────────────────┘
                    Block Summary                    

┌───────────┬────────────┬──────────────┬──────────────┬───────────────────────┬─────────────────┐
│    ID     │ VALIDATION │ CHAINCODE ID │ LUTHER EVENT │ EVENT SIZE  ( BYTES ) │ SIZE  ( BYTES ) │
├───────────┼────────────┼──────────────┼──────────────┼───────────────────────┼─────────────────┤
│ 5a3b2c... │ VALID      │ marbles      │ <none>       │ 0                     │ 3183            │
└───────────┴────────────┴──────────────┴──────────────┴───────────────────────┴─────────────────┘
                                     Transactions (block=[4])                                     

┌───────────────┬─────────┐
│      KEY      │ VERSION │
├───────────────┼─────────┤
│ marble1       │ (3:0)   │
│ color~name    │ (3:0)   │
└───────────────┴─────────┘
Read Set (namespace=[marbles], txid=[5a3b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2])

┌───────────────────────┬───────────────┐
│         KEY           │ VAL  ( SIZE ) │
├───────────────────────┼───────────────┤
│ color~name~blue~marble│ 1             │
│ marble1               │ 76            │
└───────────────────────┴───────────────┘
           Write Set [marbles]           

This example demonstrates:

• Block Summary: Shows block metadata (number, hash, transaction count, total size)
• Transaction Details: Displays transaction ID, validation status, chaincode ID, events, and sizes
• Read Set: Lists all keys read by the transaction with their versions (format: (block:tx))
• Write Set: Shows all keys written by the transaction with their value sizes in bytes

CSV Format

To output in CSV format for further analysis:

blockinspector range-peer <LEDGERDIR> <CHANNEL> <START> <END> --output-csv

Development

Building

make build

Running Tests

make test

Code Quality

This project uses golangci-lint for code quality checks. The linter runs automatically on pull requests via GitHub Actions.

License

Copyright © 2021 Luther Systems, Ltd. All rights reserved.