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

change(state): Refactor docs for `z_getsubtreesbyindex` RPC state requests (#7462) 

* Refactor some comments for subtrees

* Update docs about single subtree APIs

* Fix method rename in tree.rs

---------

Co-authored-by: teor <teor@riseup.net>
This commit is contained in:
Marek 2023-09-06 09:15:18 +02:00 committed by arya2
parent 7678036d86
commit d75f2afc2b
2 changed files with 29 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -849,14 +849,13 @@ pub enum ReadRequest {
/// * [`ReadResponse::OrchardTree(None)`](crate::ReadResponse::OrchardTree) otherwise.
OrchardTree(HashOrHeight),
/// Returns a list of Sapling note commitment subtrees by their indexes,
/// starting at `start_index`, and returning up to `limit` subtrees.
/// Returns a list of Sapling note commitment subtrees by their indexes, starting at
/// `start_index`, and returning up to `limit` subtrees.
///
/// Returns
///
/// * [`ReadResponse::SaplingSubtree(BTreeMap<_, NoteCommitmentSubtreeData<_>>))`](crate::ReadResponse::SaplingSubtrees)
///
/// If there is no subtree at `start_index`, returns an empty list.
/// * An empty list if there is no subtree at `start_index`.
SaplingSubtrees {
/// The index of the first 2^16-leaf subtree to return.
start_index: NoteCommitmentSubtreeIndex,
@ -864,14 +863,13 @@ pub enum ReadRequest {
limit: Option<NoteCommitmentSubtreeIndex>,
},
/// Returns a list of Orchard note commitment subtrees by their indexes,
/// starting at `start_index`, and returning up to `limit` subtrees.
/// Returns a list of Orchard note commitment subtrees by their indexes, starting at
/// `start_index`, and returning up to `limit` subtrees.
///
/// Returns
///
/// * [`ReadResponse::OrchardSubtree(BTreeMap<_, NoteCommitmentSubtreeData<_>>))`](crate::ReadResponse::OrchardSubtrees)
///
/// If there is no subtree at `start_index`, returns an empty list.
/// * An empty list if there is no subtree at `start_index`.
OrchardSubtrees {
/// The index of the first 2^16-leaf subtree to return.
start_index: NoteCommitmentSubtreeIndex,

50
zebra-state/src/service/read/tree.rs
View File

@ -49,12 +49,19 @@ where
}
/// Returns a list of Sapling [`NoteCommitmentSubtree`]s starting at `start_index`.
/// If `limit` is provided, the list is limited to `limit` entries.
///
/// If there is no subtree at `start_index` in the non-finalized `chain` or finalized `db`,
/// the returned list is empty. Otherwise, subtrees are continuous and consistent up to the tip.
/// If `limit` is provided, the list is limited to `limit` entries. If there is no subtree at
/// `start_index` in the non-finalized `chain` or finalized `db`, the returned list is empty.
///
/// There is no API for retrieving single subtrees, because it can accidentally be used to create
/// # Correctness
///
/// 1. After `chain` was cloned, the StateService can commit additional blocks to the finalized
/// state `db`. Usually, the subtrees of these blocks are consistent. But if the `chain` is a
/// different fork to `db`, then the trees can be inconsistent. In that case, we ignore all the
/// trees in `chain` after the first inconsistent tree, because we know they will be inconsistent as
/// well. (It is cryptographically impossible for tree roots to be equal once the leaves have
/// diverged.)
/// 2. APIs that return single subtrees can't be used here, because they can create
/// an inconsistent list of subtrees after concurrent non-finalized and finalized updates.
pub fn sapling_subtrees<C>(
chain: Option<C>,
@ -65,15 +72,6 @@ pub fn sapling_subtrees<C>(
where
C: AsRef<Chain>,
{
// # Correctness
//
// After `chain` was cloned, the StateService can commit additional blocks to the finalized
// state `db`. Usually, the subtrees of these blocks are consistent. But if the `chain` is
// a different fork to `db`, then the trees can be inconsistent.
//
// In that case, we ignore all the trees in `chain` after the first inconsistent tree,
// because we know they will be inconsistent as well. (It is cryptographically impossible
// for tree roots to be equal once the leaves have diverged.)
let mut db_list = db.sapling_subtree_list_by_index_for_rpc(start_index, limit);
// If there's no chain, then we have the complete list.
@ -137,13 +135,20 @@ where
}
/// Returns a list of Orchard [`NoteCommitmentSubtree`]s starting at `start_index`.
/// If `limit` is provided, the list is limited to `limit` entries.
///
/// If there is no subtree at `start_index` in the non-finalized `chain` or finalized `db`,
/// the returned list is empty. Otherwise, subtrees are continuous and consistent up to the tip.
/// If `limit` is provided, the list is limited to `limit` entries. If there is no subtree at
/// `start_index` in the non-finalized `chain` or finalized `db`, the returned list is empty.
///
/// There is no API for retrieving single subtrees, because it can accidentally be used to create
/// an inconsistent list of subtrees.
/// # Correctness
///
/// 1. After `chain` was cloned, the StateService can commit additional blocks to the finalized
/// state `db`. Usually, the subtrees of these blocks are consistent. But if the `chain` is a
/// different fork to `db`, then the trees can be inconsistent. In that case, we ignore all the
/// trees in `chain` after the first inconsistent tree, because we know they will be inconsistent as
/// well. (It is cryptographically impossible for tree roots to be equal once the leaves have
/// diverged.)
/// 2. APIs that return single subtrees can't be used here, because they can create
/// an inconsistent list of subtrees after concurrent non-finalized and finalized updates.
pub fn orchard_subtrees<C>(
chain: Option<C>,
db: &ZebraDb,
@ -153,15 +158,6 @@ pub fn orchard_subtrees<C>(
where
C: AsRef<Chain>,
{
// # Correctness
//
// After `chain` was cloned, the StateService can commit additional blocks to the finalized
// state `db`. Usually, the subtrees of these blocks are consistent. But if the `chain` is
// a different fork to `db`, then the trees can be inconsistent.
//
// In that case, we ignore all the trees in `chain` after the first inconsistent tree,
// because we know they will be inconsistent as well. (It is cryptographically impossible
// for tree roots to be equal once the leaves have diverged.)
let mut db_list = db.orchard_subtree_list_by_index_for_rpc(start_index, limit);
// If there's no chain, then we have the complete list.