21. Storage Engine
The Kortana storage subsystem is engineered for high-throughput, low-latency, and crash-resilient persistence of blockchain state, block headers, execution receipts, and Merkle-Patricia Trie nodes.
21.1 RocksDB Backend
Production deployments of kortanad utilize a customized, enterprise-tuned RocksDB embedded key-value storage engine. To maximize NVMe I/O efficiency, minimize read amplification, and optimize background compaction cycles, storage data is physically partitioned into 14 Dedicated Column Families:
headers: Serialized canonical block headers indexed by block hash and height.bodies: RLP-encoded block bodies containing transaction lists.receipts: Transaction execution receipts, gas consumption records, and event logs.state_trie: Merkle-Patricia Trie nodes (leaves, extensions, branches) indexed by Keccak-256 hashes.code: Executable smart contract bytecodes (EVM and KVM modules) indexed bycode_hash.tx_lookup: Transaction hash to block location mapping forO(1)RPC lookups.validators: Validator state records, bonded balances, and registered BLS12-381 public keys.epochs: Epoch boundary metadata and historical validator weight snapshots.param_store: Current and historical governance parameter dictionaries.
21.2 Write-Ahead Log (WAL)
To guarantee ACID durability against unexpected power outages, hardware crashes, or operating system kernel panics, every database write batch is written synchronously to a Write-Ahead Log (WAL) before updating in-memory memtables.
When a block finishes execution, the node constructs an atomic rocksdb::WriteBatch encompassing all state trie mutations, receipts, and header updates. The write batch is committed to the WAL using fsync, ensuring that state modifications are permanently committed to non-volatile physical storage media. Only after the WAL sync succeeds are the changes made visible to concurrent read threads.
21.3 Checkpoints
The storage layer provides hot checkpointing capabilities through RocksDB's native checkpoint API. Node operators can trigger automated, point-in-time database snapshots in milliseconds without stopping the daemon or introducing consensus latency.
A checkpoint creates hard links to immutable SST data files while flushing active memtables, creating a consistent directory snapshot that can be backed up to external object storage or distributed to new nodes for Snapshot Sync.
21.4 Crash Recovery Protocol
The crash recovery subsystem ensures that a node can recover smoothly and deterministically from abrupt termination without manual database intervention.
[!IMPORTANT] Crash & Restart: On startup, the node validates database integrity, replays uncommitted WAL records, verifies the state root against the latest finalized block header, and seamlessly resumes synchronization.
During startup initialization, kortanad opens RocksDB, replays any uncommitted records from the WAL, and inspects the latest block header in the headers column family. It traverses the state trie starting from the header's declared state_root. If the calculated state root matches the header, the node opens network ports and resumes consensus participation; if a corruption or mismatch is detected, the daemon safely halts with a diagnostic report rather than corrupting the canonical state.
21.5 IStore Interface & MemoryStore
To decouple consensus and execution logic from the underlying physical storage technology, all database operations in kortana-node are abstracted behind the pure virtual C++ IStore interface.
In production binaries, the node instantiates RocksDbStore, which wraps the multi-column RocksDB engine with RAII-managed iterators and batch builders. In automated test environments, the test suite instantiates MemoryStore—a high-performance, thread-safe in-memory key-value engine backed by standard C++ hash maps. MemoryStore enables over 1,780 unit, property, and integration tests to execute across CI pipelines in seconds without generating disk I/O overhead.
Part VI — JSON-RPC API Reference
Kortana exposes a comprehensive JSON-RPC interface providing full compatibility with standard Ethereum eth_ calls while offering native ktn_ methods for consensus, staking, and governance.