Struct StateService

pub(crate) struct StateService {

    network: Network,
    full_verifier_utxo_lookahead: Height,
    non_finalized_state_queued_blocks: QueuedBlocks,
    finalized_state_queued_blocks: HashMap<Hash, (CheckpointVerifiedBlock, Sender<Result<Hash, BoxError>>)>,
    non_finalized_block_write_sender: Option<UnboundedSender<(SemanticallyVerifiedBlock, Sender<Result<Hash, BoxError>>)>>,
    finalized_block_write_sender: Option<UnboundedSender<(CheckpointVerifiedBlock, Sender<Result<Hash, BoxError>>)>>,
    finalized_block_write_last_sent_hash: Hash,
    non_finalized_block_write_sent_hashes: SentHashes,
    invalid_block_write_reset_receiver: UnboundedReceiver<Hash>,
    pending_utxos: PendingUtxos,
    last_prune: Instant,
    read_service: ReadStateService,
    max_finalized_queue_height: f64,
}

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

This service modifies and provides access to:

• the non-finalized state: the ~100 most recent blocks. Zebra allows chain forks in the non-finalized state, stores it in memory, and re-downloads it when restarted.
• the finalized state: older blocks that have many confirmations. Zebra stores the single best chain in the finalized state, and re-loads it from disk when restarted.

Read requests to this service are buffered, then processed concurrently. Block write requests are buffered, then queued, then processed in order by a separate task.

Most state users can get faster read responses using the ReadStateService, because its requests do not share a [tower::buffer::Buffer] with block write requests.

To quickly get the latest block, use LatestChainTip or ChainTipChange. They can read the latest block directly, without queueing any requests.

Fields

network: Network

The configured Zcash network.

full_verifier_utxo_lookahead: Height

The height that we start storing UTXOs from finalized blocks.

This height should be lower than the last few checkpoints, so the full verifier can verify UTXO spends from those blocks, even if they haven’t been committed to the finalized state yet.

non_finalized_state_queued_blocks: QueuedBlocks

Queued blocks for the NonFinalizedState that arrived out of order. These blocks are awaiting their parent blocks before they can do contextual verification.

finalized_state_queued_blocks: HashMap<Hash, (CheckpointVerifiedBlock, Sender<Result<Hash, BoxError>>)>

Queued blocks for the FinalizedState that arrived out of order. These blocks are awaiting their parent blocks before they can do contextual verification.

Indexed by their parent block hash.

non_finalized_block_write_sender: Option<UnboundedSender<(SemanticallyVerifiedBlock, Sender<Result<Hash, BoxError>>)>>

A channel to send blocks to the block_write_task, so they can be written to the NonFinalizedState.

finalized_block_write_sender: Option<UnboundedSender<(CheckpointVerifiedBlock, Sender<Result<Hash, BoxError>>)>>

A channel to send blocks to the block_write_task, so they can be written to the FinalizedState.

This sender is dropped after the state has finished sending all the checkpointed blocks, and the lowest semantically verified block arrives.

finalized_block_write_last_sent_hash: Hash

The block::Hash of the most recent block sent on finalized_block_write_sender or non_finalized_block_write_sender.

On startup, this is:

• the finalized tip, if there are stored blocks, or
• the genesis block’s parent hash, if the database is empty.

If invalid_block_write_reset_receiver gets a reset, this is:

• the hash of the last valid committed block (the parent of the invalid block).

non_finalized_block_write_sent_hashes: SentHashes

A set of block hashes that have been sent to the block write task. Hashes of blocks below the finalized tip height are periodically pruned.

invalid_block_write_reset_receiver: UnboundedReceiver<Hash>

If an invalid block is sent on finalized_block_write_sender or non_finalized_block_write_sender, this channel gets the block::Hash of the valid tip.

pending_utxos: PendingUtxos

The set of outpoints with pending requests for their associated transparent::Output.

last_prune: Instant

Instant tracking the last time pending_utxos was pruned.

read_service: ReadStateService

A cloneable ReadStateService, used to answer concurrent read requests.

TODO: move users of read Requests to ReadStateService, and remove read_service.

max_finalized_queue_height: f64

A metric tracking the maximum height that’s currently in finalized_state_queued_blocks

Set to f64::NAN if finalized_state_queued_blocks is empty, because grafana shows NaNs as a break in the graph.

Implementations

impl StateService

const PRUNE_INTERVAL: Duration = _

pub fn new( config: Config, network: &Network, max_checkpoint_height: Height, checkpoint_verify_concurrency_limit: usize, ) -> (Self, ReadStateService, LatestChainTip, ChainTipChange)

Creates a new state service for the state config and network.

Uses the max_checkpoint_height and checkpoint_verify_concurrency_limit to work out when it is near the final checkpoint.

Returns the read-write and read-only state services, and read-only watch channels for its best chain tip.

pub fn log_db_metrics(&self)

Call read only state service to log rocksdb database metrics.

fn queue_and_commit_to_finalized_state( &mut self, checkpoint_verified: CheckpointVerifiedBlock, ) -> Receiver<Result<Hash, BoxError>>

Queue a checkpoint verified block for verification and storage in the finalized state.

Returns a channel receiver that provides the result of the block commit.

pub fn drain_finalized_queue_and_commit(&mut self)

Finds finalized state queue blocks to be committed to the state in order, removes them from the queue, and sends them to the block commit task.

After queueing a finalized block, this method checks whether the newly queued block (and any of its descendants) can be committed to the state.

Returns an error if the block commit channel has been closed.

fn clear_finalized_block_queue(&mut self, error: impl Into<BoxError> + Clone)

Drops all finalized state queue blocks, and sends an error on their result channels.

fn send_checkpoint_verified_block_error( queued: (CheckpointVerifiedBlock, Sender<Result<Hash, BoxError>>), error: impl Into<BoxError>, )

Send an error on a QueuedCheckpointVerified block’s result channel, and drop the block

fn clear_non_finalized_block_queue( &mut self, error: impl Into<BoxError> + Clone, )

Drops all non-finalized state queue blocks, and sends an error on their result channels.

fn send_semantically_verified_block_error( queued: (SemanticallyVerifiedBlock, Sender<Result<Hash, BoxError>>), error: impl Into<BoxError>, )

Send an error on a QueuedSemanticallyVerified block’s result channel, and drop the block

fn queue_and_commit_to_non_finalized_state( &mut self, semantically_verrified: SemanticallyVerifiedBlock, ) -> Receiver<Result<Hash, BoxError>>

Queue a semantically verified block for contextual verification and check if any queued blocks are ready to be verified and committed to the state.

This function encodes the logic for committing non-finalized blocks in RFC0005.

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

Returns true if hash is a valid previous block hash for new non-finalized blocks.

fn is_close_to_final_checkpoint(&self, queued_height: Height) -> bool

Returns true if queued_height is near the final checkpoint.

The semantic block verifier needs access to UTXOs from checkpoint verified blocks near the final checkpoint, so that it can verify blocks that spend those UTXOs.

If it doesn’t have the required UTXOs, some blocks will time out, but succeed after a syncer restart.

fn send_ready_non_finalized_queued(&mut self, new_parent: Hash)

Sends all queued blocks whose parents have recently arrived starting from new_parent in breadth-first ordering to the block write task which will attempt to validate and commit them

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

Return the tip of the current best chain.

fn assert_block_can_be_validated(&self, block: &SemanticallyVerifiedBlock)

Assert some assumptions about the semantically verified block before it is queued.

Trait Implementations

impl Debug for StateService

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

Formats the value using the given formatter.

impl Drop for StateService

fn drop(&mut self)

Executes the destructor for this type.

impl Service<Request> for StateService

type Response = Response

Responses given by the service.

type Error = Box<dyn Error + Sync + Send>

Errors produced by the service.

type Future = Pin<Box<dyn Future<Output = Result<<StateService as Service<Request>>::Response, <StateService as Service<Request>>::Error>> + Send>>

The future response value.

fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>

Returns Poll::Ready(Ok(())) when the service is able to process requests.

fn call(&mut self, req: Request) -> Self::Future

Process the request and return the response asynchronously.