Struct WalletDb

pub struct WalletDb<C, P, CL, R> { /* private fields */ }

A wrapper for the SQLite connection to the wallet database, along with a capability to read the system from the clock. A WalletDb encapsulates the full set of capabilities that are required in order to implement the WalletRead, WalletWrite and WalletCommitmentTrees traits.

Implementations

impl<P, CL, R> WalletDb<Connection, P, CL, R>

pub fn for_path<F: AsRef<Path>>( path: F, params: P, clock: CL, rng: R, ) -> Result<Self, Error>

Construct a WalletDb instance that connects to the wallet database stored at the specified path.

Parameters

• path: The path to the SQLite database used to store wallet data.
• params: Parameters associated with the Zcash network that the wallet will connect to.
• clock: The clock to use in the case that the backend needs access to the system time.
• rng: The random number generation capability to be exposed by the created WalletDb instance.

impl<C, P, CL, R> WalletDb<C, P, CL, R>

pub fn with_gap_limits(self, gap_limits: GapLimits) -> Self

Available on crate feature transparent-inputs only.

Sets the gap limits to be used by the wallet in transparent address generation.

impl<C: Borrow<Connection>, P, CL, R> WalletDb<C, P, CL, R>

pub fn from_connection(conn: C, params: P, clock: CL, rng: R) -> Self

Constructs a new wrapper around the given connection.

This is provided for use cases such as connection pooling, where conn may be an &mut rusqlite::Connection.

The caller must ensure that [rusqlite::vtab::array::load_module] has been called on the connection.

Parameters

• conn: A connection to the wallet database.
• params: Parameters associated with the Zcash network that the wallet will connect to.
• clock: The clock to use in the case that the backend needs access to the system time.
• rng: The random number generation capability to be exposed by the created WalletDb instance.

impl<C: BorrowMut<Connection>, P, CL, R> WalletDb<C, P, CL, R>

pub fn transactionally<F, A, E: From<Error>>(&mut self, f: F) -> Result<A, E>

where F: FnOnce(&mut WalletDb<SqlTransaction<'_>, &P, &CL, &mut R>) -> Result<A, E>,

pub fn check_witnesses( &mut self, ) -> Result<Vec<Range<BlockHeight>>, SqliteClientError>

Attempts to construct a witness for each note belonging to the wallet that is believed by the wallet to currently be spendable, and returns a vector of the ranges that must be rescanned in order to correct missing witness data.

This method is intended for repairing wallets that broke due to bugs in shardtree.

pub fn queue_rescans( &mut self, rescan_ranges: NonEmpty<Range<BlockHeight>>, priority: ScanPriority, ) -> Result<(), SqliteClientError>

Updates the scan queue by inserting scan ranges for the given range of block heights, with the specified scanning priority.

impl<C: BorrowMut<Connection>, P, CL: Clock, R: RngCore> WalletDb<C, P, CL, R>

pub fn schedule_ephemeral_address_checks( &mut self, ) -> Result<(), SqliteClientError>

Available on crate feature transparent-inputs only.

For each ephemeral address in the wallet, ensure that the transaction data request queue contains a request for the wallet to check for UTXOs belonging to that address at some time during the next 24-hour period.

We use randomized scheduling of ephemeral address checks to ensure that a lightwalletd-compromising adversary cannot use temporal clustering to determine what ephemeral addresses belong to a given wallet.

Trait Implementations

impl<C: Borrow<Connection>, P: Parameters, CL, R> InputSource for WalletDb<C, P, CL, R>

fn get_account_metadata( &self, account_id: Self::AccountId, selector: &NoteFilter, exclude: &[Self::NoteRef], ) -> Result<AccountMeta, Self::Error>

Returns metadata for the spendable notes in the wallet.

type Error = SqliteClientError

The type of errors produced by a wallet backend.

type NoteRef = ReceivedNoteId

Backend-specific note identifier.

type AccountId = AccountUuid

Backend-specific account identifier.

fn get_spendable_note( &self, txid: &TxId, protocol: ShieldedProtocol, index: u32, ) -> Result<Option<ReceivedNote<Self::NoteRef, Note>>, Self::Error>

Fetches a spendable note by indexing into a transaction’s shielded outputs for the specified shielded protocol.

fn select_spendable_notes( &self, account: Self::AccountId, target_value: Zatoshis, sources: &[ShieldedProtocol], anchor_height: BlockHeight, exclude: &[Self::NoteRef], ) -> Result<SpendableNotes<Self::NoteRef>, Self::Error>

Returns a list of spendable notes sufficient to cover the specified target value, if possible. Only spendable notes corresponding to the specified shielded protocol will be included.

fn get_unspent_transparent_output( &self, outpoint: &OutPoint, ) -> Result<Option<WalletTransparentOutput>, Self::Error>

Fetches the transparent output corresponding to the provided outpoint.

fn get_spendable_transparent_outputs( &self, address: &TransparentAddress, target_height: BlockHeight, min_confirmations: u32, ) -> Result<Vec<WalletTransparentOutput>, Self::Error>

Returns the list of spendable transparent outputs received by this wallet at address such that, at height target_height:

impl<C: BorrowMut<Connection>, P: Parameters, CL, R> WalletCommitmentTrees for WalletDb<C, P, CL, R>

type Error = Error

type SaplingShardStore<'a> = SqliteShardStore<&'a Transaction<'a>, Node, SAPLING_SHARD_HEIGHT>

The type of the backing [ShardStore] for the Sapling note commitment tree.

type OrchardShardStore<'a> = SqliteShardStore<&'a Transaction<'a>, MerkleHashOrchard, ORCHARD_SHARD_HEIGHT>

The type of the backing [ShardStore] for the Orchard note commitment tree.

fn with_sapling_tree_mut<F, A, E>(&mut self, callback: F) -> Result<A, E>

where for<'a> F: FnMut(&'a mut ShardTree<SqliteShardStore<&'a Transaction<'a>, Node, SAPLING_SHARD_HEIGHT>, { sapling::NOTE_COMMITMENT_TREE_DEPTH }, SAPLING_SHARD_HEIGHT>) -> Result<A, E>, E: From<ShardTreeError<Self::Error>>,

Evaluates the given callback function with a reference to the Sapling note commitment tree maintained by the wallet.

fn put_sapling_subtree_roots( &mut self, start_index: u64, roots: &[CommitmentTreeRoot<Node>], ) -> Result<(), ShardTreeError<Self::Error>>

Adds a sequence of Sapling note commitment tree subtree roots to the data store.

fn with_orchard_tree_mut<F, A, E>(&mut self, callback: F) -> Result<A, E>

where for<'a> F: FnMut(&'a mut ShardTree<SqliteShardStore<&'a Transaction<'a>, MerkleHashOrchard, ORCHARD_SHARD_HEIGHT>, { _ }, ORCHARD_SHARD_HEIGHT>) -> Result<A, E>, E: From<ShardTreeError<Self::Error>>,

Evaluates the given callback function with a reference to the Orchard note commitment tree maintained by the wallet.

fn put_orchard_subtree_roots( &mut self, start_index: u64, roots: &[CommitmentTreeRoot<MerkleHashOrchard>], ) -> Result<(), ShardTreeError<Self::Error>>

Adds a sequence of Orchard note commitment tree subtree roots to the data store.

impl<P: Parameters, CL, R> WalletCommitmentTrees for WalletDb<SqlTransaction<'_>, P, CL, R>

type Error = Error

type SaplingShardStore<'a> = SqliteShardStore<&'a Transaction<'a>, Node, SAPLING_SHARD_HEIGHT>

The type of the backing [ShardStore] for the Sapling note commitment tree.

type OrchardShardStore<'a> = SqliteShardStore<&'a Transaction<'a>, MerkleHashOrchard, ORCHARD_SHARD_HEIGHT>

The type of the backing [ShardStore] for the Orchard note commitment tree.

fn with_sapling_tree_mut<F, A, E>(&mut self, callback: F) -> Result<A, E>

where for<'a> F: FnMut(&'a mut ShardTree<SqliteShardStore<&'a Transaction<'a>, Node, SAPLING_SHARD_HEIGHT>, { sapling::NOTE_COMMITMENT_TREE_DEPTH }, SAPLING_SHARD_HEIGHT>) -> Result<A, E>, E: From<ShardTreeError<Error>>,

Evaluates the given callback function with a reference to the Sapling note commitment tree maintained by the wallet.

fn put_sapling_subtree_roots( &mut self, start_index: u64, roots: &[CommitmentTreeRoot<Node>], ) -> Result<(), ShardTreeError<Self::Error>>

Adds a sequence of Sapling note commitment tree subtree roots to the data store.

fn with_orchard_tree_mut<F, A, E>(&mut self, callback: F) -> Result<A, E>

where for<'a> F: FnMut(&'a mut ShardTree<SqliteShardStore<&'a Transaction<'a>, MerkleHashOrchard, ORCHARD_SHARD_HEIGHT>, { _ }, ORCHARD_SHARD_HEIGHT>) -> Result<A, E>, E: From<ShardTreeError<Self::Error>>,

Evaluates the given callback function with a reference to the Orchard note commitment tree maintained by the wallet.

fn put_orchard_subtree_roots( &mut self, start_index: u64, roots: &[CommitmentTreeRoot<MerkleHashOrchard>], ) -> Result<(), ShardTreeError<Self::Error>>

Adds a sequence of Orchard note commitment tree subtree roots to the data store.

impl<C: Borrow<Connection>, P: Parameters, CL, R> WalletRead for WalletDb<C, P, CL, R>

type Error = SqliteClientError

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

type AccountId = AccountUuid

The type of the account identifier.

type Account = Account

The concrete account type used by this wallet backend.

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.

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.

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, request: 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.

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.

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.

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.

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.

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

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

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

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

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.

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.

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>

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 get_transparent_receivers( &self, account: Self::AccountId, include_change: bool, ) -> Result<HashMap<TransparentAddress, Option<TransparentAddressMetadata>>, Self::Error>

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

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

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.

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

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

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

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

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

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

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

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

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.

impl<C: Borrow<Connection>, P: Parameters, CL, R> WalletTest for WalletDb<C, P, CL, R>

Available on crate feature test-dependencies only.

fn get_tx_history( &self, ) -> Result<Vec<TransactionSummary<<Self as WalletRead>::AccountId>>, <Self as WalletRead>::Error>

Returns a vector of transaction summaries.

fn get_sent_note_ids( &self, txid: &TxId, protocol: ShieldedProtocol, ) -> Result<Vec<NoteId>, <Self as WalletRead>::Error>

Returns the note IDs for shielded notes sent by the wallet in a particular transaction.

fn get_sent_outputs( &self, txid: &TxId, ) -> Result<Vec<OutputOfSentTx>, <Self as WalletRead>::Error>

Returns the outputs for a transaction sent by the wallet.

fn get_checkpoint_history( &self, protocol: &ShieldedProtocol, ) -> Result<Vec<(BlockHeight, Option<Position>)>, <Self as WalletRead>::Error>

fn get_transparent_output( &self, outpoint: &OutPoint, allow_unspendable: bool, ) -> Result<Option<WalletTransparentOutput>, <Self as InputSource>::Error>

Fetches the transparent output corresponding to the provided outpoint. Allows selecting unspendable outputs for testing purposes.

fn get_notes( &self, protocol: ShieldedProtocol, ) -> Result<Vec<ReceivedNote<Self::NoteRef, Note>>, <Self as InputSource>::Error>

Returns all the notes that have been received by the wallet.

impl<C: BorrowMut<Connection>, P: Parameters, CL: Clock, R> WalletWrite for WalletDb<C, P, CL, R>

type UtxoRef = UtxoId

The type of identifiers used to look up transparent UTXOs.

fn create_account( &mut self, account_name: &str, seed: &SecretVec<u8>, birthday: &AccountBirthday, key_source: Option<&str>, ) -> Result<(Self::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.

fn import_account_hd( &mut self, account_name: &str, seed: &SecretVec<u8>, account_index: AccountId, birthday: &AccountBirthday, key_source: Option<&str>, ) -> Result<(Self::Account, UnifiedSpendingKey), Self::Error>

Tells the wallet to track a specific account index for a given seed.

fn import_account_ufvk( &mut self, account_name: &str, ufvk: &UnifiedFullViewingKey, birthday: &AccountBirthday, purpose: AccountPurpose, key_source: Option<&str>, ) -> Result<Self::Account, Self::Error>

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

fn get_next_available_address( &mut self, account_uuid: Self::AccountId, request: UnifiedAddressRequest, ) -> Result<Option<(UnifiedAddress, DiversifierIndex)>, Self::Error>

Generates, persists, and marks as exposed the next available diversified address for the specified account, given the current addresses known to the wallet.

fn get_address_for_index( &mut self, account: Self::AccountId, diversifier_index: DiversifierIndex, request: UnifiedAddressRequest, ) -> Result<Option<UnifiedAddress>, Self::Error>

Generates, persists, and marks as exposed a diversified address for the specified account at the provided diversifier index.

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

Updates the wallet’s view of the blockchain.

fn put_blocks( &mut self, from_state: &ChainState, blocks: Vec<ScannedBlock<Self::AccountId>>, ) -> 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.

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.

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

Caches a decrypted transaction in the persistent wallet store.

fn store_transactions_to_be_sent( &mut self, transactions: &[SentTransaction<'_, Self::AccountId>], ) -> Result<(), Self::Error>

Saves information about transactions constructed by the wallet to the persistent wallet store.

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

Truncates the wallet database to at most the specified height.

fn reserve_next_n_ephemeral_addresses( &mut self, account_id: Self::AccountId, n: usize, ) -> Result<Vec<(TransparentAddress, TransparentAddressMetadata)>, Self::Error>

Reserves the next n available ephemeral addresses for the given account. This cannot be undone, so as far as possible, errors associated with transaction construction should have been reported before calling this method.

fn set_transaction_status( &mut self, txid: TxId, status: TransactionStatus, ) -> Result<(), Self::Error>

Updates the wallet backend with respect to the status of a specific transaction, from the perspective of the main chain.