Trait ColdStorage 

pub trait ColdStorage:
    Send
    + Sync
    + 'static {
    // Required methods
    fn get_header(
        &self,
        spec: HeaderSpecifier,
    ) -> impl Future<Output = ColdResult<Option<SealedHeader>>> + Send;
    fn get_headers(
        &self,
        specs: Vec<HeaderSpecifier>,
    ) -> impl Future<Output = ColdResult<Vec<Option<SealedHeader>>>> + Send;
    fn get_transaction(
        &self,
        spec: TransactionSpecifier,
    ) -> impl Future<Output = ColdResult<Option<Confirmed<RecoveredTx>>>> + Send;
    fn get_transactions_in_block(
        &self,
        block: BlockNumber,
    ) -> impl Future<Output = ColdResult<Vec<RecoveredTx>>> + Send;
    fn get_transaction_count(
        &self,
        block: BlockNumber,
    ) -> impl Future<Output = ColdResult<u64>> + Send;
    fn get_receipt(
        &self,
        spec: ReceiptSpecifier,
    ) -> impl Future<Output = ColdResult<Option<ColdReceipt>>> + Send;
    fn get_receipts_in_block(
        &self,
        block: BlockNumber,
    ) -> impl Future<Output = ColdResult<Vec<ColdReceipt>>> + Send;
    fn get_signet_events(
        &self,
        spec: SignetEventsSpecifier,
    ) -> impl Future<Output = ColdResult<Vec<DbSignetEvent>>> + Send;
    fn get_zenith_header(
        &self,
        spec: ZenithHeaderSpecifier,
    ) -> impl Future<Output = ColdResult<Option<DbZenithHeader>>> + Send;
    fn get_zenith_headers(
        &self,
        spec: ZenithHeaderSpecifier,
    ) -> impl Future<Output = ColdResult<Vec<DbZenithHeader>>> + Send;
    fn get_latest_block(
        &self,
    ) -> impl Future<Output = ColdResult<Option<BlockNumber>>> + Send;
    fn get_logs(
        &self,
        filter: &Filter,
        max_logs: usize,
    ) -> impl Future<Output = ColdResult<Vec<RpcLog>>> + Send;
    fn produce_log_stream(
        &self,
        filter: &Filter,
        params: StreamParams,
    ) -> impl Future<Output = ()> + Send;
    fn append_block(
        &self,
        data: BlockData,
    ) -> impl Future<Output = ColdResult<()>> + Send;
    fn append_blocks(
        &self,
        data: Vec<BlockData>,
    ) -> impl Future<Output = ColdResult<()>> + Send;
    fn truncate_above(
        &self,
        block: BlockNumber,
    ) -> impl Future<Output = ColdResult<()>> + Send;
}

Unified cold storage backend trait.

Backend is responsible for all data organization, indexing, and keying. The trait is agnostic to how the backend stores or indexes data.

All methods are async and return futures that are Send.

Implementation Guide

Implementers must ensure:

• Append-only ordering: append_block must enforce monotonically increasing block numbers. Attempting to append a block with a number <= the current latest should return an error.

• Atomic truncation: truncate_above must remove all data for blocks N+1 and higher atomically. Partial truncation is not acceptable.

• Index maintenance: Hash-based lookups (e.g., header by hash, transaction by hash) require the implementation to maintain appropriate indexes. These indexes must be updated during append_block and cleaned during truncate_above.

• Consistent reads: Read operations should return consistent snapshots. A read started before a write completes should not see partial data from that write.

Required Methods

fn get_header( &self, spec: HeaderSpecifier, ) -> impl Future<Output = ColdResult<Option<SealedHeader>>> + Send

Get a header by specifier.

fn get_headers( &self, specs: Vec<HeaderSpecifier>, ) -> impl Future<Output = ColdResult<Vec<Option<SealedHeader>>>> + Send

Get multiple headers by specifiers.

fn get_transaction( &self, spec: TransactionSpecifier, ) -> impl Future<Output = ColdResult<Option<Confirmed<RecoveredTx>>>> + Send

Get a transaction by specifier, with block confirmation metadata.

fn get_transactions_in_block( &self, block: BlockNumber, ) -> impl Future<Output = ColdResult<Vec<RecoveredTx>>> + Send

Get all transactions in a block.

fn get_transaction_count( &self, block: BlockNumber, ) -> impl Future<Output = ColdResult<u64>> + Send

Get the number of transactions in a block.

fn get_receipt( &self, spec: ReceiptSpecifier, ) -> impl Future<Output = ColdResult<Option<ColdReceipt>>> + Send

Get a receipt by specifier.

fn get_receipts_in_block( &self, block: BlockNumber, ) -> impl Future<Output = ColdResult<Vec<ColdReceipt>>> + Send

Get all receipts in a block.

fn get_signet_events( &self, spec: SignetEventsSpecifier, ) -> impl Future<Output = ColdResult<Vec<DbSignetEvent>>> + Send

Get signet events by specifier.

fn get_zenith_header( &self, spec: ZenithHeaderSpecifier, ) -> impl Future<Output = ColdResult<Option<DbZenithHeader>>> + Send

Get a zenith header by specifier.

fn get_zenith_headers( &self, spec: ZenithHeaderSpecifier, ) -> impl Future<Output = ColdResult<Vec<DbZenithHeader>>> + Send

Get multiple zenith headers by specifier.

fn get_latest_block( &self, ) -> impl Future<Output = ColdResult<Option<BlockNumber>>> + Send

Get the latest block number in storage.

fn get_logs( &self, filter: &Filter, max_logs: usize, ) -> impl Future<Output = ColdResult<Vec<RpcLog>>> + Send

Filter logs by block range, address, and topics.

Follows eth_getLogs semantics: returns all logs matching the filter criteria, ordered by (block_number, tx_index, log_index).

Errors

Returns ColdStorageError::TooManyLogs if the query would produce more than max_logs results. No partial results are returned — the caller must narrow the filter or increase the limit.

fn produce_log_stream( &self, filter: &Filter, params: StreamParams, ) -> impl Future<Output = ()> + Send

Produce a log stream by iterating blocks and sending matching logs.

Implementations should hold a consistent read snapshot for the duration when possible — backends with snapshot semantics (MDBX, PostgreSQL with REPEATABLE READ) need no additional reorg detection.

Backends without snapshot semantics can delegate to produce_log_stream_default, which uses per-block get_header / get_logs calls with anchor-hash reorg detection.

All errors are sent through sender. When this method returns, the sender is dropped, closing the stream.

fn append_block( &self, data: BlockData, ) -> impl Future<Output = ColdResult<()>> + Send

Append a single block to cold storage.

fn append_blocks( &self, data: Vec<BlockData>, ) -> impl Future<Output = ColdResult<()>> + Send

Append multiple blocks to cold storage.

fn truncate_above( &self, block: BlockNumber, ) -> impl Future<Output = ColdResult<()>> + Send

Truncate all data above the given block number (exclusive).

This removes block N+1 and higher from all tables. Used for reorg handling.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl ColdStorage for MemColdBackend

Available on crate features in-memory only.