papyrus-storage

Description

papyrus-storage provides a writing and reading interface for various Starknet data structures to a database, designed specifically for Papyrus, a Starknet node.

lib.rs:

A storage implementation for a Starknet node.

This crate provides a writing and reading interface for various Starknet data structures to a database. Enables at most one writing operation and multiple reading operations concurrently. The underlying storage is implemented using the libmdbx crate.

Disclaimer

This crate is still under development and is not keeping backwards compatibility with previous versions. Breaking changes are expected to happen in the near future.

Quick Start

To use this crate, open a storage by calling open_storage to get a StorageWriter and a StorageReader and use them to create StorageTxn instances. The actual functionality is implemented on the transaction in multiple traits.

use papyrus_storage::open_storage;
use papyrus_storage::header::{HeaderStorageReader, HeaderStorageWriter};    // Import the header API.
use starknet_api::block::{BlockHeader, BlockNumber, StarknetVersion};
use starknet_api::core::ChainId;

let db_config = DbConfig {
    path_prefix: dir,
    chain_id: ChainId::Mainnet,
    enforce_file_exists: false,
    min_size: 1 << 20,    // 1MB
    max_size: 1 << 35,    // 32GB
    growth_step: 1 << 26, // 64MB
};
let (reader, mut writer) = open_storage(storage_config)?;
writer
    .begin_rw_txn()?                                            // Start a RW transaction.
    .append_header(BlockNumber(0), &BlockHeader::default())?    // Append a header.
    .commit()?;                                                 // Commit the changes.

let header = reader.begin_ro_txn()?.get_block_header(BlockNumber(0))?;  // Read the header.
assert_eq!(header, Some(BlockHeader::default()));

Storage Version

Attempting to open an existing database using a crate version with a mismatching storage version will result in an error.

The storage version is composed of two components: STORAGE_VERSION_STATE for the state and STORAGE_VERSION_BLOCKS for blocks. Each version consists of a major and a minor version. A higher major version indicates that a re-sync is necessary, while a higher minor version indicates a change that is migratable.

When a storage is opened with StorageScope::StateOnly, only the state version must match. For storage opened with StorageScope::FullArchive, both versions must match the crate's versions.

Incompatibility occurs when the code and the database have differing major versions. However, if the code has the same major version but a higher minor version compared to the database, it will still function properly.

Example cases:

• Code: {major: 0, minor: 0}, Database: {major: 1, minor: 0} will fail due to major version inequality.
• Code: {major: 0, minor: 0}, Database: {major: 0, minor: 1} will fail due to the smaller code's minor version.
• Code: {major: 0, minor: 1}, Database: {major: 0, minor: 0} will succeed since the major versions match and the code's minor version is higher.