141 lines
14 KiB
HTML
141 lines
14 KiB
HTML
<!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="Tools for blockchain validation & scanning"><title>zcash_client_backend::data_api::chain - 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 (2e6882ac5 2025-05-05)" 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 chain</a></h2><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#examples" title="Examples">Examples</a></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="#structs" title="Structs">Structs</a></li><li><a href="#traits" title="Traits">Traits</a></li><li><a href="#functions" title="Functions">Functions</a></li></ul></section><div id="rustdoc-modnav"><h2><a href="../index.html">In zcash_<wbr>client_<wbr>backend::<wbr>data_<wbr>api</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>::<wbr><a href="../index.html">data_api</a></div><h1>Module <span>chain</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/chain.rs.html#1-725">Source</a> </span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Tools for blockchain validation & scanning</p>
|
|
<h2 id="examples"><a class="doc-anchor" href="#examples">§</a>Examples</h2>
|
|
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>zcash_primitives::{
|
|
consensus::{BlockHeight, Network, Parameters},
|
|
};
|
|
|
|
<span class="kw">use </span>zcash_client_backend::{
|
|
data_api::{
|
|
WalletRead, WalletWrite, WalletCommitmentTrees,
|
|
chain::{
|
|
BlockSource,
|
|
CommitmentTreeRoot,
|
|
error::Error,
|
|
scan_cached_blocks,
|
|
testing <span class="kw">as </span>chain_testing,
|
|
},
|
|
scanning::ScanPriority,
|
|
testing,
|
|
},
|
|
};
|
|
|
|
|
|
<span class="kw">let </span>network = Network::TestNetwork;
|
|
<span class="kw">let </span>block_source = chain_testing::MockBlockSource;
|
|
<span class="kw">let </span><span class="kw-2">mut </span>wallet_db = testing::MockWalletDb::new(Network::TestNetwork);
|
|
|
|
<span class="comment">// 1) Download note commitment tree data from lightwalletd
|
|
</span><span class="kw">let </span>roots: Vec<CommitmentTreeRoot<sapling::Node>> = <span class="macro">unimplemented!</span>();
|
|
|
|
<span class="comment">// 2) Pass the commitment tree data to the database.
|
|
</span>wallet_db.put_sapling_subtree_roots(<span class="number">0</span>, <span class="kw-2">&</span>roots).unwrap();
|
|
|
|
<span class="comment">// 3) Download chain tip metadata from lightwalletd
|
|
</span><span class="kw">let </span>tip_height: BlockHeight = <span class="macro">unimplemented!</span>();
|
|
|
|
<span class="comment">// 4) Notify the wallet of the updated chain tip.
|
|
</span>wallet_db.update_chain_tip(tip_height).map_err(Error::Wallet)<span class="question-mark">?</span>;
|
|
|
|
<span class="comment">// 5) Get the suggested scan ranges from the wallet database
|
|
</span><span class="kw">let </span><span class="kw-2">mut </span>scan_ranges = wallet_db.suggest_scan_ranges().map_err(Error::Wallet)<span class="question-mark">?</span>;
|
|
|
|
<span class="comment">// 6) Run the following loop until the wallet's view of the chain tip as of the previous wallet
|
|
// session is valid.
|
|
</span><span class="kw">loop </span>{
|
|
<span class="comment">// If there is a range of blocks that needs to be verified, it will always be returned as
|
|
// the first element of the vector of suggested ranges.
|
|
</span><span class="kw">match </span>scan_ranges.first() {
|
|
<span class="prelude-val">Some</span>(scan_range) <span class="kw">if </span>scan_range.priority() == ScanPriority::Verify => {
|
|
<span class="comment">// Download the chain state for the block prior to the start of the range you want
|
|
// to scan.
|
|
</span><span class="kw">let </span>chain_state = <span class="macro">unimplemented!</span>(<span class="string">"get_chain_state(scan_range.block_range().start - 1)?;"</span>);
|
|
<span class="comment">// Download the blocks in `scan_range` into the block source, overwriting any
|
|
// existing blocks in this range.
|
|
</span><span class="macro">unimplemented!</span>(<span class="string">"cache_blocks(scan_range)?;"</span>);
|
|
|
|
<span class="comment">// Scan the downloaded blocks
|
|
</span><span class="kw">let </span>scan_result = scan_cached_blocks(
|
|
<span class="kw-2">&</span>network,
|
|
<span class="kw-2">&</span>block_source,
|
|
<span class="kw-2">&mut </span>wallet_db,
|
|
scan_range.block_range().start,
|
|
chain_state,
|
|
scan_range.len()
|
|
);
|
|
|
|
<span class="comment">// Check for scanning errors that indicate that the wallet's chain tip is out of
|
|
// sync with blockchain history.
|
|
</span><span class="kw">match </span>scan_result {
|
|
<span class="prelude-val">Ok</span>(<span class="kw">_</span>) => {
|
|
<span class="comment">// At this point, the cache and scanned data are locally consistent (though
|
|
// not necessarily consistent with the latest chain tip - this would be
|
|
// discovered the next time this codepath is executed after new blocks are
|
|
// received) so we can break out of the loop.
|
|
</span><span class="kw">break</span>;
|
|
}
|
|
<span class="prelude-val">Err</span>(Error::Scan(err)) <span class="kw">if </span>err.is_continuity_error() => {
|
|
<span class="comment">// Pick a height to rewind to, which must be at least one block before
|
|
// the height at which the error occurred, but may be an earlier height
|
|
// determined based on heuristics such as the platform, available bandwidth,
|
|
// size of recent CompactBlocks, etc.
|
|
</span><span class="kw">let </span>rewind_height = err.at_height().saturating_sub(<span class="number">10</span>);
|
|
|
|
<span class="comment">// Rewind to the chosen height.
|
|
</span>wallet_db.truncate_to_height(rewind_height).map_err(Error::Wallet)<span class="question-mark">?</span>;
|
|
|
|
<span class="comment">// Delete cached blocks from rewind_height onwards.
|
|
//
|
|
// This does imply that assumed-valid blocks will be re-downloaded, but it
|
|
// is also possible that in the intervening time, a chain reorg has
|
|
// occurred that orphaned some of those blocks.
|
|
</span><span class="macro">unimplemented!</span>();
|
|
}
|
|
<span class="prelude-val">Err</span>(other) => {
|
|
<span class="comment">// Handle or return other errors
|
|
</span>}
|
|
}
|
|
|
|
<span class="comment">// In case we updated the suggested scan ranges, now re-request.
|
|
</span>scan_ranges = wallet_db.suggest_scan_ranges().map_err(Error::Wallet)<span class="question-mark">?</span>;
|
|
}
|
|
<span class="kw">_ </span>=> {
|
|
<span class="comment">// Nothing to verify; break out of the loop
|
|
</span><span class="kw">break</span>;
|
|
}
|
|
}
|
|
}
|
|
|
|
<span class="comment">// 7) Loop over the remaining suggested scan ranges, retrieving the requested data and calling
|
|
// `scan_cached_blocks` on each range. Periodically, or if a continuity error is
|
|
// encountered, this process should be repeated starting at step (3).
|
|
</span><span class="kw">let </span>scan_ranges = wallet_db.suggest_scan_ranges().map_err(Error::Wallet)<span class="question-mark">?</span>;
|
|
<span class="kw">for </span>scan_range <span class="kw">in </span>scan_ranges {
|
|
<span class="comment">// Download the chain state for the block prior to the start of the range you want
|
|
// to scan.
|
|
</span><span class="kw">let </span>chain_state = <span class="macro">unimplemented!</span>(<span class="string">"get_chain_state(scan_range.block_range().start - 1)?;"</span>);
|
|
<span class="comment">// Download the blocks in `scan_range` into the block source. While in this example this
|
|
// step is performed in-line, it's fine for the download of scan ranges to be asynchronous
|
|
// and for the scanner to process the downloaded ranges as they become available in a
|
|
// separate thread. The scan ranges should also be broken down into smaller chunks as
|
|
// appropriate, and for ranges with priority `Historic` it can be useful to download and
|
|
// scan the range in reverse order (to discover more recent unspent notes sooner), or from
|
|
// the start and end of the range inwards.
|
|
</span><span class="macro">unimplemented!</span>(<span class="string">"cache_blocks(scan_range)?;"</span>);
|
|
|
|
<span class="comment">// Scan the downloaded blocks.
|
|
</span><span class="kw">let </span>scan_result = scan_cached_blocks(
|
|
<span class="kw-2">&</span>network,
|
|
<span class="kw-2">&</span>block_source,
|
|
<span class="kw-2">&mut </span>wallet_db,
|
|
scan_range.block_range().start,
|
|
chain_state,
|
|
scan_range.len()
|
|
)<span class="question-mark">?</span>;
|
|
|
|
<span class="comment">// Handle scan errors, etc.
|
|
</span>}</code></pre></div>
|
|
</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="error/index.html" title="mod zcash_client_backend::data_api::chain::error">error</a></dt><dd>Types for chain scanning error handling.</dd><dt><a class="mod" href="testing/index.html" title="mod zcash_client_backend::data_api::chain::testing">testing</a><wbr><span class="stab portability" title="Available on crate feature `test-dependencies` only"><code>test-dependencies</code></span></dt></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.ChainState.html" title="struct zcash_client_backend::data_api::chain::ChainState">Chain<wbr>State</a></dt><dd>The final note commitment tree state for each shielded pool, as of a particular block height.</dd><dt><a class="struct" href="struct.CommitmentTreeRoot.html" title="struct zcash_client_backend::data_api::chain::CommitmentTreeRoot">Commitment<wbr>Tree<wbr>Root</a></dt><dd>A struct containing metadata about a subtree root of the note commitment tree.</dd><dt><a class="struct" href="struct.ScanSummary.html" title="struct zcash_client_backend::data_api::chain::ScanSummary">Scan<wbr>Summary</a></dt><dd>Metadata about modifications to the wallet state made in the course of scanning a set of
|
|
blocks.</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.BlockCache.html" title="trait zcash_client_backend::data_api::chain::BlockCache">Block<wbr>Cache</a></dt><dd><code>BlockCache</code> is a trait that extends <code>BlockSource</code> and defines methods for managing
|
|
a cache of compact blocks.</dd><dt><a class="trait" href="trait.BlockSource.html" title="trait zcash_client_backend::data_api::chain::BlockSource">Block<wbr>Source</a></dt><dd>This trait provides sequential access to raw blockchain data via a callback-oriented
|
|
API.</dd></dl><h2 id="functions" class="section-header">Functions<a href="#functions" class="anchor">§</a></h2><dl class="item-table"><dt><a class="fn" href="fn.scan_cached_blocks.html" title="fn zcash_client_backend::data_api::chain::scan_cached_blocks">scan_<wbr>cached_<wbr>blocks</a></dt><dd>Scans at most <code>limit</code> blocks from the provided block source for in order to find transactions
|
|
received by the accounts tracked in the provided wallet database.</dd></dl></section></div></main></body></html> |