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,
},
/// 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
///
/// * [`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.
Depth(block::Hash),
/// Returns [`Response::Tip`] with the current best chain 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
/// from the current chain tip and reaching backwards towards the genesis
/// block. The first hash is the current chain tip. The last hash is the tip
/// of the finalized portion of the state. If the state is empty, the block
/// locator is also empty.
/// 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.
BlockLocator,
/// Looks up a transaction by hash.
/// Looks up a transaction by hash in the current best chain.
///
/// 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.
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
///
/// * [`Response::Block(Some(Arc<Block>))`](Response::Block) if the block is known;
/// * [`Response::Block(None)`](Response::Transaction) otherwise.
/// * [`Response::Block(Some(Arc<Block>))`](Response::Block) if the block is in the best chain;
/// * [`Response::Block(None)`](Response::Block) otherwise.
///
/// Note: the [`HashOrHeight`] can be constructed from a [`block::Hash`] or
/// [`block::Height`] using `.into()`.
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),
}