Improve state request docs
Document best and any chain requests
Explain that the block locator is sparse
@@ -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),
}
