Transaction Indexing

Overview

The node provides advanced transaction indexing capabilities for efficient querying of blockchain data. Indexes are built on-demand and support both address-based and value-based queries.

Index Types

Transaction Hash Index

Basic transaction lookup by hash:

  • Key: Transaction hash (32 bytes)
  • Value: Transaction metadata (block hash, height, index, size, weight)
  • Lookup: O(1) hash-based lookup
  • Always Enabled: Core indexing functionality

Address Index (Optional)

Indexes transactions by output addresses:

  • Key: Address hash (20 bytes for P2PKH, 32 bytes for P2SH/P2WPKH)
  • Value: List of (transaction hash, output index) pairs
  • Lookup: Fast address balance and transaction history queries
  • Indexing: Built during block connect when enable_address_index = true (off by default)
  • Configuration: storage.indexing.enable_address_index = true

Value Range Index (Optional)

Indexes transactions by output value ranges:

  • Key: Value bucket (logarithmic buckets: 0-1, 1-10, 10-100, 100-1000, etc.)
  • Value: List of (transaction hash, output index, value) tuples
  • Lookup: Efficient queries for transactions in specific value ranges
  • Indexing: Built during block connect when enable_value_index = true (off by default)
  • Configuration: storage.indexing.enable_value_index = true

Indexing Strategy

strategyBehavior
eager (default)Address and value indexes updated during block connect when enable_* is true
lazyAdvanced indexes deferred until first query (get_transactions_by_address / value-range query scans and persists), or built in a background thread when background_indexing = true

max_indexed_addresses: cap distinct address keys in the address index (0 = unlimited). enable_compression: zstd-compress auxiliary index blobs when enabled in config (requires compression in the binary: part of blvm default features; omitted from portable Windows/aarch64 release builds). background_indexing: with lazy, enqueue per-block advanced indexing on a txindex-bg thread instead of blocking connect or waiting for a query.

Configuration

Enable Indexing

[storage.indexing]
enable_address_index = true
enable_value_index = true

Index Statistics

Query indexing statistics:

#![allow(unused)]
fn main() {
use blvm_node::storage::txindex::TxIndex;

let stats = txindex.get_stats()?;
println!("Total transactions: {}", stats.total_transactions);
println!("Indexed addresses: {}", stats.indexed_addresses);
println!("Indexed value buckets: {}", stats.indexed_value_buckets);
}

Usage

Query by Address

#![allow(unused)]
fn main() {
use blvm_node::storage::txindex::TxIndex;

// Query all transactions for an address
let address = "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa";
let transactions = txindex.query_by_address(&address)?;
}

Query by Value Range

#![allow(unused)]
fn main() {
// Query transactions with outputs in value range [1000, 10000] satoshis
let transactions = txindex.query_by_value_range(1000, 10000)?;
}

Query Transaction Metadata

#![allow(unused)]
fn main() {
// Get transaction metadata by hash
let tx_hash = Hash::from_hex("...")?;
let metadata = txindex.get_metadata(&tx_hash)?;
}

Performance Characteristics

  • Hash Lookup: O(1) constant time
  • Address Lookup: O(1) after initial indexing, O(n) for first query (indexes on-demand)
  • Value Range Lookup: O(log n) for bucket lookup, O(m) for results (where m is number of matches)
  • Index Building: Lazy, only builds what's queried
  • Storage Overhead: Minimal for basic index, grows with address/value index usage

Source

See Also