zcash_client_backend: Implement async wallet synchronization function

This implements the necessary state machine for taking a wallet in some
arbitrary synchronization status, and fully scanning (the remainder of)
the chain.

Closes #1169.

zcash_client_backend/CHANGELOG.md

@@ -7,6 +7,13 @@ and this library adheres to Rust's notion of
 
 ## [Unreleased]
 
+### Added
+- `zcash_client_backend::data_api`:
+  - `chain::BlockCache` trait, behind the `sync` feature flag.
+- `zcash_client_backend::scanning`:
+  - `testing` module
+- `zcash_client_backend::sync` module, behind the `sync` feature flag.
+
 ## [0.12.1] - 2024-03-27
 
 ### Fixed
@@ -39,7 +46,6 @@ and this library adheres to Rust's notion of
   - `WalletSummary::next_orchard_subtree_index`
   - `chain::ChainState`
   - `chain::ScanSummary::{spent_orchard_note_count, received_orchard_note_count}`
-  - `chain::BlockCache` trait
   - `impl Debug for chain::CommitmentTreeRoot`
 - `zcash_client_backend::fees`:
   - `orchard`
@@ -55,7 +61,6 @@ and this library adheres to Rust's notion of
   - `Nullifiers::{orchard, extend_orchard, retain_orchard}`
   - `TaggedOrchardBatch`
   - `TaggedOrchardBatchRunner`
-  - `testing` module
 - `zcash_client_backend::wallet`:
   - `Note::Orchard`
   - `WalletOrchardSpend`

zcash_client_backend/Cargo.toml

@@ -66,7 +66,7 @@ tracing.workspace = true
 # - Protobuf interfaces and gRPC bindings
 hex.workspace = true
 prost.workspace = true
-tonic = { workspace = true, optional = true, features = ["prost", "codegen"]}
+tonic = { workspace = true, optional = true, features = ["prost", "codegen"] }
 
 # - Secret management
 secrecy.workspace = true
@@ -78,6 +78,11 @@ group.workspace = true
 orchard = { workspace = true, optional = true }
 sapling.workspace = true
 
+# - Sync engine
+anyhow = { version = "1", optional = true }
+async-trait = { version = "0.1", optional = true }
+futures-util = { version = "0.3", optional = true }
+
 # - Note commitment trees
 incrementalmerkletree.workspace = true
 shardtree.workspace = true
@@ -89,9 +94,6 @@ jubjub = { workspace = true, optional = true }
 # - ZIP 321
 nom = "7"
 
-# - Asychronous
-async-trait = "0.1.78"
-
 # Dependencies used internally:
 # (Breaking upgrades to these are usually backwards-compatible, but check MSRVs.)
 # - Documentation
@@ -106,7 +108,7 @@ crossbeam-channel.workspace = true
 rayon.workspace = true
 
 [build-dependencies]
-tonic-build = { workspace = true, features = ["prost"]}
+tonic-build = { workspace = true, features = ["prost"] }
 which = "4"
 
 [dev-dependencies]
@@ -141,6 +143,14 @@ transparent-inputs = [
 ## Enables receiving and spending Orchard funds.
 orchard = ["dep:orchard", "zcash_keys/orchard"]
 
+## Exposes a wallet synchronization function that implements the necessary state machine.
+sync = [
+    "lightwalletd-tonic",
+    "dep:anyhow",
+    "dep:async-trait",
+    "dep:futures-util",
+]
+
 ## Exposes APIs that are useful for testing, such as `proptest` strategies.
 test-dependencies = [
     "dep:proptest",

zcash_client_backend/src/data_api/chain.rs

@@ -373,6 +373,7 @@ pub trait BlockSource {
 ///    assert_eq!(block_cache.cached_blocks.lock().unwrap().len(), 0);
 ///    assert_eq!(block_cache.get_tip_height(None).unwrap(), None);
 /// ```
+#[cfg(feature = "sync")]
 #[async_trait]
 pub trait BlockCache: BlockSource + Send + Sync
 where
@@ -404,7 +405,7 @@ where
     /// Removes all cached blocks above a specified block height.
     async fn truncate(&self, block_height: BlockHeight) -> Result<(), Self::Error> {
         if let Some(latest) = self.get_tip_height(None)? {
-            self.delete(&ScanRange::from_parts(
+            self.delete(ScanRange::from_parts(
                 Range {
                     start: block_height.add(1),
                     end: latest.add(1),
@@ -421,7 +422,7 @@ where
     /// # Errors
     ///
     /// In the case of an error, some blocks requested for deletion may remain in the block cache.
-    async fn delete(&self, range: &ScanRange) -> Result<(), Self::Error>;
+    async fn delete<'a>(&self, range: ScanRange) -> Result<(), Self::Error>;
 }
 
 /// Metadata about modifications to the wallet state made in the course of scanning a set of

zcash_client_backend/src/lib.rs

@@ -74,6 +74,9 @@ pub mod scanning;
 pub mod wallet;
 pub mod zip321;
 
+#[cfg(feature = "sync")]
+pub mod sync;
+
 #[cfg(feature = "unstable-serialization")]
 pub mod serialization;