Public importAccount method

- importAccount(ufvk, purpose, name, keySource) API

CHANGELOG.md

@@ -10,6 +10,7 @@ and this library adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `DerivationTool.deriveArbitraryWalletKey`
 - `DerivationTool.deriveArbitraryAccountKey`
 - `SDKSynchronizer.listAccounts` Returns a list of the accounts in the wallet.
+- `SDKSynchronizer.importAccount` Imports a new account for unified full viewing key.
 
 ## Changed
 - `zcashlc_propose_transfer`, `zcashlc_propose_transfer_from_uri` and `zcashlc_propose_shielding` no longer accpt a `use_zip317_fees` parameter; ZIP 317 standard fees are now always used and are not configurable.

Sources/ZcashLightClientKit/ClosureSynchronizer.swift

@@ -97,6 +97,14 @@ public protocol ClosureSynchronizer {
 
     func listAccounts(completion: @escaping (Result<[Account], Error>) -> Void)
         
+    func importAccount(
+        ufvk: String,
+        purpose: AccountPurpose,
+        name: String,
+        keySource: String?,
+        completion: @escaping (Result<AccountUUID, Error>) -> Void
+    ) async throws
+
     func clearedTransactions(completion: @escaping ([ZcashTransaction.Overview]) -> Void)
     func sentTranscations(completion: @escaping ([ZcashTransaction.Overview]) -> Void)
     func receivedTransactions(completion: @escaping ([ZcashTransaction.Overview]) -> Void)

Sources/ZcashLightClientKit/CombineSynchronizer.swift

@@ -98,6 +98,13 @@ public protocol CombineSynchronizer {
 
     func listAccounts() -> SinglePublisher<[Account], Error>
     
+    func importAccount(
+        ufvk: String,
+        purpose: AccountPurpose,
+        name: String,
+        keySource: String?
+    ) async throws -> SinglePublisher<AccountUUID, Error>
+
     var allTransactions: SinglePublisher<[ZcashTransaction.Overview], Never> { get }
     var sentTransactions: SinglePublisher<[ZcashTransaction.Overview], Never> { get }
     var receivedTransactions: SinglePublisher<[ZcashTransaction.Overview], Never> { get }

Sources/ZcashLightClientKit/Constants/ZcashSDK.swift

@@ -221,7 +221,7 @@ public enum ZcashSDKTestnetConstants: NetworkConstants {
 }
 
 /// Used when importing an aaccount `importAccount(..., purpose: AccountPurpose)`
-public enum AccountPurpose: UInt32 {
+public enum AccountPurpose: UInt32, Equatable {
     case spending = 0
     case viewOnly
 }

Sources/ZcashLightClientKit/Synchronizer.swift

@@ -120,6 +120,8 @@ public protocol Synchronizer: AnyObject {
     ///   - for: [walletMode] Set `.newWallet` when preparing synchronizer for a brand new generated wallet,
     ///   `.restoreWallet` when wallet is about to be restored from a seed
     ///   and  `.existingWallet` for all other scenarios.
+    ///   - name: name of the account.
+    ///   - keySource: custom optional string for clients, used for example to help identify the type of the account.
     /// - Throws:
     ///     - `aliasAlreadyInUse` if the Alias used to create this instance is already used by other instance.
     ///     - `cantUpdateURLWithAlias` if the updating of paths in `Initilizer` according to alias fails. When this happens it means that
@@ -289,6 +291,20 @@ public protocol Synchronizer: AnyObject {
     /// Returns a list of the accounts in the wallet.
     func listAccounts() async throws -> [Account]
     
+    /// Imports a new account with UnifiedFullViewingKey.
+    /// - Parameters:
+    ///   - ufvk: unified full viewing key
+    ///   - purpose: of the account, either `spending` or `viewOnly`
+    ///   - name: name of the account.
+    ///   - keySource: custom optional string for clients, used for example to help identify the type of the account.
+    @discardableResult
+    func importAccount(
+        ufvk: String,
+        purpose: AccountPurpose,
+        name: String,
+        keySource: String?
+    ) async throws -> AccountUUID
+    
     /// Rescans the known blocks with the current keys.
     ///
     /// `rewind(policy:)` can be called anytime. If the sync process is in progress then it is stopped first. In this case, it make some significant

Sources/ZcashLightClientKit/Synchronizer/ClosureSDKSynchronizer.swift

@@ -84,6 +84,18 @@ extension ClosureSDKSynchronizer: ClosureSynchronizer {
         }
     }
 
+    public func importAccount(
+        ufvk: String,
+        purpose: AccountPurpose,
+        name: String,
+        keySource: String?,
+        completion: @escaping (Result<AccountUUID, Error>) -> Void
+    ) async throws {
+        AsyncToClosureGateway.executeThrowingAction(completion) {
+            try await self.synchronizer.importAccount(ufvk: ufvk, purpose: purpose, name: name, keySource: keySource)
+        }
+    }
+
     public func proposeTransfer(
         accountUUID: AccountUUID,
         recipient: Recipient,

Sources/ZcashLightClientKit/Synchronizer/CombineSDKSynchronizer.swift

@@ -130,7 +130,18 @@ extension CombineSDKSynchronizer: CombineSynchronizer {
             try await self.synchronizer.listAccounts()
         }
     }
-    
+
+    public func importAccount(
+        ufvk: String,
+        purpose: AccountPurpose,
+        name: String,
+        keySource: String?
+    ) async throws -> SinglePublisher<AccountUUID, Error> {
+        AsyncToCombineGateway.executeThrowingAction() {
+            try await self.synchronizer.importAccount(ufvk: ufvk, purpose: purpose, name: name, keySource: keySource)
+        }
+    }
+
     public var allTransactions: SinglePublisher<[ZcashTransaction.Overview], Never> {
         AsyncToCombineGateway.executeAction() {
             await self.synchronizer.transactions

Sources/ZcashLightClientKit/Synchronizer/SDKSynchronizer.swift

@@ -277,6 +277,33 @@ public class SDKSynchronizer: Synchronizer {
         try await initializer.rustBackend.listAccounts()
     }
     
+    @discardableResult
+    public func importAccount(
+        ufvk: String,
+        purpose: AccountPurpose,
+        name: String,
+        keySource: String?
+    ) async throws -> AccountUUID {
+        let chainTip = try? await UInt32(initializer.lightWalletService.latestBlockHeight())
+
+        let checkpointSource = initializer.container.resolve(CheckpointSource.self)
+
+        guard let chainTip else {
+            throw ZcashError.synchronizerNotPrepared
+        }
+        
+        let checkpoint = checkpointSource.birthday(for: BlockHeight(chainTip))
+            
+        return try await initializer.rustBackend.importAccount(
+            ufvk: ufvk,
+            treeState: checkpoint.treeState(),
+            recoverUntil: chainTip,
+            purpose: purpose,
+            name: name,
+            keySource: keySource
+        )
+    }
+
     public func proposeTransfer(accountUUID: AccountUUID, recipient: Recipient, amount: Zatoshi, memo: Memo?) async throws -> Proposal {
         try throwIfUnprepared()
 

Tests/TestUtils/Sourcery/GeneratedMocks/AutoMockable.generated.swift

@@ -1807,6 +1807,30 @@ class SynchronizerMock: Synchronizer {
         }
     }
 
+    // MARK: - importAccount
+
+    var importAccountUfvkPurposeNameKeySourceThrowableError: Error?
+    var importAccountUfvkPurposeNameKeySourceCallsCount = 0
+    var importAccountUfvkPurposeNameKeySourceCalled: Bool {
+        return importAccountUfvkPurposeNameKeySourceCallsCount > 0
+    }
+    var importAccountUfvkPurposeNameKeySourceReceivedArguments: (ufvk: String, purpose: AccountPurpose, name: String, keySource: String?)?
+    var importAccountUfvkPurposeNameKeySourceReturnValue: AccountUUID!
+    var importAccountUfvkPurposeNameKeySourceClosure: ((String, AccountPurpose, String, String?) async throws -> AccountUUID)?
+
+    func importAccount(ufvk: String, purpose: AccountPurpose, name: String, keySource: String?) async throws -> AccountUUID {
+        if let error = importAccountUfvkPurposeNameKeySourceThrowableError {
+            throw error
+        }
+        importAccountUfvkPurposeNameKeySourceCallsCount += 1
+        importAccountUfvkPurposeNameKeySourceReceivedArguments = (ufvk: ufvk, purpose: purpose, name: name, keySource: keySource)
+        if let closure = importAccountUfvkPurposeNameKeySourceClosure {
+            return try await closure(ufvk, purpose, name, keySource)
+        } else {
+            return importAccountUfvkPurposeNameKeySourceReturnValue
+        }
+    }
+
     // MARK: - rewind
 
     var rewindCallsCount = 0