Structured Storage and Blueprints

Relevant source files

• .changes/changed/3134.md
• bin/fuel-core/src/cli/rollback.rs
• crates/fuel-core/src/combined_database.rs
• crates/fuel-core/src/database.rs
• crates/fuel-core/src/database/metadata.rs
• crates/fuel-core/src/service/genesis/importer/import_task.rs
• crates/fuel-core/src/state.rs
• crates/fuel-core/src/state/data_source.rs
• crates/fuel-core/src/state/generic_database.rs
• crates/fuel-core/src/state/historical_rocksdb.rs
• crates/fuel-core/src/state/in_memory/memory_store.rs
• crates/fuel-core/src/state/iterable_key_value_view.rs
• crates/fuel-core/src/state/rocks_db.rs
• crates/storage/src/iter.rs
• crates/storage/src/kv_store.rs
• crates/storage/src/structured_storage.rs
• crates/storage/src/transactional.rs

Purpose and Scope

This document explains the StructuredStorage system in fuel-core, which provides type-safe, codec-aware access to key-value storage. The system uses blueprints to define how table data is encoded, decoded, and accessed, enabling strongly-typed operations over raw byte storage while maintaining flexibility in encoding strategies.

For information about the underlying transactional layer that accumulates changes, see Transactional Storage. For the raw key-value storage implementations (RocksDB, in-memory), see RocksDB Implementation and Database Architecture Overview.

---

Architecture Overview

The structured storage system forms a layered architecture that transforms raw key-value operations into type-safe table access:

Sources: crates/storage/src/structured_storage.rs1-434 crates/storage/src/kv_store.rs1-190 crates/fuel-core/src/state/rocks_db.rs1-100

---

Core Components

StructuredStorage Wrapper

The StructuredStorage<S> type wraps any key-value storage and provides blueprint-based access:

The wrapper delegates raw operations to the inner storage while providing typed operations through blueprints. It implements AsRef<S>, AsMut<S>, Deref, and DerefMut for transparent access to the underlying storage.

Sources: crates/storage/src/structured_storage.rs94-138 crates/storage/src/structured_storage.rs140-267

TableWithBlueprint Trait

Tables declare their blueprint and column through the TableWithBlueprint trait:

Component	Type	Purpose
Blueprint	Associated type	Defines encoding/decoding strategy
Column	Associated type	Column identifier for storage
column()	Static method	Returns the column this table occupies

The trait inherits from Mappable, which defines the key-value types:

Mappable Field	Purpose
Key	The borrowed key type
OwnedKey	The owned key type
Value	The borrowed value type
OwnedValue	The owned value type

Sources: crates/storage/src/structured_storage.rs81-92 crates/fuel-core/src/database/metadata.rs25-47

Blueprint Types and Traits

Blueprints implement encoding/decoding logic through three core traits:

BlueprintCodec<M> defines the encoding strategy:

• KeyCodec: Encoder for keys (e.g., Postcard, Raw)
• ValueCodec: Encoder for values (e.g., Postcard, Raw)

BlueprintInspect<M, S> implements read operations:

• get(storage, key, column): Retrieve typed value
• exists(storage, key, column): Check existence
• size_of_value(storage, key, column): Get value size

BlueprintMutate<M, S> implements write operations:

• put(storage, key, column, value): Insert value
• replace(storage, key, column, value): Replace and return old
• delete(storage, key, column): Remove value
• take(storage, key, column): Remove and return value

Sources: crates/storage/src/structured_storage.rs269-312 crates/storage/src/blueprint.rs1-100

Codec Types

Three primary codec types handle encoding and decoding:

Codec	Encoding Strategy	Use Case
Postcard	Postcard serialization (compact binary)	Structured data types (blocks, transactions)
Raw	Identity (no encoding)	Byte slices [u8]
Manual	Custom encoding logic	Special encoding requirements

The Encode trait defines the encoding interface:

The Encoder trait provides access to encoded bytes:

Sources: crates/storage/src/codec/postcard.rs1-50 crates/storage/src/codec/raw.rs1-50 crates/storage/src/codec/manual.rs1-50

---

Type-Safe Table Access Flow

The following diagram shows how a typed table operation flows through the system:

Key encoding steps:

1. Application requests typed value using table type parameter
2. StructuredStorage delegates to blueprint's get() implementation
3. Blueprint encodes key using KeyCodec::encode()
4. Raw bytes stored/retrieved from key-value store
5. Blueprint decodes value using ValueCodec::decode()
6. Typed value returned to application

Sources: crates/storage/src/structured_storage.rs269-284 crates/storage/src/blueprint/plain.rs1-100

---

Blueprint Implementation Example

The MetadataTable demonstrates a complete blueprint implementation:

The implementation in code:

Blueprint selection rationale:

• Plain: No special indexing or merkle tree needed
• Postcard for key: Unit type () encodes to empty bytes
• Postcard for value: DatabaseMetadata is a structured enum requiring serialization

Sources: crates/fuel-core/src/database/metadata.rs25-47

---

Storage Trait Implementations

StructuredStorage automatically implements high-level storage traits for any table with a blueprint:

StorageInspect Implementation

The implementation:

1. Extracts the blueprint type from M::Blueprint
2. Calls blueprint's get() or exists() methods
3. Passes column from M::column()
4. Wraps result in Cow::Owned for zero-copy when possible

Sources: crates/storage/src/structured_storage.rs269-312

StorageMutate Implementation

All operations delegate to the blueprint's corresponding methods, ensuring consistent encoding/decoding.

Sources: crates/storage/src/structured_storage.rs287-312

---

Integration with Database System

The database system builds on StructuredStorage to provide domain-specific access:

Database Type Hierarchy

Type	Description	Role
CombinedDatabase	Aggregates domain databases	Top-level database container
Database<Description>	Domain-specific database	On-chain, off-chain, relayer domains
GenericDatabase<Storage, Metadata>	Storage + metadata wrapper	Adds height tracking to storage
StructuredStorage<S>	Blueprint-based wrapper	Provides typed table access
DataSource<Description, Stage>	Storage abstraction	Wraps TransactableStorage trait object

Table Access Pattern

Application code accesses tables through the database:

The storage() method is provided by StorageAsRef trait, which gives access to the underlying StructuredStorage for any table type.

Sources: crates/fuel-core/src/database.rs171-193 crates/fuel-core/src/state/generic_database.rs30-58

---

Iterator Support

StructuredStorage provides typed iteration over tables:

The IterableTable<M> implementation:

Iteration flow:

1. Encode start key (if provided) using KeyCodec
2. Call raw iter_store() with encoded key
3. Decode each returned key using KeyCodec
4. Decode each value using ValueCodec
5. Return iterator of typed (Key, Value) pairs

Sources: crates/storage/src/iter.rs125-226

---

Batch Operations Support

For tables implementing SupportsBatching, structured storage provides efficient batch operations:

Implementation:

Batch operations encode all keys and values at once, then call BatchOperations::batch_write() on the underlying storage, enabling atomic multi-entry operations with a single storage write.

Sources: crates/storage/src/structured_storage.rs325-356 crates/storage/src/kv_store.rs183-189

---

Summary

The structured storage system provides:

1. Type Safety: Compile-time guarantees that correct types are used for each table
2. Codec Flexibility: Blueprint system allows different encoding strategies per table
3. Zero Runtime Overhead: Trait-based design compiles to direct method calls
4. Consistent API: All tables accessed through uniform StorageInspect/StorageMutate traits
5. Storage Abstraction: Works with any KeyValueInspect implementation (RocksDB, in-memory, etc.)
6. Batch Support: Efficient multi-entry operations for supporting blueprints
7. Iterator Support: Type-safe iteration with automatic key/value decoding

The system achieves separation of concerns:

• Application layer: Works with typed domain objects
• Blueprint layer: Handles encoding/decoding strategy
• Storage layer: Manages raw bytes and persistence

This architecture enables fuel-core to maintain a clean, type-safe database API while supporting multiple storage backends and encoding strategies.

Sources: crates/storage/src/structured_storage.rs1-434 crates/fuel-core/src/database.rs1-300