Firewood Database

Firewood is a purpose-built embedded key-value store optimized for storing recent Merkleized blockchain state. Unlike traditional blockchain storage approaches that layer Merkle tries on top of generic databases, Firewood stores trie nodes directly on disk, eliminating compaction overhead and enabling superior performance.

Summary

Firewood reimagines blockchain state storage with several key innovations:

• Native trie storage: Stores Merkle trie nodes directly on disk
• No compaction: Eliminates expensive compaction cycles
• Recent state focus: Optimized for storing recent revisions
• Disk-offset addressing: Root addresses are disk offsets, not hashes

The Problem with Traditional Approaches

Most blockchain clients (including Ethereum's Geth and traditional AvalancheGo) store state using generic key-value databases like LevelDB or RocksDB. This creates a fundamental mismatch:

Problems with Generic KV Stores

How Firewood Works

Firewood implements a Patricia trie (a specific variant of radix tree) natively on disk, using the trie structure itself as the index.

Native Trie Storage

Key design decisions:

• Disk offset = address: A node's address is simply its offset in the database file
• Direct pointers: Branch nodes point to disk offsets of child nodes
• No hash lookup: Finding a node doesn't require computing or looking up hashes

Revision Management

Firewood implements a persistent (immutable) trie structure that supports multiple concurrent versions:

When state is updated:

1. New versions of modified nodes are created
2. Unchanged subtrees are shared between revisions
3. Old revisions remain accessible for reads

Future-Delete Log (FDL)

Firewood tracks which nodes become obsolete:

This enables:

• Predictable cleanup: No sudden compaction pauses
• Inline compaction: Space is reclaimed as part of normal operation
• Configurable history: Retain as many revisions as needed

Technical Architecture

Core Components

firewood/
├── storage/        # Low-level storage primitives
├── trie/           # Patricia trie implementation
├── proposal/       # Transaction staging
├── revision/       # Version management
├── proof/          # Merkle proof generation
└── ffi/            # Foreign function interface

Free Space Management

Firewood manages free space similarly to heap memory allocation:

When allocating space for new nodes:

1. Check free lists for appropriate size
2. If no suitable free space, allocate from end of file
3. When revisions expire, return space to free lists

Key Features

Concurrent Access

Firewood efficiently synchronizes between:

The persistent trie structure ensures:

• Readers always see consistent state
• Writes are atomic from readers' perspective
• No locks required for read operations

Sequential Writes

The persistent data structure enables sequential writes. New nodes are appended to the end of the file, filling free space sequentially:

Benefits for SSDs:

• Entire blocks are filled before moving to the next
• Simplified garbage collection
• Reduced write amplification
• Increased SSD longevity

Proofs and State Sync

Firewood natively supports proof generation:

These proofs enable efficient state sync without trusting the source.

Ethereum Compatibility

By default, Firewood uses SHA256 hashing (compatible with MerkleDB). For Ethereum compatibility, enable the ethhash feature:

# Build with Ethereum-compatible hashing
cargo build --features ethhash

This changes:

• Hashing algorithm: SHA256 → Keccak256
• Account handling: Understands RLP-encoded accounts
• Storage trie: Computes account storage roots correctly

Performance Characteristics

Compared to LevelDB/RocksDB

Optimal Configuration

For best performance:

# Run directly on block device (bypass filesystem)
./firewood --device /dev/nvme0n1

# Or use regular files (easier setup)
./firewood --path /data/firewood.db

Running on block devices avoids filesystem overhead:

• No block allocation delays
• No fragmentation
• No metadata management
• Direct I/O to SSD

Metrics

Firewood provides comprehensive Prometheus metrics:

# Database size
firewood_db_size_bytes

# Read/write latency
firewood_read_latency_seconds
firewood_write_latency_seconds

# Revision count
firewood_revision_count

# Free space
firewood_free_space_bytes

See METRICS.md for the complete metrics reference.

Command Line Interface

Firewood includes fwdctl for database operations:

# Create a new database
fwdctl create --path /data/firewood.db

# Insert key-value pairs
fwdctl put --path /data/firewood.db key1 value1

# Query data
fwdctl get --path /data/firewood.db key1

# Generate proofs
fwdctl prove --path /data/firewood.db key1

Integration with AvalancheGo

Firewood integrates with AvalancheGo as an alternative to LevelDB/PebbleDB:

Related Resources

External Links

• Firewood Repository
• Firewood Go Bindings
• Firewood Metrics Reference