From 2253ab3c00ec8845f1dbea0914c20643d23477e6 Mon Sep 17 00:00:00 2001
From: teor <teor@riseup.net>
Date: Tue, 17 Nov 2020 06:50:57 +1000
Subject: [PATCH] Improve state request docs

Document best and any chain requests
Explain that the block locator is sparse
---
 zebra-state/src/request.rs | 30 +++++++++++++++++-------------
 1 file changed, 17 insertions(+), 13 deletions(-)

diff --git a/zebra-state/src/request.rs b/zebra-state/src/request.rs
index 97421061..6a0da75c 100644
--- a/zebra-state/src/request.rs
+++ b/zebra-state/src/request.rs
@@ -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),
 }