zcash_client_backend: Implement async wallet synchronization function

.github/actions/prepare/action.yml

@@ -28,6 +28,7 @@ runs:
         bundled-prover
         download-params
         lightwalletd-tonic
+        sync
         temporary-zcashd
         transparent-inputs
         unstable

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,10 @@ group.workspace = true
 orchard = { workspace = true, optional = true }
 sapling.workspace = true
 
+# - Sync engine
+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 +93,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 +107,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 +142,13 @@ 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: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

@@ -151,9 +151,8 @@
 //! # }
 //! ```
 
-use std::ops::{Add, Range};
+use std::ops::Range;
 
-use async_trait::async_trait;
 use incrementalmerkletree::frontier::Frontier;
 use subtle::ConditionallySelectable;
 use zcash_primitives::{
@@ -162,15 +161,20 @@
 };
 
 use crate::{
-    data_api::{scanning::ScanRange, NullifierQuery, WalletWrite},
+    data_api::{NullifierQuery, WalletWrite},
     proto::compact_formats::CompactBlock,
     scanning::{scan_block_with_runners, BatchRunners, Nullifiers, ScanningKeys},
 };
 
+#[cfg(feature = "sync")]
+use {
+    super::scanning::ScanPriority, crate::data_api::scanning::ScanRange, async_trait::async_trait,
+};
+
 pub mod error;
 use error::Error;
 
-use super::{scanning::ScanPriority, WalletRead};
+use super::WalletRead;
 
 /// A struct containing metadata about a subtree root of the note commitment tree.
 ///
@@ -300,7 +304,7 @@
 ///            Ok(())
 ///        }
 ///
-///        async fn delete(&self, range: &ScanRange) -> Result<(), Self::Error> {
+///        async fn delete(&self, range: ScanRange) -> Result<(), Self::Error> {
 ///            self.cached_blocks
 ///                .lock()
 ///                .unwrap()
@@ -368,11 +372,12 @@
 ///
 ///    // Delete blocks from the block cache
 ///    rt.block_on(async {
-///        block_cache.delete(&range).await.unwrap();
+///        block_cache.delete(range).await.unwrap();
 ///    });
 ///    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,10 +409,10 @@
     /// 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),
+                    start: block_height + 1,
+                    end: latest + 1,
                 },
                 ScanPriority::Ignored,
             ))
@@ -421,7 +426,7 @@
     /// # 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(&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;