Struct FsBlockDb

pub struct FsBlockDb { /* private fields */ }

Available on crate feature unstable only.

A block source that reads block data from disk and block metadata from a SQLite database.

This block source expects each compact block to be stored on disk in the blocks subdirectory of the blockstore_root path provided at the time of construction. Each block should be written, as the serialized bytes of its protobuf representation, where the path for each block has the pattern:

<blockstore_root>/blocks/<block_height>-<block_hash>-compactblock

where <block_height> is the decimal value of the height at which the block was mined, and <block_hash> is the hexadecimal representation of the block hash, as produced by the fmt::Display implementation for zcash_primitives::block::BlockHash.

This block source is intended to be used with the following data flow:

• When the cache is being filled:
  • The caller requests the current maximum height at which cached data is available using FsBlockDb::get_max_cached_height. If no cached data is available, the caller can use the wallet’s synced-to height for the following operations instead.
  • (recommended for privacy) the caller should round the returned height down to some 100- / 1000-block boundary.
  • The caller uses the lightwalletd’s getblock gRPC method to obtain a stream of blocks. For each block returned, the caller writes the compact block to blocks_dir using the path format specified above. It is fine to overwrite an existing block, since block hashes are immutable and collision-resistant.
  • Once a caller-determined number of blocks have been successfully written to disk, the caller should invoke FsBlockDb::write_block_metadata with the metadata for each block written to disk.
• The cache can then be scanned using the BlockSource implementation, providing the wallet’s synced-to-height as a starting point.
• When part of the cache is no longer needed:
  • The caller determines some height H that is the earliest block data it needs to preserve. This might be determined based on where the wallet is fully-synced to, or other heuristics.
  • The caller searches the defined filesystem folder for all files beginning in HEIGHT-* where HEIGHT < H, and deletes those files.

Note: This API is unstable, and may change in the future. In particular, the BlockSource API and the above description currently assume that scanning is performed in linear block order; this assumption is likely to be weakened and/or removed in a future update.

Implementations

impl FsBlockDb

pub fn for_path<P: AsRef<Path>>( fsblockdb_root: P, ) -> Result<Self, FsBlockDbError>

Creates a filesystem-backed block store at the given path.

This will construct or open a SQLite database at the path <fsblockdb_root>/blockmeta.sqlite and will ensure that a directory exists at <fsblockdb_root>/blocks where this block store will expect to find serialized block files as described for FsBlockDb.

An application using this constructor should ensure that they call crate::chain::init::init_blockmeta_db at application startup to ensure that the resulting metadata database is properly initialized and has had all required migrations applied before use.

pub fn get_max_cached_height( &self, ) -> Result<Option<BlockHeight>, FsBlockDbError>

Returns the maximum height of blocks known to the block metadata database.

pub fn write_block_metadata( &self, block_meta: &[BlockMeta], ) -> Result<(), FsBlockDbError>

Adds a set of block metadata entries to the metadata database, overwriting any existing entries at the given block heights.

This will return an error if any block file corresponding to one of these metadata records is absent from the blocks directory.

pub fn find_block( &self, height: BlockHeight, ) -> Result<Option<BlockMeta>, FsBlockDbError>

Returns the metadata for the block with the given height, if it exists in the database.

pub fn truncate_to_height( &self, block_height: BlockHeight, ) -> Result<(), FsBlockDbError>

Rewinds the BlockMeta Db to the block_height provided.

This doesn’t delete any files referenced by the records stored in BlockMeta.

If the requested height is greater than or equal to the height of the last scanned block, or if the DB is empty, this function does nothing.

Trait Implementations

impl BlockSource for FsBlockDb

type Error = FsBlockDbError

fn with_blocks<F, DbErrT>( &self, from_height: Option<BlockHeight>, limit: Option<usize>, with_row: F, ) -> Result<(), Error<DbErrT, Self::Error>>

where F: FnMut(CompactBlock) -> Result<(), Error<DbErrT, Self::Error>>,

Scan the specified limit number of blocks from the blockchain, starting at from_height, applying the provided callback to each block. If from_height is None then scanning will begin at the first available block.