Migrations & data storage for pre-DAG-sync

zcash_client_backend/CHANGELOG.md

@@ -11,14 +11,16 @@ and this library adheres to Rust's notion of
 - `impl Eq for zcash_client_backend::zip321::{Payment, TransactionRequest}`
 - `impl Debug` for `zcash_client_backend::{data_api::wallet::input_selection::Proposal, wallet::ReceivedSaplingNote}`
 - `zcash_client_backend::data_api`:
-  - `WalletRead::{fully_scanned_height, suggest_scan_ranges}`
+  - `WalletRead::{block_metadata, block_fully_scanned, suggest_scan_ranges}`
   - `WalletWrite::put_block`
   - `WalletCommitmentTrees`
   - `testing::MockWalletDb::new`
   - `NullifierQuery` for use with `WalletRead::get_sapling_nullifiers`
+  - `BlockMetadata`
+  - `ScannedBlock`
   - `wallet::input_sellection::Proposal::{min_target_height, min_anchor_height}`:
 - `zcash_client_backend::wallet::WalletSaplingOutput::note_commitment_tree_position`
-- `zcash_client_backend::welding_rig::SyncError`
+- `zcash_client_backend::welding_rig::ScanError`
 
 ### Changed
 - MSRV is now 1.65.0.
@@ -56,27 +58,28 @@ and this library adheres to Rust's notion of
 - `zcash_client_backend::welding_rig::ScanningKey::sapling_nf` has been changed to
   take a note position instead of an incremental witness for the note.
 - Arguments to `zcash_client_backend::welding_rig::scan_block` have changed. This
-  method now takes an optional `CommitmentTreeMeta` argument instead of a base commitment
-  tree and incremental witnesses for each previously-known note.
+  method now takes an optional `BlockMetadata` argument instead of a base commitment
+  tree and incremental witnesses for each previously-known note. In addition, the
+  return type has now been updated to return a `Result<ScannedBlock, ScanError>` 
+  in the case of scan failure.
 
 
 ### Removed
 - `zcash_client_backend::data_api`:
   - `WalletRead::get_all_nullifiers`
-  - `WalletRead::{get_commitment_tree, get_witnesses}` (use
-    `WalletRead::fully_scanned_height` instead).
+  - `WalletRead::{get_commitment_tree, get_witnesses}` have been removed 
+    without replacement. The utility of these methods is now subsumed
+    by those available from the `WalletCommitmentTrees` trait.
   - `WalletWrite::advance_by_block` (use `WalletWrite::put_block` instead).
-  - The `commitment_tree` and `transactions` properties of the `PrunedBlock`
-    struct are now owned values instead of references, making this a fully owned type.
-    It is now parameterized by the nullifier type instead of by a lifetime for the 
-    fields that were previously references. In addition, two new properties,
-    `sapling_commitment_tree_size` and `sapling_commitments` have been added.
+  - `PrunedBlock` has been replaced by `ScannedBlock`
   - `testing::MockWalletDb`, which is available under the `test-dependencies`
     feature flag, has been modified by the addition of a `sapling_tree` property. 
   - `wallet::input_selection`:
     - `Proposal::target_height` (use `Proposal::min_target_height` instead).
 - `zcash_client_backend::data_api::chain::validate_chain` TODO: document how
   to handle validation given out-of-order blocks.
+- `zcash_client_backend::data_api::chain::error::{ChainError, Cause}` have been 
+  replaced by `zcash_client_backend::welding_rig::ScanError`
 - `zcash_client_backend::wallet::WalletSaplingOutput::{witness, witness_mut}`
   have been removed as individual incremental witnesses are no longer tracked on a
   per-note basis. The global note commitment tree for the wallet should be used

zcash_client_backend/src/data_api.rs

@@ -66,15 +66,17 @@ pub trait WalletRead {
     /// This will return `Ok(None)` if no block data is present in the database.
     fn block_height_extrema(&self) -> Result<Option<(BlockHeight, BlockHeight)>, Self::Error>;
 
-    /// Returns the height to which the wallet has been fully scanned.
+    /// Returns the available block metadata for the block at the specified height, if any.
+    fn block_metadata(&self, height: BlockHeight) -> Result<Option<BlockMetadata>, Self::Error>;
+
+    /// Returns the metadata for the block at the height to which the wallet has been fully
+    /// scanned.
     ///
     /// This is the height for which the wallet has fully trial-decrypted this and all preceding
     /// blocks above the wallet's birthday height. Along with this height, this method returns
     /// metadata describing the state of the wallet's note commitment trees as of the end of that
     /// block.
-    fn fully_scanned_height(
-        &self,
-    ) -> Result<Option<(BlockHeight, chain::CommitmentTreeMeta)>, Self::Error>;
+    fn block_fully_scanned(&self) -> Result<Option<BlockMetadata>, Self::Error>;
 
     /// Returns a vector of suggested scan ranges based upon the current wallet state.
     ///
@@ -248,17 +250,99 @@ pub trait WalletRead {
     ) -> Result<HashMap<TransparentAddress, Amount>, Self::Error>;
 }
 
+/// Metadata describing the sizes of the zcash note commitment trees as of a particular block.
+#[derive(Debug, Clone, Copy)]
+pub struct BlockMetadata {
+    block_height: BlockHeight,
+    block_hash: BlockHash,
+    sapling_tree_size: u32,
+    //TODO: orchard_tree_size: u32
+}
+
+impl BlockMetadata {
+    /// Constructs a new [`BlockMetadata`] value from its constituent parts.
+    pub fn from_parts(
+        block_height: BlockHeight,
+        block_hash: BlockHash,
+        sapling_tree_size: u32,
+    ) -> Self {
+        Self {
+            block_height,
+            block_hash,
+            sapling_tree_size,
+        }
+    }
+
+    /// Returns the block height.
+    pub fn block_height(&self) -> BlockHeight {
+        self.block_height
+    }
+
+    /// Returns the hash of the block
+    pub fn block_hash(&self) -> BlockHash {
+        self.block_hash
+    }
+
+    /// Returns the size of the Sapling note commitment tree as of the block that this
+    /// [`BlockMetadata`] describes.
+    pub fn sapling_tree_size(&self) -> u32 {
+        self.sapling_tree_size
+    }
+}
+
 /// The subset of information that is relevant to this wallet that has been
 /// decrypted and extracted from a [`CompactBlock`].
 ///
 /// [`CompactBlock`]: crate::proto::compact_formats::CompactBlock
-pub struct PrunedBlock<Nf> {
-    pub block_height: BlockHeight,
-    pub block_hash: BlockHash,
-    pub block_time: u32,
-    pub transactions: Vec<WalletTx<Nf>>,
-    pub sapling_commitment_tree_size: Option<u32>,
-    pub sapling_commitments: Vec<(sapling::Node, Retention<BlockHeight>)>,
+pub struct ScannedBlock<Nf> {
+    metadata: BlockMetadata,
+    block_time: u32,
+    transactions: Vec<WalletTx<Nf>>,
+    sapling_commitments: Vec<(sapling::Node, Retention<BlockHeight>)>,
+}
+
+impl<Nf> ScannedBlock<Nf> {
+    pub fn from_parts(
+        metadata: BlockMetadata,
+        block_time: u32,
+        transactions: Vec<WalletTx<Nf>>,
+        sapling_commitments: Vec<(sapling::Node, Retention<BlockHeight>)>,
+    ) -> Self {
+        Self {
+            metadata,
+            block_time,
+            transactions,
+            sapling_commitments,
+        }
+    }
+
+    pub fn height(&self) -> BlockHeight {
+        self.metadata.block_height
+    }
+
+    pub fn block_hash(&self) -> BlockHash {
+        self.metadata.block_hash
+    }
+
+    pub fn block_time(&self) -> u32 {
+        self.block_time
+    }
+
+    pub fn metadata(&self) -> &BlockMetadata {
+        &self.metadata
+    }
+
+    pub fn transactions(&self) -> &[WalletTx<Nf>] {
+        &self.transactions
+    }
+
+    pub fn sapling_commitments(&self) -> &[(sapling::Node, Retention<BlockHeight>)] {
+        &self.sapling_commitments
+    }
+
+    pub fn take_sapling_commitments(self) -> Vec<(sapling::Node, Retention<BlockHeight>)> {
+        self.sapling_commitments
+    }
 }
 
 /// A transaction that was detected during scanning of the blockchain,
@@ -404,7 +488,7 @@ pub trait WalletWrite: WalletRead {
     #[allow(clippy::type_complexity)]
     fn put_block(
         &mut self,
-        block: PrunedBlock<sapling::Nullifier>,
+        block: ScannedBlock<sapling::Nullifier>,
     ) -> Result<Vec<Self::NoteRef>, Self::Error>;
 
     /// Caches a decrypted transaction in the persistent wallet store.
@@ -489,7 +573,7 @@ pub mod testing {
     };
 
     use super::{
-        chain, DecryptedTransaction, NullifierQuery, PrunedBlock, SentTransaction,
+        BlockMetadata, DecryptedTransaction, NullifierQuery, ScannedBlock, SentTransaction,
         WalletCommitmentTrees, WalletRead, WalletWrite, SAPLING_SHARD_HEIGHT,
     };
 
@@ -520,9 +604,14 @@ pub mod testing {
             Ok(None)
         }
 
-        fn fully_scanned_height(
+        fn block_metadata(
             &self,
-        ) -> Result<Option<(BlockHeight, chain::CommitmentTreeMeta)>, Self::Error> {
+            _height: BlockHeight,
+        ) -> Result<Option<BlockMetadata>, Self::Error> {
+            Ok(None)
+        }
+
+        fn block_fully_scanned(&self) -> Result<Option<BlockMetadata>, Self::Error> {
             Ok(None)
         }
 
@@ -667,7 +756,7 @@ pub mod testing {
         #[allow(clippy::type_complexity)]
         fn put_block(
             &mut self,
-            _block: PrunedBlock<sapling::Nullifier>,
+            _block: ScannedBlock<sapling::Nullifier>,
         ) -> Result<Vec<Self::NoteRef>, Self::Error> {
             Ok(vec![])
         }