react-native-zcash 0.6.10 → 0.6.11

package/ios/ZCashLightClientKit/Rust/ZcashRustBackendWelding.swift

@@ -35,11 +35,9 @@ 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], treeState: TreeState, recoverUntil: UInt32?) async throws -> UnifiedSpendingKey
+    func createAccount(seed: [UInt8]) 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.
@@ -52,7 +50,7 @@ protocol ZcashRustBackendWelding {
         to address: String,
         value: Int64,
         memo: MemoBytes?
-    ) async throws -> Data
+    ) async throws -> Int64
 
     /// 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
@@ -91,10 +89,14 @@ protocol ZcashRustBackendWelding {
     ///     - `rustGetNextAvailableAddressInvalidAddress` if generated unified address isn't valid.
     func getNextAvailableAddress(account: Int32) async throws -> UnifiedAddress
 
-    /// 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 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 the verified cached transparent balance for the given address
     /// - parameter account; the account index to query
@@ -103,6 +105,14 @@ 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
@@ -112,6 +122,23 @@ 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
@@ -132,6 +159,26 @@ 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.
@@ -143,62 +190,21 @@ 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, 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.
-    ///
+    /// 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.
     /// 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 fromHeight: scan starting from the given height.
-    /// - parameter limit: scan up to limit blocks.
+    /// - parameter limit: scan up to limit blocks. pass 0 to set no limit.
     /// - Throws: `rustScanBlocks` if rust layer returns error.
-    func scanBlocks(fromHeight: Int32, limit: UInt32) async throws
+    func scanBlocks(limit: UInt32) async throws
 
     /// Upserts a UTXO into the data db database
     /// - parameter txid: the txid bytes for the UTXO
@@ -223,7 +229,7 @@ protocol ZcashRustBackendWelding {
         usk: UnifiedSpendingKey,
         memo: MemoBytes?,
         shieldingThreshold: Zatoshi
-    ) async throws -> Data
+    ) async throws -> Int64
 
     /// Gets the consensus branch id for the given height
     /// - Parameter height: the height you what to know the branch id for
@@ -246,5 +252,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 throws -> BlockHeight
+    func latestCachedBlockHeight() async -> BlockHeight
 }