Struct ColdStorageHandle 

pub struct ColdStorageHandle { /* private fields */ }

Handle for interacting with the cold storage task.

This handle provides full access to both read and write operations. It can be cloned and shared across tasks.

Channel Separation

Internally, this handle uses separate channels for reads and writes:

• Read channel: Shared with ColdStorageReadHandle. Reads are processed concurrently (up to 64 in flight).
• Write channel: Exclusive to this handle. Writes are processed sequentially to maintain ordering.

This design allows read-heavy workloads to proceed without being blocked by write operations, while ensuring write ordering is preserved.

Read Access

All read methods from ColdStorageReadHandle are available on this handle via Deref.

Usage

let handle = ColdStorageTask::spawn(backend, cancel);

// Full access: reads and writes
handle.append_block(data).await?;
let header = handle.get_header_by_number(100).await?;

// Get a read-only handle for query-only use cases
let reader = handle.reader();

Thread Safety

This handle is Clone + Send + Sync and can be shared across tasks.

Implementations

impl ColdStorageHandle

pub fn reader(&self) -> ColdStorageReadHandle

Get a read-only handle that shares the read channel.

The returned handle can only perform read operations and cannot modify storage. Multiple read handles can coexist and query concurrently without affecting write throughput.

pub async fn append_block(&self, data: BlockData) -> ColdResult<()>

Append a single block to cold storage.

pub async fn append_blocks(&self, data: Vec<BlockData>) -> ColdResult<()>

Append multiple blocks to cold storage.

pub async fn truncate_above(&self, block: BlockNumber) -> ColdResult<()>

Truncate all data above the given block number.

This removes block N+1 and higher from all tables.

pub fn dispatch_append_blocks(&self, data: Vec<BlockData>) -> ColdResult<()>

Dispatch append blocks without waiting for response (non-blocking).

Unlike append_blocks, this method returns immediately without waiting for the write to complete. The write result is discarded.

Errors

• ColdStorageError::Backpressure: Channel is full. The task is alive but cannot keep up. Transient; may retry or accept the gap.
• ColdStorageError::TaskTerminated: Channel is closed. The task has stopped and must be restarted.

In both cases, hot storage already contains the data and remains authoritative.

pub fn dispatch_truncate_above(&self, block: BlockNumber) -> ColdResult<()>

Dispatch truncate without waiting for response (non-blocking).

Unlike truncate_above, this method returns immediately without waiting for the truncate to complete. The result is discarded.

Errors

Same as dispatch_append_blocks. If cold storage falls behind during a reorg, it may temporarily contain stale data until the truncate is processed or replayed.

Methods from Deref<Target = ColdStorageReadHandle>

pub async fn get_header( &self, spec: HeaderSpecifier, ) -> ColdResult<Option<SealedHeader>>

Get a header by specifier.

pub async fn get_header_by_number( &self, block: BlockNumber, ) -> ColdResult<Option<SealedHeader>>

Get a header by block number.

pub async fn get_header_by_hash( &self, hash: B256, ) -> ColdResult<Option<SealedHeader>>

Get a header by block hash.

pub async fn get_headers( &self, specs: Vec<HeaderSpecifier>, ) -> ColdResult<Vec<Option<SealedHeader>>>

Get multiple headers by specifiers.

pub async fn get_transaction( &self, spec: TransactionSpecifier, ) -> ColdResult<Option<Confirmed<RecoveredTx>>>

Get a transaction by specifier, with block confirmation metadata.

pub async fn get_tx_by_hash( &self, hash: B256, ) -> ColdResult<Option<Confirmed<RecoveredTx>>>

Get a transaction by hash.

pub async fn get_tx_by_block_and_index( &self, block: BlockNumber, index: u64, ) -> ColdResult<Option<Confirmed<RecoveredTx>>>

Get a transaction by block number and index.

pub async fn get_tx_by_block_hash_and_index( &self, block_hash: B256, index: u64, ) -> ColdResult<Option<Confirmed<RecoveredTx>>>

Get a transaction by block hash and index.

pub async fn get_transactions_in_block( &self, block: BlockNumber, ) -> ColdResult<Vec<RecoveredTx>>

Get all transactions in a block.

pub async fn get_transaction_count(&self, block: BlockNumber) -> ColdResult<u64>

Get the transaction count for a block.

pub async fn get_receipt( &self, spec: ReceiptSpecifier, ) -> ColdResult<Option<ColdReceipt>>

Get a receipt by specifier.

pub async fn get_receipt_by_tx_hash( &self, hash: B256, ) -> ColdResult<Option<ColdReceipt>>

Get a receipt by transaction hash.

pub async fn get_receipt_by_block_and_index( &self, block: BlockNumber, index: u64, ) -> ColdResult<Option<ColdReceipt>>

Get a receipt by block number and index.

pub async fn get_receipts_in_block( &self, block: BlockNumber, ) -> ColdResult<Vec<ColdReceipt>>

Get all receipts in a block.

pub async fn get_signet_events( &self, spec: SignetEventsSpecifier, ) -> ColdResult<Vec<DbSignetEvent>>

Get signet events by specifier.

pub async fn get_signet_events_in_block( &self, block: BlockNumber, ) -> ColdResult<Vec<DbSignetEvent>>

Get signet events in a block.

pub async fn get_signet_events_in_range( &self, start: BlockNumber, end: BlockNumber, ) -> ColdResult<Vec<DbSignetEvent>>

Get signet events in a range of blocks.

pub async fn get_zenith_header( &self, block: BlockNumber, ) -> ColdResult<Option<DbZenithHeader>>

Get a zenith header by block number.

pub async fn get_zenith_headers( &self, spec: ZenithHeaderSpecifier, ) -> ColdResult<Vec<DbZenithHeader>>

Get zenith headers by specifier.

pub async fn get_zenith_headers_in_range( &self, start: BlockNumber, end: BlockNumber, ) -> ColdResult<Vec<DbZenithHeader>>

Get zenith headers in a range of blocks.

pub async fn get_logs( &self, filter: Filter, max_logs: usize, ) -> ColdResult<Vec<RpcLog>>

Filter logs by block range, address, and topics.

Follows eth_getLogs semantics. Returns matching logs ordered by (block_number, tx_index, log_index).

Errors

Returns ColdStorageError::TooManyLogs if the query would produce more than max_logs results.

pub async fn stream_logs( &self, filter: Filter, max_logs: usize, deadline: Duration, ) -> ColdResult<LogStream>

Stream logs matching a filter.

Returns a LogStream that yields matching logs in order. Consume with StreamExt::next() until None. If the last item is Err(...), an error occurred (deadline, too many logs, etc.).

The deadline is clamped to the task’s configured maximum.

Partial Delivery

One or more Ok(log) items may be delivered before a terminal Err(...). Consumers must be prepared for partial results — for example, a reorg or deadline expiry can interrupt a stream that has already yielded some logs.

Resource Management

The stream holds a backend concurrency permit. Dropping the stream releases the permit. Drop early if results are no longer needed.

pub async fn get_latest_block(&self) -> ColdResult<Option<BlockNumber>>

Get the latest block number in storage.

Trait Implementations

impl Clone for ColdStorageHandle

fn clone(&self) -> ColdStorageHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ColdStorageHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for ColdStorageHandle

type Target = ColdStorageReadHandle

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.