react-native-zcash 0.3.5 → 0.4.0

package/ios/ZCashLightClientKit/Rust/ZcashRustBackendWelding.swift

@@ -8,382 +8,249 @@
 
 import Foundation
 
-public enum RustWeldingError: Error {
-    case genericError(message: String)
-    case dataDbInitFailed(message: String)
-    case dataDbNotEmpty
-    case saplingSpendParametersNotFound
-    case malformedStringInput
-    case noConsensusBranchId(height: Int32)
-    case unableToDeriveKeys
-}
-
-public enum ZcashRustBackendWeldingConstants {
+enum ZcashRustBackendWeldingConstants {
     static let validChain: Int32 = -1
 }
+/// Enumeration of potential return states for database initialization. If `seedRequired`
+/// is returned, the caller must re-attempt initialization providing the seed
+public enum DbInitResult {
+    case success
+    case seedRequired
+}
+
+// sourcery: mockActor
+protocol ZcashRustBackendWelding {
+    /// Adds the next available account-level spend authority, given the current set of [ZIP 316]
+    /// account identifiers known, to the wallet database.
+    ///
+    /// Returns the newly created [ZIP 316] account identifier, along with the binary encoding of the
+    /// [`UnifiedSpendingKey`] for the newly created account.  The caller should manage the memory of
+    /// (and store) the returned spending keys in a secure fashion.
+    ///
+    /// If `seed` was imported from a backup and this method is being used to restore a
+    /// previous wallet state, you should use this method to add all of the desired
+    /// accounts before scanning the chain from the seed's birthday height.
+    ///
+    /// By convention, wallets should only allow a new account to be generated after funds
+    /// have been received by the currently-available account (in order to enable
+    /// automated account recovery).
+    /// - parameter seed: byte array of the zip32 seed
+    /// - Returns: The `UnifiedSpendingKey` structs for the number of accounts created
+    /// - Throws: `rustCreateAccount`.
+    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.
+    /// - Parameter to: recipient address
+    /// - Parameter value: transaction amount in Zatoshi
+    /// - Parameter memo: the `MemoBytes` for this transaction. pass `nil` when sending to transparent receivers
+    /// - Throws: `rustCreateToAddress`.
+    func createToAddress(
+        usk: UnifiedSpendingKey,
+        to address: String,
+        value: Int64,
+        memo: MemoBytes?
+    ) 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
+    /// - parameter minedHeight: height on which this transaction was mined. this is used to fetch the consensus branch ID.
+    /// - Throws: `rustDecryptAndStoreTransaction`.
+    func decryptAndStoreTransaction(txBytes: [UInt8], minedHeight: Int32) async throws
+
+    /// Get the (unverified) balance from the given account.
+    /// - parameter account: index of the given account
+    /// - Throws: `rustGetBalance`.
+    func getBalance(account: Int32) async throws -> Int64
+
+    /// Returns the most-recently-generated unified payment address for the specified account.
+    /// - parameter account: index of the given account
+    /// - Throws:
+    ///     - `rustGetCurrentAddress` if rust layer returns error.
+    ///     - `rustGetCurrentAddressInvalidAddress` if generated unified address isn't valid.
+    func getCurrentAddress(account: Int32) async throws -> UnifiedAddress
 
-public protocol ZcashRustBackendWelding {
-    /**
-    gets the latest error if available. Clear the existing error
-    */
-    static func lastError() -> RustWeldingError?
+    /// Wallets might need to be rewound because of a reorg, or by user request.
+    /// There are times where the wallet could get out of sync for many reasons and
+    /// users might be asked to rescan their wallets in order to fix that. This function
+    /// returns the nearest height where a rewind is possible. Currently pruning gets rid
+    /// of sapling witnesses older than 100 blocks. So in order to reconstruct the witness
+    /// tree that allows to spend notes from the given wallet the rewind can't be more than
+    /// 100 blocks or back to the oldest unspent note that this wallet contains.
+    /// - parameter height: height you would like to rewind to.
+    /// - Returns: the blockheight of the nearest rewind height.
+    /// - Throws: `rustGetNearestRewindHeight`.
+    func getNearestRewindHeight(height: Int32) async throws -> Int32
 
-    /**
-    gets the latest error message from librustzcash. Does not clear existing error
-    */
-    static func getLastError() -> String?
+    /// Returns a newly-generated unified payment address for the specified account, with the next available diversifier.
+    /// - parameter account: index of the given account
+    /// - Throws:
+    ///     - `rustGetNextAvailableAddress` if rust layer returns error.
+    ///     - `rustGetNextAvailableAddressInvalidAddress` if generated unified address isn't valid.
+    func getNextAvailableAddress(account: Int32) async throws -> UnifiedAddress
 
-    /**
-    initializes the data db
-    - Parameter dbData: location of the data db sql file
-    */
-    static func initDataDb(dbData: URL, networkType: NetworkType) throws
-    
-    /**
-    - Returns: true when the address is valid and shielded. Returns false in any other case
-    - Throws: Error when the provided address belongs to another network
-    */
-    static func isValidShieldedAddress(_ address: String, networkType: NetworkType) throws -> Bool
-    
-    /**
-    - Returns: true when the address is valid and transparent. false in any other case
-    - Throws: Error when the provided address belongs to another network
-    */
-    static func isValidTransparentAddress(_ address: String, networkType: NetworkType) throws -> Bool
-    
-    /**
-    - Returns: true when the address is valid and transparent. false in any other case
-    - Throws: Error when there's another problem not related to validity of the string in question
-    */
-    static func isValidExtendedFullViewingKey(_ key: String, networkType: NetworkType) throws -> Bool
-    
-    /**
-    initialize the accounts table from a given seed and a number of accounts
-    - Parameters:
-        - dbData: location of the data db
-        - seed: byte array of the zip32 seed
-        - accounts: how many accounts you want to have
-    */
-    static func initAccountsTable(dbData: URL, seed: [UInt8], accounts: Int32, networkType: NetworkType) -> [String]?
-    
-    /**
-    initialize the accounts table from a set of unified viewing keys
-    - Parameters:
-        - dbData: location of the data db
-        - uvks: an array of UnifiedViewingKeys
-    */
-    static func initAccountsTable(dbData: URL, uvks: [UnifiedViewingKey], networkType: NetworkType) throws -> Bool
+    /// Get received memo from note.
+    /// - parameter idNote: note_id of note where the memo is located
+    func getReceivedMemo(idNote: Int64) async -> Memo?
 
-    /**
-    initialize the blocks table from a given checkpoint (birthday)
-    - Parameters:
-        - dbData: location of the data db
-        - height: represents the block height of the given checkpoint
-        - hash: hash of the merkle tree
-        - time: in milliseconds from reference
-        - saplingTree: hash of the sapling tree
-    */
-    // swiftlint:disable function_parameter_count
-    static func initBlocksTable(
-        dbData: URL,
+    /// 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
+    /// - Throws:
+    ///     - `rustGetTransparentBalanceNegativeAccount` if `account` is < 0.
+    ///     - `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
+    /// - Returns: `DbInitResult.success` if the dataDb was initialized successfully
+    /// or `DbInitResult.seedRequired` if the operation requires the seed to be passed
+    /// in order to be completed successfully.
+    /// 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,
-        networkType: NetworkType
-    ) throws
+        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
+    /// - Throws:
+    ///     - `rustListTransparentReceivers` if rust layer returns error.
+    ///     - `rustListTransparentReceiversInvalidAddress` if transarent received generated by rust is invalid.
+    func listTransparentReceivers(account: Int32) async throws -> [TransparentAddress]
 
-    /**
-    gets the address from data db from the given account
-    - Parameters:
-        - dbData: location of the data db
-        - account: index of the given account
-        - Returns: an optional string with the address if found
-    */
-    static func getAddress(dbData: URL, account: Int32, networkType: NetworkType) -> String?
+    /// Get the verified balance from the given account
+    /// - parameter account: index of the given account
+    /// - Throws: `rustGetVerifiedBalance` when rust layer throws error.
+    func getVerifiedBalance(account: Int32) async throws -> Int64
 
-    /**
-    get the (unverified) balance from the given account
-    - Parameters:
-        - dbData: location of the data db
-        - account: index of the given account
-    */
-    static func getBalance(dbData: URL, account: Int32, networkType: NetworkType) -> Int64
+    /// Get the verified cached transparent balance for the given account
+    /// - parameter account: account index to query the balance for.
+    /// - Throws:
+    ///     - `rustGetVerifiedTransparentBalanceNegativeAccount` if `account` is < 0.
+    ///     - `rustGetVerifiedTransparentBalance` if rust layer returns error.
+    func getVerifiedTransparentBalance(account: Int32) async throws -> Int64
 
-    /**
-    get the verified balance from the given account
-    - Parameters:
-        - dbData: location of the data db
-        - account: index of the given account
-    */
-    static func getVerifiedBalance(dbData: URL, account: Int32, networkType: NetworkType) -> Int64
-    
-    /**
-    Get the verified cached transparent balance for the given address
-    */
-    static func getVerifiedTransparentBalance(dbData: URL, address: String, networkType: NetworkType) throws -> Int64
-    
-    /**
-    Get the verified cached transparent balance for the given address
-    */
-    static func getTransparentBalance(dbData: URL, address: String, networkType: NetworkType) 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
 
-    /**
-    get received memo from note
-    - Parameters:
-        - dbData: location of the data db file
-        - idNote: note_id of note where the memo is located
-    */
-    static func getReceivedMemoAsUTF8(dbData: URL, idNote: Int64, networkType: NetworkType) -> String?
-    
-    /**
-    get sent memo from note
-    - Parameters:
-        - dbData: location of the data db file
-        - idNote: note_id of note where the memo is located
-    */
-    static func getSentMemoAsUTF8(dbData: URL, idNote: Int64, networkType: NetworkType) -> String?
-    
-    /**
-    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.
-        - Returns:
-            * `-1` if the combined chain is valid.
-            * `upper_bound` if the combined chain is invalid.
-            * `upper_bound` is the height of the highest invalid block (on the assumption that the highest block in the cache database is correct).
-            * `0` if there was an error during validation unrelated to chain validity.
-    - Important: This function does not mutate either of the databases.
-    */
-    static func validateCombinedChain(dbCache: URL, dbData: URL, networkType: NetworkType) -> Int32
-    
-    /**
-    Returns the nearest height where a rewind is possible. Currently prunning gets rid of sapling witnesses older
-    than 100 blocks. So in order to reconstruct the witness tree that allows to spend notes from the given wallet
-    the rewind can't be more than 100 block or back to the oldest unspent note that this wallet contains.
-    - Parameters:
-        - dbData: location of the data db file
-        - height: height you would like to rewind to.
-    */
-    static func getNearestRewindHeight(dbData: URL, height: Int32, networkType: NetworkType) -> Int32
+    /// 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.
+    func rewindToHeight(height: Int32) async throws
 
-    /**
-    rewinds the compact block storage to the given height. clears up all derived data as well
-    - Parameters:
-        - dbData: location of the data db file
-        - height: height to rewind to. DON'T PASS ARBITRARY HEIGHT. Use getNearestRewindHeight when unsure
-    */
-    static func rewindToHeight(dbData: URL, height: Int32, networkType: NetworkType) -> Bool
-    
-    /**
-    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.
-    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
-    [`zcashlc_init_blocks_table`] before this function.
-    Scanned blocks are required to be height-sequential. If a block is missing from the
-    cache, an error will be signalled.
-     
-    - Parameters:
-        - dbCache: location of the compact block cache db
-        - dbData:  location of the data db file
-        - limit: scan up to limit blocks. pass 0 to set no limit.
-    returns false if fails to scan.
-    */
-    static func scanBlocks(dbCache: URL, dbData: URL, limit: UInt32, networkType: NetworkType) -> Bool
+    /// Resets the state of the FsBlock database to only contain block and transaction information up to the given height.
+    /// - Note: this does not delete the files. Only rolls back the database.
+    /// - parameter height: height to rewind to. DON'T PASS ARBITRARY HEIGHT. Use `getNearestRewindHeight` when unsure
+    /// - Throws: `rustRewindCacheToHeight` if rust layer returns error.
+    func rewindCacheToHeight(height: Int32) async throws
 
-    /**
-    puts a UTXO into the data db database
-    - Parameters:
-        - dbData: location of the data db file
-        - address: the address of the UTXO
-        - txid: the txid bytes for the UTXO
-        - index: the index of the UTXO
-        - value: the value of the UTXO
-        - height: the mined height for the UTXO
-    - Returns: true if the operation succeded or false otherwise
-    */
-    static func putUnspentTransparentOutput(
-        dbData: URL,
-        address: String,
+    /// 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.
+    /// 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.
+    /// - Throws: `rustScanBlocks` if rust layer returns error.
+    func scanBlocks(limit: UInt32) async throws
+
+    /// Upserts a UTXO into the data db database
+    /// - parameter txid: the txid bytes for the UTXO
+    /// - parameter index: the index of the UTXO
+    /// - parameter script: the script of the UTXO
+    /// - parameter value: the value of the UTXO
+    /// - parameter height: the mined height for the UTXO
+    /// - Throws: `rustPutUnspentTransparentOutput` if rust layer returns error.
+    func putUnspentTransparentOutput(
         txid: [UInt8],
         index: Int,
         script: [UInt8],
         value: Int64,
-        height: BlockHeight,
-        networkType: NetworkType
-    ) throws -> Bool
-    
-    /**
-    clears the cached utxos for the given address from the specified height on
-    - Parameters:
-        - dbData: location of the data db file
-        - address: the address of the UTXO
-        - sinceheight: clear the UXTOs from that address on
-    - Returns: the amount of UTXOs cleared or -1 on error
-    */
-    static func clearUtxos(dbData: URL, address: String, sinceHeight: BlockHeight, networkType: NetworkType) throws -> Int32
+        height: BlockHeight
+    ) async throws
 
-    /**
-    Gets the balance of the previously downloaded UTXOs
-    - Parameters:
-        - dbData: location of the data db file
-        - address: the address of the UTXO
-    - Returns: the wallet balance containing verified and total balance.
-    - Throws: Rustwelding Error if something fails
-    */
-    static func downloadedUtxoBalance(dbData: URL, address: String, networkType: NetworkType) throws -> WalletBalance
-    
-    /**
-    Scans a transaction for any information that can be decrypted by the accounts in the
-    wallet, and saves it to the wallet.
+    /// Creates a transaction to shield all found UTXOs in data db for the account the provided `UnifiedSpendingKey` has spend authority for.
+    /// - Parameter usk: `UnifiedSpendingKey` that spend transparent funds and where the funds will be shielded to.
+    /// - Parameter memo: the `Memo` for this transaction
+    /// - Throws: `rustShieldFunds` if rust layer returns error.
+    func shieldFunds(
+        usk: UnifiedSpendingKey,
+        memo: MemoBytes?,
+        shieldingThreshold: Zatoshi
+    ) async throws -> Int64
 
-    - Parameters:
-        - dbData: location of the data db file
-        - tx:     the transaction to decrypt
-        - minedHeight: height on which this transaction was mined. this is used to fetch the consensus branch ID.
-    returns false if fails to decrypt.
-    */
-    static func decryptAndStoreTransaction(
-        dbData: URL,
-        txBytes: [UInt8],
-        minedHeight: Int32,
-        networkType: NetworkType
-    ) -> Bool
-    
-    /**
-    Creates a transaction to the given address from the given account
-    - Parameters:
-        - dbData: URL for the Data DB
-        - account: the account index that will originate the transaction
-        - extsk: extended spending key string
-        - to: recipient address
-        - value: transaction amount in Zatoshi
-        - memo: the memo string for this transaction
-        - spendParamsPath: path escaped String for the filesystem locations where the spend parameters are located
-        - outputParamsPath: path escaped String for the filesystem locations where the output parameters are located
-    */
-    // swiftlint:disable function_parameter_count
-    static func createToAddress(
-        dbData: URL,
-        account: Int32,
-        extsk: String,
-        to address: String,
-        value: Int64,
-        memo: String?,
-        spendParamsPath: String,
-        outputParamsPath: String,
-        networkType: NetworkType
-    ) -> Int64
-    
-    /**
-    Creates a transaction to shield all found UTXOs in cache db.
-    - Parameters:
-        - dbCache: URL for the Cache DB
-        - dbData: URL for the Data DB
-        - account: the account index that will originate the transaction
-        - tsk: transparent Secret Key for the shielded funds.
-        - extsk: extended spending key string
-        - memo: the memo string for this transaction
-        - spendParamsPath: path escaped String for the filesystem locations where the spend parameters are located
-        - outputParamsPath: path escaped String for the filesystem locations where the output parameters are located
-    */
-    // swiftlint:disable function_parameter_count
-    static func shieldFunds(
-        dbCache: URL,
-        dbData: URL,
-        account: Int32,
-        tsk: String,
-        extsk: String,
-        memo: String?,
-        spendParamsPath: String,
-        outputParamsPath: String,
-        networkType: NetworkType
-    ) -> Int64
-    
-    /**
-    Derives a full viewing key from a seed
-    - Parameter spendingKey: a string containing the spending key
-    - Returns: the derived key
-    - Throws: RustBackendError if fatal error occurs
-    */
-    static func deriveExtendedFullViewingKey(_ spendingKey: String, networkType: NetworkType) throws -> String?
-    
-    /**
-    Derives a set of full viewing keys from a seed
-    - Parameter spendingKey: a string containing the spending key
-    - Parameter accounts: the number of accounts you want to derive from this seed
-    - Returns: an array containing the derived keys
-    - Throws: RustBackendError if fatal error occurs
-    */
-    static func deriveExtendedFullViewingKeys(seed: [UInt8], accounts: Int32, networkType: NetworkType) throws -> [String]?
-    
-    /**
-    Derives a set of full viewing keys from a seed
-    - Parameter seed: a string containing the seed
-    - Parameter accounts: the number of accounts you want to derive from this seed
-    - Returns: an array containing the spending keys
-    - Throws: RustBackendError if fatal error occurs
-    */
-    static func deriveExtendedSpendingKeys(seed: [UInt8], accounts: Int32, networkType: NetworkType) throws -> [String]?
-    
-    /**
-    Derives a shielded address from a seed
-    - Parameter seed: an array of bytes of the seed
-    - Parameter accountIndex: the index of the account you want the address for
-    - Returns: an optional String containing the Shielded address
-    - Throws: RustBackendError if fatal error occurs
-    */
-    static func deriveShieldedAddressFromSeed(seed: [UInt8], accountIndex: Int32, networkType: NetworkType) throws -> String?
-    
-    /**
-    Derives a shielded address from an Extended Full Viewing Key
-    - Parameter extfvk: a string containing the extended full viewing key
-    - Returns: an optional String containing the Shielded address
-    - Throws: RustBackendError if fatal error occurs
-    */
-    static func deriveShieldedAddressFromViewingKey(_  extfvk: String, networkType: NetworkType) throws -> String?
-    
-    /**
-    Derives a shielded address from an Extended Full Viewing Key
-    - Parameter seed: an array of bytes of the seed
-    - Returns: an optional String containing the transparent address
-    - Throws: RustBackendError if fatal error occurs
-    */
-    static func deriveTransparentAddressFromSeed(seed: [UInt8], account: Int, index: Int, networkType: NetworkType) throws -> String?
-    
-    /**
-    Derives a transparent secret key from Seed
-    - Parameter seed: an array of bytes containing the seed
-    - Returns: an optional String containing the transparent secret (private) key
-    */
-    static func deriveTransparentPrivateKeyFromSeed(seed: [UInt8], account: Int, index: Int, networkType: NetworkType) throws -> String?
-    
-    /**
-    Derives a transparent address from a secret key
-    - Parameter tsk: a hex string containing the Secret Key
-    - Returns: an optional String containing the transparent address.
-    */
-    static func deriveTransparentAddressFromSecretKey(_ tsk: String, networkType: NetworkType) throws -> String?
-    
-    /**
-    Derives a tranparent address from a public key
-    - Parameter pubkey: public key represented as a string
-    */
-    static func derivedTransparentAddressFromPublicKey(_ pubkey: String, networkType: NetworkType) throws -> String
-    
-    static func deriveUnifiedViewingKeyFromSeed(_ seed: [UInt8], numberOfAccounts: Int, networkType: NetworkType) throws -> [UnifiedViewingKey]
+    /// Gets the consensus branch id for the given height
+    /// - Parameter height: the height you what to know the branch id for
+    /// - Throws: `rustNoConsensusBranchId` if rust layer returns error.
+    func consensusBranchIdFor(height: Int32) throws -> Int32
+
+    /// Initializes Filesystem based block cache
+    /// - Throws: `rustInitBlockMetadataDb` if rust layer returns error.
+    func initBlockMetadataDb() async throws
+
+    /// Write compact block metadata to a database known to the Rust layer
+    /// - Parameter blocks: The `ZcashCompactBlock`s that are going to be marked as stored by the metadata Db.
+    /// - Throws:
+    ///     - `rustWriteBlocksMetadataAllocationProblem` if there problem with allocating memory on Swift side.
+    ///     - `rustWriteBlocksMetadata` if there is problem with writing blocks metadata.
+    func writeBlocksMetadata(blocks: [ZcashCompactBlock]) async throws
 
-    /**
-    Gets the consensus branch id for the given height
-    - Parameter height: the height you what to know the branch id for
-    */
-    static func consensusBranchIdFor(height: Int32, networkType: NetworkType) throws -> Int32
+    /// Gets the latest block height stored in the filesystem based cache.
+    /// -  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.
+    /// - Returns `BlockHeight` of the latest cached block or `.empty` if no blocks are stored.
+    func latestCachedBlockHeight() async -> BlockHeight
 }