2019-11-14 06:38:54 -08:00
|
|
|
//
|
|
|
|
// Synchronizer.swift
|
|
|
|
// ZcashLightClientKit
|
|
|
|
//
|
|
|
|
// Created by Francisco Gindre on 11/5/19.
|
|
|
|
// Copyright © 2019 Electric Coin Company. All rights reserved.
|
|
|
|
//
|
|
|
|
|
|
|
|
import Foundation
|
|
|
|
|
2020-02-26 08:54:48 -08:00
|
|
|
/**
|
|
|
|
Represents errors thrown by a Synchronizer
|
|
|
|
*/
|
2019-11-14 06:38:54 -08:00
|
|
|
public enum SynchronizerError: Error {
|
2020-03-13 17:00:01 -07:00
|
|
|
case initFailed(message: String)
|
2019-11-14 06:38:54 -08:00
|
|
|
case syncFailed
|
2020-08-10 15:19:59 -07:00
|
|
|
case connectionFailed(message: Error)
|
2019-11-14 06:38:54 -08:00
|
|
|
case generalError(message: String)
|
2020-03-13 17:00:01 -07:00
|
|
|
case maxRetryAttemptsReached(attempts: Int)
|
2020-04-09 15:25:43 -07:00
|
|
|
case connectionError(status: Int, message: String)
|
2020-08-10 15:19:59 -07:00
|
|
|
case networkTimeout
|
|
|
|
case uncategorized(underlyingError: Error)
|
|
|
|
case criticalError
|
2020-10-08 10:00:27 -07:00
|
|
|
case parameterMissing(underlyingError: Error)
|
2019-11-14 06:38:54 -08:00
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
Primary interface for interacting with the SDK. Defines the contract that specific
|
2020-02-26 08:54:48 -08:00
|
|
|
implementations like SdkSynchronizer fulfill.
|
2019-11-14 06:38:54 -08:00
|
|
|
*/
|
|
|
|
|
|
|
|
public protocol Synchronizer {
|
|
|
|
/**
|
|
|
|
Starts this synchronizer within the given scope.
|
2020-02-26 08:54:48 -08:00
|
|
|
|
2019-11-14 06:38:54 -08:00
|
|
|
Implementations should leverage structured concurrency and
|
|
|
|
cancel all jobs when this scope completes.
|
|
|
|
*/
|
2020-03-13 17:00:01 -07:00
|
|
|
func start(retry: Bool) throws
|
2019-11-14 06:38:54 -08:00
|
|
|
|
|
|
|
/**
|
|
|
|
Stop this synchronizer. Implementations should ensure that calling this method cancels all
|
|
|
|
jobs that were created by this instance.
|
|
|
|
*/
|
|
|
|
func stop() throws
|
|
|
|
|
|
|
|
/**
|
2020-02-26 08:54:48 -08:00
|
|
|
Value representing the Status of this Synchronizer. As the status changes, a new
|
2019-11-14 06:38:54 -08:00
|
|
|
value will be emitted by KVO
|
|
|
|
*/
|
|
|
|
var status: Status { get }
|
|
|
|
|
|
|
|
/**
|
|
|
|
A flow of progress values, typically corresponding to this Synchronizer downloading blocks.
|
2020-02-26 08:54:48 -08:00
|
|
|
Typically, any non-zero value below 1.0 indicates that progress indicators can be shown and
|
2019-11-14 06:38:54 -08:00
|
|
|
a value of 1.0 signals that progress is complete and any progress indicators can be hidden. KVO Compliant
|
|
|
|
*/
|
|
|
|
var progress: Float { get }
|
2019-12-06 04:38:47 -08:00
|
|
|
|
|
|
|
/**
|
|
|
|
Gets the address for the given account.
|
2020-02-26 08:54:48 -08:00
|
|
|
- Parameter accountIndex: the optional accountId whose address is of interest. By default, the first account is used.
|
2019-12-06 04:38:47 -08:00
|
|
|
*/
|
|
|
|
func getAddress(accountIndex: Int) -> String
|
|
|
|
|
|
|
|
/**
|
|
|
|
Sends zatoshi.
|
2020-02-26 08:54:48 -08:00
|
|
|
- Parameter spendingKey: the key that allows spends to occur.
|
|
|
|
- Parameter zatoshi: the amount of zatoshi to send.
|
|
|
|
- Parameter toAddress: the recipient's address.
|
|
|
|
- Parameter memo: the optional memo to include as part of the transaction.
|
|
|
|
- Parameter accountIndex: the optional account id to use. By default, the first account is used.
|
2019-12-06 04:38:47 -08:00
|
|
|
*/
|
|
|
|
func sendToAddress(spendingKey: String, zatoshi: Int64, toAddress: String, memo: String?, from accountIndex: Int, resultBlock: @escaping (_ result: Result<PendingTransactionEntity, Error>) -> Void)
|
|
|
|
|
|
|
|
/**
|
|
|
|
Attempts to cancel a transaction that is about to be sent. Typically, cancellation is only
|
|
|
|
an option if the transaction has not yet been submitted to the server.
|
2020-02-26 08:54:48 -08:00
|
|
|
- Parameter transaction: the transaction to cancel.
|
|
|
|
- Returns: true when the cancellation request was successful. False when it is too late.
|
2019-12-06 04:38:47 -08:00
|
|
|
*/
|
|
|
|
|
|
|
|
func cancelSpend(transaction: PendingTransactionEntity) -> Bool
|
|
|
|
|
|
|
|
/**
|
|
|
|
all outbound pending transactions that have been sent but are awaiting confirmations
|
|
|
|
*/
|
|
|
|
var pendingTransactions: [PendingTransactionEntity] { get }
|
|
|
|
/**
|
|
|
|
al the transactions that are on the blockchain
|
|
|
|
*/
|
|
|
|
var clearedTransactions: [ConfirmedTransactionEntity] { get }
|
|
|
|
/**
|
|
|
|
All transactions that are related to sending funds
|
|
|
|
*/
|
|
|
|
var sentTransactions: [ConfirmedTransactionEntity] { get }
|
|
|
|
/**
|
|
|
|
all transactions related to receiving funds
|
|
|
|
*/
|
|
|
|
var receivedTransactions: [ConfirmedTransactionEntity] { get }
|
2019-12-16 14:25:45 -08:00
|
|
|
|
|
|
|
/**
|
|
|
|
a repository serving transactions in a paginated manner
|
2020-02-26 08:54:48 -08:00
|
|
|
- Parameter kind: Transaction Kind expected from this PaginatedTransactionRepository
|
2019-12-16 14:25:45 -08:00
|
|
|
*/
|
|
|
|
func paginatedTransactions(of kind: TransactionKind) -> PaginatedTransactionRepository
|
|
|
|
|
2020-10-19 17:01:46 -07:00
|
|
|
/**
|
|
|
|
Returns a list of confirmed transactions that preceed the given transaction with a limit count.
|
|
|
|
- Parameters:
|
|
|
|
- from: the confirmed transaction from which the query should start from or nil to retrieve from the most recent transaction
|
|
|
|
- limit: the maximum amount of items this should return if available
|
|
|
|
- Returns: an array with the given Transactions or nil
|
|
|
|
|
|
|
|
*/
|
|
|
|
func allConfirmedTransactions(from transaction: ConfirmedTransactionEntity?, limit: Int) throws -> [ConfirmedTransactionEntity]?
|
|
|
|
|
2020-10-06 16:35:17 -07:00
|
|
|
/**
|
|
|
|
gets the latest downloaded height from the compact block cache
|
|
|
|
*/
|
|
|
|
func latestDownloadedHeight() throws -> BlockHeight
|
|
|
|
|
|
|
|
/**
|
|
|
|
Gets the latest block height from the provided Lightwallet endpoint
|
|
|
|
*/
|
|
|
|
func latestHeight(result: @escaping (Result<BlockHeight, Error>) -> Void)
|
|
|
|
|
|
|
|
/**
|
|
|
|
Gets the latest block height from the provided Lightwallet endpoint
|
|
|
|
Blocking
|
|
|
|
*/
|
|
|
|
func latestHeight() throws -> BlockHeight
|
2020-12-11 12:15:29 -08:00
|
|
|
|
|
|
|
/**
|
|
|
|
Gets the latest UTXOs for the given t-address and caches the result
|
|
|
|
*/
|
|
|
|
func latestUTXOs(address: String, result: @escaping (Result<[UnspentTransactionOutputEntity], Error>) -> Void)
|
|
|
|
|
|
|
|
/**
|
|
|
|
gets the latest cached UTXOs for the given t-address for the given address
|
|
|
|
*/
|
|
|
|
func cachedUTXOs(address: String) throws -> [UnspentTransactionOutputEntity]
|
|
|
|
|
2019-11-14 06:38:54 -08:00
|
|
|
}
|
|
|
|
|
2020-02-26 08:54:48 -08:00
|
|
|
/**
|
|
|
|
The Status of the synchronizer
|
|
|
|
*/
|
2019-11-14 06:38:54 -08:00
|
|
|
public enum Status {
|
|
|
|
|
|
|
|
/**
|
|
|
|
Indicates that [stop] has been called on this Synchronizer and it will no longer be used.
|
|
|
|
*/
|
|
|
|
case stopped
|
|
|
|
|
|
|
|
/**
|
|
|
|
Indicates that this Synchronizer is disconnected from its lightwalletd server.
|
|
|
|
When set, a UI element may want to turn red.
|
|
|
|
*/
|
|
|
|
case disconnected
|
|
|
|
|
|
|
|
/**
|
|
|
|
Indicates that this Synchronizer is not yet synced and therefore should not broadcast
|
|
|
|
transactions because it does not have the latest data. When set, a UI element may want
|
|
|
|
to turn yellow.
|
|
|
|
*/
|
|
|
|
case syncing
|
|
|
|
|
|
|
|
/**
|
|
|
|
Indicates that this Synchronizer is fully up to date and ready for all wallet functions.
|
|
|
|
When set, a UI element may want to turn green.
|
|
|
|
*/
|
|
|
|
case synced
|
|
|
|
}
|
2019-12-16 14:25:45 -08:00
|
|
|
|
2020-02-26 08:54:48 -08:00
|
|
|
/**
|
|
|
|
Kind of transactions handled by a Synchronizer
|
|
|
|
*/
|
2019-12-16 14:25:45 -08:00
|
|
|
public enum TransactionKind {
|
|
|
|
case sent
|
|
|
|
case received
|
|
|
|
case all
|
|
|
|
}
|