Module data_api

Utilities for Zcash wallet construction

This module defines a set of APIs for wallet data persistence, and provides a suite of methods based upon these APIs that can be used to implement a fully functional Zcash wallet. At present, the interfaces provided here are built primarily around the use of a source of CompactBlock data such as the Zcash Light Client Protocol as defined in ZIP 307 but they may be generalized to full-block use cases in the future.

Important Concepts

There are several important operations that a Zcash wallet must perform that distinguish Zcash wallet design from wallets for other cryptocurrencies.

• Viewing Keys: Wallets based upon this module are built around the capabilities of Zcash UnifiedFullViewingKeys; the wallet backend provides no facilities for the storage of spending keys, and spending keys must be provided by the caller in order to perform transaction creation operations.
• Blockchain Scanning: A Zcash wallet must download and trial-decrypt each transaction on the Zcash blockchain using one or more Viewing Keys in order to find new shielded transaction outputs (generally termed “notes”) belonging to the wallet. The primary entrypoint for this functionality is the scan_cached_blocks method. See the chain module for additional details.
• Witness Updates: In order to spend a shielded note, the wallet must be able to compute the Merkle path to that note in the global note commitment tree. When scan_cached_blocks is used to process a range of blocks, the note commitment tree is updated with the note commitments for the blocks in that range.
• Transaction Construction: The wallet module provides functions for creating Zcash transactions that spend funds belonging to the wallet.

Core Traits

The utility functions described above depend upon four important traits defined in this module, which between them encompass the data storage requirements of a light wallet. The relevant traits are InputSource, WalletRead, WalletWrite, and WalletCommitmentTrees. A complete implementation of the data storage layer for a wallet will include an implementation of all four of these traits. See the zcash_client_sqlite crate for a complete example of the implementation of these traits.

Accounts

The operation of the InputSource, WalletRead and WalletWrite traits is built around the concept of a wallet having one or more accounts, with a unique AccountId for each account.

An account identifier corresponds to at most a single UnifiedSpendingKey’s worth of spend authority, with the received and spent notes of that account tracked via the corresponding UnifiedFullViewingKey. Both received notes and change spendable by that spending authority (both the external and internal parts of that key, as defined by ZIP 316) will be interpreted as belonging to that account.

Modules

chain

Tools for blockchain validation & scanning

error

Types for wallet error handling.

scanning

Common types used for managing a queue of scanning ranges.

testingtest-dependencies

Utilities for testing wallets based upon the crate::data_api traits.

wallet

Functions for creating Zcash transactions that spend funds belonging to the wallet

Macros

ambassador_impl_InputSource

A macro to be used by [ambassador::Delegate] to delegate InputSource

ambassador_impl_WalletCommitmentTrees

A macro to be used by [ambassador::Delegate] to delegate WalletCommitmentTrees

ambassador_impl_WalletRead

A macro to be used by [ambassador::Delegate] to delegate WalletRead

ambassador_impl_WalletTest

A macro to be used by [ambassador::Delegate] to delegate WalletTest

ambassador_impl_WalletWrite

A macro to be used by [ambassador::Delegate] to delegate WalletWrite

Structs

AccountBalance

Balance information for a single account. The sum of this struct’s fields is the total balance of the wallet.

AccountBirthday

A data structure used to set the birthday height for an account, and ensure that the initial note commitment tree state is recorded at that height.

AccountMeta

Metadata about the structure of the wallet for a particular account.

AddressInfo

Information about an address in the wallet.

Balance

Balance information for a value within a single pool in an account.

BlockMetadata

Metadata describing the sizes of the zcash note commitment trees as of a particular block.

BoundedU8

A u8 value in the range 0..=MAX

DecryptedTransaction

A transaction that was detected during scanning of the blockchain, including its decrypted Sapling and/or Orchard outputs.

OutputOfSentTxtest-dependencies

The output of a transaction sent by the wallet.

PoolMeta

Metadata about the structure of unspent outputs in a single pool within a wallet account.

Progress

A type representing the progress the wallet has made toward detecting all of the funds belonging to the wallet.

Ratio

A polymorphic ratio type, usually used for rational numbers.

ScannedBlock

The subset of information that is relevant to this wallet that has been decrypted and extracted from a CompactBlock.

ScannedBlockCommitments

A struct used to return the vectors of note commitments for a ScannedBlock as owned values.

ScannedBundles

The protocol-specific note commitment and nullifier data extracted from the per-transaction shielded bundles in CompactBlock, used by the wallet for note commitment tree maintenance and spend detection.

SentTransaction

A transaction that was constructed and sent by the wallet.

SentTransactionOutput

An output of a transaction generated by the wallet.

SpendableNotes

Spendable shielded outputs controlled by the wallet.

WalletSummary

A type representing the potentially-spendable value of unspent outputs in the wallet.

Zip32Derivation

Source metadata for a ZIP 32-derived key.

Enums

AccountPurpose

An enumeration used to control what information is tracked by the wallet for notes received by a given account.

AccountSource

The kinds of accounts supported by zcash_client_backend.

BirthdayError

Errors that can occur in the construction of an AccountBirthday from a TreeState.

NoteFilter

A small query language for filtering notes belonging to an account.

NullifierQuery

An enumeration of constraints that can be applied when querying for nullifiers for notes belonging to the wallet.

OutputStatusFiltertransparent-inputs

A type used to filter transactions to be returned in response to a TransactionDataRequest, in terms of the spentness of the transaction’s transparent outputs.

SeedRelevance

The relevance of a seed to a given wallet.

TransactionDataRequest

A request for transaction data enhancement, spentness check, or discovery of spends from a given transparent address within a specific block range.

TransactionStatus

Metadata about the status of a transaction obtained by inspecting the chain state.

TransactionStatusFiltertransparent-inputs

A type describing the mined-ness of transactions that should be returned in response to a TransactionDataRequest.

Constants

ORCHARD_SHARD_HEIGHTorchard

The height of subtree roots in the Orchard note commitment tree.

SAPLING_SHARD_HEIGHT

The height of subtree roots in the Sapling note commitment tree.

Traits

Account

A set of capabilities that a client account must provide.

InputSource

A trait representing the capability to query a data store for unspent transaction outputs belonging to a account.

NoteRetention

A predicate that can be used to choose whether or not a particular note is retained in note selection.

WalletCommitmentTrees

This trait describes a capability for manipulating wallet note commitment trees.

WalletRead

Read-only operations required for light wallet functions.

WalletTest

Read-only operations required for testing light wallet functions.

WalletWrite

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