From 129ac4398e86a62abd73056d55c26ba947dd5ef6 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Fri, 8 Mar 2024 00:41:58 +0000 Subject: [PATCH] Add missing changes to protocols for `Synchronizer` wrappers --- .../ClosureSynchronizer.swift | 59 +++++++++++++++++++ .../CombineSynchronizer.swift | 56 ++++++++++++++++++ 2 files changed, 115 insertions(+) diff --git a/Sources/ZcashLightClientKit/ClosureSynchronizer.swift b/Sources/ZcashLightClientKit/ClosureSynchronizer.swift index 66ad1d22..18d9b1ea 100644 --- a/Sources/ZcashLightClientKit/ClosureSynchronizer.swift +++ b/Sources/ZcashLightClientKit/ClosureSynchronizer.swift @@ -36,6 +36,64 @@ public protocol ClosureSynchronizer { func getUnifiedAddress(accountIndex: Int, completion: @escaping (Result) -> Void) func getTransparentAddress(accountIndex: Int, completion: @escaping (Result) -> Void) + /// Creates a proposal for transferring funds to the given recipient. + /// + /// - Parameter accountIndex: the account from which to transfer funds. + /// - Parameter recipient: the recipient's address. + /// - Parameter amount: the amount to send in Zatoshi. + /// - Parameter memo: an optional memo to include as part of the proposal's transactions. Use `nil` when sending to transparent receivers otherwise the function will throw an error. + /// + /// If `prepare()` hasn't already been called since creation of the synchronizer instance or since the last wipe then this method throws + /// `SynchronizerErrors.notPrepared`. + func proposeTransfer( + accountIndex: Int, + recipient: Recipient, + amount: Zatoshi, + memo: Memo?, + completion: @escaping (Result) -> Void + ) + + /// Creates a proposal for shielding any transparent funds received by the given account. + /// + /// - Parameter accountIndex: the account for which to shield funds. + /// - Parameter shieldingThreshold: the minimum transparent balance required before a proposal will be created. + /// - Parameter memo: an optional memo to include as part of the proposal's transactions. + /// - 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. + /// + /// Returns the proposal, or `nil` if the transparent balance that would be shielded + /// is zero or below `shieldingThreshold`. + /// + /// If `prepare()` hasn't already been called since creation of the synchronizer instance or since the last wipe then this method throws + /// `SynchronizerErrors.notPrepared`. + func proposeShielding( + accountIndex: Int, + shieldingThreshold: Zatoshi, + memo: Memo, + transparentReceiver: TransparentAddress?, + completion: @escaping (Result) -> Void + ) + + /// Creates the transactions in the given proposal. + /// + /// - Parameter proposal: the proposal for which to create transactions. + /// - Parameter spendingKey: the `UnifiedSpendingKey` associated with the account for which the proposal was created. + /// + /// Returns a stream of objects for the transactions that were created as part of the + /// proposal, indicating whether they were submitted to the network or if an error + /// occurred. + /// + /// If `prepare()` hasn't already been called since creation of the synchronizer instance + /// or since the last wipe then this method throws `SynchronizerErrors.notPrepared`. + func createProposedTransactions( + proposal: Proposal, + spendingKey: UnifiedSpendingKey, + completion: @escaping (Result, Error>) -> Void + ) + + @available(*, deprecated, message: "Upcoming SDK 2.1 will create multiple transactions at once for some recipients.") func sendToAddress( spendingKey: UnifiedSpendingKey, zatoshi: Zatoshi, @@ -44,6 +102,7 @@ public protocol ClosureSynchronizer { completion: @escaping (Result) -> Void ) + @available(*, deprecated, message: "Upcoming SDK 2.1 will create multiple transactions at once for some recipients.") func shieldFunds( spendingKey: UnifiedSpendingKey, memo: Memo, diff --git a/Sources/ZcashLightClientKit/CombineSynchronizer.swift b/Sources/ZcashLightClientKit/CombineSynchronizer.swift index 2581af68..324e5336 100644 --- a/Sources/ZcashLightClientKit/CombineSynchronizer.swift +++ b/Sources/ZcashLightClientKit/CombineSynchronizer.swift @@ -35,6 +35,61 @@ public protocol CombineSynchronizer { func getUnifiedAddress(accountIndex: Int) -> SinglePublisher func getTransparentAddress(accountIndex: Int) -> SinglePublisher + /// Creates a proposal for transferring funds to the given recipient. + /// + /// - Parameter accountIndex: the account from which to transfer funds. + /// - Parameter recipient: the recipient's address. + /// - Parameter amount: the amount to send in Zatoshi. + /// - Parameter memo: an optional memo to include as part of the proposal's transactions. Use `nil` when sending to transparent receivers otherwise the function will throw an error. + /// + /// If `prepare()` hasn't already been called since creation of the synchronizer instance or since the last wipe then this method throws + /// `SynchronizerErrors.notPrepared`. + func proposeTransfer( + accountIndex: Int, + recipient: Recipient, + amount: Zatoshi, + memo: Memo? + ) -> SinglePublisher + + /// Creates a proposal for shielding any transparent funds received by the given account. + /// + /// - Parameter accountIndex: the account for which to shield funds. + /// - Parameter shieldingThreshold: the minimum transparent balance required before a proposal will be created. + /// - Parameter memo: an optional memo to include as part of the proposal's transactions. + /// - 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. + /// + /// Returns the proposal, or `nil` if the transparent balance that would be shielded + /// is zero or below `shieldingThreshold`. + /// + /// If `prepare()` hasn't already been called since creation of the synchronizer instance or since the last wipe then this method throws + /// `SynchronizerErrors.notPrepared`. + func proposeShielding( + accountIndex: Int, + shieldingThreshold: Zatoshi, + memo: Memo, + transparentReceiver: TransparentAddress? + ) -> SinglePublisher + + /// Creates the transactions in the given proposal. + /// + /// - Parameter proposal: the proposal for which to create transactions. + /// - Parameter spendingKey: the `UnifiedSpendingKey` associated with the account for which the proposal was created. + /// + /// Returns a stream of objects for the transactions that were created as part of the + /// proposal, indicating whether they were submitted to the network or if an error + /// occurred. + /// + /// If `prepare()` hasn't already been called since creation of the synchronizer instance + /// or since the last wipe then this method throws `SynchronizerErrors.notPrepared`. + func createProposedTransactions( + proposal: Proposal, + spendingKey: UnifiedSpendingKey + ) -> SinglePublisher, Error> + + @available(*, deprecated, message: "Upcoming SDK 2.1 will create multiple transactions at once for some recipients.") func sendToAddress( spendingKey: UnifiedSpendingKey, zatoshi: Zatoshi, @@ -42,6 +97,7 @@ public protocol CombineSynchronizer { memo: Memo? ) -> SinglePublisher + @available(*, deprecated, message: "Upcoming SDK 2.1 will create multiple transactions at once for some recipients.") func shieldFunds( spendingKey: UnifiedSpendingKey, memo: Memo,