zcash-android-wallet-sdk/docs/-sdk-synchronizer

zcash-android-wallet-sdk / cash.z.wallet.sdk / SdkSynchronizer

SdkSynchronizer

@ExperimentalCoroutinesApi class SdkSynchronizer : Synchronizer

A Synchronizer that attempts to remain operational, despite any number of errors that can occur. It acts as the glue that ties all the pieces of the SDK together. Each component of the SDK is designed for the potential of stand-alone usage but coordinating all the interactions is non- trivial. So the Synchronizer facilitates this, acting as reference that demonstrates how all the pieces can be tied together. Its goal is to allow a developer to focus on their app rather than the nuances of how Zcash works.

Parameters

ledger - exposes flows of wallet transaction information.

manager - manages and tracks outbound transactions.

processor - saves the downloaded compact blocks to the cache and then scans those blocks for data related to this wallet.

Properties

Name	Summary
balances	val balances: Flow<CompactBlockProcessor.WalletBalance> A stream of balance values, separately reflecting both the available and total balance.
clearedTransactions	val clearedTransactions: Flow<PagedList<ConfirmedTransaction>> A flow of all the transactions that are on the blockchain.
coroutineScope	lateinit var coroutineScope: CoroutineScope The lifespan of this Synchronizer. This scope is initialized once the Synchronizer starts because it will be a child of the parentScope that gets passed into the start function. Everything launched by this Synchronizer will be cancelled once the Synchronizer or its parentScope stops. This is a lateinit rather than nullable property so that it fails early rather than silently, whenever the scope is used before the Synchronizer has been started.
onCriticalErrorHandler	var onCriticalErrorHandler: ((Throwable?) -> Boolean)? A callback to invoke whenever an uncaught error is encountered. By definition, the return value of the function is ignored because this error is unrecoverable. The only reason the function has a return value is so that all error handlers work with the same signature which allows one function to handle all errors in simple apps. This callback is not called on the main thread so any UI work would need to switch context to the main thread.
onProcessorErrorHandler	var onProcessorErrorHandler: ((Throwable?) -> Boolean)? A callback to invoke whenever a processor error is encountered. Returning true signals that the error was handled and a retry attempt should be made, if possible. This callback is not called on the main thread so any UI work would need to switch context to the main thread.
onSubmissionErrorHandler	var onSubmissionErrorHandler: ((Throwable?) -> Boolean)? A callback to invoke whenever a server error is encountered while submitting a transaction to lightwalletd. Returning true signals that the error was handled and a retry attempt should be made, if possible. This callback is not called on the main thread so any UI work would need to switch context to the main thread.
pendingTransactions	val pendingTransactions: Flow<List<PendingTransaction>> A flow of all the outbound pending transaction that have been sent but are awaiting confirmations.
processor	val processor: CompactBlockProcessor saves the downloaded compact blocks to the cache and then scans those blocks for data related to this wallet.
processorInfo	val processorInfo: Flow<CompactBlockProcessor.ProcessorInfo> Indicates the latest information about the blocks that have been processed by the SDK. This is very helpful for conveying detailed progress and status to the user.
progress	val progress: Flow<Int> Indicates the download progress of the Synchronizer. When progress reaches 100, that signals that the Synchronizer is in sync with the network. Balances should be considered inaccurate and outbound transactions should be prevented until this sync is complete. It is a simplified version of processorInfo.
receivedTransactions	val receivedTransactions: Flow<PagedList<ConfirmedTransaction>> A flow of all transactions related to receiving funds.
sentTransactions	val sentTransactions: Flow<PagedList<ConfirmedTransaction>> A flow of all transactions related to sending funds.
status	val status: Flow<Synchronizer.Status> Indicates the status of this Synchronizer. This implementation basically simplifies the status of the processor to focus only on the high level states that matter most. Whenever the processor is finished scanning, the synchronizer updates transaction and balance info and then emits a SYNCED status.

Functions

Name	Summary
cancelSpend	suspend fun cancelSpend(transaction: PendingTransaction): Boolean 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.
getAddress	suspend fun getAddress(accountId: Int): String Gets the address for the given account.
isValidShieldedAddr	suspend fun isValidShieldedAddr(address: String): Boolean Returns true when the given address is a valid z-addr. Invalid addresses will throw an exception. Valid z-addresses have these characteristics: //TODO
isValidTransparentAddr	suspend fun isValidTransparentAddr(address: String): Boolean Returns true when the given address is a valid t-addr. Invalid addresses will throw an exception. Valid t-addresses have these characteristics: //TODO
refreshBalance	suspend fun refreshBalance(): Unit
sendToAddress	fun sendToAddress(spendingKey: String, zatoshi: Long, toAddress: String, memo: String, fromAccountIndex: Int): Flow<PendingTransaction> Sends zatoshi.
start	fun start(parentScope: CoroutineScope?): Synchronizer Starts this synchronizer within the given scope. For simplicity, attempting to start an instance that has already been started will throw a SynchronizerException.FalseStart exception. This reduces the complexity of managing resources that must be recycled. Instead, each synchronizer is designed to have a long lifespan and should be started from an activity, application or session.
stop	fun stop(): Unit Stop this synchronizer and all of its child jobs. Once a synchronizer has been stopped it should not be restarted and attempting to do so will result in an error. Also, this function will throw an exception if the synchronizer was never previously started.
validateAddress	suspend fun validateAddress(address: String): Synchronizer.AddressType Validates the given address, returning information about why it is invalid.