ZcashLightClientKit/MIGRATING.md

Migrating from 0.16.x-beta to 0.17.0-alpha.x

Changes to Demo APP

The demo application now uses the SDKSynchronizer to create addresses and shield funds. DerivationToolViewController was removed. See DerivationTool unit tests for sample code. GetAddressViewController now derives transparent and sapling addresses from Unified Address SendViewController uses Unified Spending Key and type-safe Memo

Changes To SDK

CompactBlockProcessor

public func getUnifiedAddress(accountIndex: Int) -> UnifiedAddress? public func getSaplingAddress(accountIndex: Int) -> SaplingAddress? derived from UA public func getTransparentAddress(accountIndex: Int) -> TransparentAddress? is derived from UA public func getTransparentBalance(accountIndex: Int) throws -> WalletBalance now fetches from account exclusively func refreshUTXOs(tAddress: TransparentAddress, startHeight: BlockHeight) async throws -> RefreshedUTXOs uses TransparentAddress

Initializer

Migration of DataDB and CacheDB are delegated to librustzcash

removed public func getAddress(index account: Int = 0) -> String

Wallet Types

UnifiedSpendingKey to represent Unified Spending Keys. This is a binary encoded not meant to be stored or backed up. This only serves the purpuse of letting clients use the least priviledge keys at all times for every operation.

Synchronizer

sendToAddress and shieldFunds now take a UnifiedSpendingKey instead of the respective spending and transparent private keys. refreshUTXOs uses TransparentAddress

KeyDeriving protocol

Addresses should be obtained from the Synchronizer by using the get_address functions Transparent and Sapling receivers should be obtained by extracting the receivers of a UA

public extension UnifiedAddress {
    /// Extracts the sapling receiver from this UA if available
    /// - Returns: an `Optional<SaplingAddress>`
    func saplingReceiver() -> SaplingAddress? {
        try? DerivationTool.saplingReceiver(from: self)
    }

    /// Extracts the transparent receiver from this UA if available
    /// - Returns: an `Optional<TransparentAddress>`
    func transparentReceiver() -> TransparentAddress? {
        try? DerivationTool.transparentReceiver(from: self)
    }

Removed func deriveUnifiedFullViewingKeys(seed: [UInt8], numberOfAccounts: Int) throws -> [UnifiedFullViewingKey] func deriveViewingKey(spendingKey: SaplingExtendedSpendingKey) throws -> SaplingExtendedFullViewingKey func deriveSpendingKeys(seed: [UInt8], numberOfAccounts: Int) throws -> [SaplingExtendedSpendingKey] func deriveUnifiedAddress(from ufvk: UnifiedFullViewingKey) throws -> UnifiedAddress func deriveTransparentAddress(seed: [UInt8], account: Int, index: Int) throws -> TransparentAddress func deriveTransparentAccountPrivateKey(seed: [UInt8], account: Int) throws -> TransparentAccountPrivKey func deriveTransparentAddressFromAccountPrivateKey(_ xprv: TransparentAccountPrivKey, index: Int) throws -> TransparentAddress

Added static func saplingReceiver(from unifiedAddress: UnifiedAddress) throws -> SaplingAddress? static func transparentReceiver(from unifiedAddress: UnifiedAddress) throws -> TransparentAddress? static func receiverTypecodesFromUnifiedAddress(_ address: UnifiedAddress) throws -> [UnifiedAddress.ReceiverTypecodes] func deriveUnifiedSpendingKey(seed: [UInt8], accountIndex: Int) throws -> UnifiedSpendingKey public func deriveUnifiedFullViewingKey(from spendingKey: UnifiedSpendingKey) throws -> UnifiedFullViewingKey

Notes on Structured Concurrency

CompactBlockProcessor is now an Swift Actor. This makes it more robust and have its own async environment.

SDK Clients will likely be affected by some async methods on SDKSynchronizer.

We recommend clients that don't support structured concurrency features, to work around this by surrounding the these function calls either in @MainActor contexts either by marking callers as @MainActor or launching tasks on that actor with Task { @MainActor in ... }