APIs for mobile SDKs

zcash_client_backend/CHANGELOG.md

@@ -24,12 +24,14 @@ and this library adheres to Rust's notion of
   - `ORCHARD_SHARD_HEIGHT`
   - `BlockMetadata::orchard_tree_size`
   - `WalletSummary::next_orchard_subtree_index`
+  - `chain::ChainState`
   - `chain::ScanSummary::{spent_orchard_note_count, received_orchard_note_count}`
 - `zcash_client_backend::fees`:
   - `orchard`
   - `ChangeValue::orchard`
 - `zcash_client_backend::proto`:
   - `service::TreeState::orchard_tree`
+  - `service::TreeState::to_chain_state`
   - `impl TryFrom<&CompactOrchardAction> for CompactAction`
   - `CompactOrchardAction::{cmx, nf, ephemeral_key}`
 - `zcash_client_backend::scanning`:

zcash_client_backend/src/data_api.rs

@@ -543,6 +543,17 @@
     /// The concrete account type used by this wallet backend.
     type Account: Account<Self::AccountId>;
 
+    /// Returns a vector with the IDs of all accounts known to this wallet.
+    fn get_account_ids(&self) -> Result<Vec<Self::AccountId>, Self::Error>;
+
+    /// Returns the account corresponding to a given [`HdSeedFingerprint`] and
+    /// [`zip32::AccountId`], if any.
+    fn get_seed_account(
+        &self,
+        seed: &HdSeedFingerprint,
+        account_id: zip32::AccountId,
+    ) -> Result<Option<Self::Account>, Self::Error>;
+
     /// Verifies that the given seed corresponds to the viewing key for the specified account.
     ///
     /// Returns:
@@ -558,12 +569,50 @@
         seed: &SecretVec<u8>,
     ) -> Result<bool, Self::Error>;
 
+    /// Returns the account corresponding to a given [`UnifiedFullViewingKey`], if any.
+    fn get_account_for_ufvk(
+        &self,
+        ufvk: &UnifiedFullViewingKey,
+    ) -> Result<Option<Self::Account>, Self::Error>;
+
+    /// Returns the most recently generated unified address for the specified account, if the
+    /// account identifier specified refers to a valid account for this wallet.
+    ///
+    /// This will return `Ok(None)` if the account identifier does not correspond to a known
+    /// account.
+    fn get_current_address(
+        &self,
+        account: Self::AccountId,
+    ) -> Result<Option<UnifiedAddress>, Self::Error>;
+
+    /// Returns the birthday height for the given account, or an error if the account is not known
+    /// to the wallet.
+    fn get_account_birthday(&self, account: Self::AccountId) -> Result<BlockHeight, Self::Error>;
+
+    /// Returns the birthday height for the wallet.
+    ///
+    /// This returns the earliest birthday height among accounts maintained by this wallet,
+    /// or `Ok(None)` if the wallet has no initialized accounts.
+    fn get_wallet_birthday(&self) -> Result<Option<BlockHeight>, Self::Error>;
+
+    /// Returns the wallet balances and sync status for an account given the specified minimum
+    /// number of confirmations, or `Ok(None)` if the wallet has no balance data available.
+    fn get_wallet_summary(
+        &self,
+        min_confirmations: u32,
+    ) -> Result<Option<WalletSummary<Self::AccountId>>, Self::Error>;
+
     /// Returns the height of the chain as known to the wallet as of the most recent call to
     /// [`WalletWrite::update_chain_tip`].
     ///
     /// This will return `Ok(None)` if the height of the current consensus chain tip is unknown.
     fn chain_height(&self) -> Result<Option<BlockHeight>, Self::Error>;
 
+    /// Returns the block hash for the block at the given height, if the
+    /// associated block data is available. Returns `Ok(None)` if the hash
+    /// is not found in the database.
+    fn get_block_hash(&self, block_height: BlockHeight) -> Result<Option<BlockHash>, Self::Error>;
+
     /// 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>;
 
@@ -576,6 +625,11 @@
     /// block.
     fn block_fully_scanned(&self) -> Result<Option<BlockMetadata>, Self::Error>;
 
+    /// Returns the block height and hash for the block at the maximum scanned block height.
+    ///
+    /// This will return `Ok(None)` if no blocks have been scanned.
+    fn get_max_height_hash(&self) -> Result<Option<(BlockHeight, BlockHash)>, Self::Error>;
+
     /// Returns block metadata for the maximum height that the wallet has scanned.
     ///
     /// If the wallet is fully synced, this will be equivalent to `block_fully_scanned`;
@@ -614,66 +668,15 @@
     /// Returns the minimum block height corresponding to an unspent note in the wallet.
     fn get_min_unspent_height(&self) -> Result<Option<BlockHeight>, Self::Error>;
 
-    /// Returns the block hash for the block at the given height, if the
-    /// associated block data is available. Returns `Ok(None)` if the hash
-    /// is not found in the database.
-    fn get_block_hash(&self, block_height: BlockHeight) -> Result<Option<BlockHash>, Self::Error>;
-
-    /// Returns the block height and hash for the block at the maximum scanned block height.
-    ///
-    /// This will return `Ok(None)` if no blocks have been scanned.
-    fn get_max_height_hash(&self) -> Result<Option<(BlockHeight, BlockHash)>, Self::Error>;
-
     /// Returns the block height in which the specified transaction was mined, or `Ok(None)` if the
     /// transaction is not in the main chain.
     fn get_tx_height(&self, txid: TxId) -> Result<Option<BlockHeight>, Self::Error>;
 
-    /// Returns the birthday height for the wallet.
-    ///
-    /// This returns the earliest birthday height among accounts maintained by this wallet,
-    /// or `Ok(None)` if the wallet has no initialized accounts.
-    fn get_wallet_birthday(&self) -> Result<Option<BlockHeight>, Self::Error>;
-
-    /// Returns the birthday height for the given account, or an error if the account is not known
-    /// to the wallet.
-    fn get_account_birthday(&self, account: Self::AccountId) -> Result<BlockHeight, Self::Error>;
-
-    /// Returns the most recently generated unified address for the specified account, if the
-    /// account identifier specified refers to a valid account for this wallet.
-    ///
-    /// This will return `Ok(None)` if the account identifier does not correspond to a known
-    /// account.
-    fn get_current_address(
-        &self,
-        account: Self::AccountId,
-    ) -> Result<Option<UnifiedAddress>, Self::Error>;
-
     /// Returns all unified full viewing keys known to this wallet.
     fn get_unified_full_viewing_keys(
         &self,
     ) -> Result<HashMap<Self::AccountId, UnifiedFullViewingKey>, Self::Error>;
 
-    /// Returns the account corresponding to a given [`UnifiedFullViewingKey`], if any.
-    fn get_account_for_ufvk(
-        &self,
-        ufvk: &UnifiedFullViewingKey,
-    ) -> Result<Option<Self::Account>, Self::Error>;
-
-    /// Returns the account corresponding to a given [`HdSeedFingerprint`] and
-    /// [`zip32::AccountId`], if any.
-    fn get_seed_account(
-        &self,
-        seed: &HdSeedFingerprint,
-        account_id: zip32::AccountId,
-    ) -> Result<Option<Self::Account>, Self::Error>;
-
-    /// Returns the wallet balances and sync status for an account given the specified minimum
-    /// number of confirmations, or `Ok(None)` if the wallet has no balance data available.
-    fn get_wallet_summary(
-        &self,
-        min_confirmations: u32,
-    ) -> Result<Option<WalletSummary<Self::AccountId>>, Self::Error>;
-
     /// Returns the memo for a note.
     ///
     /// Returns `Ok(None)` if the note is known to the wallet but memo data has not yet been
@@ -724,9 +727,6 @@
     ) -> Result<HashMap<TransparentAddress, NonNegativeAmount>, Self::Error> {
         Ok(HashMap::new())
     }
-
-    /// Returns a vector with the IDs of all accounts known to this wallet.
-    fn get_account_ids(&self) -> Result<Vec<Self::AccountId>, Self::Error>;
 }
 
 /// Metadata describing the sizes of the zcash note commitment trees as of a particular block.
@@ -1299,6 +1299,15 @@
         request: UnifiedAddressRequest,
     ) -> Result<Option<UnifiedAddress>, Self::Error>;
 
+    /// Updates the wallet's view of the blockchain.
+    ///
+    /// This method is used to provide the wallet with information about the state of the
+    /// blockchain, and detect any previously scanned data that needs to be re-validated
+    /// before proceeding with scanning. It should be called at wallet startup prior to calling
+    /// [`WalletRead::suggest_scan_ranges`] in order to provide the wallet with the information it
+    /// needs to correctly prioritize scanning operations.
+    fn update_chain_tip(&mut self, tip_height: BlockHeight) -> Result<(), Self::Error>;
+
     /// Updates the state of the wallet database by persisting the provided block information,
     /// along with the note commitments that were detected when scanning the block for transactions
     /// pertaining to this wallet.
@@ -1313,14 +1322,11 @@
         blocks: Vec<ScannedBlock<Self::AccountId>>,
     ) -> Result<(), Self::Error>;
 
-    /// Updates the wallet's view of the blockchain.
-    ///
-    /// This method is used to provide the wallet with information about the state of the
-    /// blockchain, and detect any previously scanned data that needs to be re-validated
-    /// before proceeding with scanning. It should be called at wallet startup prior to calling
-    /// [`WalletRead::suggest_scan_ranges`] in order to provide the wallet with the information it
-    /// needs to correctly prioritize scanning operations.
-    fn update_chain_tip(&mut self, tip_height: BlockHeight) -> Result<(), Self::Error>;
+    /// Adds a transparent UTXO received by the wallet to the data store.
+    fn put_received_transparent_utxo(
+        &mut self,
+        output: &WalletTransparentOutput,
+    ) -> Result<Self::UtxoRef, Self::Error>;
 
     /// Caches a decrypted transaction in the persistent wallet store.
     fn store_decrypted_tx(
@@ -1349,12 +1355,6 @@
     ///
     /// There may be restrictions on heights to which it is possible to truncate.
     fn truncate_to_height(&mut self, block_height: BlockHeight) -> Result<(), Self::Error>;
-
-    /// Adds a transparent UTXO received by the wallet to the data store.
-    fn put_received_transparent_utxo(
-        &mut self,
-        output: &WalletTransparentOutput,
-    ) -> Result<Self::UtxoRef, Self::Error>;
 }
 
 /// This trait describes a capability for manipulating wallet note commitment trees.
@@ -1521,6 +1521,18 @@
         type AccountId = u32;
         type Account = (Self::AccountId, UnifiedFullViewingKey);
 
+        fn get_account_ids(&self) -> Result<Vec<Self::AccountId>, Self::Error> {
+            Ok(Vec::new())
+        }
+
+        fn get_seed_account(
+            &self,
+            _seed: &HdSeedFingerprint,
+            _account_id: zip32::AccountId,
+        ) -> Result<Option<Self::Account>, Self::Error> {
+            Ok(None)
+        }
+
         fn validate_seed(
             &self,
             _account_id: Self::AccountId,
@@ -1529,37 +1541,39 @@
             Ok(false)
         }
 
-        fn chain_height(&self) -> Result<Option<BlockHeight>, Self::Error> {
+        fn get_account_for_ufvk(
+            &self,
+            _ufvk: &UnifiedFullViewingKey,
+        ) -> Result<Option<Self::Account>, Self::Error> {
             Ok(None)
         }
 
-        fn block_metadata(
+        fn get_current_address(
             &self,
-            _height: BlockHeight,
-        ) -> Result<Option<BlockMetadata>, Self::Error> {
+            _account: Self::AccountId,
+        ) -> Result<Option<UnifiedAddress>, Self::Error> {
             Ok(None)
         }
 
-        fn block_fully_scanned(&self) -> Result<Option<BlockMetadata>, Self::Error> {
-            Ok(None)
+        fn get_account_birthday(
+            &self,
+            _account: Self::AccountId,
+        ) -> Result<BlockHeight, Self::Error> {
+            Err(())
         }
 
-        fn block_max_scanned(&self) -> Result<Option<BlockMetadata>, Self::Error> {
+        fn get_wallet_birthday(&self) -> Result<Option<BlockHeight>, Self::Error> {
             Ok(None)
         }
 
-        fn suggest_scan_ranges(&self) -> Result<Vec<ScanRange>, Self::Error> {
-            Ok(vec![])
-        }
-
-        fn get_target_and_anchor_heights(
+        fn get_wallet_summary(
             &self,
-            _min_confirmations: NonZeroU32,
-        ) -> Result<Option<(BlockHeight, BlockHeight)>, Self::Error> {
+            _min_confirmations: u32,
+        ) -> Result<Option<WalletSummary<Self::AccountId>>, Self::Error> {
             Ok(None)
         }
 
-        fn get_min_unspent_height(&self) -> Result<Option<BlockHeight>, Self::Error> {
+        fn chain_height(&self) -> Result<Option<BlockHeight>, Self::Error> {
             Ok(None)
         }
 
@@ -1570,58 +1584,48 @@
             Ok(None)
         }
 
-        fn get_max_height_hash(&self) -> Result<Option<(BlockHeight, BlockHash)>, Self::Error> {
+        fn block_metadata(
+            &self,
+            _height: BlockHeight,
+        ) -> Result<Option<BlockMetadata>, Self::Error> {
             Ok(None)
         }
 
-        fn get_tx_height(&self, _txid: TxId) -> Result<Option<BlockHeight>, Self::Error> {
+        fn block_fully_scanned(&self) -> Result<Option<BlockMetadata>, Self::Error> {
             Ok(None)
         }
 
-        fn get_wallet_birthday(&self) -> Result<Option<BlockHeight>, Self::Error> {
+        fn get_max_height_hash(&self) -> Result<Option<(BlockHeight, BlockHash)>, Self::Error> {
             Ok(None)
         }
 
-        fn get_account_birthday(
-            &self,
-            _account: Self::AccountId,
-        ) -> Result<BlockHeight, Self::Error> {
-            Err(())
+        fn block_max_scanned(&self) -> Result<Option<BlockMetadata>, Self::Error> {
+            Ok(None)
         }
 
-        fn get_current_address(
-            &self,
-            _account: Self::AccountId,
-        ) -> Result<Option<UnifiedAddress>, Self::Error> {
-            Ok(None)
+        fn suggest_scan_ranges(&self) -> Result<Vec<ScanRange>, Self::Error> {
+            Ok(vec![])
         }
 
-        fn get_unified_full_viewing_keys(
+        fn get_target_and_anchor_heights(
             &self,
-        ) -> Result<HashMap<Self::AccountId, UnifiedFullViewingKey>, Self::Error> {
-            Ok(HashMap::new())
+            _min_confirmations: NonZeroU32,
+        ) -> Result<Option<(BlockHeight, BlockHeight)>, Self::Error> {
+            Ok(None)
         }
 
-        fn get_account_for_ufvk(
-            &self,
-            _ufvk: &UnifiedFullViewingKey,
-        ) -> Result<Option<Self::Account>, Self::Error> {
+        fn get_min_unspent_height(&self) -> Result<Option<BlockHeight>, Self::Error> {
             Ok(None)
         }
 
-        fn get_seed_account(
-            &self,
-            _seed: &HdSeedFingerprint,
-            _account_id: zip32::AccountId,
-        ) -> Result<Option<Self::Account>, Self::Error> {
+        fn get_tx_height(&self, _txid: TxId) -> Result<Option<BlockHeight>, Self::Error> {
             Ok(None)
         }
 
-        fn get_wallet_summary(
+        fn get_unified_full_viewing_keys(
             &self,
-            _min_confirmations: u32,
-        ) -> Result<Option<WalletSummary<Self::AccountId>>, Self::Error> {
-            Ok(None)
+        ) -> Result<HashMap<Self::AccountId, UnifiedFullViewingKey>, Self::Error> {
+            Ok(HashMap::new())
         }
 
         fn get_memo(&self, _id_note: NoteId) -> Result<Option<Memo>, Self::Error> {
@@ -1664,10 +1668,6 @@
         ) -> Result<HashMap<TransparentAddress, NonNegativeAmount>, Self::Error> {
             Ok(HashMap::new())
         }
-
-        fn get_account_ids(&self) -> Result<Vec<Self::AccountId>, Self::Error> {
-            Ok(Vec::new())
-        }
     }
 
     impl WalletWrite for MockWalletDb {