react-native-zcash 0.6.14 → 0.7.1

package/ios/ZCashLightClientKit/Rust/ZcashRustBackendWelding.swift

@@ -2,7 +2,7 @@
 //  ZcashRustBackendWelding.swift
 //  ZcashLightClientKit
 //
-//  Created by Francisco Gindre on 12/09/2019.
+//  Created by Francisco 'Pacu' Gindre on 2019-12-09.
 //  Copyright © 2019 Electric Coin Company. All rights reserved.
 //
 
@@ -11,15 +11,20 @@ import Foundation
 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
+
+/// 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
+    case seedNotRelevant
 }
 
-// sourcery: mockActor
 protocol ZcashRustBackendWelding {
+    /// Returns a list of the accounts in the wallet.
+    func listAccounts() async throws -> [Int32]
+
     /// Adds the next available account-level spend authority, given the current set of [ZIP 316]
     /// account identifiers known, to the wallet database.
     ///
@@ -41,18 +46,10 @@ protocol ZcashRustBackendWelding {
     /// - Throws: `rustCreateAccount`.
     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.
-    /// - 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 -> Data
+    /// Checks whether the given seed is relevant to any of the derived accounts in the wallet.
+    ///
+    /// - parameter seed: byte array of the seed
+    func isSeedRelevantToAnyDerivedAccount(seed: [UInt8]) async throws -> Bool
 
     /// 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
@@ -60,11 +57,6 @@ protocol ZcashRustBackendWelding {
     /// - 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:
@@ -93,8 +85,9 @@ protocol ZcashRustBackendWelding {
 
     /// Get memo from note.
     /// - parameter txId: ID of transaction containing the note
+    /// - parameter outputPool: output pool identifier (2 = Sapling, 3 = Orchard)
     /// - parameter outputIndex: output index of note
-    func getMemo(txId: Data, outputIndex: UInt16) async throws -> Memo?
+    func getMemo(txId: Data, outputPool: UInt32, outputIndex: UInt16) async throws -> Memo?
 
     /// Get the verified cached transparent balance for the given address
     /// - parameter account; the account index to query
@@ -120,11 +113,6 @@ protocol ZcashRustBackendWelding {
     ///     - `rustListTransparentReceiversInvalidAddress` if transarent received generated by rust is invalid.
     func listTransparentReceivers(account: Int32) async throws -> [TransparentAddress]
 
-    /// 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 verified cached transparent balance for the given account
     /// - parameter account: account index to query the balance for.
     /// - Throws:
@@ -145,6 +133,8 @@ protocol ZcashRustBackendWelding {
 
     func putSaplingSubtreeRoots(startIndex: UInt64, roots: [SubtreeRoot]) async throws
 
+    func putOrchardSubtreeRoots(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,
@@ -167,8 +157,8 @@ protocol ZcashRustBackendWelding {
     /// 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 the account balances and sync status of the wallet.
+    func getWalletSummary() async throws -> WalletSummary?
 
     /// Returns a list of suggested scan ranges based upon the current wallet state.
     ///
@@ -196,9 +186,10 @@ protocol ZcashRustBackendWelding {
     /// cache, an error will be signalled.
     ///
     /// - parameter fromHeight: scan starting from the given height.
+    /// - parameter fromState: The TreeState Protobuf object for the height prior to `fromHeight`
     /// - parameter limit: scan up to limit blocks.
     /// - Throws: `rustScanBlocks` if rust layer returns error.
-    func scanBlocks(fromHeight: Int32, limit: UInt32) async throws
+    func scanBlocks(fromHeight: Int32, fromState: TreeState, limit: UInt32) async throws -> ScanSummary
 
     /// Upserts a UTXO into the data db database
     /// - parameter txid: the txid bytes for the UTXO
@@ -215,15 +206,66 @@ protocol ZcashRustBackendWelding {
         height: BlockHeight
     ) async throws
 
-    /// 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.
+    /// Select transaction inputs, compute fees, and construct a proposal for a transaction
+    /// that can then be authorized and made ready for submission to the network with
+    /// `createProposedTransaction`.
+    ///
+    /// - parameter account: index of the given account
+    /// - 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 proposeTransfer(
+        account: Int32,
+        to address: String,
+        value: Int64,
+        memo: MemoBytes?
+    ) async throws -> FfiProposal
+
+    /// Select transaction inputs, compute fees, and construct a proposal for a transaction
+    /// that can then be authorized and made ready for submission to the network with
+    /// `createProposedTransaction` from a valid [ZIP-321](https://zips.z.cash/zip-0321) Payment Request UR
+    ///
+    /// - parameter uri: the URI String that the proposal will be made from.
+    /// - parameter account: index of the given account
+    /// - 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 proposeTransferFromURI(
+        _ uri: String,
+        account: Int32
+    ) async throws -> FfiProposal
+
+    /// Constructs a transaction proposal to shield all found UTXOs in data db for the given account,
+    /// that can then be authorized and made ready for submission to the network with
+    /// `createProposedTransaction`.
+    ///
+    /// Returns the proposal, or `nil` if the transparent balance that would be shielded
+    /// is zero or below `shieldingThreshold`.
+    ///
+    /// - parameter account: index of the given account
     /// - Parameter memo: the `Memo` for this transaction
+    /// - Parameter transparentReceiver: a specific transparent receiver within the account
+    ///             that should be the source of transparent funds. Default is `nil` which
+    ///             will select whichever of the account's transparent receivers has funds
+    ///             to shield.
     /// - Throws: `rustShieldFunds` if rust layer returns error.
-    func shieldFunds(
-        usk: UnifiedSpendingKey,
+    func proposeShielding(
+        account: Int32,
         memo: MemoBytes?,
-        shieldingThreshold: Zatoshi
-    ) async throws -> Data
+        shieldingThreshold: Zatoshi,
+        transparentReceiver: String?
+    ) async throws -> FfiProposal?
+
+    /// Creates a transaction from the given proposal.
+    /// - Parameter proposal: the transaction proposal.
+    /// - Parameter usk: `UnifiedSpendingKey` for the account that controls the funds to be spent.
+    /// - Throws: `rustCreateToAddress`.
+    func createProposedTransactions(
+        proposal: FfiProposal,
+        usk: UnifiedSpendingKey
+    ) async throws -> [Data]
 
     /// Gets the consensus branch id for the given height
     /// - Parameter height: the height you what to know the branch id for