react-native-zcash 0.9.13 → 0.10.1-beta.1

package/ios/ZCashLightClientKit/Error/ZcashErrorCodeDefinition.swift

@@ -83,6 +83,27 @@ enum ZcashErrorDefinition {
     /// LightWalletService.getTaddressTxids failed.
     // sourcery: code="ZSRVC0010"
     case serviceGetTaddressTxidsFailed(_ error: LightWalletServiceError)
+    /// LightWalletService.getMempoolStream failed.
+    // sourcery: code="ZSRVC0011"
+    case serviceGetMempoolStreamFailed(_ error: LightWalletServiceError)
+
+    // MARK: - Tor
+
+    /// Endpoint is not provided
+    // sourcery: code="ZTSRV0001"
+    case torServiceMissingEndpoint
+    /// Tor client fails to resolve ServiceMode
+    // sourcery: code="ZTSRV0002"
+    case torServiceUnresolvedMode
+    /// GRPC Service is called with a Tor mode instead of direct one
+    // sourcery: code="ZTSRV0003"
+    case grpcServiceCalledWithTorMode
+    /// TorClient is nil
+    // sourcery: code="ZTSRV0004"
+    case torClientUnavailable
+    /// TorClient is called but SDKFlags are set as Tor disabled
+    // sourcery: code="ZTSRV0005"
+    case torNotEnabled
 
     // MARK: SQLite connection
 
@@ -178,15 +199,11 @@ enum ZcashErrorDefinition {
     /// Unified address generated by rust layer is invalid when calling ZcashRustBackend.getNextAvailableAddress
     // sourcery: code="ZRUST0009"
     case rustGetNextAvailableAddressInvalidAddress
-    /// account parameter is lower than 0 when calling ZcashRustBackend.getTransparentBalance
-    /// - `account` is account passed to ZcashRustBackend.getTransparentBalance.
-    // sourcery: code="ZRUST0010"
-    case rustGetTransparentBalanceNegativeAccount(_ account: Int)
     /// Error from rust layer when calling ZcashRustBackend.getTransparentBalance
     /// - `account` is account passed to ZcashRustBackend.getTransparentBalance.
     /// - `rustError` contains error generated by the rust layer.
     // sourcery: code="ZRUST0011"
-    case rustGetTransparentBalance(_ account: Int, _ rustError: String)
+    case rustGetTransparentBalance(_ accountUUID: AccountUUID, _ rustError: String)
     /// Error from rust layer when calling ZcashRustBackend.getVerifiedBalance
     /// - `account` is account passed to ZcashRustBackend.getVerifiedBalance.
     /// - `rustError` contains error generated by the rust layer.
@@ -200,7 +217,7 @@ enum ZcashErrorDefinition {
     /// - `account` is account passed to ZcashRustBackend.getVerifiedTransparentBalance.
     /// - `rustError` contains error generated by the rust layer.
     // sourcery: code="ZRUST0014"
-    case rustGetVerifiedTransparentBalance(_ account: Int, _ rustError: String)
+    case rustGetVerifiedTransparentBalance(_ accountUUID: AccountUUID, _ rustError: String)
     /// Error from rust layer when calling ZcashRustBackend.initDataDb
     /// - `rustError` contains error generated by the rust layer.
     // sourcery: code="ZRUST0015"
@@ -382,6 +399,105 @@ enum ZcashErrorDefinition {
     /// - `rustError` contains error generated by the rust layer.
     /// sourcery: code="ZRUST0064"
     case rustTransactionDataRequests(_ rustError: String)
+    /// Error from rust layer when calling ZcashRustBackend.deriveArbitraryWalletKey
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0065"
+    case rustDeriveArbitraryWalletKey(_ rustError: String)
+    /// Error from rust layer when calling ZcashRustBackend.deriveArbitraryAccountKey
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0066"
+    case rustDeriveArbitraryAccountKey(_ rustError: String)
+    /// Error from rust layer when calling ZcashRustBackend.importAccountUfvk
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0067"
+    case rustImportAccountUfvk(_ rustError: String)
+    /// Error from rust layer when calling ZcashRustBackend.deriveAddressFromUfvk
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0068"
+    case rustDeriveAddressFromUfvk(_ rustError: String)
+    /// Error from rust layer when calling ZcashRustBackend.createPCZTFromProposal
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0069"
+    case rustCreatePCZTFromProposal(_ rustError: String)
+    /// Error from rust layer when calling ZcashRustBackend.addProofsToPCZT
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0070"
+    case rustAddProofsToPCZT(_ rustError: String)
+    /// Error from rust layer when calling ZcashRustBackend.extractAndStoreTxFromPCZT
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0071"
+    case rustExtractAndStoreTxFromPCZT(_ rustError: String)
+    /// Error from rust layer when calling ZcashRustBackend.getAccount
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0072"
+    case rustUUIDAccountNotFound(_ rustError: String)
+    /// Error from rust layer when calling ZcashRustBackend.extractAndStoreTxFromPCZT
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0073"
+    case rustTxidPtrIncorrectLength(_ rustError: String)
+    /// Error from rust layer when calling ZcashRustBackend.redactPCZTForSigner
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0074"
+    case rustRedactPCZTForSigner(_ rustError: String)
+    /// Error from rust layer when calling AccountMetadatKey.init with a seed.
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0075"
+    case rustDeriveAccountMetadataKey(_ rustError: String)
+    /// Error from rust layer when calling AccountMetadatKey.derivePrivateUseMetadataKey
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0076"
+    case rustDerivePrivateUseMetadataKey(_ rustError: String)
+    /// Error from rust layer when calling TorClient.isolatedClient
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0077"
+    case rustTorIsolatedClient(_ rustError: String)
+    /// Error from rust layer when calling TorClient.connectToLightwalletd
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0078"
+    case rustTorConnectToLightwalletd(_ rustError: String)
+    /// Error from rust layer when calling TorLwdConn.fetchTransaction
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0079"
+    case rustTorLwdFetchTransaction(_ rustError: String)
+    /// Error from rust layer when calling TorLwdConn.submit
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0080"
+    case rustTorLwdSubmit(_ rustError: String)
+    /// Error from rust layer when calling TorLwdConn.getInfo
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0081"
+    case rustTorLwdGetInfo(_ rustError: String)
+    /// Error from rust layer when calling TorLwdConn.latestBlockHeight
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0082"
+    case rustTorLwdLatestBlockHeight(_ rustError: String)
+    /// Error from rust layer when calling TorLwdConn.getTreeState
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0083"
+    case rustTorLwdGetTreeState(_ rustError: String)
+    /// Error from rust layer when calling TorClient.httpRequest
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0084"
+    case rustTorHttpRequest(_ rustError: String)
+    /// Error from rust layer when calling ZcashRustBackend.getSingleUseTransparentAddress
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0085"
+    case rustGetSingleUseTransparentAddress(_ rustError: String)
+    /// Single use transparent address generated by rust layer is invalid when calling ZcashRustBackend.getSingleUseTransparentAddress
+    // sourcery: code="ZRUST0086"
+    case rustGetSingleUseTransparentAddressInvalidAddress
+    /// Error from rust layer when calling ZcashRustBackend.checkSingleUseTransparentAddresses
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0087"
+    case rustCheckSingleUseTransparentAddresses(_ rustError: String)
+    /// Error from rust layer when calling ZcashRustBackend.updateTransparentAddressTransactions
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0088"
+    case rustUpdateTransparentAddressTransactions(_ rustError: String)
+    /// Error from rust layer when calling ZcashRustBackend.fetchUTXOsByAddress
+    /// - `rustError` contains error generated by the rust layer.
+    // sourcery: code="ZRUST0089"
+    case rustFetchUTXOsByAddress(_ rustError: String)
 
     // MARK: - Account DAO
 
@@ -530,12 +646,6 @@ enum ZcashErrorDefinition {
     // sourcery: code="ZCHKP0002"
     case checkpointDecode(_ error: Error)
 
-    // MARK: - DerivationTool
-
-    /// Invalid account when trying to derive spending key
-    // sourcery: code="ZDRVT0001"
-    case derivationToolSpendingKeyInvalidAccount
-
     // MARK: - UnspentTransactionOutputDAO
 
     /// Creation of the table for unspent transaction output failed.

package/ios/ZCashLightClientKit/Initializer.swift

@@ -40,6 +40,10 @@ public struct LightWalletEndpoint {
         self.singleCallTimeoutInMillis = singleCallTimeoutInMillis
         self.streamingCallTimeoutInMillis = streamingCallTimeoutInMillis
     }
+
+    var urlString: String {
+        String(format: "%@://%@:%d", secure ? "https" : "http", host, port)
+    }
 }
 
 /// This contains URLs from which can the SDK fetch files that contain sapling parameters.
@@ -49,7 +53,7 @@ public struct SaplingParamsSourceURL {
     public let outputParamFileURL: URL
 
     public static var `default`: SaplingParamsSourceURL {
-        return SaplingParamsSourceURL(spendParamFileURL: ZcashSDK.spendParamFileURL, outputParamFileURL: ZcashSDK.outputParamFileURL)
+        SaplingParamsSourceURL(spendParamFileURL: ZcashSDK.spendParamFileURL, outputParamFileURL: ZcashSDK.outputParamFileURL)
     }
 }
 
@@ -167,7 +171,9 @@ public class Initializer {
         outputParamsURL: URL,
         saplingParamsSourceURL: SaplingParamsSourceURL,
         alias: ZcashSynchronizerAlias = .default,
-        loggingPolicy: LoggingPolicy = .default(.debug)
+        loggingPolicy: LoggingPolicy = .default(.debug),
+        isTorEnabled: Bool,
+        isExchangeRateEnabled: Bool
     ) {
         let container = DIContainer()
         
@@ -186,7 +192,9 @@ public class Initializer {
             outputParamsURL: outputParamsURL,
             saplingParamsSourceURL: saplingParamsSourceURL,
             alias: alias,
-            loggingPolicy: loggingPolicy
+            loggingPolicy: loggingPolicy,
+            isTorEnabled: isTorEnabled,
+            isExchangeRateEnabled: isExchangeRateEnabled
         )
         
         self.init(
@@ -198,7 +206,9 @@ public class Initializer {
             saplingParamsSourceURL: saplingParamsSourceURL,
             alias: alias,
             urlsParsingError: parsingError,
-            loggingPolicy: loggingPolicy
+            loggingPolicy: loggingPolicy,
+            isTorEnabled: isTorEnabled,
+            isExchangeRateEnabled: isExchangeRateEnabled
         )
     }
 
@@ -216,7 +226,9 @@ public class Initializer {
         outputParamsURL: URL,
         saplingParamsSourceURL: SaplingParamsSourceURL,
         alias: ZcashSynchronizerAlias = .default,
-        loggingPolicy: LoggingPolicy = .default(.debug)
+        loggingPolicy: LoggingPolicy = .default(.debug),
+        isTorEnabled: Bool,
+        isExchangeRateEnabled: Bool
     ) {
         // It's not possible to fail from constructor. Technically it's possible but it can be pain for the client apps to handle errors thrown
         // from constructor. So `parsingError` is just stored in initializer and `SDKSynchronizer.prepare()` throw this error if it exists.
@@ -233,7 +245,9 @@ public class Initializer {
             outputParamsURL: outputParamsURL,
             saplingParamsSourceURL: saplingParamsSourceURL,
             alias: alias,
-            loggingPolicy: loggingPolicy
+            loggingPolicy: loggingPolicy,
+            isTorEnabled: isTorEnabled,
+            isExchangeRateEnabled: isExchangeRateEnabled
         )
 
         self.init(
@@ -245,7 +259,9 @@ public class Initializer {
             saplingParamsSourceURL: saplingParamsSourceURL,
             alias: alias,
             urlsParsingError: parsingError,
-            loggingPolicy: loggingPolicy
+            loggingPolicy: loggingPolicy,
+            isTorEnabled: isTorEnabled,
+            isExchangeRateEnabled: isExchangeRateEnabled
         )
     }
     
@@ -258,7 +274,9 @@ public class Initializer {
         saplingParamsSourceURL: SaplingParamsSourceURL,
         alias: ZcashSynchronizerAlias,
         urlsParsingError: ZcashError?,
-        loggingPolicy: LoggingPolicy = .default(.debug)
+        loggingPolicy: LoggingPolicy = .default(.debug),
+        isTorEnabled: Bool,
+        isExchangeRateEnabled: Bool
     ) {
         self.container = container
         self.cacheDbURL = cacheDbURL
@@ -296,7 +314,9 @@ public class Initializer {
         outputParamsURL: URL,
         saplingParamsSourceURL: SaplingParamsSourceURL,
         alias: ZcashSynchronizerAlias,
-        loggingPolicy: LoggingPolicy = .default(.debug)
+        loggingPolicy: LoggingPolicy = .default(.debug),
+        isTorEnabled: Bool,
+        isExchangeRateEnabled: Bool
     ) -> (URLs, ZcashError?) {
         let urls = URLs(
             fsBlockDbRoot: fsBlockDbRoot,
@@ -317,7 +337,9 @@ public class Initializer {
             alias: alias,
             networkType: network.networkType,
             endpoint: endpoint,
-            loggingPolicy: loggingPolicy
+            loggingPolicy: loggingPolicy,
+            isTorEnabled: isTorEnabled,
+            isExchangeRateEnabled: isExchangeRateEnabled
         )
         
         return (updatedURLs, parsingError)
@@ -406,7 +428,13 @@ public class Initializer {
     /// - Parameter seed: ZIP-32 Seed bytes for the wallet that will be initialized
     /// - Throws: `InitializerError.dataDbInitFailed` if the creation of the dataDb fails
     /// `InitializerError.accountInitFailed` if the account table can't be initialized. 
-    func initialize(with seed: [UInt8]?, walletBirthday: BlockHeight, for walletMode: WalletInitMode) async throws -> InitializationResult {
+    func initialize(
+        with seed: [UInt8]?,
+        walletBirthday: BlockHeight,
+        for walletMode: WalletInitMode,
+        name: String,
+        keySource: String? = nil
+    ) async throws -> InitializationResult {
         try await storage.create()
 
         if case .seedRequired = try await rustBackend.initDataDb(seed: seed) {
@@ -423,14 +451,21 @@ public class Initializer {
         if let seed, try await rustBackend.listAccounts().isEmpty {
             var chainTip: UInt32?
             
-            if walletMode == .restoreWallet, let latestBlockHeight = try? await lightWalletService.latestBlockHeight() {
-                chainTip = UInt32(latestBlockHeight)
+            let sdkFlags = container.resolve(SDKFlags.self)
+            
+            // called when client starts and restore of the wallet is in progress
+            if walletMode == .restoreWallet {
+                if let latestBlockHeight = try? await lightWalletService.latestBlockHeight(mode: await sdkFlags.ifTor(.uniqueTor)) {
+                    chainTip = UInt32(latestBlockHeight)
+                }
             }
             
             _ = try await rustBackend.createAccount(
                 seed: seed,
                 treeState: checkpoint.treeState(),
-                recoverUntil: chainTip
+                recoverUntil: chainTip,
+                name: name,
+                keySource: keySource
             )
         }
 

package/ios/ZCashLightClientKit/Metrics/SDKMetrics.swift

@@ -101,20 +101,29 @@ final class SDKMetricsImpl: SDKMetrics {
         cbpOverview[lastActionInRun] = report
     }
     
-    // swiftlint:disable string_concatenation
+    // swiftlint:disable:next string_concatenation
     func logCBPOverviewReport(_ logger: Logger, walletSummary: WalletSummary?) async {
         actionStop()
 
-        let accountBalance = walletSummary?.accountBalances[0]
         logger.sync(
             """
             SYNC (\(syncs)) REPORT
             finished in: \(Date().timeIntervalSince1970 - cbpStartTime)
-            verified balance: \(accountBalance?.saplingBalance.spendableValue.amount ?? 0)
-            total balance: \(accountBalance?.saplingBalance.total().amount ?? 0)
             """
         )
 
+        if let accountBalances = walletSummary?.accountBalances {
+            for accountBalance in accountBalances {
+                logger.sync(
+                """
+                account index: \(accountBalance.key)
+                    verified balance: \(accountBalance.value.saplingBalance.spendableValue.amount)
+                    total balance: \(accountBalance.value.saplingBalance.total().amount)
+                """
+                )
+            }
+        }
+
         try? await Task.sleep(nanoseconds: 100_000)
 
         for action in cbpOverview {
@@ -130,10 +139,10 @@ final class SDKMetricsImpl: SDKMetrics {
                 """
             
             if !report.details.isEmpty {
-                resText += "\ndetails:\n"
+                resText = "\(resText)\ndetails:\n"
                 
                 for detail in report.details {
-                    resText += "\t\(detail)\n"
+                    resText = "\(resText)\t\(detail)\n"
                 }
             }
             

package/ios/ZCashLightClientKit/Model/SingleUseTransparentAddress.swift

@@ -0,0 +1,29 @@
+//
+//  SingleUseTransparentAddress.swift
+//  ZcashLightClientKit
+//
+//  Created by Lukáš Korba on 2025-10-27.
+//
+
+import Foundation
+
+public struct SingleUseTransparentAddress: Equatable {
+    let address: String
+    let gapPosition: UInt32
+    let gapLimit: UInt32
+    
+    public init(address: String, gapPosition: UInt32, gapLimit: UInt32) {
+        self.address = address
+        self.gapPosition = gapPosition
+        self.gapLimit = gapLimit
+    }
+}
+
+public enum TransparentAddressCheckResult: Equatable {
+    /// Some funds found with a string of the address associated with the funds
+    case found(String)
+    /// No funds found
+    case notFound
+    /// Fallback for the non-Tor path, there is no grpc method at the moment
+    case torRequired
+}

package/ios/ZCashLightClientKit/Model/TransactionDataRequest.swift

@@ -7,20 +7,101 @@
 
 import Foundation
 
-struct SpendsFromAddress: Equatable {
+/// A type describing the mined-ness of transactions that should be returned in response to a
+/// `TransactionDataRequest`.
+enum TransactionStatusFilter: Equatable {
+    /// Only mined transactions should be returned.
+    case mined
+    /// Only mempool transactions should be returned.
+    case mempool
+    /// Both mined transactions and transactions in the mempool should be returned.
+    case all
+}
+
+/// A type used to filter transactions to be returned in response to a `TransactionDataRequest`,
+/// in terms of the spentness of the transaction's transparent outputs.
+enum OutputStatusFilter: Equatable {
+    /// Only transactions that have currently-unspent transparent outputs should be returned.
+    case unspent
+    /// All transactions corresponding to the data request should be returned, irrespective of
+    /// whether or not those transactions produce transparent outputs that are currently unspent.
+    case all
+}
+
+struct TransactionsInvolvingAddress: Equatable {
+    /// The address to request transactions and/or UTXOs for.
     let address: String
+    /// Only transactions mined at heights greater than or equal to this height should be
+    /// returned.
     let blockRangeStart: UInt32
+    /// If set, only transactions mined at heights less than this height should be returned.
     let blockRangeEnd: UInt32?
+    /// If `request_at` is set, the caller evaluating this request should attempt to
+    /// retrieve transaction data related to the specified address at a time that is as close
+    /// as practical to the specified instant, and in a fashion that decorrelates this request
+    /// to a light wallet server from other requests made by the same caller.
+    ///
+    /// This may be ignored by callers that are able to satisfy the request without exposing
+    /// correlations between addresses to untrusted parties; for example, a wallet application
+    /// that uses a private, trusted-for-privacy supplier of chain data can safely ignore this
+    /// field.
+    let requestAt: Date?
+    /// The caller should respond to this request only with transactions that conform to the
+    /// specified transaction status filter.
+    let txStatusFilter: TransactionStatusFilter
+    /// The caller should respond to this request only with transactions containing outputs
+    /// that conform to the specified output status filter.
+    let outputStatusFilter: OutputStatusFilter
 }
 
+/// A request for transaction data enhancement, spentness check, or discovery
+/// of spends from a given transparent address within a specific block range.
 enum TransactionDataRequest: Equatable {
+    /// Information about the chain's view of a transaction is requested.
+    ///
+    /// The caller evaluating this request on behalf of the wallet backend should respond to this
+    /// request by determining the status of the specified transaction with respect to the main
+    /// chain; if using `lightwalletd` for access to chain data, this may be obtained by
+    /// interpreting the results of the `GetTransaction` RPC method. It should then call
+    /// `ZcashRustBackend.setTransactionStatus` to provide the resulting transaction status
+    /// information to the wallet backend.
     case getStatus([UInt8])
+    /// Transaction enhancement (download of complete raw transaction data) is requested.
+    ///
+    /// The caller evaluating this request on behalf of the wallet backend should respond to this
+    /// request by providing complete data for the specified transaction to
+    /// `ZcashRustBackend.decryptAndStoreTransaction`; if using `lightwalletd` for access to chain
+    /// state, this may be obtained via the `GetTransaction` RPC method. If no data is available
+    /// for the specified transaction, this should be reported to the backend using
+    /// `ZcashRustBackend.setTransactionStatus`. A `TransactionDataRequest.enhancement` request
+    /// subsumes any previously existing `TransactionDataRequest.getStatus` request.
     case enhancement([UInt8])
-    case spendsFromAddress(SpendsFromAddress)
+    /// Information about transactions that receive or spend funds belonging to the specified
+    /// transparent address is requested.
+    ///
+    /// Fully transparent transactions, and transactions that do not contain either shielded inputs
+    /// or shielded outputs belonging to the wallet, may not be discovered by the process of chain
+    /// scanning; as a consequence, the wallet must actively query to find transactions that spend
+    /// such funds. Ideally we'd be able to query by `OutPoint` but this is not currently
+    /// functionality that is supported by the light wallet server.
+    ///
+    /// The caller evaluating this request on behalf of the wallet backend should respond to this
+    /// request by detecting transactions involving the specified address within the provided block
+    /// range; if using `lightwalletd` for access to chain data, this may be performed using the
+    /// `GetTaddressTxids` RPC method. It should then call `ZcashRustBackend.decryptAndStoreTransaction`
+    /// for each transaction so detected.
+    case transactionsInvolvingAddress(TransactionsInvolvingAddress)
 }
 
+/// Metadata about the status of a transaction obtained by inspecting the chain state.
 enum TransactionStatus: Equatable {
+    /// The requested transaction ID was not recognized by the node.
     case txidNotRecognized
+    /// The requested transaction ID corresponds to a transaction that is recognized by the node,
+    /// but is in the mempool or is otherwise not mined in the main chain (but may have been mined
+    /// on a fork that was reorged away).
     case notInMainChain
+    /// The requested transaction ID corresponds to a transaction that has been included in the
+    /// block at the provided height.
     case mined(BlockHeight)
 }

package/ios/ZCashLightClientKit/Model/WalletSummary.swift

@@ -24,17 +24,33 @@ public struct AccountBalance: Equatable {
     public let orchardBalance: PoolBalance
     public let unshielded: Zatoshi
     
-    static let zero = AccountBalance(saplingBalance: .zero, orchardBalance: .zero, unshielded: .zero)
+    /// This field is reserved for special operations.
+    /// Its current use relates to the time period when the chain tip has not yet been updated, and an attempt would otherwise be made to shield transparent funds.
+    /// Such a scenario would result in failure, so the funds are moved to `awaitingResolution` until the chain tip is updated.
+    /// The goal is to report the total amount along with the expected value.
+    public let awaitingResolution: Zatoshi
+    
+    static let zero = AccountBalance(saplingBalance: .zero, orchardBalance: .zero, unshielded: .zero, awaitingResolution: .zero)
+    
+    init(saplingBalance: PoolBalance, orchardBalance: PoolBalance, unshielded: Zatoshi, awaitingResolution: Zatoshi = .zero) {
+        self.saplingBalance = saplingBalance
+        self.orchardBalance = orchardBalance
+        self.unshielded = unshielded
+        self.awaitingResolution = awaitingResolution
+    }
 }
 
 struct ScanProgress: Equatable {
     let numerator: UInt64
     let denominator: UInt64
     
+    var isComplete: Bool {
+        numerator == denominator
+    }
+    
     func progress() throws -> Float {
         guard denominator != 0 else {
-            // this shouldn't happen but if it does, we need to get notified by clients and work on a fix
-            throw ZcashError.rustScanProgressOutOfRange("\(numerator)/\(denominator)")
+            return 1.0
         }
 
         let value = Float(numerator) / Float(denominator)
@@ -49,9 +65,10 @@ struct ScanProgress: Equatable {
 }
 
 struct WalletSummary: Equatable {
-    let accountBalances: [UInt32: AccountBalance]
+    let accountBalances: [AccountUUID: AccountBalance]
     let chainTipHeight: BlockHeight
     let fullyScannedHeight: BlockHeight
+    let recoveryProgress: ScanProgress?
     let scanProgress: ScanProgress?
     let nextSaplingSubtreeIndex: UInt32
     let nextOrchardSubtreeIndex: UInt32

package/ios/ZCashLightClientKit/Model/WalletTypes.swift

@@ -10,10 +10,18 @@ public protocol StringEncoded {
     var stringEncoded: String { get }
 }
 
+public struct Account: Equatable, Hashable, Codable, Identifiable {
+    public let id: AccountUUID
+    public let name: String?
+    public let keySource: String?
+    public let seedFingerprint: [UInt8]?
+    public let hdAccountIndex: Zip32AccountIndex?
+    public let ufvk: UnifiedFullViewingKey?
+}
+
 public struct UnifiedSpendingKey: Equatable, Undescribable {
     let network: NetworkType
     let bytes: [UInt8]
-    public let account: UInt32
 }
 
 /// Sapling Extended Spending Key
@@ -43,25 +51,22 @@ public struct TransparentAccountPrivKey: Equatable, Undescribable {
 }
 
 /// A ZIP 316 Unified Full Viewing Key.
-public struct UnifiedFullViewingKey: Equatable, StringEncoded, Undescribable {
+public struct UnifiedFullViewingKey: Equatable, StringEncoded, Undescribable, Hashable, Codable {
     let encoding: String
-    public let account: UInt32
 
     public var stringEncoded: String { encoding }
 
     /// Initializes a new UnifiedFullViewingKey (UFVK) from the provided string encoding
     /// - Parameters:
     ///  - parameter encoding: String encoding of unified full viewing key
-    ///  - parameter account: account number of the given UFVK
     ///  - parameter network: `NetworkType` corresponding to the encoding (Mainnet or Testnet)
     /// - Throws: `unifiedFullViewingKeyInvalidInput`when the provided encoding is found to be invalid
-    public init(encoding: String, account: UInt32, network: NetworkType) throws {
+    public init(encoding: String, network: NetworkType) throws {
         guard DerivationTool(networkType: network).isValidUnifiedFullViewingKey(encoding) else {
             throw ZcashError.unifiedFullViewingKeyInvalidInput
         }
 
         self.encoding = encoding
-        self.account = account
     }
 }
 
@@ -115,6 +120,31 @@ extension AddressType {
     }
 }
 
+/// Receiver types supported in a `UnifiedAddress` generated by the SDK.
+public enum ReceiverType: Equatable {
+    /// A transparent P2PKH receiver.
+    case p2pkh
+    /// A shielded Sapling receiver.
+    case sapling
+    /// A shielded Orchard receiver.
+    case orchard
+}
+
+extension Set<ReceiverType> {
+    /// The set of all possible receivers in a `UnifiedAddress` generated by the SDK.
+    static let all: Set<ReceiverType> = [.p2pkh, .sapling, .orchard]
+    /// The set of all shielded receivers in a `UnifiedAddress` generated by the SDK.
+    static let shielded: Set<ReceiverType> = [.sapling, .orchard]
+
+    func toFlags() -> UInt32 {
+        var flags: UInt32 = 0
+        if contains(.p2pkh) { flags |= 1 << 0 }
+        if contains(.sapling) { flags |= 1 << 2 }
+        if contains(.orchard) { flags |= 1 << 3 }
+        return flags
+    }
+}
+
 /// A Transparent Address that can be encoded as a String
 ///
 /// Transactions sent to this address are totally visible in the public
@@ -166,7 +196,7 @@ public struct SaplingAddress: Equatable, StringEncoded {
     }
 }
 
-public struct UnifiedAddress: Equatable, StringEncoded {
+public struct UnifiedAddress: Equatable, StringEncoded, Codable, Hashable {
     let networkType: NetworkType
 
     public enum ReceiverTypecodes: Hashable {
@@ -247,7 +277,7 @@ public struct TexAddress: Equatable, StringEncoded, Comparable {
 
 public enum TransactionRecipient: Equatable {
     case address(Recipient)
-    case internalAccount(UInt32)
+    case internalAccount(AccountUUID)
 }
 
 /// Represents a valid recipient of Zcash