Merge pull request #1210 from nuttycom/wallet/account_doc
zcash_client_backend: Add documentation for the `data_api` module.
This commit is contained in:
commit
af303e810a
|
@ -338,6 +338,10 @@ and this library adheres to Rust's notion of
|
|||
- `TransactionBalance::{fee_required, total}`
|
||||
- `zcash_client_backend::wallet::WalletTransparentOutput::value`
|
||||
|
||||
### Deprecated
|
||||
- `zcash_client_backend::data_api::wallet`:
|
||||
- `spend` (use `propose_transfer` and `create_proposed_transactions` instead).
|
||||
|
||||
### Removed
|
||||
- `zcash_client_backend::wallet`:
|
||||
- `ReceivedSaplingNote` (use `zcash_client_backend::ReceivedNote` instead).
|
||||
|
|
|
@ -1,4 +1,59 @@
|
|||
//! Interfaces for wallet data persistence & low-level wallet utilities.
|
||||
//! # 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](https://zips.z.cash/zip-0307) 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
|
||||
//! [`UnifiedFullViewingKey`]s; 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](https://zips.z.cash/zip-0316)) will be interpreted as belonging to that account.
|
||||
//!
|
||||
//! [`CompactBlock`]: crate::proto::compact_formats::CompactBlock
|
||||
//! [`scan_cached_blocks`]: crate::data_api::chain::scan_cached_blocks
|
||||
//! [`zcash_client_sqlite`]: https://crates.io/crates/zcash_client_sqlite
|
||||
//! [`TransactionRequest`]: crate::zip321::TransactionRequest
|
||||
//! [`propose_shielding`]: crate::data_api::wallet::propose_shielding
|
||||
|
||||
use std::{
|
||||
collections::HashMap,
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//! Common types used for managing a queue of scanning ranges.
|
||||
|
||||
use std::fmt;
|
||||
use std::ops::Range;
|
||||
|
||||
|
|
|
@ -1,3 +1,33 @@
|
|||
//! # Functions for creating Zcash transactions that spend funds belonging to the wallet
|
||||
//!
|
||||
//! This module contains several different ways of creating Zcash transactions. This module is
|
||||
//! designed around the idea that a Zcash wallet holds its funds in notes in either the Orchard
|
||||
//! or Sapling shielded pool. In order to better preserve users' privacy, it does not provide any
|
||||
//! functionality that allows users to directly spend transparent funds except by sending them to a
|
||||
//! shielded internal address belonging to their wallet.
|
||||
//!
|
||||
//! The important high-level operations provided by this module are [`propose_transfer`],
|
||||
//! [`propose_shielding`], and [`create_proposed_transactions`].
|
||||
//!
|
||||
//! [`propose_transfer`] takes a [`TransactionRequest`] object, selects inputs notes and
|
||||
//! computes the fees required to satisfy that request, and returns a [`Proposal`] object that
|
||||
//! describes the transaction to be made.
|
||||
//!
|
||||
//! [`propose_shielding`] takes a set of transparent source addresses, and constructs a
|
||||
//! [`Proposal`] to send those funds to a wallet-internal shielded address, as described in
|
||||
//! [ZIP 316](https://zips.z.cash/zip-0316).
|
||||
//!
|
||||
//! [`create_proposed_transactions`] constructs one or more Zcash [`Transaction`]s based upon a
|
||||
//! provided [`Proposal`], stores them to the wallet database, and returns the [`TxId`] for each
|
||||
//! constructed transaction to the caller. The caller can then use the
|
||||
//! [`WalletRead::get_transaction`] method to retrieve the newly constructed transactions. It is
|
||||
//! the responsibility of the caller to retrieve and serialize the transactions and submit them for
|
||||
//! inclusion into the Zcash blockchain.
|
||||
//!
|
||||
//! [`TransactionRequest`]: crate::zip321::TransactionRequest
|
||||
//! [`propose_transfer`]: crate::data_api::wallet::propose_transfer
|
||||
//! [`propose_shielding`]: crate::data_api::wallet::propose_shielding
|
||||
|
||||
use nonempty::NonEmpty;
|
||||
use rand_core::OsRng;
|
||||
use sapling::{
|
||||
|
@ -195,7 +225,7 @@ where
|
|||
#[allow(clippy::too_many_arguments)]
|
||||
#[allow(clippy::type_complexity)]
|
||||
#[deprecated(
|
||||
note = "Use `spend` instead. `create_spend_to_address` uses a fixed fee of 10000 zatoshis, which is not compliant with ZIP 317."
|
||||
note = "Use `propose_transfer` and `create_proposed_transactions` instead. `create_spend_to_address` uses a fixed fee of 10000 zatoshis, which is not compliant with ZIP 317."
|
||||
)]
|
||||
pub fn create_spend_to_address<DbT, ParamsT>(
|
||||
wallet_db: &mut DbT,
|
||||
|
@ -311,6 +341,7 @@ where
|
|||
/// [`sapling::OutputProver`]: sapling::prover::OutputProver
|
||||
#[allow(clippy::too_many_arguments)]
|
||||
#[allow(clippy::type_complexity)]
|
||||
#[deprecated(note = "Use `propose_transfer` and `create_proposed_transactions` instead.")]
|
||||
pub fn spend<DbT, ParamsT, InputsT>(
|
||||
wallet_db: &mut DbT,
|
||||
params: &ParamsT,
|
||||
|
|
|
@ -494,6 +494,7 @@ impl<Cache> TestState<Cache> {
|
|||
where
|
||||
InputsT: InputSelector<InputSource = WalletDb<Connection, Network>>,
|
||||
{
|
||||
#![allow(deprecated)]
|
||||
let params = self.network();
|
||||
let prover = test_prover();
|
||||
spend(
|
||||
|
|
Loading…
Reference in New Issue