zec
/
librustzcash
mirror of https://github.com/zcash/librustzcash.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
librustzcash/rustdoc/latest/zcash_client_backend/data_api/index.html

59 lines
23 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Utilities for Zcash wallet construction"><title>zcash_client_backend::data_api - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Italic-81dc35de.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-MediumItalic-ccf7e434.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../../static.files/rustdoc-20739d33.css"><meta name="rustdoc-vars" data-root-path="../../" data-static-root-path="../../static.files/" data-current-crate="zcash_client_backend" data-themes="" data-resource-suffix="" data-rustdoc-version="1.88.0-nightly (74509131e 2025-04-29)" data-channel="nightly" data-search-js="search-f7877310.js" data-settings-js="settings-5514c975.js" ><script src="../../static.files/storage-4e99c027.js"></script><script defer src="../sidebar-items.js"></script><script defer src="../../static.files/main-7ef8a74a.js"></script><noscript><link rel="stylesheet" href="../../static.files/noscript-893ab5e7.css"></noscript><link rel="alternate icon" type="image/png" href="../../static.files/favicon-32x32-6580c154.png"><link rel="icon" type="image/svg+xml" href="../../static.files/favicon-044be391.svg"></head><body class="rustdoc mod"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../zcash_client_backend/index.html">zcash_<wbr>client_<wbr>backend</a><span class="version">0.18.0</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">Module data_<wbr>api</a></h2><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#utilities-for-zcash-wallet-construction" title="Utilities for Zcash wallet construction">Utilities for Zcash wallet construction</a><ul><li><a href="#important-concepts" title="Important Concepts">Important Concepts</a></li><li><a href="#core-traits" title="Core Traits">Core Traits</a></li><li><a href="#accounts" title="Accounts">Accounts</a></li></ul></li></ul><h3><a href="#modules">Module Items</a></h3><ul class="block"><li><a href="#modules" title="Modules">Modules</a></li><li><a href="#macros" title="Macros">Macros</a></li><li><a href="#structs" title="Structs">Structs</a></li><li><a href="#enums" title="Enums">Enums</a></li><li><a href="#constants" title="Constants">Constants</a></li><li><a href="#traits" title="Traits">Traits</a></li></ul></section><div id="rustdoc-modnav"><h2 class="in-crate"><a href="../index.html">In crate zcash_<wbr>client_<wbr>backend</a></h2></div></div></nav><div class="sidebar-resizer"></div><main><div class="width-limiter"><rustdoc-search></rustdoc-search><section id="main-content" class="content"><div class="main-heading"><div class="rustdoc-breadcrumbs"><a href="../index.html">zcash_client_backend</a></div><h1>Module <span>data_api</span><button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../../src/zcash_client_backend/data_api.rs.html#1-2690">Source</a> </span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><h2 id="utilities-for-zcash-wallet-construction"><a class="doc-anchor" href="#utilities-for-zcash-wallet-construction">§</a>Utilities for Zcash wallet construction</h2>
<p>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
<a href="../proto/compact_formats/struct.CompactBlock.html" title="struct zcash_client_backend::proto::compact_formats::CompactBlock"><code>CompactBlock</code></a> data such as the Zcash Light Client Protocol as defined in
<a href="https://zips.z.cash/zip-0307">ZIP 307</a> but they may be generalized to full-block use cases in
the future.</p>
<h3 id="important-concepts"><a class="doc-anchor" href="#important-concepts">§</a>Important Concepts</h3>
<p>There are several important operations that a Zcash wallet must perform that distinguish Zcash
wallet design from wallets for other cryptocurrencies.</p>
<ul>
<li>Viewing Keys: Wallets based upon this module are built around the capabilities of Zcash
<a href="../keys/struct.UnifiedFullViewingKey.html" title="struct zcash_client_backend::keys::UnifiedFullViewingKey"><code>UnifiedFullViewingKey</code></a>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.</li>
<li>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 <a href="chain/fn.scan_cached_blocks.html" title="fn zcash_client_backend::data_api::chain::scan_cached_blocks"><code>scan_cached_blocks</code></a> method. See the <a href="chain/index.html" title="mod zcash_client_backend::data_api::chain"><code>chain</code></a> module for additional
details.</li>
<li>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 <a href="chain/fn.scan_cached_blocks.html" title="fn zcash_client_backend::data_api::chain::scan_cached_blocks"><code>scan_cached_blocks</code></a> is
used to process a range of blocks, the note commitment tree is updated with the note
commitments for the blocks in that range.</li>
<li>Transaction Construction: The <a href="wallet/index.html" title="mod zcash_client_backend::data_api::wallet"><code>wallet</code></a> module provides functions for creating Zcash
transactions that spend funds belonging to the wallet.</li>
</ul>
<h3 id="core-traits"><a class="doc-anchor" href="#core-traits">§</a>Core Traits</h3>
<p>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 <a href="trait.InputSource.html" title="trait zcash_client_backend::data_api::InputSource"><code>InputSource</code></a>, <a href="trait.WalletRead.html" title="trait zcash_client_backend::data_api::WalletRead"><code>WalletRead</code></a>, <a href="trait.WalletWrite.html" title="trait zcash_client_backend::data_api::WalletWrite"><code>WalletWrite</code></a>, and
<a href="trait.WalletCommitmentTrees.html" title="trait zcash_client_backend::data_api::WalletCommitmentTrees"><code>WalletCommitmentTrees</code></a>. A complete implementation of the data storage layer for a wallet
will include an implementation of all four of these traits. See the <a href="https://crates.io/crates/zcash_client_sqlite"><code>zcash_client_sqlite</code></a>
crate for a complete example of the implementation of these traits.</p>
<h3 id="accounts"><a class="doc-anchor" href="#accounts">§</a>Accounts</h3>
<p>The operation of the <a href="trait.InputSource.html" title="trait zcash_client_backend::data_api::InputSource"><code>InputSource</code></a>, <a href="trait.WalletRead.html" title="trait zcash_client_backend::data_api::WalletRead"><code>WalletRead</code></a> and <a href="trait.WalletWrite.html" title="trait zcash_client_backend::data_api::WalletWrite"><code>WalletWrite</code></a> traits is built around
the concept of a wallet having one or more accounts, with a unique <code>AccountId</code> for each
account.</p>
<p>An account identifier corresponds to at most a single <a href="../keys/struct.UnifiedSpendingKey.html" title="struct zcash_client_backend::keys::UnifiedSpendingKey"><code>UnifiedSpendingKey</code></a>’s worth of spend
authority, with the received and spent notes of that account tracked via the corresponding
<a href="../keys/struct.UnifiedFullViewingKey.html" title="struct zcash_client_backend::keys::UnifiedFullViewingKey"><code>UnifiedFullViewingKey</code></a>. Both received notes and change spendable by that spending authority
(both the external and internal parts of that key, as defined by
<a href="https://zips.z.cash/zip-0316">ZIP 316</a>) will be interpreted as belonging to that account.</p>
</div></details><h2 id="modules" class="section-header">Modules<a href="#modules" class="anchor">§</a></h2><dl class="item-table"><dt><a class="mod" href="chain/index.html" title="mod zcash_client_backend::data_api::chain">chain</a></dt><dd>Tools for blockchain validation &amp; scanning</dd><dt><a class="mod" href="error/index.html" title="mod zcash_client_backend::data_api::error">error</a></dt><dd>Types for wallet error handling.</dd><dt><a class="mod" href="scanning/index.html" title="mod zcash_client_backend::data_api::scanning">scanning</a></dt><dd>Common types used for managing a queue of scanning ranges.</dd><dt><a class="mod" href="testing/index.html" title="mod zcash_client_backend::data_api::testing">testing</a><wbr><span class="stab portability" title="Available on crate feature `test-dependencies` only"><code>test-dependencies</code></span></dt><dd>Utilities for testing wallets based upon the <a href="index.html" title="mod zcash_client_backend::data_api"><code>crate::data_api</code></a> traits.</dd><dt><a class="mod" href="wallet/index.html" title="mod zcash_client_backend::data_api::wallet">wallet</a></dt><dd>Functions for creating Zcash transactions that spend funds belonging to the wallet</dd></dl><h2 id="macros" class="section-header">Macros<a href="#macros" class="anchor">§</a></h2><dl class="item-table"><dt><a class="macro" href="macro.ambassador_impl_InputSource.html" title="macro zcash_client_backend::data_api::ambassador_impl_InputSource">ambassador_<wbr>impl_<wbr>Input<wbr>Source</a></dt><dd>A macro to be used by [<code>ambassador::Delegate</code>] to delegate <a href="trait.InputSource.html" title="trait zcash_client_backend::data_api::InputSource"><code>InputSource</code></a></dd><dt><a class="macro" href="macro.ambassador_impl_WalletCommitmentTrees.html" title="macro zcash_client_backend::data_api::ambassador_impl_WalletCommitmentTrees">ambassador_<wbr>impl_<wbr>Wallet<wbr>Commitment<wbr>Trees</a></dt><dd>A macro to be used by [<code>ambassador::Delegate</code>] to delegate <a href="trait.WalletCommitmentTrees.html" title="trait zcash_client_backend::data_api::WalletCommitmentTrees"><code>WalletCommitmentTrees</code></a></dd><dt><a class="macro" href="macro.ambassador_impl_WalletRead.html" title="macro zcash_client_backend::data_api::ambassador_impl_WalletRead">ambassador_<wbr>impl_<wbr>Wallet<wbr>Read</a></dt><dd>A macro to be used by [<code>ambassador::Delegate</code>] to delegate <a href="trait.WalletRead.html" title="trait zcash_client_backend::data_api::WalletRead"><code>WalletRead</code></a></dd><dt><a class="macro" href="macro.ambassador_impl_WalletTest.html" title="macro zcash_client_backend::data_api::ambassador_impl_WalletTest">ambassador_<wbr>impl_<wbr>Wallet<wbr>Test</a></dt><dd>A macro to be used by [<code>ambassador::Delegate</code>] to delegate <a href="trait.WalletTest.html" title="trait zcash_client_backend::data_api::WalletTest"><code>WalletTest</code></a></dd><dt><a class="macro" href="macro.ambassador_impl_WalletWrite.html" title="macro zcash_client_backend::data_api::ambassador_impl_WalletWrite">ambassador_<wbr>impl_<wbr>Wallet<wbr>Write</a></dt><dd>A macro to be used by [<code>ambassador::Delegate</code>] to delegate <a href="trait.WalletWrite.html" title="trait zcash_client_backend::data_api::WalletWrite"><code>WalletWrite</code></a></dd></dl><h2 id="structs" class="section-header">Structs<a href="#structs" class="anchor">§</a></h2><dl class="item-table"><dt><a class="struct" href="struct.AccountBalance.html" title="struct zcash_client_backend::data_api::AccountBalance">Account<wbr>Balance</a></dt><dd>Balance information for a single account. The sum of this struct’s fields is the total balance
of the wallet.</dd><dt><a class="struct" href="struct.AccountBirthday.html" title="struct zcash_client_backend::data_api::AccountBirthday">Account<wbr>Birthday</a></dt><dd>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.</dd><dt><a class="struct" href="struct.AccountMeta.html" title="struct zcash_client_backend::data_api::AccountMeta">Account<wbr>Meta</a></dt><dd>Metadata about the structure of the wallet for a particular account.</dd><dt><a class="struct" href="struct.AddressInfo.html" title="struct zcash_client_backend::data_api::AddressInfo">Address<wbr>Info</a></dt><dd>Information about an address in the wallet.</dd><dt><a class="struct" href="struct.Balance.html" title="struct zcash_client_backend::data_api::Balance">Balance</a></dt><dd>Balance information for a value within a single pool in an account.</dd><dt><a class="struct" href="struct.BlockMetadata.html" title="struct zcash_client_backend::data_api::BlockMetadata">Block<wbr>Metadata</a></dt><dd>Metadata describing the sizes of the zcash note commitment trees as of a particular block.</dd><dt><a class="struct" href="struct.BoundedU8.html" title="struct zcash_client_backend::data_api::BoundedU8">Bounded<wbr>U8</a></dt><dd>A <code>u8</code> value in the range 0..=MAX</dd><dt><a class="struct" href="struct.DecryptedTransaction.html" title="struct zcash_client_backend::data_api::DecryptedTransaction">Decrypted<wbr>Transaction</a></dt><dd>A transaction that was detected during scanning of the blockchain,
including its decrypted Sapling and/or Orchard outputs.</dd><dt><a class="struct" href="struct.OutputOfSentTx.html" title="struct zcash_client_backend::data_api::OutputOfSentTx">Output<wbr>OfSent<wbr>Tx</a><wbr><span class="stab portability" title="Available on crate feature `test-dependencies` only"><code>test-dependencies</code></span></dt><dd>The output of a transaction sent by the wallet.</dd><dt><a class="struct" href="struct.PoolMeta.html" title="struct zcash_client_backend::data_api::PoolMeta">Pool<wbr>Meta</a></dt><dd>Metadata about the structure of unspent outputs in a single pool within a wallet account.</dd><dt><a class="struct" href="struct.Progress.html" title="struct zcash_client_backend::data_api::Progress">Progress</a></dt><dd>A type representing the progress the wallet has made toward detecting all of the funds
belonging to the wallet.</dd><dt><a class="struct" href="struct.Ratio.html" title="struct zcash_client_backend::data_api::Ratio">Ratio</a></dt><dd>A polymorphic ratio type, usually used for rational numbers.</dd><dt><a class="struct" href="struct.ScannedBlock.html" title="struct zcash_client_backend::data_api::ScannedBlock">Scanned<wbr>Block</a></dt><dd>The subset of information that is relevant to this wallet that has been
decrypted and extracted from a <a href="../proto/compact_formats/struct.CompactBlock.html" title="struct zcash_client_backend::proto::compact_formats::CompactBlock"><code>CompactBlock</code></a>.</dd><dt><a class="struct" href="struct.ScannedBlockCommitments.html" title="struct zcash_client_backend::data_api::ScannedBlockCommitments">Scanned<wbr>Block<wbr>Commitments</a></dt><dd>A struct used to return the vectors of note commitments for a <a href="struct.ScannedBlock.html" title="struct zcash_client_backend::data_api::ScannedBlock"><code>ScannedBlock</code></a>
as owned values.</dd><dt><a class="struct" href="struct.ScannedBundles.html" title="struct zcash_client_backend::data_api::ScannedBundles">Scanned<wbr>Bundles</a></dt><dd>The protocol-specific note commitment and nullifier data extracted from the per-transaction
shielded bundles in <a href="../proto/compact_formats/struct.CompactBlock.html" title="struct zcash_client_backend::proto::compact_formats::CompactBlock"><code>CompactBlock</code></a>, used by the wallet for note commitment tree maintenance
and spend detection.</dd><dt><a class="struct" href="struct.SentTransaction.html" title="struct zcash_client_backend::data_api::SentTransaction">Sent<wbr>Transaction</a></dt><dd>A transaction that was constructed and sent by the wallet.</dd><dt><a class="struct" href="struct.SentTransactionOutput.html" title="struct zcash_client_backend::data_api::SentTransactionOutput">Sent<wbr>Transaction<wbr>Output</a></dt><dd>An output of a transaction generated by the wallet.</dd><dt><a class="struct" href="struct.SpendableNotes.html" title="struct zcash_client_backend::data_api::SpendableNotes">Spendable<wbr>Notes</a></dt><dd>Spendable shielded outputs controlled by the wallet.</dd><dt><a class="struct" href="struct.WalletSummary.html" title="struct zcash_client_backend::data_api::WalletSummary">Wallet<wbr>Summary</a></dt><dd>A type representing the potentially-spendable value of unspent outputs in the wallet.</dd><dt><a class="struct" href="struct.Zip32Derivation.html" title="struct zcash_client_backend::data_api::Zip32Derivation">Zip32<wbr>Derivation</a></dt><dd>Source metadata for a ZIP 32-derived key.</dd></dl><h2 id="enums" class="section-header">Enums<a href="#enums" class="anchor">§</a></h2><dl class="item-table"><dt><a class="enum" href="enum.AccountPurpose.html" title="enum zcash_client_backend::data_api::AccountPurpose">Account<wbr>Purpose</a></dt><dd>An enumeration used to control what information is tracked by the wallet for
notes received by a given account.</dd><dt><a class="enum" href="enum.AccountSource.html" title="enum zcash_client_backend::data_api::AccountSource">Account<wbr>Source</a></dt><dd>The kinds of accounts supported by <code>zcash_client_backend</code>.</dd><dt><a class="enum" href="enum.BirthdayError.html" title="enum zcash_client_backend::data_api::BirthdayError">Birthday<wbr>Error</a></dt><dd>Errors that can occur in the construction of an <a href="struct.AccountBirthday.html" title="struct zcash_client_backend::data_api::AccountBirthday"><code>AccountBirthday</code></a> from a <a href="../proto/service/struct.TreeState.html" title="struct zcash_client_backend::proto::service::TreeState"><code>TreeState</code></a>.</dd><dt><a class="enum" href="enum.NoteFilter.html" title="enum zcash_client_backend::data_api::NoteFilter">Note<wbr>Filter</a></dt><dd>A small query language for filtering notes belonging to an account.</dd><dt><a class="enum" href="enum.NullifierQuery.html" title="enum zcash_client_backend::data_api::NullifierQuery">Nullifier<wbr>Query</a></dt><dd>An enumeration of constraints that can be applied when querying for nullifiers for notes
belonging to the wallet.</dd><dt><a class="enum" href="enum.OutputStatusFilter.html" title="enum zcash_client_backend::data_api::OutputStatusFilter">Output<wbr>Status<wbr>Filter</a><wbr><span class="stab portability" title="Available on crate feature `transparent-inputs` only"><code>transparent-inputs</code></span></dt><dd>A type used to filter transactions to be returned in response to a <a href="enum.TransactionDataRequest.html" title="enum zcash_client_backend::data_api::TransactionDataRequest"><code>TransactionDataRequest</code></a>,
in terms of the spentness of the transaction’s transparent outputs.</dd><dt><a class="enum" href="enum.SeedRelevance.html" title="enum zcash_client_backend::data_api::SeedRelevance">Seed<wbr>Relevance</a></dt><dd>The relevance of a seed to a given wallet.</dd><dt><a class="enum" href="enum.TransactionDataRequest.html" title="enum zcash_client_backend::data_api::TransactionDataRequest">Transaction<wbr>Data<wbr>Request</a></dt><dd>A request for transaction data enhancement, spentness check, or discovery
of spends from a given transparent address within a specific block range.</dd><dt><a class="enum" href="enum.TransactionStatus.html" title="enum zcash_client_backend::data_api::TransactionStatus">Transaction<wbr>Status</a></dt><dd>Metadata about the status of a transaction obtained by inspecting the chain state.</dd><dt><a class="enum" href="enum.TransactionStatusFilter.html" title="enum zcash_client_backend::data_api::TransactionStatusFilter">Transaction<wbr>Status<wbr>Filter</a><wbr><span class="stab portability" title="Available on crate feature `transparent-inputs` only"><code>transparent-inputs</code></span></dt><dd>A type describing the mined-ness of transactions that should be returned in response to a
<a href="enum.TransactionDataRequest.html" title="enum zcash_client_backend::data_api::TransactionDataRequest"><code>TransactionDataRequest</code></a>.</dd></dl><h2 id="constants" class="section-header">Constants<a href="#constants" class="anchor">§</a></h2><dl class="item-table"><dt><a class="constant" href="constant.ORCHARD_SHARD_HEIGHT.html" title="constant zcash_client_backend::data_api::ORCHARD_SHARD_HEIGHT">ORCHARD_<wbr>SHARD_<wbr>HEIGHT</a><wbr><span class="stab portability" title="Available on crate feature `orchard` only"><code>orchard</code></span></dt><dd>The height of subtree roots in the Orchard note commitment tree.</dd><dt><a class="constant" href="constant.SAPLING_SHARD_HEIGHT.html" title="constant zcash_client_backend::data_api::SAPLING_SHARD_HEIGHT">SAPLING_<wbr>SHARD_<wbr>HEIGHT</a></dt><dd>The height of subtree roots in the Sapling note commitment tree.</dd></dl><h2 id="traits" class="section-header">Traits<a href="#traits" class="anchor">§</a></h2><dl class="item-table"><dt><a class="trait" href="trait.Account.html" title="trait zcash_client_backend::data_api::Account">Account</a></dt><dd>A set of capabilities that a client account must provide.</dd><dt><a class="trait" href="trait.InputSource.html" title="trait zcash_client_backend::data_api::InputSource">Input<wbr>Source</a></dt><dd>A trait representing the capability to query a data store for unspent transaction outputs
belonging to a account.</dd><dt><a class="trait" href="trait.NoteRetention.html" title="trait zcash_client_backend::data_api::NoteRetention">Note<wbr>Retention</a></dt><dd>A predicate that can be used to choose whether or not a particular note is retained in note
selection.</dd><dt><a class="trait" href="trait.WalletCommitmentTrees.html" title="trait zcash_client_backend::data_api::WalletCommitmentTrees">Wallet<wbr>Commitment<wbr>Trees</a></dt><dd>This trait describes a capability for manipulating wallet note commitment trees.</dd><dt><a class="trait" href="trait.WalletRead.html" title="trait zcash_client_backend::data_api::WalletRead">Wallet<wbr>Read</a></dt><dd>Read-only operations required for light wallet functions.</dd><dt><a class="trait" href="trait.WalletTest.html" title="trait zcash_client_backend::data_api::WalletTest">Wallet<wbr>Test</a></dt><dd>Read-only operations required for testing light wallet functions.</dd><dt><a class="trait" href="trait.WalletWrite.html" title="trait zcash_client_backend::data_api::WalletWrite">Wallet<wbr>Write</a></dt><dd>This trait encapsulates the write capabilities required to update stored wallet data.</dd></dl></section></div></main></body></html>
Reference in New Issue View Git Blame Copy Permalink