Struct zebra_consensus::checkpoint::CheckpointVerifier

pub struct CheckpointVerifier<S>
where
    S: Service<Request, Response = Response, Error = BoxError> + Send + Clone + 'static,
    S::Future: Send + 'static,
{
    checkpoint_list: CheckpointList,
    network: Network,
    initial_tip_hash: Option<Hash>,
    state_service: S,
    queued: BTreeMap<Height, Vec<QueuedBlock>>,
    verifier_progress: Progress<Height>,
    reset_receiver: Receiver<Option<(Height, Hash)>>,
    reset_sender: Sender<Option<(Height, Hash)>>,
    queued_blocks_bar: Tx,
    verified_checkpoint_bar: Tx,
}

A checkpointing block verifier.

Verifies blocks using a supplied list of checkpoints. There must be at least one checkpoint for the genesis block.

Fields

checkpoint_list: CheckpointList

The checkpoint list for this verifier.

network: Network

The network rules used by this verifier.

initial_tip_hash: Option<Hash>

The hash of the initial tip, if any.

state_service: S

The underlying state service, possibly wrapped in other services.

queued: BTreeMap<Height, Vec<QueuedBlock>>

A queue of unverified blocks.

Contains a list of unverified blocks at each block height. In most cases, the checkpoint verifier will store zero or one block at each height.

Blocks are verified in order, once there is a chain from the previous checkpoint to a target checkpoint.

The first checkpoint does not have any ancestors, so it only verifies the genesis block.

verifier_progress: Progress<Height>

The current progress of this verifier.

reset_receiver: Receiver<Option<(Height, Hash)>>

A channel to receive requests to reset the verifier, receiving the tip of the state.

reset_sender: Sender<Option<(Height, Hash)>>

A channel to send requests to reset the verifier, passing the tip of the state.

queued_blocks_bar: Tx

Queued block height progress transmitter.

verified_checkpoint_bar: Tx

Verified checkpoint progress transmitter.

Implementations

impl<S> CheckpointVerifier<S>

where S: Service<Request, Response = Response, Error = BoxError> + Send + Clone + 'static, S::Future: Send + 'static,

pub fn new( network: &Network, initial_tip: Option<(Height, Hash)>, state_service: S, ) -> Self

Return a checkpoint verification service for network, using the hard-coded checkpoint list, and the provided state_service.

If initial_tip is Some(_), the verifier starts at that initial tip. The initial tip can be between the checkpoints in the hard-coded checkpoint list.

The checkpoint verifier holds a state service of type S, into which newly verified blocks will be committed. This state is pluggable to allow for testing or instrumentation.

This function should be called only once for a particular network, rather than constructing multiple verification services for the same network. To clone a CheckpointVerifier, you might need to wrap it in a tower::Buffer service.

pub(crate) fn from_list( list: impl IntoIterator<Item = (Height, Hash)>, network: &Network, initial_tip: Option<(Height, Hash)>, state_service: S, ) -> Result<Self, VerifyCheckpointError>

Return a checkpoint verification service using list, network, initial_tip, and state_service.

Assumes that the provided genesis checkpoint is correct.

Callers should prefer CheckpointVerifier::new, which uses the hard-coded checkpoint lists, or CheckpointList::from_list if you need to specify a custom checkpoint list. See those functions for more details.

This function is designed for use in tests.

pub(crate) fn from_checkpoint_list( checkpoint_list: CheckpointList, network: &Network, initial_tip: Option<(Height, Hash)>, state_service: S, ) -> Self

Return a checkpoint verification service using checkpoint_list, network, initial_tip, and state_service.

Assumes that the provided genesis checkpoint is correct.

Callers should prefer CheckpointVerifier::new, which uses the hard-coded checkpoint lists. See that function for more details.

fn queued_block_diagnostics(&self, height: Height, hash: Hash)

Update diagnostics for queued blocks.

fn verified_checkpoint_diagnostics( &self, verified_height: impl Into<Option<Height>>, )

Update diagnostics for verified checkpoints.

fn finish_diagnostics(&self)

Finish checkpoint verifier diagnostics.

fn reset_progress(&mut self, tip: Option<(Height, Hash)>)

Reset the verifier progress back to given tip.

fn previous_checkpoint_height(&self) -> Progress<Height>

Return the current verifier’s progress.

If verification has not started yet, returns BeforeGenesis, or InitialTip(height) if there were cached verified blocks.

If verification is ongoing, returns PreviousCheckpoint(height). height increases as checkpoints are verified.

If verification has finished, returns FinalCheckpoint.

fn current_start_bound(&self) -> Option<Bound<Height>>

Return the start of the current checkpoint range.

Returns None if verification has finished.

fn target_checkpoint_height(&self) -> TargetHeight

Return the target checkpoint height that we want to verify.

If we need more blocks, returns WaitingForBlocks.

If the queued blocks are continuous from the previous checkpoint to a target checkpoint, returns Checkpoint(height). The target checkpoint can be multiple checkpoints ahead of the previous checkpoint.

height increases as checkpoints are verified.

If verification has finished, returns FinishedVerifying.

fn previous_checkpoint_hash(&self) -> Progress<Hash>

Return the most recently verified checkpoint’s hash.

See previous_checkpoint_height() for details.

fn check_height(&self, height: Height) -> Result<(), VerifyCheckpointError>

Check that height is valid and able to be verified.

Returns an error if:

• the block’s height is greater than the maximum checkpoint
• there are no checkpoints
• the block’s height is less than or equal to the previously verified checkpoint
• verification has finished

fn update_progress(&mut self, verified_height: Height)

Increase the current checkpoint height to verified_height,

fn check_block( &self, block: Arc<Block>, ) -> Result<CheckpointVerifiedBlock, VerifyCheckpointError>

Check that the block height, proof of work, and Merkle root are valid.

Returns a CheckpointVerifiedBlock with precalculated block data.

Security

Checking the proof of work makes resource exhaustion attacks harder to carry out, because malicious blocks require a valid proof of work.

Checking the Merkle root ensures that the block hash binds the block contents. To prevent malleability (CVE-2012-2459), we also need to check whether the transaction hashes are unique.

fn queue_block( &mut self, block: Arc<Block>, ) -> Result<RequestBlock, VerifyCheckpointError>

Queue block for verification.

On success, returns a RequestBlock containing the block, precalculated request data, and the queued result receiver.

Verification will finish when the chain to the next checkpoint is complete, and the caller will be notified via the channel.

If the block does not pass basic validity checks, returns an error immediately.

fn process_height( &mut self, height: Height, expected_hash: Hash, ) -> Option<QueuedBlock>

During checkpoint range processing, process all the blocks at height.

Returns the first valid block. If there is no valid block, returns None.

fn process_checkpoint_range(&mut self)

Try to verify from the previous checkpoint to a target checkpoint.

Send Ok for the blocks that are in the chain, and Err for side-chain blocks.

Does nothing if we are waiting for more blocks, or if verification has finished.

Trait Implementations

impl<S> Debug for CheckpointVerifier<S>

where S: Service<Request, Response = Response, Error = BoxError> + Send + Clone + 'static, S::Future: Send + 'static,

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

Formats the value using the given formatter.

impl<S> Drop for CheckpointVerifier<S>

where S: Service<Request, Response = Response, Error = BoxError> + Send + Clone + 'static, S::Future: Send + 'static,

CheckpointVerifier rejects pending futures on drop.

fn drop(&mut self)

Send an error on tx for any QueuedBlocks that haven’t been verified.

We can’t implement Drop on QueuedBlock, because send() consumes tx. And tx doesn’t implement Copy or Default (for take()).

impl<S> Service<Arc<Block>> for CheckpointVerifier<S>

where S: Service<Request, Response = Response, Error = BoxError> + Send + Clone + 'static, S::Future: Send + 'static,

The CheckpointVerifier service implementation.

After verification, the block futures resolve to their hashes.

type Response = Hash

Responses given by the service.

type Error = VerifyCheckpointError

Errors produced by the service.

type Future = Pin<Box<dyn Future<Output = Result<<CheckpointVerifier<S> as Service<Arc<Block>>>::Response, <CheckpointVerifier<S> as Service<Arc<Block>>>::Error>> + Send>>

The future response value.

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

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

fn call(&mut self, block: Arc<Block>) -> Self::Future

Process the request and return the response asynchronously.