Trait zcash_client_backend::data_api::WalletWrite

pub trait WalletWrite: WalletRead {
    type UtxoRef;

    // Required methods
    fn create_account(
        &mut self,
        seed: &SecretVec<u8>,
        birthday: AccountBirthday
    ) -> Result<(AccountId, UnifiedSpendingKey), Self::Error>;
    fn get_next_available_address(
        &mut self,
        account: AccountId
    ) -> Result<Option<UnifiedAddress>, Self::Error>;
    fn put_blocks(
        &mut self,
        blocks: Vec<ScannedBlock<Nullifier>>
    ) -> Result<(), Self::Error>;
    fn update_chain_tip(
        &mut self,
        tip_height: BlockHeight
    ) -> Result<(), Self::Error>;
    fn store_decrypted_tx(
        &mut self,
        received_tx: DecryptedTransaction<'_>
    ) -> Result<(), Self::Error>;
    fn store_sent_tx(
        &mut self,
        sent_tx: &SentTransaction<'_>
    ) -> Result<(), Self::Error>;
    fn truncate_to_height(
        &mut self,
        block_height: BlockHeight
    ) -> Result<(), Self::Error>;
    fn put_received_transparent_utxo(
        &mut self,
        output: &WalletTransparentOutput
    ) -> Result<Self::UtxoRef, Self::Error>;
}

This trait encapsulates the write capabilities required to update stored wallet data.

Required Associated Types

type UtxoRef

The type of identifiers used to look up transparent UTXOs.

Required Methods

fn create_account( &mut self, seed: &SecretVec<u8>, birthday: AccountBirthday ) -> Result<(AccountId, UnifiedSpendingKey), Self::Error>

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

Returns the account identifier for the newly-created wallet database entry, along with the associated [UnifiedSpendingKey].

If birthday.height() is below the current chain tip, this operation will trigger a re-scan of the blocks at and above the provided height. The birthday height is defined as the minimum block height that will be scanned for funds belonging to the wallet.

For new wallets, callers should construct the AccountBirthday using AccountBirthday::from_treestate for the block at height chain_tip_height - 100. Setting the birthday height to a tree state below the pruning depth ensures that reorgs cannot cause funds intended for the wallet to be missed; otherwise, if the chain tip height were used for the wallet birthday, a transaction targeted at a height greater than the chain tip could be mined at a height below that tip as part of a reorg.

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 confirmed funds have been received by the currently-available account (in order to enable automated account recovery).

fn get_next_available_address( &mut self, account: AccountId ) -> Result<Option<UnifiedAddress>, Self::Error>

Generates and persists the next available diversified address, given the current addresses known to the wallet.

Returns Ok(None) if the account identifier does not correspond to a known account.

fn put_blocks( &mut self, blocks: Vec<ScannedBlock<Nullifier>> ) -> Result<(), Self::Error>

Updates the state of the wallet database by persisting the provided block information, along with the note commitments that were detected when scanning the block for transactions pertaining to this wallet.

blocks must be sequential, in order of increasing block height

fn update_chain_tip( &mut self, tip_height: BlockHeight ) -> Result<(), Self::Error>

Updates the wallet’s view of the blockchain.

This method is used to provide the wallet with information about the state of the blockchain, and detect any previously scanned data that needs to be re-validated before proceeding with scanning. It should be called at wallet startup prior to calling WalletRead::suggest_scan_ranges in order to provide the wallet with the information it needs to correctly prioritize scanning operations.

fn store_decrypted_tx( &mut self, received_tx: DecryptedTransaction<'_> ) -> Result<(), Self::Error>

Caches a decrypted transaction in the persistent wallet store.

fn store_sent_tx( &mut self, sent_tx: &SentTransaction<'_> ) -> Result<(), Self::Error>

Saves information about a transaction that was constructed and sent by the wallet to the persistent wallet store.

fn truncate_to_height( &mut self, block_height: BlockHeight ) -> Result<(), Self::Error>

Truncates the wallet database to the specified height.

This method assumes that the state of the underlying data store is consistent up to a particular block height. Since it is possible that a chain reorg might invalidate some stored state, this method must be implemented in order to allow users of this API to “reset” the data store to correctly represent chainstate as of a specified block height.

After calling this method, the block at the given height will be the most recent block and all other operations will treat this block as the chain tip for balance determination purposes.

There may be restrictions on heights to which it is possible to truncate.

fn put_received_transparent_utxo( &mut self, output: &WalletTransparentOutput ) -> Result<Self::UtxoRef, Self::Error>

Adds a transparent UTXO received by the wallet to the data store.

Implementors