react-native-zcash 0.4.2 → 0.6.0

package/ios/ZCashLightClientKit/Rust/ZcashRustBackendWelding.swift

@@ -35,9 +35,11 @@ protocol ZcashRustBackendWelding {
     /// have been received by the currently-available account (in order to enable
     /// automated account recovery).
     /// - parameter seed: byte array of the zip32 seed
+    /// - parameter treeState: The TreeState Protobuf object for the height prior to the account birthday
+    /// - parameter recoverUntil: the fully-scanned height up to which the account will be treated as "being recovered"
     /// - Returns: The `UnifiedSpendingKey` structs for the number of accounts created
     /// - Throws: `rustCreateAccount`.
-    func createAccount(seed: [UInt8]) async throws -> UnifiedSpendingKey
+    func createAccount(seed: [UInt8], treeState: TreeState, recoverUntil: UInt32?) async throws -> UnifiedSpendingKey
 
     /// Creates a transaction to the given address from the given account
     /// - Parameter usk: `UnifiedSpendingKey` for the account that controls the funds to be spent.
@@ -50,7 +52,7 @@ protocol ZcashRustBackendWelding {
         to address: String,
         value: Int64,
         memo: MemoBytes?
-    ) async throws -> Int64
+    ) async throws -> Data
 
     /// Scans a transaction for any information that can be decrypted by the accounts in the wallet, and saves it to the wallet.
     /// - parameter tx:     the transaction to decrypt
@@ -89,14 +91,10 @@ protocol ZcashRustBackendWelding {
     ///     - `rustGetNextAvailableAddressInvalidAddress` if generated unified address isn't valid.
     func getNextAvailableAddress(account: Int32) async throws -> UnifiedAddress
 
-    /// Get received memo from note.
-    /// - parameter idNote: note_id of note where the memo is located
-    func getReceivedMemo(idNote: Int64) async -> Memo?
-
-    /// Get sent memo from note.
-    /// - parameter idNote: note_id of note where the memo is located
-    /// - Returns: a `Memo` if any
-    func getSentMemo(idNote: Int64) async -> Memo?
+    /// Get memo from note.
+    /// - parameter txId: ID of transaction containing the note
+    /// - parameter outputIndex: output index of note
+    func getMemo(txId: Data, outputIndex: UInt16) async throws -> Memo?
 
     /// Get the verified cached transparent balance for the given address
     /// - parameter account; the account index to query
@@ -105,14 +103,6 @@ protocol ZcashRustBackendWelding {
     ///     - `rustGetTransparentBalance` if rust layer returns error.
     func getTransparentBalance(account: Int32) async throws -> Int64
 
-    /// Initialize the accounts table from a set of unified full viewing keys.
-    /// - Note: this function should only be used when restoring an existing seed phrase. when creating a new wallet, use `createAccount()` instead.
-    /// - Parameter ufvks: an array of UnifiedFullViewingKeys
-    /// - Throws:
-    ///     - `rustInitAccountsTableViewingKeyCotainsNullBytes` if any of the key in `ufvks` contains null bytes before end.
-    ///     - `rustInitAccountsTableViewingKeyIsInvalid` if any of the key in `ufvks` isn't valid.
-    func initAccountsTable(ufvks: [UnifiedFullViewingKey]) async throws
-
     /// Initializes the data db. This will performs any migrations needed on the sqlite file
     /// provided. Some migrations might need that callers provide the seed bytes.
     /// - Parameter seed: ZIP-32 compliant seed bytes for this wallet
@@ -122,23 +112,6 @@ protocol ZcashRustBackendWelding {
     /// Throws `rustInitDataDb` if rust layer returns error.
     func initDataDb(seed: [UInt8]?) async throws -> DbInitResult
 
-    /// Initialize the blocks table from a given checkpoint (heigh, hash, time, saplingTree and networkType).
-    /// - parameter height: represents the block height of the given checkpoint
-    /// - parameter hash: hash of the merkle tree
-    /// - parameter time: in milliseconds from reference
-    /// - parameter saplingTree: hash of the sapling tree
-    /// - Throws:
-    ///     - `rustInitBlocksTableHashContainsNullBytes` if `hash` contains null bytes before end.
-    ///     - `rustInitBlocksTableSaplingTreeContainsNullBytes` if `saplingTree` contains null bytes before end.
-    ///     - `rustInitBlocksTableDataDbNotEmpty` if data DB is not empty.
-    ///     - `rustInitBlocksTable` if rust layer returns error.
-    func initBlocksTable(
-        height: Int32,
-        hash: String,
-        time: UInt32,
-        saplingTree: String
-    ) async throws
-
     /// Returns a list of the transparent receivers for the diversified unified addresses that have
     /// been allocated for the provided account.
     /// - parameter account: index of the given account
@@ -159,26 +132,6 @@ protocol ZcashRustBackendWelding {
     ///     - `rustGetVerifiedTransparentBalance` if rust layer returns error.
     func getVerifiedTransparentBalance(account: Int32) async throws -> Int64
 
-    /// Checks that the scanned blocks in the data database, when combined with the recent
-    /// `CompactBlock`s in the cache database, form a valid chain.
-    /// This function is built on the core assumption that the information provided in the
-    /// cache database is more likely to be accurate than the previously-scanned information.
-    /// This follows from the design (and trust) assumption that the `lightwalletd` server
-    /// provides accurate block information as of the time it was requested.
-    /// - parameter fsBlockDbRoot: `URL` pointing to the filesystem root directory where the fsBlock cache is.
-    /// this directory  is expected to contain a `/blocks` sub-directory with the blocks stored in the convened filename
-    /// format `{height}-{hash}-block`. This directory has must be granted both write and read permissions.
-    /// - parameter dbData: location of the data db file
-    /// - parameter networkType: the network type
-    /// - parameter limit: a limit to validate a fixed number of blocks instead of the whole cache.
-    /// - Throws:
-    ///  - `rustValidateCombinedChainValidationFailed` if there was an error during validation unrelated to chain validity.
-    ///  - `rustValidateCombinedChainInvalidChain(upperBound)` if the combined chain is invalid. `upperBound` is the height of the highest invalid
-    ///    block(on the assumption that the highest block in the cache database is correct).
-    ///
-    /// - Important: This function does not mutate either of the databases.
-    func validateCombinedChain(limit: UInt32) async throws
-
     /// Resets the state of the database to only contain block and transaction information up to the given height. clears up all derived data as well
     /// - parameter height: height to rewind to.
     /// - Throws: `rustRewindToHeight` if rust layer returns error.
@@ -190,21 +143,62 @@ protocol ZcashRustBackendWelding {
     /// - Throws: `rustRewindCacheToHeight` if rust layer returns error.
     func rewindCacheToHeight(height: Int32) async throws
 
+    func putSaplingSubtreeRoots(startIndex: UInt64, roots: [SubtreeRoot]) async throws
+
+    /// 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 `suggestScanRanges`
+    /// in order to provide the wallet with the information it needs to correctly prioritize scanning
+    /// operations.
+    func updateChainTip(height: Int32) async throws
+
+    /// Returns 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 beginning with the wallet's birthday height.
+    func fullyScannedHeight() async throws -> BlockHeight?
+
+    /// Returns the maximum height that the wallet has scanned.
+    ///
+    /// If the wallet is fully synced, this will be equivalent to `fullyScannedHeight`;
+    /// otherwise the maximal scanned height is likely to be greater than the fully scanned
+    /// height due to the fact that out-of-order scanning can leave gaps.
+    func maxScannedHeight() async throws -> BlockHeight?
+
+    /// Returns the scan progress derived from the current wallet state.
+    func getScanProgress() async throws -> ScanProgress?
+
+    /// Returns a list of suggested scan ranges based upon the current wallet state.
+    ///
+    /// This method should only be used in cases where the `CompactBlock` data that will be
+    /// made available to `scanBlocks` for the requested block ranges includes note
+    /// commitment tree size information for each block; or else the scan is likely to fail if
+    /// notes belonging to the wallet are detected.
+    func suggestScanRanges() async throws -> [ScanRange]
+
     /// Scans new blocks added to the cache for any transactions received by the tracked
-    /// accounts.
-    /// This function pays attention only to cached blocks with heights greater than the
-    /// highest scanned block in `db_data`. Cached blocks with lower heights are not verified
-    /// against previously-scanned blocks. In particular, this function **assumes** that the
-    /// caller is handling rollbacks.
+    /// accounts, while checking that they form a valid chan.
+    ///
+    /// This function is built on the core assumption that the information provided in the
+    /// block cache is more likely to be accurate than the previously-scanned information.
+    /// This follows from the design (and trust) assumption that the `lightwalletd` server
+    /// provides accurate block information as of the time it was requested.
+    ///
+    /// This function **assumes** that the caller is handling rollbacks.
+    ///
     /// For brand-new light client databases, this function starts scanning from the Sapling
     /// activation height. This height can be fast-forwarded to a more recent block by calling
     /// [`initBlocksTable`] before this function.
+    ///
     /// Scanned blocks are required to be height-sequential. If a block is missing from the
     /// cache, an error will be signalled.
     ///
-    /// - parameter limit: scan up to limit blocks. pass 0 to set no limit.
+    /// - parameter fromHeight: scan starting from the given height.
+    /// - parameter limit: scan up to limit blocks.
     /// - Throws: `rustScanBlocks` if rust layer returns error.
-    func scanBlocks(limit: UInt32) async throws
+    func scanBlocks(fromHeight: Int32, limit: UInt32) async throws
 
     /// Upserts a UTXO into the data db database
     /// - parameter txid: the txid bytes for the UTXO
@@ -229,7 +223,7 @@ protocol ZcashRustBackendWelding {
         usk: UnifiedSpendingKey,
         memo: MemoBytes?,
         shieldingThreshold: Zatoshi
-    ) async throws -> Int64
+    ) async throws -> Data
 
     /// Gets the consensus branch id for the given height
     /// - Parameter height: the height you what to know the branch id for
@@ -252,5 +246,5 @@ protocol ZcashRustBackendWelding {
     /// this directory  is expected to contain a `/blocks` sub-directory with the blocks stored in the convened filename
     /// format `{height}-{hash}-block`. This directory has must be granted both write and read permissions.
     /// - Returns `BlockHeight` of the latest cached block or `.empty` if no blocks are stored.
-    func latestCachedBlockHeight() async -> BlockHeight
+    func latestCachedBlockHeight() async throws -> BlockHeight
 }