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;
• pub use constants::latest_version_for_adding_subtrees;

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.
• 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.
• 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.