13 KiB
13 KiB
zcash-android-wallet-sdk / cash.z.ecc.android.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.
Properties
| Name | Summary |
|---|---|
| balances | A stream of balance values, separately reflecting both the available and total balance.val balances: Flow<WalletBalance> |
| channel | The channel that this Synchronizer uses to communicate with lightwalletd. In most cases, this should not be needed or used. Instead, APIs should be added to the synchronizer to enable the desired behavior. In the rare case, such as testing, it can be helpful to share the underlying channel to connect to the same service, and use other APIs (such as darksidewalletd) because channels are heavyweight.val channel: ManagedChannel |
| clearedTransactions | A flow of all the transactions that are on the blockchain.val clearedTransactions: Flow<PagedList<ConfirmedTransaction>> |
| 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 coordinates with isStarted so that it fails early rather than silently, whenever the scope is used before the Synchronizer has been started.var coroutineScope: CoroutineScope |
| isStarted | var isStarted: Boolean |
| latestBalance | Convenience function for the latest balance. Instead of using this, a wallet will more likely want to consume the flow of balances using balances.val latestBalance: WalletBalance |
| latestHeight | Convenience function for the latest height. Specifically, this value represents the last height that the synchronizer has observed from the lightwalletd server. Instead of using this, a wallet will more likely want to consume the flow of processor info using processorInfo.val latestHeight: Int |
| onChainErrorHandler | A callback to invoke whenever a chain error is encountered. These occur whenever the processor detects a missing or non-chain-sequential block (i.e. a reorg).var onChainErrorHandler: ((errorHeight: Int, rewindHeight: Int) -> Any)? |
| onCriticalErrorHandler | 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.var onCriticalErrorHandler: ((Throwable?) -> Boolean)? |
| onProcessorErrorHandler | 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.var onProcessorErrorHandler: ((Throwable?) -> Boolean)? |
| onSubmissionErrorHandler | 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.var onSubmissionErrorHandler: ((Throwable?) -> Boolean)? |
| pendingTransactions | A flow of all the outbound pending transaction that have been sent but are awaiting confirmations.val pendingTransactions: Flow<List<PendingTransaction>> |
| processor | saves the downloaded compact blocks to the cache and then scans those blocks for data related to this wallet.val processor: 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.val processorInfo: Flow<ProcessorInfo> |
| progress | 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.val progress: Flow<Int> |
| receivedTransactions | A flow of all transactions related to receiving funds.val receivedTransactions: Flow<PagedList<ConfirmedTransaction>> |
| sentTransactions | A flow of all transactions related to sending funds.val sentTransactions: Flow<PagedList<ConfirmedTransaction>> |
| 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.val status: Flow<Status> |
Functions
| Name | Summary |
|---|---|
| cancelSpend | 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.suspend fun cancelSpend(transaction: PendingTransaction): Boolean |
| findBlockHash | fun findBlockHash(height: Int): ByteArray? |
| findBlockHashAsHex | fun findBlockHashAsHex(height: Int): String? |
| getAddress | Gets the address for the given account.suspend fun getAddress(accountId: Int): String |
| getServerInfo | Convenience function that exposes the underlying server information, like its name and consensus branch id. Most wallets should already have a different source of truth for the server(s) with which they operate.suspend fun getServerInfo(): <ERROR CLASS> |
| getTransactionCount | fun getTransactionCount(): Int |
| isValidShieldedAddr | Returns true when the given address is a valid z-addr. Invalid addresses will throw an exception. Valid z-addresses have these characteristics: //TODO copy info from related ZIPsuspend fun isValidShieldedAddr(address: String): Boolean |
| isValidTransparentAddr | Returns true when the given address is a valid t-addr. Invalid addresses will throw an exception. Valid t-addresses have these characteristics: //TODO copy info from related ZIPsuspend fun isValidTransparentAddr(address: String): Boolean |
| refreshBalance | Calculate the latest balance, based on the blocks that have been scanned and transmit this information into the flow of balances.suspend fun refreshBalance(): Unit |
| sendToAddress | Sends zatoshi.fun sendToAddress(spendingKey: String, zatoshi: Long, toAddress: String, memo: String, fromAccountIndex: Int): Flow<PendingTransaction> |
| start | 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.fun start(parentScope: CoroutineScope?): Synchronizer |
| stop | 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.fun stop(): Unit |
| validateAddress | Validates the given address, returning information about why it is invalid. This is a convenience method that combines the behavior of isValidShieldedAddr and isValidTransparentAddr into one call so that the developer doesn't have to worry about handling the exceptions that they throw. Rather, exceptions are converted to AddressType.Invalid which has a reason property describing why it is invalid.suspend fun validateAddress(address: String): AddressType |
| validateConsensusBranch | Validate whether the server and this SDK share the same consensus branch. This is particularly important to check around network updates so that any wallet that's connected to an incompatible server can surface that information effectively. For the SDK, the consensus branch is used when creating transactions as each one needs to target a specific branch. This function compares the server's branch id to this SDK's and returns information that helps determine whether they match.suspend fun validateConsensusBranch(): ConsensusMatchType |