zecfoundation
/
zebra
mirror of https://github.com/ZcashFoundation/zebra.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Improve state request docs 

Document best and any chain requests
Explain that the block locator is sparse
This commit is contained in:
teor 2020-11-17 06:50:57 +10:00
parent ca4e792f47
commit 2253ab3c00
1 changed files with 17 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
zebra-state/src/request.rs
View File

@ -83,45 +83,49 @@ pub enum Request {
// sapling_anchor: sapling::tree::Root, // sapling_anchor: sapling::tree::Root,
}, },
/// Computes the depth in the best chain of the block identified by the given hash. /// Computes the depth in the current best chain of the block identified by the given hash.
/// ///
/// Returns /// Returns
/// ///
/// * [`Response::Depth(Some(depth))`](Response::Depth) if the block is in the main chain; /// * [`Response::Depth(Some(depth))`](Response::Depth) if the block is in the best chain;
/// * [`Response::Depth(None)`](Response::Depth) otherwise. /// * [`Response::Depth(None)`](Response::Depth) otherwise.
Depth(block::Hash), Depth(block::Hash),
/// Returns [`Response::Tip`] with the current best chain tip. /// Returns [`Response::Tip`] with the current best chain tip.
Tip, Tip,
/// Computes a block locator object based on the current chain state. /// Computes a block locator object based on the current best chain.
/// ///
/// Returns [`Response::BlockLocator`] with hashes starting /// Returns [`Response::BlockLocator`] with hashes starting
/// from the current chain tip and reaching backwards towards the genesis /// from the best chain tip, and following the chain of previous
/// block. The first hash is the current chain tip. The last hash is the tip /// hashes. The first hash is the best chain tip. The last hash is
/// of the finalized portion of the state. If the state is empty, the block /// the tip of the finalized portion of the state. Block locators
/// locator is also empty. /// are not continuous - some intermediate hashes might be skipped.
///
/// If the state is empty, the block locator is also empty.
BlockLocator, BlockLocator,
/// Looks up a transaction by hash. /// Looks up a transaction by hash in the current best chain.
/// ///
/// Returns /// Returns
/// ///
/// * [`Response::Transaction(Some(Arc<Transaction>))`](Response::Transaction) if the transaction is known; /// * [`Response::Transaction(Some(Arc<Transaction>))`](Response::Transaction) if the transaction is in the best chain;
/// * [`Response::Transaction(None)`](Response::Transaction) otherwise. /// * [`Response::Transaction(None)`](Response::Transaction) otherwise.
Transaction(transaction::Hash), Transaction(transaction::Hash),
/// Looks up a block by hash or height. /// Looks up a block by hash or height in the current best chain.
/// ///
/// Returns /// Returns
/// ///
/// * [`Response::Block(Some(Arc<Block>))`](Response::Block) if the block is known; /// * [`Response::Block(Some(Arc<Block>))`](Response::Block) if the block is in the best chain;
/// * [`Response::Block(None)`](Response::Transaction) otherwise. /// * [`Response::Block(None)`](Response::Block) otherwise.
/// ///
/// Note: the [`HashOrHeight`] can be constructed from a [`block::Hash`] or /// Note: the [`HashOrHeight`] can be constructed from a [`block::Hash`] or
/// [`block::Height`] using `.into()`. /// [`block::Height`] using `.into()`.
Block(HashOrHeight), Block(HashOrHeight),
/// Request a UTXO identified by the given Outpoint /// Request a UTXO identified by the given Outpoint in any chain.
///
/// Returns UTXOs fron any chain, including side-chains.
AwaitUtxo(transparent::OutPoint), AwaitUtxo(transparent::OutPoint),
} }