Enum Request

pub enum Request {
    CommitSemanticallyVerifiedBlock(SemanticallyVerifiedBlock),
    CommitCheckpointVerifiedBlock(CheckpointVerifiedBlock),
    Depth(Hash),
    Tip,
    BlockLocator,
    Transaction(Hash),
    UnspentBestChainUtxo(OutPoint),
    Block(HashOrHeight),
    BlockAndSize(HashOrHeight),
    BlockHeader(HashOrHeight),
    AwaitUtxo(OutPoint),
    FindBlockHashes {
        known_blocks: Vec<Hash>,
        stop: Option<Hash>,
    },
    FindBlockHeaders {
        known_blocks: Vec<Hash>,
        stop: Option<Hash>,
    },
    CheckBestChainTipNullifiersAndAnchors(UnminedTx),
    BestChainNextMedianTimePast,
    BestChainBlockHash(Height),
    KnownBlock(Hash),
    InvalidateBlock(Hash),
    ReconsiderBlock(Hash),
    CheckBlockProposalValidity(SemanticallyVerifiedBlock),
}

A query about or modification to the chain state, via the StateService.

Variants

CommitSemanticallyVerifiedBlock(SemanticallyVerifiedBlock)

Performs contextual validation of the given semantically verified block, committing it to the state if successful.

This request can be made out-of-order; the state service will queue it until its parent is ready.

Returns Response::Committed with the hash of the block when it is committed to the state, or an error if the block fails contextual validation or has already been committed to the state.

This request cannot be cancelled once submitted; dropping the response future will have no effect on whether it is eventually processed. A request to commit a block which has been queued internally but not yet committed will fail the older request and replace it with the newer request.

Correctness

Block commit requests should be wrapped in a timeout, so that out-of-order and invalid requests do not hang indefinitely. See the crate documentation for details.

CommitCheckpointVerifiedBlock(CheckpointVerifiedBlock)

Commit a checkpointed block to the state, skipping most but not all contextual validation.

This is exposed for use in checkpointing, which produces checkpoint vefified blocks. This request can be made out-of-order; the state service will queue it until its parent is ready.

Returns Response::Committed with the hash of the newly committed block, or an error.

This request cannot be cancelled once submitted; dropping the response future will have no effect on whether it is eventually processed. Duplicate requests will replace the older duplicate, and return an error in its response future.

Note

SemanticallyVerifiedBlock, ContextuallyVerifiedBlock and CheckpointVerifiedBlock are an internal Zebra implementation detail. There is no difference between these blocks on the Zcash network, or in Zebra’s network or syncer implementations.

Consensus

Checkpointing is allowed under the Zcash “social consensus” rules. Zebra checkpoints both settled network upgrades, and blocks past the rollback limit. (By the time Zebra release is tagged, its final checkpoint is typically hours or days old.)

A network upgrade is settled on a given network when there is a social consensus that it has activated with a given activation block hash. A full validator that potentially risks Mainnet funds or displays Mainnet transaction information to a user MUST do so only for a block chain that includes the activation block of the most recent settled network upgrade, with the corresponding activation block hash. … A full validator MAY impose a limit on the number of blocks it will “roll back” when switching from one best valid block chain to another that is not a descendent. For zcashd and zebra this limit is 100 blocks.

https://zips.z.cash/protocol/protocol.pdf#blockchain

Correctness

Block commit requests should be wrapped in a timeout, so that out-of-order and invalid requests do not hang indefinitely. See the crate documentation for details.

Depth(Hash)

Computes the depth in the current best chain of the block identified by the given hash.

Returns

• Response::Depth(Some(depth)) if the block is in the best chain;
• Response::Depth(None) otherwise.

Tip

Returns Response::Tip(Option<(Height, block::Hash)>) with the current best chain tip.

BlockLocator

Computes a block locator object based on the current best chain.

Returns Response::BlockLocator with hashes starting from the best chain tip, and following the chain of previous hashes. The first hash is the best chain tip. The last hash is the tip of the finalized portion of the state. Block locators are not continuous - some intermediate hashes might be skipped.

If the state is empty, the block locator is also empty.

Transaction(Hash)

Looks up a transaction by hash in the current best chain.

Returns

• Response::Transaction(Some(Arc<Transaction>)) if the transaction is in the best chain;
• Response::Transaction(None) otherwise.

UnspentBestChainUtxo(OutPoint)

Looks up a UTXO identified by the given OutPoint, returning None immediately if it is unknown.

Checks verified blocks in the finalized chain and the best non-finalized chain.

Block(HashOrHeight)

Looks up a block by hash or height in the current best chain.

Returns

• Response::Block(Some(Arc<Block>)) if the block is in the best chain;
• Response::Block(None) otherwise.

Note: the HashOrHeight can be constructed from a block::Hash or block::Height using .into().

BlockAndSize(HashOrHeight)

Returns

• ReadResponse::BlockAndSize(Some((Arc<Block>, usize))) if the block is in the best chain;
• ReadResponse::BlockAndSize(None) otherwise.

BlockHeader(HashOrHeight)

Looks up a block header by hash or height in the current best chain.

Returns

Response::BlockHeader(block::Header).

Note: the HashOrHeight can be constructed from a block::Hash or block::Height using .into().

AwaitUtxo(OutPoint)

Request a UTXO identified by the given OutPoint, waiting until it becomes available if it is unknown.

Checks the finalized chain, all non-finalized chains, queued unverified blocks, and any blocks that arrive at the state after the request future has been created.

This request is purely informational, and there are no guarantees about whether the UTXO remains unspent or is on the best chain, or any chain. Its purpose is to allow asynchronous script verification or to wait until the UTXO arrives in the state before validating dependent transactions.

Correctness

UTXO requests should be wrapped in a timeout, so that out-of-order and invalid requests do not hang indefinitely. See the crate documentation for details.

Outdated requests are pruned on a regular basis.

FindBlockHashes

Finds the first hash that’s in the peer’s known_blocks and the local best chain. Returns a list of hashes that follow that intersection, from the best chain.

If there is no matching hash in the best chain, starts from the genesis hash.

Stops the list of hashes after:

• adding the best tip,
• adding the stop hash to the list, if it is in the best chain, or
• adding 500 hashes to the list.

Returns an empty list if the state is empty.

Returns

Response::BlockHashes(Vec<block::Hash>). See https://en.bitcoin.it/wiki/Protocol_documentation#getblocks

Fields

known_blocks: Vec<Hash>

Hashes of known blocks, ordered from highest height to lowest height.

stop: Option<Hash>

Optionally, the last block hash to request.

FindBlockHeaders

Finds the first hash that’s in the peer’s known_blocks and the local best chain. Returns a list of headers that follow that intersection, from the best chain.

If there is no matching hash in the best chain, starts from the genesis header.

Stops the list of headers after:

• adding the best tip,
• adding the header matching the stop hash to the list, if it is in the best chain, or
• adding MAX_FIND_BLOCK_HEADERS_RESULTS headers to the list.

Returns an empty list if the state is empty.

Returns

Response::BlockHeaders(Vec<block::Header>). See https://en.bitcoin.it/wiki/Protocol_documentation#getheaders

Fields

known_blocks: Vec<Hash>

Hashes of known blocks, ordered from highest height to lowest height.

stop: Option<Hash>

Optionally, the hash of the last header to request.

CheckBestChainTipNullifiersAndAnchors(UnminedTx)

Contextually validates anchors and nullifiers of a transaction on the best chain

Returns Response::ValidBestChainTipNullifiersAndAnchors

BestChainNextMedianTimePast

Calculates the median-time-past for the next block on the best chain.

Returns Response::BestChainNextMedianTimePast when successful.

BestChainBlockHash(Height)

Looks up a block hash by height in the current best chain.

Returns

• Response::BlockHash(Some(hash)) if the block is in the best chain;
• Response::BlockHash(None) otherwise.

KnownBlock(Hash)

Checks if a block is present anywhere in the state service. Looks up hash in block queues as well as the finalized chain and all non-finalized chains.

Returns Response::KnownBlock(Some(Location)) if the block is in the best state service. Returns Response::KnownBlock(None) otherwise.

InvalidateBlock(Hash)

Invalidates a block in the non-finalized state with the provided hash if one is present, removing it and its child blocks, and rejecting it during contextual validation if it’s resubmitted to the state.

ReconsiderBlock(Hash)

Reconsiders a previously invalidated block in the non-finalized state with the provided hash if one is present.

CheckBlockProposalValidity(SemanticallyVerifiedBlock)

Performs contextual validation of the given block, but does not commit it to the state.

Returns Response::ValidBlockProposal when successful. See [ReadRequest::CheckBlockProposalValidity] for details.

Implementations

impl Request

pub fn count_metric(&self)

Counts metric for StateService call

Trait Implementations

impl Clone for Request

fn clone(&self) -> Request

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Request

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

Formats the value using the given formatter.

impl PartialEq for Request

fn eq(&self, other: &Request) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TryFrom<Request> for ReadRequest

Conversion from read-write Requests to read-only ReadRequests.

Used to dispatch read requests concurrently from the StateService.

type Error = &'static str

The type returned in the event of a conversion error.

fn try_from(request: Request) -> Result<ReadRequest, Self::Error>

Performs the conversion.

impl Eq for Request

impl StructuralPartialEq for Request