Package 

Interface Synchronizer

    • Method Detail

      • importAccountByUfvk

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

      • getFastestServers

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

      • getUnifiedAddress

         abstract String getUnifiedAddress(Account account)

        Gets the current unified address for the given account.

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

      • getCustomUnifiedAddress

         abstract 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

         abstract String getSaplingAddress(Account account)

        Gets the legacy Sapling address corresponding to the current unified address for the given account.

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

      • getTransparentAddress

         abstract String getTransparentAddress(Account account)

        Gets the legacy transparent address corresponding to the current unified address for the given account.

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

      • proposeTransfer

         abstract Proposal proposeTransfer(Account account, String recipient, Zatoshi amount, String memo)

        Creates a proposal for transferring funds to the given recipient.

        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.

      • proposeFulfillingPaymentUri

         abstract 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

      • proposeShielding

         abstract Proposal proposeShielding(Account account, Zatoshi shieldingThreshold, String memo, String transparentReceiver)

        Creates a proposal for shielding any transparent funds received by the given account.

        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

         abstract 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

         abstract 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

         abstract 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

         abstract Pczt addProofsToPczt(Pczt pczt)

        Adds proofs to the given PCZT.

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

      • createTransactionFromPczt

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

      • isValidShieldedAddr

         abstract 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

         abstract 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

         abstract 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

         abstract 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

         abstract 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

         abstract 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

      • refreshUtxos

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

      • rewindToNearestHeight

         abstract 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

         abstract 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

         abstract 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

         abstract 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

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

      • getTorHttpClient

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

      • getNetwork

         abstract ZcashNetwork getNetwork()

        The network to which this synchronizer is connected and from which it is processing blocks.

      • getStatus

         abstract Flow<Synchronizer.Status> getStatus()

        A flow of values representing the Status of this Synchronizer. As the status changes, a new value will be emitted by this flow.

      • getProgress

         abstract 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

         abstract Flow<Boolean> getAreFundsSpendable()

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

      • getProcessorInfo

         abstract Flow<CompactBlockProcessor.ProcessorInfo> getProcessorInfo()

        A flow of processor details, updated every time blocks are processed to include the latest block height, blocks downloaded and blocks scanned. Similar to the progress flow but with a lot more detail.

      • getNetworkHeight

         abstract StateFlow<BlockHeight> getNetworkHeight()

        The latest height observed on the network, which does not necessarily correspond to the latest downloaded height or scanned height. Although this is present in processorInfo, it is such a frequently used value that it is convenient to have the real-time value by itself.

      • getLatestBirthdayHeight

         abstract BlockHeight getLatestBirthdayHeight()

        An in-memory reference to the best known birthday height, which can change if the first transaction has not yet occurred.

      • getOnProcessorErrorHandler

         abstract Function1<Throwable, Boolean> getOnProcessorErrorHandler()

        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.

      • setOnProcessorErrorHandler

         abstract Unit setOnProcessorErrorHandler(Function1<Throwable, Boolean> onProcessorErrorHandler)

        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.

      • getOnSetupErrorHandler

         abstract Function1<Throwable, Boolean> getOnSetupErrorHandler()

        Callback for setup errors that occur prior to processing compact blocks. Can be used to override any errors encountered during setup. When this listener is missing then all setup errors will result in the synchronizer not starting. This is particularly useful for wallets to receive a callback right before the SDK will reject a lightwalletd server because it appears not to match.

      • setOnSetupErrorHandler

         abstract Unit setOnSetupErrorHandler(Function1<Throwable, Boolean> onSetupErrorHandler)

        Callback for setup errors that occur prior to processing compact blocks. Can be used to override any errors encountered during setup. When this listener is missing then all setup errors will result in the synchronizer not starting. This is particularly useful for wallets to receive a callback right before the SDK will reject a lightwalletd server because it appears not to match.

      • getOnChainErrorHandler

         abstract 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). At a minimum, it is best to log these errors because they are the most common source of bugs and unexpected behavior in wallets, due to the chain data mutating and wallets becoming out of sync.

      • setOnChainErrorHandler

         abstract 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). At a minimum, it is best to log these errors because they are the most common source of bugs and unexpected behavior in wallets, due to the chain data mutating and wallets becoming out of sync.