Package 

Class SdkSynchronizer

  • All Implemented Interfaces:
    cash.z.ecc.android.sdk.CloseableSynchronizer , cash.z.ecc.android.sdk.Synchronizer , java.io.Closeable , java.lang.AutoCloseable

    
    public final class SdkSynchronizer
     implements CloseableSynchronizer
                        

    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.

    • Method Detail

      • getExchangeRateUsd

         <ERROR CLASS> getExchangeRateUsd()

        The latest known USD/ZEC exchange rate, paired with the time it was queried.

        The rate can be initialized and refreshed by calling refreshExchangeRateUsd.

      • getStatus

         <ERROR CLASS> getStatus()

        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.

      • getProgress

         Flow<PercentDecimal> getProgress()

        Indicates the download progress of the Synchronizer.

        When progress reaches PercentDecimal.ONE_HUNDRED_PERCENT, it signals that the Synchronizer is up-to-date with the network's current chain tip. Balances should be considered inaccurate and outbound transactions should be prevented until this sync is complete.

      • getAreFundsSpendable

         Flow<Boolean> getAreFundsSpendable()

        Indicates whether are the shielded wallet balances spendable or not during the block synchronization process.

      • getNetworkHeight

         StateFlow<BlockHeight> getNetworkHeight()

        The latest height seen on the network while processing blocks. This may differ from the latest height scanned and is useful for determining block confirmations and expiration.

      • getOnCriticalErrorHandler

         Function1<Throwable, Boolean> getOnCriticalErrorHandler()

        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.

      • setOnCriticalErrorHandler

         Unit setOnCriticalErrorHandler(Function1<Throwable, Boolean> 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.

      • getOnProcessorErrorHandler

         Function1<Throwable, Boolean> getOnProcessorErrorHandler()

        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.

      • setOnProcessorErrorHandler

         Unit setOnProcessorErrorHandler(Function1<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.

      • getOnSetupErrorHandler

         Function1<Throwable, Boolean> getOnSetupErrorHandler()

        A callback to invoke whenever a processor is not setup correctly. Returning true signals that the invalid setup should be ignored. If no handler is set, then any setup error will result in a critical error. This callback is not called on the main thread so any UI work would need to switch context to the main thread.

      • setOnSetupErrorHandler

         Unit setOnSetupErrorHandler(Function1<Throwable, Boolean> onSetupErrorHandler)

        A callback to invoke whenever a processor is not setup correctly. Returning true signals that the invalid setup should be ignored. If no handler is set, then any setup error will result in a critical error. This callback is not called on the main thread so any UI work would need to switch context to the main thread.

      • getOnChainErrorHandler

         Function2<BlockHeight, BlockHeight, Object> getOnChainErrorHandler()

        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).

      • setOnChainErrorHandler

         Unit setOnChainErrorHandler(Function2<BlockHeight, BlockHeight, Object> 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).

      • getFastestServers

         Flow<FastestServersResult> getFastestServers(List<LightWalletEndpoint> servers)

        Adds the next available account-level spend authority, given the current set of ZIP 316 account identifiers known, to the wallet database.

        The caller should store the byte encoding of the returned spending key in a secure fashion. This encoding MUST NOT be exposed to users. It is an internal encoding that is inherently unstable, and only intended to be passed between the SDK and the storage backend. The caller MUST NOT allow this encoding to be exported or imported.

        If seed was imported from a backup and this method is being used to restore a previous wallet state, you should use this method to add all of the desired accounts before scanning the chain from the seed's birthday height.

        By convention, wallets should only allow a new account to be generated after funds have been received by the currently-available account (in order to enable automated account recovery).

      • closeFlow

         final Flow<Unit> closeFlow()

        A Flow-providing version of close function. This safely closes the Synchronizer together with the related components.

      • rewindToNearestHeight

         BlockHeight rewindToNearestHeight(BlockHeight height)

        Rewinds to the safest height to which we can rewind, given a desire to rewind to the height provided.

        Due to how witness incrementing works, a wallet cannot simply rewind to any arbitrary height. This handles all that complexity yet remains flexible in the future as improvements are made.

        Returns the height to which we actually rewound, or null if the rewind failed.

      • getMemos

         Flow<String> getMemos(TransactionOverview transactionOverview)

        Returns a stream of memos for a transaction. It works for both received and sent transaction.

        Note that this function internally resolves any error which comes, logs it, and then transforms it to an empty string.

        Parameters:
        transactionOverview - For which the memos will be queried
      • getTransactionsByMemoSubstring

         Flow<List<TransactionId>> getTransactionsByMemoSubstring(String query)

        Filters the current transactions based on their memos. It returns the transaction ID of those transactions whose memo contains the given query or its part. Note that white space trimming or normalization is the client's responsibility.

        Parameters:
        query - Memo or its substring
      • checkSingleUseTransparentAddress

         Boolean checkSingleUseTransparentAddress(AccountUuid accountUuid)

        Checks to find any single-use ephemeral addresses exposed in the past day that have not yet received funds, excluding any whose next check time is in the future. This will then choose the address that is most overdue for checking, retrieve any UTXOs for that address over Tor, and add them to the wallet database. If no such UTXOs are found, the check will be rescheduled following an expoential-backoff-with-jitter algorithm.

      • fetchUtxosByAddress

         Boolean fetchUtxosByAddress(AccountUuid accountUuid, String address)

        Queries the light wallet server to find any UTXOs associated with the given transparent address, and adds any UTXOs discovered to the wallet.

        This check will cover the block range starting at the exposure height for that address, if known, or otherwise at the birthday height of the specified account.

      • refreshAllBalances

         final Unit refreshAllBalances()

        Recalculate the latest balance based on the blocks that have been scanned.

      • getTorHttpClient

         HttpClient getTorHttpClient(Function1<HttpClientConfig<HttpClientEngineConfig>, Unit> config)
        Parameters:
        config - to configure HttpClient
      • importAccountByUfvk

         Account importAccountByUfvk(AccountImportSetup setup)

        Tells the wallet to track an account using a unified full viewing key.

        Returns details about the imported account, including the unique account identifier for the newly-created wallet database entry. Unlike the other account creation APIs, no spending key is returned because the wallet has no information about the mnemonic phrase from which the UFVK was derived.

        Parameters:
        setup - The account's setup information.
      • getUnifiedAddress

         String getUnifiedAddress(Account account)

        Returns the current Unified Address for this account.

        Parameters:
        account - the account whose address is of interest.
      • getCustomUnifiedAddress

         String getCustomUnifiedAddress(Account account, UnifiedAddressRequest request)

        Gets a new unified address that conforms to the specified request.

        Parameters:
        account - the account whose address is of interest.
        request - a description of the receivers to create in the newly generated address.
      • getSaplingAddress

         String getSaplingAddress(Account account)

        Returns the legacy Sapling address corresponding to the current Unified Address for this account.

        Parameters:
        account - the account whose address is of interest.
      • getTransparentAddress

         String getTransparentAddress(Account account)

        Returns the legacy transparent address corresponding to the current Unified Address for this account.

        Parameters:
        account - the account whose address is of interest.
      • proposeFulfillingPaymentUri

         Proposal proposeFulfillingPaymentUri(Account account, String uri)

        Creates a proposal for fulfilling a payment ZIP-321 URI

        Parameters:
        account - the account from which to transfer funds.
        uri - a ZIP-321 compliant payment URI String
      • proposeTransfer

         Proposal proposeTransfer(Account account, String recipient, Zatoshi amount, String memo)
        Parameters:
        account - the account from which to transfer funds.
        recipient - the recipient's address.
        amount - the amount of zatoshi to send.
        memo - the optional memo to include as part of the proposal's transactions.
      • proposeShielding

         Proposal proposeShielding(Account account, Zatoshi shieldingThreshold, String memo, String transparentReceiver)
        Parameters:
        account - the account for which to shield funds.
        shieldingThreshold - the minimum transparent balance required before a proposal will be created.
        memo - the optional memo to include as part of the proposal's transactions.
        transparentReceiver - a specific transparent receiver within the account that should be the source of transparent funds.
      • createPcztFromProposal

         Pczt createPcztFromProposal(AccountUuid accountUuid, Proposal proposal)

        Creates a partially-created (unsigned without proofs) transaction from the given proposal.

        Do not call this multiple times in parallel, or you will generate PCZT instances that, if finalized, would double-spend the same notes.

        Parameters:
        accountUuid - The account for which the proposal was created.
        proposal - The proposal for which to create the transaction.
      • redactPcztForSigner

         Pczt redactPcztForSigner(Pczt pczt)

        Redacts information from the given PCZT that is unnecessary for the Signer role.

        Parameters:
        pczt - The partially created transaction in its serialized format.
      • pcztRequiresSaplingProofs

         Boolean pcztRequiresSaplingProofs(Pczt pczt)

        Checks whether the caller needs to have downloaded the Sapling parameters.

        Parameters:
        pczt - The partially created transaction in its serialized format.
      • addProofsToPczt

         Pczt addProofsToPczt(Pczt pczt)

        Adds proofs to the given PCZT.

        Parameters:
        pczt - The partially created transaction in its serialized format.
      • createTransactionFromPczt

         Flow<TransactionSubmitResult> createTransactionFromPczt(Pczt pcztWithProofs, Pczt pcztWithSignatures)

        Takes a PCZT that has been separately proven and signed, finalizes it, and stores it in the wallet. Internally, this logic also submits and checks the newly stored and encoded transaction.

      • refreshUtxos

         Integer refreshUtxos(Account account, BlockHeight since)

        Download all UTXOs for the given account addresses and store any new ones in the database.

        Parameters:
        account - The Account, for which all addresses blocks will be downloaded.
        since - The BlockHeight, from which blocks will be downloaded.
      • isValidShieldedAddr

         Boolean isValidShieldedAddr(String address)

        Returns true when the given address is a valid z-addr. Invalid addresses will throw an exception. See valid z-addresses characteristics in related ZIP.

        Parameters:
        address - the address to validate.
      • isValidTransparentAddr

         Boolean isValidTransparentAddr(String address)

        Returns true when the given address is a valid t-addr. Invalid addresses will throw an exception. See valid t-addresses characteristics in related ZIP.

        Parameters:
        address - the address to validate.
      • isValidUnifiedAddr

         Boolean isValidUnifiedAddr(String address)

        Returns true when the given address is a valid ZIP 316 unified address.

        This method is intended for type checking (e.g. form validation). Invalid addresses will throw an exception.

        Parameters:
        address - the address to validate.
      • isValidTexAddr

         Boolean isValidTexAddr(String address)

        Returns true when the given address is a valid ZIP 320 TEX address.

        This method is intended for type checking (e.g. form validation). Invalid addresses will throw an exception. See valid t-addresses characteristics in the related ZIP.

        Parameters:
        address - the address to validate.
      • validateConsensusBranch

         ConsensusMatchType 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.

      • validateServerEndpoint

         ServerValidation validateServerEndpoint(Context context, LightWalletEndpoint endpoint)

        This function checks whether the provided server endpoint is valid. The validation is based on comparing:

        • network types,

        • sapling activation heights

        • consensus branches

        Parameters:
        context - Context
        endpoint - LightWalletEndpoint data to be validated