Crate zebra_state

State contextual verification and storage code for Zebra.

Correctness

Await UTXO and block commit requests should be wrapped in a timeout, because:

• await UTXO requests wait for a block containing that UTXO, and
• contextual verification and state updates wait for all previous blocks.

Otherwise, verification of out-of-order and invalid blocks can hang indefinitely.

Re-exports

pub use config::check_and_delete_old_databases;

pub use config::check_and_delete_old_state_databases;

pub use config::database_format_version_on_disk;

pub use config::state_database_format_version_on_disk;

pub use config::Config;

pub use constants::state_database_format_version_in_code;

pub use constants::MAX_BLOCK_REORG_HEIGHT;

Modules

arbitrary

Randomised data generation for state data.

check

Consensus critical contextual checks

config

Cached state configuration for Zebra.

constants

Constants that impact state behaviour.

error 🔒

Error types for Zebra’s state.

request 🔒

State [tower::Service] request types.

response 🔒

State [tower::Service] response types.

service 🔒

[tower::Service]s for Zebra’s cached chain state.

Structs

ChainTipBlock

A chain tip block, with precalculated block data.

ChainTipChange

A chain tip change monitor.

ChainTipSender

A sender for changes to the non-finalized and finalized chain tips.

CheckpointVerifiedBlock

A block ready to be committed directly to the finalized state with a small number of checks if compared with a ContextuallyVerifiedBlock.

CloneError

A wrapper for type erased errors that is itself clonable and implements the Error trait

CommitSemanticallyVerifiedError

An error describing the reason a semantically verified block could not be committed to the state.

ContextuallyVerifiedBlock

A contextually verified block, ready to be committed directly to the finalized state with no checks, if it becomes the root of the best non-finalized chain.

DiskWriteBatch

Wrapper struct to ensure low-level database writes go through the correct API.

FinalizedState

The finalized part of the chain state, stored in the db.

GetBlockTemplateChainInfo

A structure with the information needed from the state to build a getblocktemplate RPC response.

KV

A formatting struct for raw key-value data

LatestChainTip

Efficient access to the state’s current best chain tip.

MinedTx

Information about a transaction in the best chain

NonFinalizedState

The state of the chains in memory, including queued blocks.

OutputIndex

A transparent output’s index in its transaction.

OutputLocation

A transparent output’s location in the chain, by block height and transaction index.

RawBytes

Access database keys or values as raw bytes. Mainly for use in tests, runtime checks, or format compatibility code.

ReadStateService

A read-only service for accessing Zebra’s cached blockchain state.

SaplingScannedDatabaseEntry

A database column family entry for a block scanned with a Sapling vieweing key.

SaplingScannedDatabaseIndex

A database column family key for a block scanned with a Sapling vieweing key.

SaplingScannedResult

Stores a scanning result.

SemanticallyVerifiedBlock

A block which has undergone semantic validation and has been prepared for contextual validation.

TransactionIndex

A transaction’s index in its block.

TransactionLocation

A transaction’s location in the chain, by block height and transaction index.

TypedColumnFamily

A type-safe read-only column family reference.

WatchReceiver

Efficient access to state data via a [tokio] [watch::Receiver] channel, while avoiding deadlocks.

WriteTypedBatch

A type-safe and drop-safe batch write to a column family.

ZebraDb

Wrapper struct to ensure high-level zebra-state database access goes through the correct API.

Enums

HashOrHeight

Identify a block by hash or height.

KnownBlock

An enum of block stores in the state where a block hash could be found.

ReadRequest

A read-only query about the chain state, via the ReadStateService.

ReadResponse

A response to a read-only ReadStateService’s ReadRequest.

Request

A query about or modification to the chain state, via the StateService.

Response

A response to a StateService Request.

Spend

Identify a spend by a transparent outpoint or revealed nullifier.

TipAction

Actions that we can take in response to a ChainTipChange.

ValidateContextError

An error describing why a block failed contextual validation.

Constants

CHAIN_TIP_UPDATE_WAIT_LIMIT

How long we wait for chain tip updates before skipping them.

MAX_ON_DISK_HEIGHT

The maximum value of an on-disk serialized Height.

Traits

DuplicateNullifierError

Trait for creating the corresponding duplicate nullifier error from a nullifier.

FromDisk

Helper type for reading types from disk as raw bytes.

IntoDisk

Helper type for writing types to disk as raw bytes. Also used to convert key types to raw bytes for disk lookups.

ReadDisk

Helper trait for retrieving and deserializing values from rocksdb column families.

WriteDisk

Helper trait for inserting serialized typed (Key, Value) pairs into rocksdb.

Functions

init

Initialize a state service from the provided Config. Returns a boxed state service, a read-only state service, and receivers for state chain tip updates.

init_read_only

Initialize a read state service from the provided Config. Returns a read-only state service,

init_test

Returns a StateService with an ephemeral Config and a buffer with a single slot.

init_test_services

Initializes a state service with an ephemeral Config and a buffer with a single slot, then returns the read-write service, read-only service, and tip watch channels.

populated_state

Initialize a state service with blocks, and return:

spawn_init

Calls init with the provided Config and Network from a blocking task. Returns a [tokio::task::JoinHandle] with a boxed state service, a read state service, and receivers for state chain tip updates.

spawn_init_read_only

Calls init_read_only with the provided Config and Network from a blocking task. Returns a [tokio::task::JoinHandle] with a read state service and chain tip sender.

write_database_format_version_to_disk

Writes changed_version to the on-disk database after the format is changed. (Or a new database is created.)

write_state_database_format_version_to_disk

Writes changed_version to the on-disk state database after the format is changed. (Or a new database is created.)

Type Aliases

BoxError

A boxed std::error::Error.

SaplingScanningKey

The type used in Zebra to store Sapling scanning keys. It can represent a full viewing key or an individual viewing key.