Struct ZebraDb

pub struct ZebraDb { /* private fields */ }

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

rocksdb allows concurrent writes through a shared reference, so database instances are cloneable. When the final clone is dropped, the database is closed.

Implementations

impl ZebraDb

pub fn is_empty(&self) -> bool

Returns true if the database is empty.

pub fn tip(&self) -> Option<(Height, Hash)>

Returns the tip height and hash, if there is one.

pub fn contains_height(&self, height: Height) -> bool

Returns true if height is present in the finalized state.

pub fn hash(&self, height: Height) -> Option<Hash>

Returns the finalized hash for a given block::Height if it is present.

pub fn contains_hash(&self, hash: Hash) -> bool

Returns true if hash is present in the finalized state.

pub fn height(&self, hash: Hash) -> Option<Height>

Returns the height of the given block if it exists.

pub fn prev_block_hash_for_hash(&self, hash: Hash) -> Option<Hash>

Returns the previous block hash for the given block hash in the finalized state.

pub fn prev_block_height_for_hash(&self, hash: Hash) -> Option<Height>

Returns the previous block height for the given block hash in the finalized state.

pub fn block_header(&self, hash_or_height: HashOrHeight) -> Option<Arc<Header>>

Returns the block::Header with block::Hash or Height, if it exists in the finalized chain.

pub fn block(&self, hash_or_height: HashOrHeight) -> Option<Arc<Block>>

Returns the Block with block::Hash or Height, if it exists in the finalized chain.

pub fn block_and_size( &self, hash_or_height: HashOrHeight, ) -> Option<(Arc<Block>, usize)>

Returns the Block with block::Hash or Height, if it exists in the finalized chain, and its serialized size.

pub fn sapling_tree_by_hash_or_height( &self, hash_or_height: HashOrHeight, ) -> Option<Arc<NoteCommitmentTree>>

Returns the Sapling note commitment tree specified by a hash or height, if it exists in the finalized state.

pub fn orchard_tree_by_hash_or_height( &self, hash_or_height: HashOrHeight, ) -> Option<Arc<NoteCommitmentTree>>

Returns the Orchard note commitment tree specified by a hash or height, if it exists in the finalized state.

pub fn finalized_tip_hash(&self) -> Hash

Returns the hash of the current finalized tip block.

pub fn finalized_tip_height(&self) -> Option<Height>

Returns the height of the current finalized tip block.

pub fn tip_block(&self) -> Option<Arc<Block>>

Returns the tip block, if there is one.

pub fn transaction( &self, hash: Hash, ) -> Option<(Arc<Transaction>, Height, DateTime<Utc>)>

Returns the Transaction with transaction::Hash, and its Height, if a transaction with that hash exists in the finalized chain.

pub fn transactions_by_height( &self, height: Height, ) -> impl Iterator<Item = (TransactionLocation, Transaction)> + '_

Returns an iterator of all Transactions for a provided block height in finalized state.

pub fn transactions_by_location_range<R>( &self, range: R, ) -> impl Iterator<Item = (TransactionLocation, Transaction)> + '_

where R: RangeBounds<TransactionLocation>,

Returns an iterator of all Transactions in the provided range of TransactionLocations in finalized state.

pub fn transaction_location(&self, hash: Hash) -> Option<TransactionLocation>

Returns the TransactionLocation for transaction::Hash, if it exists in the finalized chain.

pub fn transaction_hash(&self, location: TransactionLocation) -> Option<Hash>

Returns the transaction::Hash for TransactionLocation, if it exists in the finalized chain.

pub fn transaction_hashes_for_block( &self, hash_or_height: HashOrHeight, ) -> Option<Arc<[Hash]>>

Returns the transaction::Hashes in the block with hash_or_height, if it exists in this chain.

Hashes are returned in block order.

Returns None if the block is not found.

pub fn write_batch(&self, batch: DiskWriteBatch) -> Result<(), Error>

Writes the given batch to the database.

impl ZebraDb

pub fn history_tree(&self) -> Arc<HistoryTree>

Returns the ZIP-221 history tree of the finalized tip.

If history trees have not been activated yet (pre-Heartwood), or the state is empty, returns an empty history tree.

pub fn finalized_value_pool(&self) -> ValueBalance<NonNegative>

Returns the stored ValueBalance for the best chain at the finalized tip height.

impl ZebraDb

pub fn contains_sprout_nullifier(&self, sprout_nullifier: &Nullifier) -> bool

Returns true if the finalized state contains sprout_nullifier.

pub fn contains_sapling_nullifier(&self, sapling_nullifier: &Nullifier) -> bool

Returns true if the finalized state contains sapling_nullifier.

pub fn contains_orchard_nullifier(&self, orchard_nullifier: &Nullifier) -> bool

Returns true if the finalized state contains orchard_nullifier.

pub fn sprout_revealing_tx_loc( &self, sprout_nullifier: &Nullifier, ) -> Option<TransactionLocation>

Returns the TransactionLocation of the transaction that revealed the given sprout::Nullifier, if it is revealed in the finalized state and its spending transaction hash has been indexed.

pub fn sapling_revealing_tx_loc( &self, sapling_nullifier: &Nullifier, ) -> Option<TransactionLocation>

Returns the TransactionLocation of the transaction that revealed the given sapling::Nullifier, if it is revealed in the finalized state and its spending transaction hash has been indexed.

pub fn orchard_revealing_tx_loc( &self, orchard_nullifier: &Nullifier, ) -> Option<TransactionLocation>

Returns the TransactionLocation of the transaction that revealed the given orchard::Nullifier, if it is revealed in the finalized state and its spending transaction hash has been indexed.

pub fn contains_sprout_anchor(&self, sprout_anchor: &Root) -> bool

Returns true if the finalized state contains sprout_anchor.

pub fn contains_sapling_anchor(&self, sapling_anchor: &Root) -> bool

Returns true if the finalized state contains sapling_anchor.

pub fn contains_orchard_anchor(&self, orchard_anchor: &Root) -> bool

Returns true if the finalized state contains orchard_anchor.

pub fn sprout_tree_for_tip(&self) -> Arc<NoteCommitmentTree>

Returns the Sprout note commitment tree of the finalized tip or the empty tree if the state is empty.

pub fn sprout_tree_by_anchor( &self, sprout_anchor: &Root, ) -> Option<Arc<NoteCommitmentTree>>

Returns the Sprout note commitment tree matching the given anchor.

This is used for interstitial tree building, which is unique to Sprout.

pub fn sprout_trees_full_map(&self) -> HashMap<Root, Arc<NoteCommitmentTree>>

Returns all the Sprout note commitment trees in the database.

Calling this method can load a lot of data into RAM, and delay block commit transactions.

pub fn sprout_trees_full_tip( &self, ) -> impl Iterator<Item = (RawBytes, Arc<NoteCommitmentTree>)> + '_

Returns all the Sprout note commitment tip trees. We only store the sprout tree for the tip, so this method is mainly used in tests.

pub fn sapling_tree_for_tip(&self) -> Arc<NoteCommitmentTree>

Returns the Sapling note commitment tree of the finalized tip or the empty tree if the state is empty.

pub fn sapling_tree_by_height( &self, height: &Height, ) -> Option<Arc<NoteCommitmentTree>>

Returns the Sapling note commitment tree matching the given block height, or None if the height is above the finalized tip.

pub fn sapling_tree_by_height_range<R>( &self, range: R, ) -> impl Iterator<Item = (Height, Arc<NoteCommitmentTree>)> + '_

where R: RangeBounds<Height>,

Returns the Sapling note commitment trees in the supplied range, in increasing height order.

pub fn sapling_tree_by_reversed_height_range<R>( &self, range: R, ) -> impl Iterator<Item = (Height, Arc<NoteCommitmentTree>)> + '_

where R: RangeBounds<Height>,

Returns the Sapling note commitment trees in the reversed range, in decreasing height order.

pub fn sapling_subtree_list_by_index_range( &self, range: impl RangeBounds<NoteCommitmentSubtreeIndex>, ) -> BTreeMap<NoteCommitmentSubtreeIndex, NoteCommitmentSubtreeData<Node>>

Returns a list of Sapling NoteCommitmentSubtrees in the provided range.

pub fn orchard_tree_for_tip(&self) -> Arc<NoteCommitmentTree>

Returns the Orchard note commitment tree of the finalized tip or the empty tree if the state is empty.

pub fn orchard_tree_by_height( &self, height: &Height, ) -> Option<Arc<NoteCommitmentTree>>

Returns the Orchard note commitment tree matching the given block height, or None if the height is above the finalized tip.

pub fn orchard_tree_by_height_range<R>( &self, range: R, ) -> impl Iterator<Item = (Height, Arc<NoteCommitmentTree>)> + '_

where R: RangeBounds<Height>,

Returns the Orchard note commitment trees in the supplied range, in increasing height order.

pub fn orchard_tree_by_reversed_height_range<R>( &self, range: R, ) -> impl Iterator<Item = (Height, Arc<NoteCommitmentTree>)> + '_

where R: RangeBounds<Height>,

Returns the Orchard note commitment trees in the reversed range, in decreasing height order.

pub fn orchard_subtree_list_by_index_range( &self, range: impl RangeBounds<NoteCommitmentSubtreeIndex>, ) -> BTreeMap<NoteCommitmentSubtreeIndex, NoteCommitmentSubtreeData<Node>>

Returns a list of Orchard NoteCommitmentSubtrees in the provided range.

pub fn note_commitment_trees_for_tip(&self) -> NoteCommitmentTrees

Returns the shielded note commitment trees of the finalized tip or the empty trees if the state is empty. Additionally, returns the sapling and orchard subtrees for the finalized tip if the current subtree is finalizing in the tip, None otherwise.

impl ZebraDb

pub fn tx_location_by_spent_output_location( &self, output_location: &OutputLocation, ) -> Option<TransactionLocation>

Returns the TransactionLocation for a transaction that spent the output at the provided OutputLocation, if it is in the finalized state.

pub fn address_balance_location( &self, address: &Address, ) -> Option<AddressBalanceLocation>

Returns the [AddressBalanceLocation] for a transparent::Address, if it is in the finalized state.

pub fn address_balance(&self, address: &Address) -> Option<Amount<NonNegative>>

Returns the balance for a transparent::Address, if it is in the finalized state.

pub fn address_location(&self, address: &Address) -> Option<OutputLocation>

Returns the first output that sent funds to a transparent::Address, if it is in the finalized state.

This location is used as an efficient index key for addresses.

pub fn output_location(&self, outpoint: &OutPoint) -> Option<OutputLocation>

Returns the OutputLocation for a transparent::OutPoint.

This method returns the locations of spent and unspent outpoints. Returns None if the output was never in the finalized state.

pub fn utxo(&self, outpoint: &OutPoint) -> Option<OrderedUtxo>

Returns the transparent output for a transparent::OutPoint, if it is unspent in the finalized state.

pub fn spending_tx_loc( &self, outpoint: &OutPoint, ) -> Option<TransactionLocation>

Returns the TransactionLocation of the transaction that spent the given transparent::OutPoint, if it is unspent in the finalized state and its spending transaction hash has been indexed.

pub fn utxo_by_location( &self, output_location: OutputLocation, ) -> Option<OrderedUtxo>

Returns the transparent output for an OutputLocation, if it is unspent in the finalized state.

pub fn address_utxos( &self, address: &Address, ) -> BTreeMap<OutputLocation, Output>

Returns the unspent transparent outputs for a transparent::Address, if they are in the finalized state.

pub fn address_utxo_locations( &self, address_location: OutputLocation, ) -> BTreeSet<AddressUnspentOutput>

Returns the unspent transparent output locations for a transparent::Address, if they are in the finalized state.

pub fn tx_id_by_location( &self, tx_location: TransactionLocation, ) -> Option<Hash>

Returns the transaction hash for an TransactionLocation.

pub fn address_tx_ids( &self, address: &Address, query_height_range: RangeInclusive<Height>, ) -> BTreeMap<TransactionLocation, Hash>

Returns the transaction IDs that sent or received funds to address, in the finalized chain query_height_range.

If address has no finalized sends or receives, or the query_height_range is totally outside the finalized block range, returns an empty list.

pub fn address_transaction_locations( &self, address_location: OutputLocation, query_height_range: RangeInclusive<Height>, ) -> BTreeSet<AddressTransaction>

Returns the locations of any transactions that sent or received from a transparent::Address, if they are in the finalized state.

pub fn partial_finalized_transparent_balance( &self, addresses: &HashSet<Address>, ) -> Amount<NonNegative>

Returns the total transparent balance for addresses in the finalized chain.

If none of the addresses has a balance, returns zero.

Correctness

Callers should apply the non-finalized balance change for addresses to the returned balance.

The total balance will only be correct if the non-finalized chain matches the finalized state. Specifically, the root of the partial non-finalized chain must be a child block of the finalized tip.

pub fn partial_finalized_address_utxos( &self, addresses: &HashSet<Address>, ) -> BTreeMap<OutputLocation, Output>

Returns the UTXOs for addresses in the finalized chain.

If none of the addresses has finalized UTXOs, returns an empty list.

Correctness

Callers should apply the non-finalized UTXO changes for addresses to the returned UTXOs.

The UTXOs will only be correct if the non-finalized chain matches or overlaps with the finalized state.

Specifically, a block in the partial chain must be a child block of the finalized tip. (But the child block does not have to be the partial chain root.)

pub fn partial_finalized_transparent_tx_ids( &self, addresses: &HashSet<Address>, query_height_range: RangeInclusive<Height>, ) -> BTreeMap<TransactionLocation, Hash>

Returns the transaction IDs that sent or received funds to addresses, in the finalized chain query_height_range.

If none of the addresses has finalized sends or receives, or the query_height_range is totally outside the finalized block range, returns an empty list.

Correctness

Callers should combine the non-finalized transactions for addresses with the returned transactions.

The transaction IDs will only be correct if the non-finalized chain matches or overlaps with the finalized state.

Specifically, a block in the partial chain must be a child block of the finalized tip. (But the child block does not have to be the partial chain root.)

This condition does not apply if there is only one address. Since address transactions are only appended by blocks, and this query reads them in order, it is impossible to get inconsistent transactions for a single address.

impl ZebraDb

pub fn new( config: &Config, db_kind: impl AsRef<str>, format_version_in_code: &Version, network: &Network, debug_skip_format_upgrades: bool, column_families_in_code: impl IntoIterator<Item = String>, read_only: bool, ) -> ZebraDb

Opens or creates the database at a path based on the kind, major version and network, with the supplied column families, preserving any existing column families, and returns a shared high-level typed database wrapper.

If debug_skip_format_upgrades is true, don’t do any format upgrades or format checks. This argument is only used when running tests, it is ignored in production code.

pub fn spawn_format_change(&mut self, format_change: DbFormatChange)

Launch any required format changes or format checks, and store their thread handle.

pub fn config(&self) -> &Config

Returns config for this database.

pub fn db_kind(&self) -> String

Returns the configured database kind for this database.

pub fn format_version_in_code(&self) -> Version

Returns the format version of the running code that created this ZebraDb instance in memory.

pub fn major_version(&self) -> u64

Returns the fixed major version for this database.

pub fn format_version_on_disk(&self) -> Result<Option<Version>, BoxError>

Returns the format version of this database on disk.

See database_format_version_on_disk() for details.

pub fn network(&self) -> Network

Returns the configured network for this database.

pub fn path(&self) -> &Path

Returns the Path where the files used by this database are located.

pub fn check_for_panics(&mut self)

Check for panics in code running in spawned threads. If a thread exited with a panic, resume that panic.

This method should be called regularly, so that panics are detected as soon as possible.

pub fn try_catch_up_with_primary(&self) -> Result<(), Error>

When called with a secondary DB instance, tries to catch up with the primary DB instance

pub fn shutdown(&mut self, force: bool)

Shut down the database, cleaning up background tasks and ephemeral data.

If force is true, clean up regardless of any shared references. force can cause errors accessing the database from other shared references. It should only be used in debugging or test code, immediately before a manual shutdown.

See [DiskDb::shutdown] for details.

pub fn print_db_metrics(&self)

Logs metrics related to the underlying RocksDB instance.

This function prints various metrics and statistics about the RocksDB database, such as disk usage, memory usage, and other performance-related metrics.

pub fn size(&self) -> u64

Returns the estimated total disk space usage of the database.

Trait Implementations

impl Clone for ZebraDb

fn clone(&self) -> ZebraDb

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ZebraDb

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

Formats the value using the given formatter.

impl Drop for ZebraDb

fn drop(&mut self)

Executes the destructor for this type.