Trait WalletRead

pub trait WalletRead {
    type Error: Debug;
    type AccountId: Copy + Debug + Eq + Hash;
    type Account: Account<AccountId = Self::AccountId>;

    // Required methods
    fn get_account_ids(&self) -> Result<Vec<Self::AccountId>, Self::Error>;
    fn get_account(
        &self,
        account_id: Self::AccountId,
    ) -> Result<Option<Self::Account>, Self::Error>;
    fn get_derived_account(
        &self,
        seed: &SeedFingerprint,
        account_id: AccountId,
    ) -> Result<Option<Self::Account>, Self::Error>;
    fn validate_seed(
        &self,
        account_id: Self::AccountId,
        seed: &SecretVec<u8>,
    ) -> Result<bool, Self::Error>;
    fn seed_relevance_to_derived_accounts(
        &self,
        seed: &SecretVec<u8>,
    ) -> Result<SeedRelevance<Self::AccountId>, Self::Error>;
    fn get_account_for_ufvk(
        &self,
        ufvk: &UnifiedFullViewingKey,
    ) -> Result<Option<Self::Account>, Self::Error>;
    fn list_addresses(
        &self,
        account: Self::AccountId,
    ) -> Result<Vec<AddressInfo>, Self::Error>;
    fn get_last_generated_address_matching(
        &self,
        account: Self::AccountId,
        address_filter: UnifiedAddressRequest,
    ) -> Result<Option<UnifiedAddress>, Self::Error>;
    fn get_account_birthday(
        &self,
        account: Self::AccountId,
    ) -> Result<BlockHeight, Self::Error>;
    fn get_wallet_birthday(&self) -> Result<Option<BlockHeight>, Self::Error>;
    fn get_wallet_summary(
        &self,
        min_confirmations: u32,
    ) -> Result<Option<WalletSummary<Self::AccountId>>, Self::Error>;
    fn chain_height(&self) -> Result<Option<BlockHeight>, Self::Error>;
    fn get_block_hash(
        &self,
        block_height: BlockHeight,
    ) -> Result<Option<BlockHash>, Self::Error>;
    fn block_metadata(
        &self,
        height: BlockHeight,
    ) -> Result<Option<BlockMetadata>, Self::Error>;
    fn block_fully_scanned(&self) -> Result<Option<BlockMetadata>, Self::Error>;
    fn get_max_height_hash(
        &self,
    ) -> Result<Option<(BlockHeight, BlockHash)>, Self::Error>;
    fn block_max_scanned(&self) -> Result<Option<BlockMetadata>, Self::Error>;
    fn suggest_scan_ranges(&self) -> Result<Vec<ScanRange>, Self::Error>;
    fn get_target_and_anchor_heights(
        &self,
        min_confirmations: NonZeroU32,
    ) -> Result<Option<(BlockHeight, BlockHeight)>, Self::Error>;
    fn get_tx_height(
        &self,
        txid: TxId,
    ) -> Result<Option<BlockHeight>, Self::Error>;
    fn get_unified_full_viewing_keys(
        &self,
    ) -> Result<HashMap<Self::AccountId, UnifiedFullViewingKey>, Self::Error>;
    fn get_memo(&self, note_id: NoteId) -> Result<Option<Memo>, Self::Error>;
    fn get_transaction(
        &self,
        txid: TxId,
    ) -> Result<Option<Transaction>, Self::Error>;
    fn get_sapling_nullifiers(
        &self,
        query: NullifierQuery,
    ) -> Result<Vec<(Self::AccountId, Nullifier)>, Self::Error>;
    fn get_orchard_nullifiers(
        &self,
        query: NullifierQuery,
    ) -> Result<Vec<(Self::AccountId, Nullifier)>, Self::Error>;
    fn utxo_query_height(
        &self,
        account: Self::AccountId,
    ) -> Result<BlockHeight, Self::Error>;
    fn transaction_data_requests(
        &self,
    ) -> Result<Vec<TransactionDataRequest>, Self::Error>;

    // Provided methods
    fn get_transparent_receivers(
        &self,
        _account: Self::AccountId,
        _include_change: bool,
    ) -> Result<HashMap<TransparentAddress, Option<TransparentAddressMetadata>>, Self::Error> { ... }
    fn get_transparent_balances(
        &self,
        _account: Self::AccountId,
        _max_height: BlockHeight,
    ) -> Result<HashMap<TransparentAddress, Zatoshis>, Self::Error> { ... }
    fn get_transparent_address_metadata(
        &self,
        account: Self::AccountId,
        address: &TransparentAddress,
    ) -> Result<Option<TransparentAddressMetadata>, Self::Error> { ... }
    fn get_known_ephemeral_addresses(
        &self,
        _account: Self::AccountId,
        _index_range: Option<Range<NonHardenedChildIndex>>,
    ) -> Result<Vec<(TransparentAddress, TransparentAddressMetadata)>, Self::Error> { ... }
    fn find_account_for_ephemeral_address(
        &self,
        address: &TransparentAddress,
    ) -> Result<Option<Self::AccountId>, Self::Error> { ... }
}

Read-only operations required for light wallet functions.

This trait defines the read-only portion of the storage interface atop which higher-level wallet operations are implemented. It serves to allow wallet functions to be abstracted away from any particular data storage substrate.

Required Associated Types

type Error: Debug

The type of errors that may be generated when querying a wallet data store.

type AccountId: Copy + Debug + Eq + Hash

The type of the account identifier.

An account identifier corresponds to at most a single unified spending key’s worth of spend authority, such that both received notes and change spendable by that spending authority will be interpreted as belonging to that account.

type Account: Account<AccountId = Self::AccountId>

The concrete account type used by this wallet backend.

Required Methods

fn get_account_ids(&self) -> Result<Vec<Self::AccountId>, Self::Error>

Returns a vector with the IDs of all accounts known to this wallet.

fn get_account( &self, account_id: Self::AccountId, ) -> Result<Option<Self::Account>, Self::Error>

Returns the account corresponding to the given ID, if any.

fn get_derived_account( &self, seed: &SeedFingerprint, account_id: AccountId, ) -> Result<Option<Self::Account>, Self::Error>

Returns the account corresponding to a given [SeedFingerprint] and [zip32::AccountId], if any.

fn validate_seed( &self, account_id: Self::AccountId, seed: &SecretVec<u8>, ) -> Result<bool, Self::Error>

Verifies that the given seed corresponds to the viewing key for the specified account.

Returns:

• Ok(true) if the viewing key for the specified account can be derived from the provided seed.
• Ok(false) if the derived viewing key does not match, or the specified account is not present in the database.
• Err(_) if a Unified Spending Key cannot be derived from the seed for the specified account or the account has no known ZIP-32 derivation.

fn seed_relevance_to_derived_accounts( &self, seed: &SecretVec<u8>, ) -> Result<SeedRelevance<Self::AccountId>, Self::Error>

Checks whether the given seed is relevant to any of the derived accounts (where Account::source is AccountSource::Derived) in the wallet.

This API does not check whether the seed is relevant to any imported account, because that would require brute-forcing the ZIP 32 account index space.

fn get_account_for_ufvk( &self, ufvk: &UnifiedFullViewingKey, ) -> Result<Option<Self::Account>, Self::Error>

Returns the account corresponding to a given UnifiedFullViewingKey, if any.

fn list_addresses( &self, account: Self::AccountId, ) -> Result<Vec<AddressInfo>, Self::Error>

Returns information about every address tracked for this account.

fn get_last_generated_address_matching( &self, account: Self::AccountId, address_filter: UnifiedAddressRequest, ) -> Result<Option<UnifiedAddress>, Self::Error>

Returns the most recently generated unified address for the specified account that conforms to the specified address filter, if the account identifier specified refers to a valid account for this wallet.

This will return Ok(None) if no previously generated address conforms to the specified request.

fn get_account_birthday( &self, account: Self::AccountId, ) -> Result<BlockHeight, Self::Error>

Returns the birthday height for the given account, or an error if the account is not known to the wallet.

fn get_wallet_birthday(&self) -> Result<Option<BlockHeight>, Self::Error>

Returns the birthday height for the wallet.

This returns the earliest birthday height among accounts maintained by this wallet, or Ok(None) if the wallet has no initialized accounts.

fn get_wallet_summary( &self, min_confirmations: u32, ) -> Result<Option<WalletSummary<Self::AccountId>>, Self::Error>

Returns a WalletSummary that represents the sync status, and the wallet balances given the specified minimum number of confirmations for all accounts known to the wallet; or Ok(None) if the wallet has no summary data available.

fn chain_height(&self) -> Result<Option<BlockHeight>, Self::Error>

Returns the height of the chain as known to the wallet as of the most recent call to WalletWrite::update_chain_tip.

This will return Ok(None) if the height of the current consensus chain tip is unknown.

fn get_block_hash( &self, block_height: BlockHeight, ) -> Result<Option<BlockHash>, Self::Error>

Returns the block hash for the block at the given height, if the associated block data is available. Returns Ok(None) if the hash is not found in the database.

fn block_metadata( &self, height: BlockHeight, ) -> Result<Option<BlockMetadata>, Self::Error>

Returns the available block metadata for the block at the specified height, if any.

fn block_fully_scanned(&self) -> Result<Option<BlockMetadata>, Self::Error>

Returns the metadata for the block at the height to which the wallet has been fully scanned.

This is the height for which the wallet has fully trial-decrypted this and all preceding blocks above the wallet’s birthday height. Along with this height, this method returns metadata describing the state of the wallet’s note commitment trees as of the end of that block.

fn get_max_height_hash( &self, ) -> Result<Option<(BlockHeight, BlockHash)>, Self::Error>

Returns the block height and hash for the block at the maximum scanned block height.

This will return Ok(None) if no blocks have been scanned.

fn block_max_scanned(&self) -> Result<Option<BlockMetadata>, Self::Error>

Returns block metadata for the maximum height that the wallet has scanned.

If the wallet is fully synced, this will be equivalent to block_fully_scanned; otherwise the maximal scanned height is likely to be greater than the fully scanned height due to the fact that out-of-order scanning can leave gaps.

fn suggest_scan_ranges(&self) -> Result<Vec<ScanRange>, Self::Error>

Returns a vector of suggested scan ranges based upon the current wallet state.

This method should only be used in cases where the CompactBlock data that will be made available to scan_cached_blocks for the requested block ranges includes note commitment tree size information for each block; or else the scan is likely to fail if notes belonging to the wallet are detected.

The returned range(s) may include block heights beyond the current chain tip. Ranges are returned in order of descending priority, and higher-priority ranges should always be scanned before lower-priority ranges; in particular, ranges with ScanPriority::Verify priority must always be scanned first in order to avoid blockchain continuity errors in the case of a reorg.

fn get_target_and_anchor_heights( &self, min_confirmations: NonZeroU32, ) -> Result<Option<(BlockHeight, BlockHeight)>, Self::Error>

Returns the default target height (for the block in which a new transaction would be mined) and anchor height (to use for a new transaction), given the range of block heights that the backend knows about.

This will return Ok(None) if no block data is present in the database.

fn get_tx_height(&self, txid: TxId) -> Result<Option<BlockHeight>, Self::Error>

Returns the block height in which the specified transaction was mined, or Ok(None) if the transaction is not in the main chain.

fn get_unified_full_viewing_keys( &self, ) -> Result<HashMap<Self::AccountId, UnifiedFullViewingKey>, Self::Error>

Returns all unified full viewing keys known to this wallet.

fn get_memo(&self, note_id: NoteId) -> Result<Option<Memo>, Self::Error>

Returns the memo for a note.

Returns Ok(None) if the note is known to the wallet but memo data has not yet been populated for that note, or if the note identifier does not correspond to a note that is known to the wallet.

fn get_transaction( &self, txid: TxId, ) -> Result<Option<Transaction>, Self::Error>

Returns a transaction.

fn get_sapling_nullifiers( &self, query: NullifierQuery, ) -> Result<Vec<(Self::AccountId, Nullifier)>, Self::Error>

Returns the nullifiers for Sapling notes that the wallet is tracking, along with their associated account IDs, that are either unspent or have not yet been confirmed as spent (in that a spending transaction known to the wallet has not yet been included in a block).

fn get_orchard_nullifiers( &self, query: NullifierQuery, ) -> Result<Vec<(Self::AccountId, Nullifier)>, Self::Error>

Available on crate feature orchard only.

Returns the nullifiers for Orchard notes that the wallet is tracking, along with their associated account IDs, that are either unspent or have not yet been confirmed as spent (in that a spending transaction known to the wallet has not yet been included in a block).

fn utxo_query_height( &self, account: Self::AccountId, ) -> Result<BlockHeight, Self::Error>

Available on crate feature transparent-inputs only.

Returns the maximum block height at which a transparent output belonging to the wallet has been observed.

We must start looking for UTXOs for addresses within the current gap limit as of the block height at which they might have first been revealed. This would have occurred when the gap advanced as a consequence of a transaction being mined. The address at the start of the current gap was potentially first revealed after the address at index gap_start - (gap_limit + 1) received an output in a mined transaction; therefore, we take that height to be where we should start searching for UTXOs.

fn transaction_data_requests( &self, ) -> Result<Vec<TransactionDataRequest>, Self::Error>

Returns a vector of TransactionDataRequest values that describe information needed by the wallet to complete its view of transaction history.

Requests for the same transaction data may be returned repeatedly by successive data requests. The caller of this method should consider the latest set of requests returned by this method to be authoritative and to subsume that returned by previous calls.

Callers should poll this method on a regular interval, not as part of ordinary chain scanning, which already produces requests for transaction data enhancement. Note that responding to a set of transaction data requests may result in the creation of new transaction data requests, such as when it is necessary to fill in purely-transparent transaction history by walking the chain backwards via transparent inputs.

Provided Methods

fn get_transparent_receivers( &self, _account: Self::AccountId, _include_change: bool, ) -> Result<HashMap<TransparentAddress, Option<TransparentAddressMetadata>>, Self::Error>

Available on crate feature transparent-inputs only.

Returns the set of non-ephemeral transparent receivers associated with the given account controlled by this wallet.

The set contains all non-ephemeral transparent receivers that are known to have been derived under this account. Wallets should scan the chain for UTXOs sent to these receivers.

Use Self::get_known_ephemeral_addresses to obtain the ephemeral transparent receivers.

fn get_transparent_balances( &self, _account: Self::AccountId, _max_height: BlockHeight, ) -> Result<HashMap<TransparentAddress, Zatoshis>, Self::Error>

Available on crate feature transparent-inputs only.

Returns a mapping from each transparent receiver associated with the specified account to its not-yet-shielded UTXO balance as of the end of the block at the provided max_height, when that balance is non-zero.

Balances of ephemeral transparent addresses will not be included.

fn get_transparent_address_metadata( &self, account: Self::AccountId, address: &TransparentAddress, ) -> Result<Option<TransparentAddressMetadata>, Self::Error>

Available on crate feature transparent-inputs only.

Returns the metadata associated with a given transparent receiver in an account controlled by this wallet, if available.

This is equivalent to (but may be implemented more efficiently than):

Ok(
    if let Some(result) = self.get_transparent_receivers(account, true)?.get(address) {
        result.clone()
    } else {
        self.get_known_ephemeral_addresses(account, None)?
            .into_iter()
            .find(|(known_addr, _)| known_addr == address)
            .map(|(_, metadata)| metadata)
    },
)

Returns Ok(None) if the address is not recognized, or we do not have metadata for it. Returns Ok(Some(metadata)) if we have the metadata.

fn get_known_ephemeral_addresses( &self, _account: Self::AccountId, _index_range: Option<Range<NonHardenedChildIndex>>, ) -> Result<Vec<(TransparentAddress, TransparentAddressMetadata)>, Self::Error>

Available on crate feature transparent-inputs only.

Returns a vector of ephemeral transparent addresses associated with the given account controlled by this wallet, along with their metadata. The result includes reserved addresses, and addresses for the backend’s configured gap limit worth of additional indices (capped to the maximum index).

If index_range is some Range, it limits the result to addresses with indices in that range. An index_range of None is defined to be equivalent to 0..(1u32 << 31).

Wallets should scan the chain for UTXOs sent to these ephemeral transparent receivers, but do not need to do so regularly. Under expected usage, outputs would only be detected with these receivers in the following situations:

• This wallet created a payment to a ZIP 320 (TEX) address, but the second transaction (that spent the output sent to the ephemeral address) did not get mined before it expired.

  • In this case the output will already be known to the wallet (because it stores the transactions that it creates).

• Another wallet app using the same seed phrase created a payment to a ZIP 320 address, and this wallet queried for the ephemeral UTXOs after the first transaction was mined but before the second transaction was mined.

  • In this case, the output should not be considered unspent until the expiry height of the transaction it was received in has passed. Wallets creating payments to TEX addresses generally set the same expiry height for the first and second transactions, meaning that this wallet does not need to observe the second transaction to determine when it would have expired.

• A TEX address recipient decided to return funds that the wallet had sent to them.

In all cases, the wallet should re-shield the unspent outputs, in a separate transaction per ephemeral address, before re-spending the funds.

fn find_account_for_ephemeral_address( &self, address: &TransparentAddress, ) -> Result<Option<Self::AccountId>, Self::Error>

Available on crate feature transparent-inputs only.

If a given ephemeral address might have been reserved, i.e. would be included in the result of get_known_ephemeral_addresses(account_id, None) for any of the wallet’s accounts, then return Ok(Some(account_id)). Otherwise return Ok(None).

This is equivalent to (but may be implemented more efficiently than):

for account_id in self.get_account_ids()? {
    if self
        .get_known_ephemeral_addresses(account_id, None)?
        .into_iter()
        .any(|(known_addr, _)| &known_addr == address)
    {
        return Ok(Some(account_id));
    }
}
Ok(None)

Implementors

impl WalletRead for MockWalletDb

Available on crate feature test-dependencies only.

type Error = ()

type AccountId = u32

type Account = (<MockWalletDb as WalletRead>::AccountId, UnifiedFullViewingKey)