2019-01-02 21:31:12 -08:00
|
|
|
package cash.z.wallet.sdk.data
|
|
|
|
|
2019-07-14 15:13:12 -07:00
|
|
|
import cash.z.wallet.sdk.entity.ClearedTransaction
|
|
|
|
import cash.z.wallet.sdk.entity.PendingTransaction
|
|
|
|
import cash.z.wallet.sdk.entity.SentTransaction
|
2019-02-26 14:36:08 -08:00
|
|
|
import cash.z.wallet.sdk.secure.Wallet
|
2019-02-14 13:43:06 -08:00
|
|
|
import kotlinx.coroutines.CoroutineScope
|
2019-01-02 21:31:12 -08:00
|
|
|
import kotlinx.coroutines.channels.ReceiveChannel
|
|
|
|
|
2019-03-28 23:04:25 -07:00
|
|
|
/**
|
|
|
|
* Primary interface for interacting with the SDK. Defines the contract that specific implementations like
|
2019-07-14 15:13:12 -07:00
|
|
|
* [MockSynchronizer] and [StableSynchronizer] fulfill. Given the language-level support for coroutines, we favor their
|
|
|
|
* use in the SDK and incorporate that choice into this contract.
|
2019-03-28 23:04:25 -07:00
|
|
|
*/
|
2019-02-14 13:43:06 -08:00
|
|
|
interface Synchronizer {
|
2019-01-02 21:31:12 -08:00
|
|
|
|
2019-07-14 15:13:12 -07:00
|
|
|
//
|
|
|
|
// Lifecycle
|
|
|
|
//
|
|
|
|
|
2019-03-28 23:04:25 -07:00
|
|
|
/**
|
|
|
|
* Starts this synchronizer within the given scope.
|
|
|
|
*
|
|
|
|
* @param parentScope the scope to use for this synchronizer, typically something with a lifecycle such as an
|
|
|
|
* Activity. Implementations should leverage structured concurrency and cancel all jobs when this scope completes.
|
|
|
|
*/
|
2019-02-14 13:43:06 -08:00
|
|
|
fun start(parentScope: CoroutineScope): Synchronizer
|
2019-03-28 23:04:25 -07:00
|
|
|
|
|
|
|
/**
|
2019-07-14 15:13:12 -07:00
|
|
|
* Stop this synchronizer. Implementations should ensure that calling this method cancels all jobs that were created
|
|
|
|
* by this instance.
|
2019-03-28 23:04:25 -07:00
|
|
|
*/
|
2019-02-14 13:43:06 -08:00
|
|
|
fun stop()
|
2019-01-23 02:45:26 -08:00
|
|
|
|
2019-03-28 23:04:25 -07:00
|
|
|
|
2019-07-14 15:13:12 -07:00
|
|
|
//
|
|
|
|
// Channels
|
|
|
|
//
|
2019-03-28 23:04:25 -07:00
|
|
|
|
|
|
|
/**
|
2019-07-14 15:13:12 -07:00
|
|
|
* A stream of balance values, separately reflecting both the available and total balance.
|
2019-03-28 23:04:25 -07:00
|
|
|
*/
|
2019-07-14 15:13:12 -07:00
|
|
|
fun balances(): ReceiveChannel<Wallet.WalletBalance>
|
2019-03-28 23:04:25 -07:00
|
|
|
|
|
|
|
/**
|
2019-07-14 15:13:12 -07:00
|
|
|
* A stream of progress values, typically corresponding to this Synchronizer downloading blocks. Typically, any non-
|
|
|
|
* zero value below 100 indicates that progress indicators can be shown and a value of 100 signals that progress is
|
|
|
|
* complete and any progress indicators can be hidden.
|
2019-03-28 23:04:25 -07:00
|
|
|
*/
|
2019-07-14 15:13:12 -07:00
|
|
|
fun progress(): ReceiveChannel<Int>
|
2019-03-28 23:04:25 -07:00
|
|
|
|
|
|
|
/**
|
2019-07-14 15:13:12 -07:00
|
|
|
* A stream of all the outbound pending transaction that have been sent but are awaiting confirmations.
|
2019-03-28 23:04:25 -07:00
|
|
|
*/
|
2019-07-14 15:13:12 -07:00
|
|
|
fun pendingTransactions(): ReceiveChannel<List<PendingTransaction>>
|
2019-03-28 23:04:25 -07:00
|
|
|
|
|
|
|
/**
|
2019-07-14 15:13:12 -07:00
|
|
|
* A stream of all the transactions that are on the blockchain. Implementations should consider only returning a
|
|
|
|
* subset like the most recent 100 transactions, perhaps through paging the underlying database.
|
2019-03-28 23:04:25 -07:00
|
|
|
*/
|
2019-07-14 15:13:12 -07:00
|
|
|
fun clearedTransactions(): ReceiveChannel<List<ClearedTransaction>>
|
2019-01-23 02:45:26 -08:00
|
|
|
|
2019-07-14 15:13:12 -07:00
|
|
|
/**
|
|
|
|
* Holds the most recent value that was transmitted through the [pendingTransactions] channel. Typically, if the
|
|
|
|
* underlying channel is a BroadcastChannel (and it should be),then this value is simply [pendingChannel.value]
|
|
|
|
*/
|
|
|
|
fun lastPending(): List<PendingTransaction>
|
2019-03-28 23:04:25 -07:00
|
|
|
|
2019-07-14 15:13:12 -07:00
|
|
|
/**
|
|
|
|
* Holds the most recent value that was transmitted through the [clearedTransactions] channel. Typically, if the
|
|
|
|
* underlying channel is a BroadcastChannel (and it should be), then this value is simply [clearedChannel.value]
|
|
|
|
*/
|
|
|
|
fun lastCleared(): List<ClearedTransaction>
|
2019-03-28 23:04:25 -07:00
|
|
|
|
|
|
|
/**
|
2019-07-14 15:13:12 -07:00
|
|
|
* Holds the most recent value that was transmitted through the [balances] channel. Typically, if the
|
|
|
|
* underlying channel is a BroadcastChannel (and it should be), then this value is simply [balanceChannel.value]
|
2019-03-28 23:04:25 -07:00
|
|
|
*/
|
2019-07-14 15:13:12 -07:00
|
|
|
fun lastBalance(): Wallet.WalletBalance
|
|
|
|
|
|
|
|
|
|
|
|
//
|
|
|
|
// Status
|
|
|
|
//
|
2019-03-28 23:04:25 -07:00
|
|
|
|
2019-02-24 15:59:07 -08:00
|
|
|
/**
|
2019-07-14 15:13:12 -07:00
|
|
|
* A flag indicating whether this Synchronizer is connected to its lightwalletd server. When false, a UI element
|
|
|
|
* may want to turn red.
|
2019-02-24 15:59:07 -08:00
|
|
|
*/
|
2019-07-14 15:13:12 -07:00
|
|
|
val isConnected: Boolean
|
2019-01-23 02:45:26 -08:00
|
|
|
|
2019-03-28 23:04:25 -07:00
|
|
|
|
2019-07-14 15:13:12 -07:00
|
|
|
/**
|
|
|
|
* A flag indicating whether this Synchronizer is actively downloading compact blocks. When true, a UI element
|
|
|
|
* may want to turn yellow.
|
|
|
|
*/
|
|
|
|
val isSyncing: Boolean
|
2019-03-28 23:04:25 -07:00
|
|
|
|
|
|
|
/**
|
2019-07-14 15:13:12 -07:00
|
|
|
* A flag indicating whether this Synchronizer is actively decrypting compact blocks, searching for transactions.
|
|
|
|
* When true, a UI element may want to turn yellow.
|
2019-03-28 23:04:25 -07:00
|
|
|
*/
|
2019-07-14 15:13:12 -07:00
|
|
|
val isScanning: Boolean
|
|
|
|
|
|
|
|
|
|
|
|
//
|
|
|
|
// Operations
|
|
|
|
//
|
2019-03-28 23:04:25 -07:00
|
|
|
|
2019-04-23 23:44:51 -07:00
|
|
|
/**
|
2019-07-14 15:13:12 -07:00
|
|
|
* Gets the address for the given account.
|
2019-04-23 23:44:51 -07:00
|
|
|
*
|
2019-07-14 15:13:12 -07:00
|
|
|
* @param accountId the optional accountId whose address is of interest. By default, the first account is used.
|
2019-04-23 23:44:51 -07:00
|
|
|
*/
|
2019-07-14 15:13:12 -07:00
|
|
|
suspend fun getAddress(accountId: Int = 0): String
|
2019-04-23 23:44:51 -07:00
|
|
|
|
2019-03-28 23:04:25 -07:00
|
|
|
/**
|
|
|
|
* Sends zatoshi.
|
|
|
|
*
|
|
|
|
* @param zatoshi the amount of zatoshi to send.
|
|
|
|
* @param toAddress the recipient's address.
|
|
|
|
* @param memo the optional memo to include as part of the transaction.
|
|
|
|
* @param fromAccountId the optional account id to use. By default, the first account is used.
|
|
|
|
*/
|
2019-07-14 15:13:12 -07:00
|
|
|
suspend fun sendToAddress(
|
|
|
|
zatoshi: Long,
|
|
|
|
toAddress: String,
|
|
|
|
memo: String = "",
|
|
|
|
fromAccountId: Int = 0
|
|
|
|
): PendingTransaction
|
2019-03-28 23:04:25 -07:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Attempts to cancel a previously sent transaction. Typically, cancellation is only an option if the transaction
|
|
|
|
* has not yet been submitted to the server.
|
|
|
|
*
|
|
|
|
* @param transaction the transaction to cancel.
|
|
|
|
* @return true when the cancellation request was successful. False when it is too late to cancel.
|
|
|
|
*/
|
2019-07-14 15:13:12 -07:00
|
|
|
fun cancelSend(transaction: SentTransaction): Boolean
|
|
|
|
|
|
|
|
|
|
|
|
//
|
|
|
|
// Error Handling
|
|
|
|
//
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets or sets a global error handler. This is a useful hook for handling unexpected critical errors.
|
|
|
|
*
|
|
|
|
* @return true when the error has been handled and the Synchronizer should attempt to continue. False when the
|
|
|
|
* error is unrecoverable and the Synchronizer should [stop].
|
|
|
|
*/
|
|
|
|
var onCriticalErrorHandler: ((Throwable?) -> Boolean)?
|
|
|
|
|
|
|
|
/**
|
|
|
|
* An error handler for exceptions during processing. For instance, a block might be missing or a reorg may get
|
|
|
|
* mishandled or the database may get corrupted.
|
|
|
|
*
|
|
|
|
* @return true when the error has been handled and the processor should attempt to continue. False when the
|
|
|
|
* error is unrecoverable and the processor should [stop].
|
|
|
|
*/
|
|
|
|
var onProcessorErrorHandler: ((Throwable?) -> Boolean)?
|
|
|
|
|
|
|
|
/**
|
|
|
|
* An error handler for exceptions while submitting transactions to lightwalletd. For instance, a transaction may
|
|
|
|
* get rejected because it would be a double-spend or the user might lose their cellphone signal.
|
|
|
|
*
|
|
|
|
* @return true when the error has been handled and the sender should attempt to resend. False when the
|
|
|
|
* error is unrecoverable and the sender should [stop].
|
|
|
|
*/
|
|
|
|
var onSubmissionErrorHandler: ((Throwable?) -> Boolean)?
|
2019-01-02 21:31:12 -08:00
|
|
|
}
|