1585 lines
98 KiB
HTML
1585 lines
98 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="sidebar-visible no-js light">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>The zcashd Book</title>
|
||
<meta name="robots" content="noindex" />
|
||
|
||
|
||
<!-- Custom HTML head -->
|
||
|
||
<meta name="description" content="">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<meta name="theme-color" content="#ffffff" />
|
||
|
||
<link rel="icon" href="favicon.svg">
|
||
<link rel="shortcut icon" href="favicon.png">
|
||
<link rel="stylesheet" href="css/variables.css">
|
||
<link rel="stylesheet" href="css/general.css">
|
||
<link rel="stylesheet" href="css/chrome.css">
|
||
<link rel="stylesheet" href="css/print.css" media="print">
|
||
|
||
<!-- Fonts -->
|
||
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
|
||
<link rel="stylesheet" href="fonts/fonts.css">
|
||
|
||
<!-- Highlight.js Stylesheets -->
|
||
<link rel="stylesheet" href="highlight.css">
|
||
<link rel="stylesheet" href="tomorrow-night.css">
|
||
<link rel="stylesheet" href="ayu-highlight.css">
|
||
|
||
<!-- Custom theme stylesheets -->
|
||
|
||
</head>
|
||
<body>
|
||
<div id="body-container">
|
||
<!-- Provide site root to javascript -->
|
||
<script>
|
||
var path_to_root = "";
|
||
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
|
||
</script>
|
||
|
||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||
<script>
|
||
try {
|
||
var theme = localStorage.getItem('mdbook-theme');
|
||
var sidebar = localStorage.getItem('mdbook-sidebar');
|
||
|
||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||
}
|
||
|
||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||
}
|
||
} catch (e) { }
|
||
</script>
|
||
|
||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||
<script>
|
||
var theme;
|
||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||
var html = document.querySelector('html');
|
||
html.classList.remove('no-js')
|
||
html.classList.remove('light')
|
||
html.classList.add(theme);
|
||
html.classList.add('js');
|
||
</script>
|
||
|
||
<!-- Hide / unhide sidebar before it is displayed -->
|
||
<script>
|
||
var html = document.querySelector('html');
|
||
var sidebar = null;
|
||
if (document.body.clientWidth >= 1080) {
|
||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||
sidebar = sidebar || 'visible';
|
||
} else {
|
||
sidebar = 'hidden';
|
||
}
|
||
html.classList.remove('sidebar-visible');
|
||
html.classList.add("sidebar-" + sidebar);
|
||
</script>
|
||
|
||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||
<div class="sidebar-scrollbox">
|
||
<ol class="chapter"><li class="chapter-item expanded affix "><a href="index.html">zcashd</a></li><li class="chapter-item expanded "><a href="user.html"><strong aria-hidden="true">1.</strong> User Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="user/release-support.html"><strong aria-hidden="true">1.1.</strong> Release Support</a></li><li class="chapter-item expanded "><a href="user/platform-support.html"><strong aria-hidden="true">1.2.</strong> Platform Support</a></li><li class="chapter-item expanded "><a href="user/wallet-backup.html"><strong aria-hidden="true">1.3.</strong> Wallet Backup</a></li><li class="chapter-item expanded "><a href="user/shield-coinbase.html"><strong aria-hidden="true">1.4.</strong> Shielding Coinbase Outputs</a></li><li class="chapter-item expanded "><a href="user/files.html"><strong aria-hidden="true">1.5.</strong> Data Directory Structure</a></li><li class="chapter-item expanded "><a href="user/metrics.html"><strong aria-hidden="true">1.6.</strong> Metrics</a></li><li class="chapter-item expanded "><a href="user/tor.html"><strong aria-hidden="true">1.7.</strong> Using zcashd with Tor</a></li><li class="chapter-item expanded "><a href="user/security-warnings.html"><strong aria-hidden="true">1.8.</strong> Security Warnings</a></li><li class="chapter-item expanded "><a href="user/deprecation.html"><strong aria-hidden="true">1.9.</strong> Deprecated Features</a></li></ol></li><li class="chapter-item expanded "><a href="dev.html"><strong aria-hidden="true">2.</strong> Developer Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="dev/dnsseed-policy.html"><strong aria-hidden="true">2.1.</strong> DNS Seeders</a></li><li class="chapter-item expanded "><a href="dev/rust.html"><strong aria-hidden="true">2.2.</strong> Rust in zcashd</a></li><li class="chapter-item expanded "><a href="dev/regtest.html"><strong aria-hidden="true">2.3.</strong> Regtest Tips And Hints</a></li><li class="chapter-item expanded "><a href="dev/platform-tier-policy.html"><strong aria-hidden="true">2.4.</strong> Platform Tier Policy</a></li><li class="chapter-item expanded "><a href="dev/deprecation.html"><strong aria-hidden="true">2.5.</strong> Deprecation Procedure</a></li></ol></li><li class="chapter-item expanded "><a href="design.html"><strong aria-hidden="true">3.</strong> Design</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="design/chain-state.html"><strong aria-hidden="true">3.1.</strong> Chain State</a></li><li class="chapter-item expanded "><a href="design/coins-view.html"><strong aria-hidden="true">3.2.</strong> "Coins" View</a></li><li class="chapter-item expanded "><a href="design/p2p-data-propagation.html"><strong aria-hidden="true">3.3.</strong> P2P Data Propagation</a></li></ol></li></ol>
|
||
</div>
|
||
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
|
||
</nav>
|
||
|
||
<div id="page-wrapper" class="page-wrapper">
|
||
|
||
<div class="page">
|
||
<div id="menu-bar-hover-placeholder"></div>
|
||
<div id="menu-bar" class="menu-bar sticky bordered">
|
||
<div class="left-buttons">
|
||
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||
<i class="fa fa-bars"></i>
|
||
</button>
|
||
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||
<i class="fa fa-paint-brush"></i>
|
||
</button>
|
||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||
</ul>
|
||
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
||
<i class="fa fa-search"></i>
|
||
</button>
|
||
</div>
|
||
|
||
<h1 class="menu-title">The zcashd Book</h1>
|
||
|
||
<div class="right-buttons">
|
||
<a href="print.html" title="Print this book" aria-label="Print this book">
|
||
<i id="print-button" class="fa fa-print"></i>
|
||
</a>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
<div id="search-wrapper" class="hidden">
|
||
<form id="searchbar-outer" class="searchbar-outer">
|
||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||
</form>
|
||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||
<div id="searchresults-header" class="searchresults-header"></div>
|
||
<ul id="searchresults">
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
|
||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||
<script>
|
||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||
});
|
||
</script>
|
||
|
||
<div id="content" class="content">
|
||
<main>
|
||
<h1>Zcash 5.5.0-rc1
|
||
<img align="right" width="120" height="80" src="doc/imgs/logo.png"></h1>
|
||
<h2 id="what-is-zcash"><a class="header" href="#what-is-zcash">What is Zcash?</a></h2>
|
||
<p><a href="https://z.cash/">Zcash</a> is an implementation of the "Zerocash" protocol.
|
||
Initially based on Bitcoin's design, Zcash intends to offer a far
|
||
higher standard of privacy through a sophisticated zero-knowledge
|
||
proving scheme that preserves confidentiality of transaction
|
||
metadata. More technical details are available in our <a href="https://zips.z.cash/protocol/protocol.pdf">Protocol
|
||
Specification</a>.</p>
|
||
<h2 id="the-zcashd-full-node"><a class="header" href="#the-zcashd-full-node">The <code>zcashd</code> Full Node</a></h2>
|
||
<p>This repository hosts the <code>zcashd</code> software, a Zcash consensus node
|
||
implementation. It downloads and stores the entire history of Zcash
|
||
transactions. Depending on the speed of your computer and network
|
||
connection, the synchronization process could take several days.</p>
|
||
<p align="center">
|
||
<img src="doc/imgs/zcashd_screen.gif" height="500">
|
||
</p>
|
||
<p>The <code>zcashd</code> code is derived from a source fork of
|
||
<a href="https://github.com/bitcoin/bitcoin">Bitcoin Core</a>. The code was forked
|
||
initially from Bitcoin Core v0.11.2, and the two codebases have diverged
|
||
substantially.</p>
|
||
<h4 id="lock-security-warnings"><a class="header" href="#lock-security-warnings">:lock: Security Warnings</a></h4>
|
||
<p>See important security warnings on the
|
||
<a href="https://z.cash/support/security/">Security Information page</a>.</p>
|
||
<p><strong>Zcash is experimental and a work in progress.</strong> Use it at your own risk.</p>
|
||
<h4 id="ledger-deprecation-policy"><a class="header" href="#ledger-deprecation-policy">:ledger: Deprecation Policy</a></h4>
|
||
<p>This release is considered deprecated 16 weeks after the release day. There
|
||
is an automatic deprecation shutdown feature which will halt the node some
|
||
time after this 16-week period. The automatic feature is based on block
|
||
height.</p>
|
||
<h2 id="other-zcash-implementations"><a class="header" href="#other-zcash-implementations">Other Zcash Implementations</a></h2>
|
||
<p>The <a href="https://github.com/ZcashFoundation/zebra">Zebra</a> project offers a
|
||
different Zcash consensus node implementation, written largely from the
|
||
ground up.</p>
|
||
<h2 id="getting-started"><a class="header" href="#getting-started">Getting Started</a></h2>
|
||
<p>Please see our <a href="https://zcash.readthedocs.io/en/latest/rtd_pages/rtd_docs/user_guide.html">user
|
||
guide</a>
|
||
for instructions on joining the main Zcash network.</p>
|
||
<h3 id="need-help"><a class="header" href="#need-help">Need Help?</a></h3>
|
||
<ul>
|
||
<li>:blue_book: See the documentation at the <a href="https://zcash.readthedocs.io">ReadTheDocs</a>
|
||
for help and more information.</li>
|
||
<li>:incoming_envelope: Ask for help on the <a href="https://forum.z.cash/">Zcash</a> forum.</li>
|
||
<li>:speech_balloon: Join our community on <a href="https://discordapp.com/invite/PhJY6Pm">Discord</a></li>
|
||
</ul>
|
||
<p>Participation in the Zcash project is subject to a
|
||
<a href="code_of_conduct.html">Code of Conduct</a>.</p>
|
||
<h3 id="building"><a class="header" href="#building">Building</a></h3>
|
||
<p>Build Zcash along with most dependencies from source by running the following command:</p>
|
||
<pre><code>./zcutil/build.sh -j$(nproc)
|
||
</code></pre>
|
||
<p>Currently, Zcash is only officially supported on Debian and Ubuntu. See the
|
||
<a href="https://zcash.readthedocs.io/en/latest/rtd_pages/Debian-Ubuntu-build.html">Debian / Ubuntu build</a>
|
||
for detailed instructions.</p>
|
||
<h2 id="license"><a class="header" href="#license">License</a></h2>
|
||
<p>For license information see the file <a href="COPYING">COPYING</a>.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="user-documentation"><a class="header" href="#user-documentation">User Documentation</a></h1>
|
||
<p>This section contains user documentation specific to <code>zcashd</code>.</p>
|
||
<p>See <a href="https://zcash.readthedocs.io/">here</a> for more general Zcash documentation, as well as
|
||
installation instructions for <code>zcashd</code>.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="zcashd-release-support"><a class="header" href="#zcashd-release-support"><code>zcashd</code> Release Support</a></h1>
|
||
<h2 id="release-cadence-and-support-window"><a class="header" href="#release-cadence-and-support-window">Release cadence and support window</a></h2>
|
||
<p><code>zcashd</code> releases happen approximately every six weeks, although this may change if a
|
||
particular release is delayed, or if a hotfix release occurs.</p>
|
||
<p>Each <code>zcashd</code> release is generally supported for 16 weeks. Occasionally this changes for
|
||
individual releases (for example, near to a Network Upgrade activation).</p>
|
||
<p>These two policies mean that there are generally at least two separate <code>zcashd</code> versions
|
||
currently supported at any given time.</p>
|
||
<h2 id="end-of-support-halt"><a class="header" href="#end-of-support-halt">End-of-Support halt</a></h2>
|
||
<p>Every <code>zcashd</code> version released by ECC has an End-of-Support height. When the Zcash chain
|
||
reaches this height, <code>zcashd</code> will automatically shut down, and the binary will refuse to
|
||
restart. This is for several reasons:</p>
|
||
<ul>
|
||
<li>The <code>zcashd</code> maintainers do not have the resources to maintain old versions of <code>zcashd</code>
|
||
indefinitely.</li>
|
||
<li>Each time a user upgrades their <code>zcashd</code> node, they are re-confirming that they are
|
||
happy to run the Zcash consensus rules encoded in the version of <code>zcashd</code> they are
|
||
running. This is an important part of the overall strategy for changes to the node and
|
||
consensus rules; users who want to follow different rules (or even just have a different
|
||
End-of-Support halt policy) will obtain a <code>zcashd</code> binary from some other source, with
|
||
its own support policies.</li>
|
||
<li>Knowing that old versions will shut down is useful for planning backwards-incompatible
|
||
changes in Network Upgrades. A Network Upgrade activation can be targeted for a height
|
||
where we know that all released <code>zcashd</code> versions which <em>did not</em> support the Network
|
||
Upgrade will have shut down by the time the Network Upgrade activates.</li>
|
||
</ul>
|
||
<h2 id="end-of-support-heights"><a class="header" href="#end-of-support-heights">End-of-Support heights</a></h2>
|
||
<p>The End-of-Support height for a running <code>zcashd</code> can be queried over JSON-RPC using the
|
||
<code>getdeprecationinfo</code> method.</p>
|
||
<p>The following table shows End-of-Support information for recent <code>zcashd</code> releases. It is
|
||
automatically updated during each release. "End of Support" dates are estimated at that
|
||
time, and may shift due to changes in network solution power.</p>
|
||
<!-- RELEASE_SCRIPT_START_MARKER - If you make changes here, check make-release.py -->
|
||
<div class="table-wrapper"><table><thead><tr><th><code>zcashd</code> version</th><th>Release date</th><th>Halt height</th><th>End of Support</th></tr></thead><tbody>
|
||
<tr><td>5.4.0</td><td>2023-02-09</td><td>2106524</td><td>2023-06-01</td></tr>
|
||
<tr><td>5.4.1</td><td>2023-02-13</td><td>2112024</td><td>2023-06-05</td></tr>
|
||
<tr><td>5.3.3</td><td>2023-03-13</td><td>2121024</td><td>2023-06-13</td></tr>
|
||
<tr><td>5.4.2</td><td>2023-03-13</td><td>2121024</td><td>2023-06-13</td></tr>
|
||
<tr><td>5.5.0-rc1</td><td>2023-04-20</td><td>2059000</td><td>2023-08-10</td></tr>
|
||
</tbody></table>
|
||
</div><!-- RELEASE_SCRIPT_END_MARKER -->
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="platform-support"><a class="header" href="#platform-support">Platform Support</a></h1>
|
||
<p>Support for different platforms (build "targets" and operating systems) are organised into
|
||
three tiers, each with a different set of guarantees. For more information on the policies
|
||
for targets at each tier, see the <a href="user/../dev/platform-tier-policy.html">Platform Tier Policy</a>.</p>
|
||
<h2 id="tier-1"><a class="header" href="#tier-1">Tier 1</a></h2>
|
||
<p>Tier 1 platforms can be thought of as "guaranteed to work". ECC builds official binary
|
||
releases for each tier 1 platform, and automated testing ensures that each tier 1 platform
|
||
builds and passes tests after each change.</p>
|
||
<p>"End of Support" dates are the latest currently-known date after which the platform will
|
||
be removed from tier 1. These dates are subject to change.</p>
|
||
<div class="table-wrapper"><table><thead><tr><th>target</th><th>OS</th><th>End of Support</th></tr></thead><tbody>
|
||
<tr><td><code>x86_64-pc-linux-gnu</code></td><td>Debian 10</td><td>June 2024</td></tr>
|
||
<tr><td></td><td>Debian 11</td><td>June 2026</td></tr>
|
||
<tr><td></td><td>Ubuntu 18.04</td><td>April 2023</td></tr>
|
||
<tr><td></td><td>Ubuntu 20.04</td><td>April 2025</td></tr>
|
||
</tbody></table>
|
||
</div>
|
||
<h2 id="tier-2"><a class="header" href="#tier-2">Tier 2</a></h2>
|
||
<p>Tier 2 platforms can be thought of as "guaranteed to build". ECC builds official binary
|
||
releases for each tier 2 platform, and automated builds ensure that each tier 2 platform
|
||
builds after each change. Automated tests are not always run so it's not guaranteed to
|
||
produce a working build, but tier 2 platforms often work to quite a good degree, and
|
||
patches are always welcome!</p>
|
||
<p>"End of Support" dates are the latest currently-known date after which the platform will
|
||
be removed from tier 2. These dates are subject to change.</p>
|
||
<div class="table-wrapper"><table><thead><tr><th>target</th><th>OS</th><th>End of Support</th></tr></thead><tbody>
|
||
<tr><td>N/A</td><td></td><td></td></tr>
|
||
</tbody></table>
|
||
</div>
|
||
<h2 id="tier-3"><a class="header" href="#tier-3">Tier 3</a></h2>
|
||
<p>Tier 3 platforms are those for which the <code>zcashd</code> codebase has support, but ECC does not
|
||
require builds or tests to pass, so these may or may not work. Official builds are not
|
||
available.</p>
|
||
<div class="table-wrapper"><table><thead><tr><th>target</th><th>OS</th><th>notes</th></tr></thead><tbody>
|
||
<tr><td><code>x86_64-pc-linux-gnu</code></td><td>Arch</td><td></td></tr>
|
||
<tr><td><code>x86_64-unknown-freebsd</code></td><td>FreeBSD</td><td></td></tr>
|
||
<tr><td><code>x86_64-w64-mingw32</code></td><td>Windows</td><td>64-bit MinGW</td></tr>
|
||
<tr><td><code>x86_64-apple-darwin16</code></td><td>macOS 10.14+</td><td></td></tr>
|
||
<tr><td><code>aarch64-linux-gnu</code></td><td>ARM64 Linux</td><td></td></tr>
|
||
</tbody></table>
|
||
</div><div style="break-before: page; page-break-before: always;"></div><h1 id="wallet-backup-instructions"><a class="header" href="#wallet-backup-instructions">Wallet Backup Instructions</a></h1>
|
||
<h2 id="overview"><a class="header" href="#overview">Overview</a></h2>
|
||
<p>Backing up your Zcash private keys is the best way to be proactive about
|
||
preventing loss of access to your ZEC.</p>
|
||
<p>Problems resulting from bugs in the code, user error, device failure, etc. may
|
||
lead to losing access to your wallet (and as a result, the private keys of
|
||
addresses which are required to spend from them).</p>
|
||
<p>No matter what the cause of a corrupted or lost wallet could be, we highly
|
||
recommend all users backup on a regular basis. Anytime a new address in the
|
||
wallet is generated, we recommending making a new backup so all private keys
|
||
for addresses in your wallet are safe.</p>
|
||
<p>Note that a backup is a duplicate of data needed to spend ZEC so where you keep
|
||
your backup(s) is another important consideration. You should not store backups
|
||
where they would be equally or increasingly susceptible to loss or theft.</p>
|
||
<h2 id="instructions-for-backing-up-your-wallet-andor-private-keys"><a class="header" href="#instructions-for-backing-up-your-wallet-andor-private-keys">Instructions for backing up your wallet and/or private keys</a></h2>
|
||
<p>These instructions are specific for the officially supported Zcash Linux
|
||
client. For backing up with third-party wallets, please consult with user
|
||
guides or support channels provided for those services.</p>
|
||
<p>There are multiple ways to make sure you have at least one other copy of the
|
||
private keys needed to spend your ZEC and view your shielded ZEC.</p>
|
||
<p>For all methods, you will need to include an export directory setting in your
|
||
config file (<code>zcash.conf</code> located in the data directory which is <code>~/.zcash/</code>
|
||
unless it's been overridden with <code>datadir=</code> setting):</p>
|
||
<p><code>exportdir=path/to/chosen/export/directory</code></p>
|
||
<p>You may chose any directory within the home directory as the location for
|
||
export & backup files. If the directory doesn't exist, it will be created.</p>
|
||
<p>Note that zcashd will need to be stopped and restarted for edits in the config
|
||
file to take effect.</p>
|
||
<h3 id="using-backupwallet"><a class="header" href="#using-backupwallet">Using <code>backupwallet</code></a></h3>
|
||
<p>To create a backup of your wallet, use:</p>
|
||
<pre><code class="language-bash">$ zcash-cli backupwallet <nameofbackup>
|
||
</code></pre>
|
||
<p>The backup will be an exact copy of the current state of your wallet.dat file
|
||
stored in the export directory you specified in the config file. The file path
|
||
will also be returned.</p>
|
||
<p>If you generate a new Zcash address, it will not be reflected in the backup
|
||
file.</p>
|
||
<p>If your original <code>wallet.dat</code> file becomes inaccessible for whatever reason,
|
||
you can use your backup by copying it into your data directory and renaming the
|
||
copy to <code>wallet.dat</code>.</p>
|
||
<h3 id="using-z_exportwallet--z_importwallet"><a class="header" href="#using-z_exportwallet--z_importwallet">Using <code>z_exportwallet</code> & <code>z_importwallet</code></a></h3>
|
||
<p>If you prefer to have an export of your private keys in human readable format,
|
||
you can use:</p>
|
||
<pre><code class="language-bash">$ zcash-cli z_exportwallet <nameofbackup>`
|
||
</code></pre>
|
||
<p>This will generate a file in the export directory listing all transparent and
|
||
shielded private keys with their associated public addresses. The file path
|
||
will be returned in the command line.</p>
|
||
<p>To import keys into a wallet which were previously exported to a file, use:</p>
|
||
<pre><code class="language-bash">$ zcash-cli z_importwallet <path/to/exportdir/nameofbackup>
|
||
</code></pre>
|
||
<h3 id="using-z_exportkey-z_importkey-dumpprivkey--importprivkey"><a class="header" href="#using-z_exportkey-z_importkey-dumpprivkey--importprivkey">Using <code>z_exportkey</code>, <code>z_importkey</code>, <code>dumpprivkey</code> & <code>importprivkey</code></a></h3>
|
||
<p>If you prefer to export a single private key for a shielded address, you can
|
||
use:</p>
|
||
<pre><code class="language-bash">$ zcash-cli z_exportkey <z-address>
|
||
</code></pre>
|
||
<p>This will return the private key and will not create a new file.</p>
|
||
<p>For exporting a single private key for a transparent address, you can use the
|
||
command inherited from Bitcoin:</p>
|
||
<pre><code class="language-bash">$ zcash-cli dumpprivkey <t-address>
|
||
</code></pre>
|
||
<p>This will return the private key and will not create a new file.</p>
|
||
<p>To import a private key for a shielded address, use:</p>
|
||
<pre><code class="language-bash">$ zcash-cli z_importkey <z-priv-key>
|
||
</code></pre>
|
||
<p>This will add the key to your wallet and rescan the wallet for associated
|
||
transactions if it is not already part of the wallet.</p>
|
||
<p>The rescanning process can take a few minutes for a new private key. To skip
|
||
it, instead use:</p>
|
||
<pre><code class="language-bash">$ zcash-cli z_importkey <z-private-key> no
|
||
</code></pre>
|
||
<p>For other instructions on fine-tuning the wallet rescan, see the command's help
|
||
documentation:</p>
|
||
<pre><code class="language-bash">$ zcash-cli help z_importkey
|
||
</code></pre>
|
||
<p>To import a private key for a transparent address, use:</p>
|
||
<pre><code class="language-bash">$ zcash-cli importprivkey <t-priv-key>
|
||
</code></pre>
|
||
<p>This has the same functionality as <code>z_importkey</code> but works with transparent
|
||
addresses.</p>
|
||
<p>See the command's help documentation for instructions on fine-tuning the wallet
|
||
rescan:</p>
|
||
<pre><code class="language-bash">$ zcash-cli help importprivkey
|
||
</code></pre>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="shielding-coinbase-utxos"><a class="header" href="#shielding-coinbase-utxos">Shielding Coinbase UTXOs</a></h1>
|
||
<p><strong>Summary</strong></p>
|
||
<p>Use <code>z_shieldcoinbase</code> RPC call to shield coinbase UTXOs.</p>
|
||
<p><strong>Who should read this document</strong></p>
|
||
<p>Miners, Mining pools, Online wallets</p>
|
||
<h2 id="background"><a class="header" href="#background">Background</a></h2>
|
||
<p>The current Zcash protocol includes a consensus rule that coinbase rewards must
|
||
be sent to a shielded address.</p>
|
||
<h2 id="user-experience-challenges"><a class="header" href="#user-experience-challenges">User Experience Challenges</a></h2>
|
||
<p>A user can use the z_sendmany RPC call to shield coinbase funds, but the call
|
||
was not designed for sweeping up many UTXOs, and offered a suboptimal user
|
||
experience.</p>
|
||
<p>If customers send mining pool payouts to their online wallet, the service
|
||
provider must sort through UTXOs to correctly determine the non-coinbase UTXO
|
||
funds that can be withdrawn or transferred by customers to another transparent
|
||
address.</p>
|
||
<h2 id="solution"><a class="header" href="#solution">Solution</a></h2>
|
||
<p>The z_shieldcoinbase call makes it easy to sweep up coinbase rewards from
|
||
multiple coinbase UTXOs across multiple coinbase reward addresses.</p>
|
||
<pre><code>z_shieldcoinbase fromaddress toaddress (fee) (limit)
|
||
</code></pre>
|
||
<p>The default fee is 0.0010000 ZEC and the default limit on the maximum number of
|
||
UTXOs to shield is 50.</p>
|
||
<h2 id="examples"><a class="header" href="#examples">Examples</a></h2>
|
||
<p>Sweep up coinbase UTXOs from a transparent address you use for mining:</p>
|
||
<pre><code>zcash-cli z_shieldcoinbase tMyMiningAddress zMyPrivateAddress
|
||
</code></pre>
|
||
<p>Sweep up coinbase UTXOs from multiple transparent addresses to a shielded
|
||
address:</p>
|
||
<pre><code>zcash-cli z_shieldcoinbase "*" zMyPrivateAddress
|
||
</code></pre>
|
||
<p>Sweep up with a fee of 1.23 ZEC:</p>
|
||
<pre><code>zcash-cli z_shieldcoinbase tMyMiningAddress zMyPrivateAddress 1.23
|
||
</code></pre>
|
||
<p>Sweep up with a fee of 0.1 ZEC and set limit on the maximum number of UTXOs to
|
||
shield at 25:</p>
|
||
<pre><code>zcash-cli z_shieldcoinbase "*" zMyPrivateAddress 0.1 25
|
||
</code></pre>
|
||
<h3 id="asynchronous-call"><a class="header" href="#asynchronous-call">Asynchronous Call</a></h3>
|
||
<p>The <code>z_shieldcoinbase</code> RPC call is an asynchronous call, so you can queue up
|
||
multiple operations.</p>
|
||
<p>When you invoke</p>
|
||
<pre><code>zcash-cli z_shieldcoinbase tMyMiningAddress zMyPrivateAddress
|
||
</code></pre>
|
||
<p>JSON will be returned immediately, with the following data fields populated:</p>
|
||
<ul>
|
||
<li>operationid: a temporary id to use with <code>z_getoperationstatus</code> and
|
||
<code>z_getoperationresult</code> to get the status and result of the operation.</li>
|
||
<li>shieldedUTXOs: number of coinbase UTXOs being shielded</li>
|
||
<li>shieldedValue: value of coinbase UTXOs being shielded.</li>
|
||
<li>remainingUTXOs: number of coinbase UTXOs still available for shielding.</li>
|
||
<li>remainingValue: value of coinbase UTXOs still available for shielding</li>
|
||
</ul>
|
||
<h3 id="locking-utxos"><a class="header" href="#locking-utxos">Locking UTXOs</a></h3>
|
||
<p>The <code>z_shieldcoinbase</code> call will lock any selected UTXOs. This prevents the
|
||
selected UTXOs which are already queued up from being selected for any other
|
||
send operation. If the <code>z_shieldcoinbase</code> call fails, any locked UTXOs are
|
||
unlocked.</p>
|
||
<p>You can use the RPC call <code>lockunspent</code> to see which UTXOs have been locked.
|
||
You can also use this call to unlock any UTXOs in the event of an unexpected
|
||
system failure which leaves UTXOs in a locked state.</p>
|
||
<h3 id="limits-performance-and-transaction-confirmation"><a class="header" href="#limits-performance-and-transaction-confirmation">Limits, Performance and Transaction Confirmation</a></h3>
|
||
<p>The number of coinbase UTXOs selected for shielding can be adjusted by setting
|
||
the limit parameter. The default value is 50.</p>
|
||
<p>If the limit parameter is set to zero, the zcashd <code>mempooltxinputlimit</code> option
|
||
will be used instead, where the default value for <code>mempooltxinputlimit</code> is
|
||
zero, which means no limit.</p>
|
||
<p>Any limit is constrained by a hard limit due to the consensus rule defining a
|
||
maximum transaction size of 100,000 bytes.</p>
|
||
<p>In general, the more UTXOs that are selected, the longer it takes for the
|
||
transaction to be verified. Due to the quadratic hashing problem, some miners
|
||
use the <code>mempooltxinputlimit</code> option to reject transactions with a large number
|
||
of UTXO inputs.</p>
|
||
<p>Currently, as of November 2017, there is no commonly agreed upon limit, but as
|
||
a rule of thumb (a form of emergent consensus) if a transaction has less than
|
||
100 UTXO inputs, the transaction will be mined promptly by the majority of
|
||
mining pools, but if it has many more UTXO inputs, such as 500, it might take
|
||
several days to be mined by a miner who has higher or no limits.</p>
|
||
<h3 id="anatomy-of-a-z_shieldcoinbase-transaction"><a class="header" href="#anatomy-of-a-z_shieldcoinbase-transaction">Anatomy of a z_shieldcoinbase transaction</a></h3>
|
||
<p>The transaction created is a shielded transaction. It consists of a single
|
||
joinsplit, which consumes coinbase UTXOs as input, and deposits value at a
|
||
shielded address, minus any fee.</p>
|
||
<p>The number of coinbase UTXOs is determined by a user configured limit.</p>
|
||
<p>If no limit is set (in the case when limit parameter and <code>mempooltxinputlimit</code>
|
||
options are set to zero) the behaviour of z_shieldcoinbase is to consume as
|
||
many UTXOs as possible, with <code>z_shieldcoinbase</code> constructing a transaction up
|
||
to the size limit of 100,000 bytes.</p>
|
||
<p>As a result, the maximum number of inputs that can be selected is:</p>
|
||
<ul>
|
||
<li>P2PKH coinbase UTXOs ~ 662</li>
|
||
<li>2-of-3 multisig P2SH coinbase UTXOs ~ 244.</li>
|
||
</ul>
|
||
<p>Here is an example of using <code>z_shieldcoinbase</code> on testnet to shield multi-sig coinbase UTXOs.</p>
|
||
<ul>
|
||
<li>Block 141042 is almost ~2 MB in size (the maximum size for a block) and
|
||
contains 1 coinbase reward transaction and 20 transactions, each indivually
|
||
created by a call to z_shieldcoinbase.
|
||
<ul>
|
||
<li>https://explorer.testnet.z.cash/block/0050552a78e97c89f666713c8448d49ad1d7263274422272696187dedf6c0d03</li>
|
||
</ul>
|
||
</li>
|
||
<li>Drilling down into a transaction, you can see there is one joinsplit, with
|
||
244 inputs (vin) and 0 outputs (vout).
|
||
<ul>
|
||
<li>https://explorer.testnet.z.cash/tx/cf4f3da2e434f68b6e361303403344e22a9ff9a8fda9abc180d9520d0ca6527d</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="data-directory-files"><a class="header" href="#data-directory-files">Data Directory Files</a></h1>
|
||
<p>Files within the zcashd data directory (<code>~/.zcash/</code> on Linux unless otherwise specified)
|
||
include:</p>
|
||
<div class="table-wrapper"><table><thead><tr><th>File</th><th>Description</th></tr></thead><tbody>
|
||
<tr><td><code>zcash.conf</code></td><td>contains configuration settings for zcashd</td></tr>
|
||
<tr><td><code>zcashd.pid</code></td><td>stores the process id of zcashd while running</td></tr>
|
||
<tr><td><code>blocks/blk000*.dat</code></td><td>block data (custom, 128 MiB per file)</td></tr>
|
||
<tr><td><code>blocks/rev000*.dat</code></td><td>block undo data (custom)</td></tr>
|
||
<tr><td><code>blocks/index/*</code></td><td>block index (LevelDB)</td></tr>
|
||
<tr><td><code>chainstate/*</code></td><td>block chain state database (LevelDB)</td></tr>
|
||
<tr><td><code>database/*</code></td><td>BDB database environment</td></tr>
|
||
<tr><td><code>db.log</code></td><td>wallet database log file</td></tr>
|
||
<tr><td><code>debug.log</code></td><td>contains debug information and general logging generated by zcashd</td></tr>
|
||
<tr><td><code>fee_estimates.dat</code></td><td>stores statistics used to estimate minimum transaction fees and priorities required for confirmation</td></tr>
|
||
<tr><td><code>peers.dat</code></td><td>peer IP address database (custom format)</td></tr>
|
||
<tr><td><code>wallet.dat</code></td><td>personal wallet (BDB) with keys and transactions (keep private, back this up!)</td></tr>
|
||
<tr><td><code>.cookie</code></td><td>session RPC authentication cookie (written at start when cookie authentication is used, deleted on shutdown)</td></tr>
|
||
<tr><td><code>.lock</code></td><td>data directory lock file (empty)</td></tr>
|
||
<tr><td><code>testnet3/*</code></td><td>contains testnet versions of these files, except <code>zcash.conf</code>, if running <code>-testnet</code></td></tr>
|
||
<tr><td><code>onion_private_key</code></td><td>cached Tor hidden service private key for <code>-listenonion</code></td></tr>
|
||
</tbody></table>
|
||
</div><div style="break-before: page; page-break-before: always;"></div><h1 id="zcashd-metrics"><a class="header" href="#zcashd-metrics">zcashd metrics</a></h1>
|
||
<h2 id="metrics-ui"><a class="header" href="#metrics-ui">Metrics UI</a></h2>
|
||
<p>This is the user interface that <code>zcashd</code> displays by default when run. It
|
||
displays a small selection of interesting metrics, but is not intended for
|
||
programmatic consumption.</p>
|
||
<h2 id="rpc-methods"><a class="header" href="#rpc-methods">RPC methods</a></h2>
|
||
<p><code>zcashd</code> provides the following JSON-RPC methods that expose node metrics:</p>
|
||
<ul>
|
||
<li>Chain:
|
||
<ul>
|
||
<li><code>getblockchaininfo</code>: Various state info regarding block chain processing.</li>
|
||
<li><code>gettxoutsetinfo</code>: Statistics about the unspent transparent transaction output set.</li>
|
||
<li><code>getmempoolinfo</code>: Details on the active state of the TX memory pool.</li>
|
||
</ul>
|
||
</li>
|
||
<li>P2P network:
|
||
<ul>
|
||
<li><code>getnetworkinfo</code>: Various state info regarding P2P networking.</li>
|
||
<li><code>getpeerinfo</code>: Data about each connected network node.</li>
|
||
<li><code>getdeprecationinfo</code>: The current node version and deprecation block height.</li>
|
||
</ul>
|
||
</li>
|
||
<li>Miscellaneous
|
||
<ul>
|
||
<li><code>getmemoryinfo</code>: Information about memory usage.</li>
|
||
<li><code>getmininginfo</code>: Mining-related information.</li>
|
||
<li><code>getinfo</code> (deprecated): A small subset of the above metrics.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>You can see what each method provides with <code>zcash-cli help METHOD_NAME</code>.</p>
|
||
<h2 id="prometheus-support"><a class="header" href="#prometheus-support">Prometheus support</a></h2>
|
||
<p><code>zcashd</code> can optionally expose an HTTP server that acts as a Prometheus scrape
|
||
endpoint. The server will respond to <code>GET</code> requests on any request path.</p>
|
||
<p>To enable the endpoint, add <code>-prometheusport=<port></code> to your <code>zcashd</code>
|
||
configuration (either in <code>zcash.conf</code> or on the command line). After
|
||
restarting <code>zcashd</code> you can then test the endpoint by querying it:</p>
|
||
<pre><code>$ curl http://127.0.0.1:<port>
|
||
# TYPE zcash_net_out_messages counter
|
||
zcash_net_out_messages 181
|
||
|
||
# TYPE zcash_net_in_bytes_total counter
|
||
zcash_net_in_bytes_total 3701998
|
||
|
||
# TYPE zcash_net_in_messages counter
|
||
zcash_net_in_messages 184
|
||
|
||
# TYPE zcashd_build_info counter
|
||
zcashd_build_info{version="v4.2.0"} 1
|
||
|
||
# TYPE zcash_chain_verified_block_total counter
|
||
zcash_chain_verified_block_total 162
|
||
...
|
||
</code></pre>
|
||
<p>By default, access is restricted to localhost. This can be expanded with
|
||
<code>-metricsallowip=<ip></code>, which can specify IPs or subnets. Note that HTTPS is
|
||
not supported, and therefore connections to the endpoint are not encrypted or
|
||
authenticated. Access to the endpoint should be assumed to compromise the
|
||
privacy of node operations, by the provided metrics and/or by timing side
|
||
channels. Non-localhost access is <strong>strongly discouraged</strong> if the node has a
|
||
wallet holding live funds.</p>
|
||
<h3 id="metrics-collection-with-docker"><a class="header" href="#metrics-collection-with-docker">Metrics collection with Docker</a></h3>
|
||
<p>A docker-compose.yml has been provided in <code>./contrib/metrics</code> that sets up
|
||
local instances of <code>prometheus</code> and <code>grafana</code> and provides a dashboard that
|
||
charts several of the various metrics exposed by <code>zcashd</code>'s <code>prometheus</code>
|
||
endpoint. Note that both <code>docker</code> and <code>docker-compose</code> must ordinarily be run
|
||
with superuser permissions (use <code>sudo</code>) when running on Linux.</p>
|
||
<p><code>docker-compose up</code><sup class="footnote-reference"><a href="#1">1</a></sup> will start local instances of <code>prometheus</code> and <code>grafana</code>,
|
||
accessible over HTTP on ports <code>9090</code> and <code>3030</code>, respectively. </p>
|
||
<pre><code>cd <zcash_root>/contrib/metrics
|
||
docker-compose up -d
|
||
</code></pre>
|
||
<p>(substitute the root directory where you have checked out the <code>zcash</code> git
|
||
repository for <code><zcash_root></code>)</p>
|
||
<p><code>~/.zcash/zcash.conf</code> must be updated to enable <code>prometheus</code> and to allow the
|
||
<code>prometheus</code> server launched via <code>docker-compose</code> to connect to the <code>zcashd</code>
|
||
prometheus endpoint. The following commands can be used to detect the local IP
|
||
address for the <code>prometheus</code> server and add it to the <code>~/.zcash/zcash.conf</code>
|
||
file. </p>
|
||
<p>First, figure out where <code>prometheus</code> is running.</p>
|
||
<pre><code>export PROMETHEUS_DOCKER_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' zcashd-prometheus)
|
||
</code></pre>
|
||
<p>Then, update your <code>~/.zcash/zcash.conf</code> file to open port <code>9969</code> and allow
|
||
connections from the <code>zcashd-prometheus</code> docker container.</p>
|
||
<pre><code>cat << PROM_CONF >> ~/.zcash/zcash.conf
|
||
prometheusport=9969
|
||
metricsallowip=$PROMETHEUS_DOCKER_IP/32
|
||
PROM_CONF
|
||
</code></pre>
|
||
<p>You may then (re)start <code>zcashd</code> and navigate to
|
||
<a href="http://localhost:9090/targets?search=">http://localhost:9090/targets?search=</a>
|
||
to verify that the <code>prometheus</code> server is able to connect to the <code>zcashd</code>
|
||
prometheus endpoint; you should see the host
|
||
<code>http://host.docker.internal:9969/</code> having <code>UP</code> status. Once this is working,
|
||
navigate to
|
||
<a href="http://localhost:3030/d/U4U58t-Gk/zcashd-metrics">http://localhost:3030/d/U4U58t-Gk/zcashd-metrics</a>
|
||
to view the dashboard. The username and password for this local grafana
|
||
instance are set by default to <code>admin</code>/<code>admin</code>; the UI will ask you to change
|
||
this on first use. Data gathered by the running prometheus instance and changes
|
||
that you make to the grafana interface will be persisted across restarts.</p>
|
||
<h4 id="manual-docker-setup-without-docker-compose"><a class="header" href="#manual-docker-setup-without-docker-compose">Manual Docker Setup Without docker-compose</a></h4>
|
||
<p>The example instructions below were tested on Windows 10 using Docker Desktop
|
||
with the WSL 2 backend, connected to a <code>zcashd</code> running inside WSL2 (but not
|
||
inside Docker):</p>
|
||
<pre><code># Create a storage volume for Grafana (once)
|
||
docker volume create grafana-storage
|
||
|
||
# Create a storage volume for Prometheus (once)
|
||
docker volume create prometheus-storage
|
||
|
||
# Run Prometheus
|
||
# You will need to modify $(zcash_root)/contrib/metrics/prometheus.yaml to match the
|
||
# port configured with -prometheusport and -metricsbind / -metricsallowip
|
||
# (and possibly also for your Docker network setup).
|
||
docker run --detach -p 9090:9090 --volume prometheus-storage:/prometheus --volume $(zcash_root)/contrib/metrics/prometheus.yaml:/etc/prometheus/prometheus.yml prom/prometheus
|
||
|
||
# Run Grafana
|
||
docker run --detach -p 3030:3030 --env GF_SERVER_HTTP_PORT=3030 --volume grafana-storage:/var/lib/grafana grafana/grafana
|
||
</code></pre>
|
||
<div class="footnote-definition" id="1"><sup class="footnote-definition-label">1</sup>
|
||
<p>This requires a running Docker daemon. See <a href="https://docs.docker.com/config/daemon/start/">the relevant section of the
|
||
Docker Engine manual</a>.</p>
|
||
</div>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="tor-support-in-zcash"><a class="header" href="#tor-support-in-zcash">Tor Support in Zcash</a></h1>
|
||
<p>Tor can be used to provide a layer of network anonymity for Zcash users.
|
||
Additionally, Zcash users may chose to connect only to Tor hidden services, and
|
||
also to expose their own Tor hidden service to allow users to connect to them
|
||
over the Tor network.</p>
|
||
<ol start="0">
|
||
<li>Install Tor</li>
|
||
</ol>
|
||
<hr />
|
||
<p>The easiest way to install Tor is to use the
|
||
<a href="https://www.torproject.org/download/">Tor Browser Bundle</a>. For headless
|
||
installs, you probably want to install the Tor daemon. The Tor Project
|
||
provides <a href="https://support.torproject.org/apt/">instructions</a> for doing this on
|
||
common Linux distributions. Note that the Tor Browser Bundle exposes a SOCKS
|
||
listener on tcp/9150 by default, while the Tor daemon exposes the SOCKS
|
||
listener on tcp/9050. For the purposes of the example below, we'll assume that
|
||
you're using the Tor daemon and that the SOCKS listener is on tcp/9050.</p>
|
||
<ol>
|
||
<li>Run zcashd over Tor</li>
|
||
</ol>
|
||
<hr />
|
||
<p>Configuring zcashd to use a Tor SOCKS proxy will route all outgoing connections
|
||
over Tor.</p>
|
||
<pre><code class="language-bash">$ zcashd -proxy=127.0.0.1:9050
|
||
</code></pre>
|
||
<p>Yay! Your zcashd node is now leveraging the Tor network to connect to other
|
||
zcashd nodes. But there's more fun to be had. By creating a
|
||
<a href="https://2019.www.torproject.org/docs/faq.html.en#TorOnionServices">Tor Hidden Service</a>.
|
||
you can help promote privacy for Zcash users by advertising your node's .onion
|
||
address to other Tor Zcash users.</p>
|
||
<ol start="2">
|
||
<li>Expose your zcashd via a Tor hidden service (optional)</li>
|
||
</ol>
|
||
<hr />
|
||
<p>Edit your /etc/tor/torrc (or equivalent config file) to map the hidden service
|
||
to your zcashd TCP listener. The directory can be whatever you like but the
|
||
port numbers should be equal to the zcashd p2p listen port (8233 by default).
|
||
An example is below.</p>
|
||
<pre><code class="language-yaml">############### This section is just for location-hidden services ###
|
||
|
||
## Once you have configured a hidden service, you can look at the
|
||
## contents of the file ".../hidden_service/hostname" for the address
|
||
## to tell people.
|
||
##
|
||
## HiddenServicePort x y:z says to redirect requests on port x to the
|
||
## address y:z.
|
||
|
||
#
|
||
# Placeholder for when zcashd adds support for Onion v3 addresses
|
||
#HiddenServiceDir /var/lib/tor/zcash_hidden_service_v3/
|
||
#HiddenServiceVersion 3
|
||
#HiddenServicePort 8233 127.0.0.1:8233
|
||
|
||
# use the generated v2 Onion hostname until v3 support is complete
|
||
HiddenServiceDir /var/lib/tor/zcash_hidden_service_v2/
|
||
HiddenServiceVersion 2
|
||
HiddenServicePort 8233 127.0.0.1:8233
|
||
</code></pre>
|
||
<p>Note that zcashd does not yet support Onion v3 addresses, but will do so before
|
||
v2 addresses are removed from Tor. See <a href="https://github.com/zcash/zcash/issues/3051">this
|
||
issue</a> for more information on
|
||
what's required to make zcashd support v3 Onion addresses.</p>
|
||
<p>After making these edits to /etc/tor/torrc, restart tor to create the hidden
|
||
service hostname and keys.</p>
|
||
<pre><code class="language-bash">$ sudo systemctl restart tor
|
||
</code></pre>
|
||
<p>Then set a bash variable to provide your Onion service hostname to zcashd so it
|
||
can advertise your node to other Tor capable nodes on the Zcash network.</p>
|
||
<pre><code class="language-bash">$ export MY_ONION_HOSTNAME=`sudo cat /var/lib/tor/zcash_hidden_service_v2/hostname`
|
||
</code></pre>
|
||
<p>Now configure the zcashd node to use the Tor proxy, enable the TCP listener
|
||
(only on localhost), and advertise your onion address so that other nodes on
|
||
the Zcash network can connect to you over Tor.</p>
|
||
<pre><code class="language-bash">$ zcashd -proxy=127.0.0.1:9050 -externalip=$MY_ONION_HOSTNAME -listen -bind=127.0.0.1 -listenonion=0
|
||
</code></pre>
|
||
<p>zcashd flags used:</p>
|
||
<ul>
|
||
<li><code>-proxy=ip:port</code>: sets the proxy server. This must match the port IP and port
|
||
on which your Tor listener is configured.</li>
|
||
<li><code>-externalip=<ip|host></code>: sets the publicly routable address that zcashd will
|
||
advertise to other zcash nodes. This can be an IPv4, IPv6 or .onion address.
|
||
Onion addresses are given preference for advertising and connections. Onionv3
|
||
addresses are <a href="https://github.com/zcash/zcash/issues/3051">not yet supported</a>.</li>
|
||
<li><code>-listen</code>: Enable listening for incoming connections with this flag;
|
||
listening is off by default, but is needed in order for Tor to connect to
|
||
zcashd.</li>
|
||
<li><code>-bind=ip</code>: Bind (only) to this IP. Will bind to all interfaces by default
|
||
if <code>listen=1</code>.</li>
|
||
<li><code>-listenonion=<0|1></code>: Enable or disable autoconfiguration of Tor hidden
|
||
service via control socket API. Disabled in this example because we manually
|
||
configured the hidden service in /etc/tor/torrc.</li>
|
||
</ul>
|
||
<p>Once your node is up and running, you can use <code>zcash-cli</code> to verify that it
|
||
is properly connected to other Zcash nodes over the p2p network, and is
|
||
correctly advertising its Onion address to the network.</p>
|
||
<pre><code class="language-bash">$ zcash-cli getnetworkinfo
|
||
</code></pre>
|
||
<pre><code class="language-javascript">{
|
||
"version": 4020050,
|
||
"subversion": "/MagicBean:4.2.0/",
|
||
"protocolversion": 170013,
|
||
"connections": 9,
|
||
"networks": [
|
||
{
|
||
"name": "ipv4",
|
||
"limited": true,
|
||
"reachable": false,
|
||
"proxy": "127.0.0.1:9050",
|
||
"proxy_randomize_credentials": true
|
||
},
|
||
{
|
||
"name": "ipv6",
|
||
"limited": true,
|
||
"reachable": false,
|
||
"proxy": "127.0.0.1:9050",
|
||
"proxy_randomize_credentials": true
|
||
},
|
||
{
|
||
"name": "onion",
|
||
"limited": false,
|
||
"reachable": true,
|
||
"proxy": "127.0.0.1:9050",
|
||
"proxy_randomize_credentials": true
|
||
}
|
||
],
|
||
"relayfee": 0.00000100,
|
||
"localaddresses": [
|
||
{
|
||
"address": "ynizm2wpla6ec22q.onion",
|
||
"port": 8233,
|
||
"score": 10
|
||
}
|
||
],
|
||
}
|
||
</code></pre>
|
||
<ol start="3">
|
||
<li>Dynamically Configure Onion Service (Optional)</li>
|
||
</ol>
|
||
<hr />
|
||
<p>Starting with Tor version 0.2.7.1 it is possible, through Tor's control socket
|
||
API, to create and destroy 'ephemeral' hidden services programmatically. zcashd
|
||
has been updated to make use of this.</p>
|
||
<p>This configuration could be used instead of manually configuring the Onion
|
||
service as in step 2 above.</p>
|
||
<p>If Tor is running (and proper authentication has been configured), zcashd
|
||
automatically creates a hidden service to listen on. zcashd will also use Tor
|
||
automatically to connect to other .onion nodes if the control socket can be
|
||
successfully opened.</p>
|
||
<p>This new feature is enabled by default if zcashd is listening (<code>-listen</code>) and
|
||
requires a Tor connection to work. It can be explicitly disabled with
|
||
<code>-listenonion=0</code> and, if not disabled, configured using the <code>-torcontrol</code>
|
||
and <code>-torpassword</code> settings. To show verbose debugging information, pass
|
||
<code>-debug=tor</code>.</p>
|
||
<p>Connecting to Tor's control socket API requires one of two authentication
|
||
methods to be configured:</p>
|
||
<ol>
|
||
<li>Cookie authentication, which requires write access to the <code>CookieAuthFile</code>
|
||
specified in Tor configuration. In some cases, this is preconfigured and the
|
||
creation of a hidden service is automatic. If permission problems are seen
|
||
with <code>-debug=tor</code> they can be resolved by adding both the user running tor
|
||
and the user running zcashd to the same group and setting permissions
|
||
appropriately. On Debian-based systems the user running zcashd can be added
|
||
to the debian-tor group, which has the appropriate permissions.</li>
|
||
<li>Authentication with the <code>-torpassword</code> flag and a <code>hash-password</code>, which
|
||
can be enabled and specified in Tor configuration.</li>
|
||
</ol>
|
||
<p>On Debian systems, where Tor is installed via APT, you can trivially permit
|
||
zcashd to connect to the Tor socket by adding the zcash user to the
|
||
<code>debian-tor</code> group.</p>
|
||
<pre><code class="language-bash">$ sudo usermod -aG debian-tor zcash
|
||
</code></pre>
|
||
<p>When properly configured, this will allow zcashd to automatically connect to
|
||
the Tor control socket API and configure an ephemeral hidden service.</p>
|
||
<pre><code class="language-bash">$ zcashd -debug=tor
|
||
</code></pre>
|
||
<pre><code>Feb 11 15:26:20.323 INFO main: tor: Got service ID tweustb4j6o3u5x7, advertizing service tweustb4j6o3u5x7.onion:8233
|
||
Feb 11 15:26:20.323 DEBUG tor: tor: Cached service private key to /home/zcash/.zcash/onion_private_key
|
||
Feb 11 15:26:20.323 INFO main: AddLocal(tweustb4j6o3u5x7.onion:8233,4)
|
||
...
|
||
Feb 11 15:26:47.565 INFO main: ProcessMessages: advertizing address tweustb4j6o3u5x7.onion:8233
|
||
</code></pre>
|
||
<ol start="4">
|
||
<li>Connect to a single Zcash Onion server</li>
|
||
</ol>
|
||
<hr />
|
||
<p>This invocation will start zcashd and connect via Tor to a single zcashd onion
|
||
server.</p>
|
||
<p>Launch zcashd as follows:</p>
|
||
<pre><code class="language-bash">$ zcashd -onion=127.0.0.1:9050 -connect=ynizm2wpla6ec22q.onion
|
||
</code></pre>
|
||
<ul>
|
||
<li><code>-onion=ip:port</code>: Use SOCKS5 proxy to reach peers via Tor hidden services.
|
||
This must match the port IP and port on which your Tor listener is
|
||
configured.</li>
|
||
<li><code>-connect=<hostname|ip></code>: Connect only to the specified node(s); <code>-noconnect</code>
|
||
or <code>-connect=0</code> alone to disable automatic connections</li>
|
||
</ul>
|
||
<p>Now use zcash-cli to verify there is only a single peer connection.</p>
|
||
<pre><code class="language-bash">$ zcash-cli getpeerinfo
|
||
</code></pre>
|
||
<pre><code class="language-javascript">[
|
||
{
|
||
"id": 1,
|
||
"addr": "ynizm2wpla6ec22q.onion",
|
||
...
|
||
"version": 170013,
|
||
"subver": "/MagicBean:4.2.0/",
|
||
"inbound": false,
|
||
...
|
||
}
|
||
]
|
||
</code></pre>
|
||
<ol start="4">
|
||
<li>Connect to multiple Zcash Onion servers</li>
|
||
</ol>
|
||
<hr />
|
||
<p>This invocation will start zcashd, skip DNS seeding, connect via Tor to a
|
||
multiple zcashd onion servers, and also advertise your Onion server to other
|
||
Tor capable Zcash nodes.</p>
|
||
<p>Launch zcashd as follows:</p>
|
||
<pre><code class="language-bash">$ export MY_ONION_HOSTNAME=`sudo cat /var/lib/tor/zcash_hidden_service_v2/hostname`
|
||
$ zcashd -listen -onion=127.0.0.1:9050 -addnode=ynizm2wpla6ec22q.onion -dnsseed=0 -onlynet=onion -externalip=$MY_ONION_HOSTNAME -bind=127.0.0.1
|
||
</code></pre>
|
||
<p>zcashd flags used:</p>
|
||
<ul>
|
||
<li><code>-onion=ip:port</code>: Use SOCKS5 proxy to reach peers via Tor hidden services.
|
||
This must match the port IP and port on which your Tor listener is
|
||
configured.</li>
|
||
<li><code>-addnode=<host|ip></code>: Add a node to connect to and attempt to keep the
|
||
connection open</li>
|
||
<li><code>-externalip=<ip|onion></code>: sets the publicly routable address that zcashd will
|
||
advertise to other zcash nodes. This can be an IPv4, IPv6 or .onion address.
|
||
Onion addresses are given preference for advertising and connections. Onionv3
|
||
addresses are <a href="https://github.com/zcash/zcash/issues/3051">not yet supported</a>.</li>
|
||
<li><code>-listen</code>: Enable listening for incoming connections with this flag;
|
||
listening is off by default, but is needed in order for Tor to connect to
|
||
zcashd.</li>
|
||
<li><code>-bind=<ip></code>: Bind (only) to this IP. Will bind to all interfaces by default
|
||
if <code>listen=1</code> and <code>bind</code> is not set.</li>
|
||
<li><code>-onlynet=<net></code>: Only connect to nodes in network <code><net></code> (ipv4, ipv6 or
|
||
onion)</li>
|
||
</ul>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="security-warnings"><a class="header" href="#security-warnings">Security Warnings</a></h1>
|
||
<h2 id="security-audit"><a class="header" href="#security-audit">Security Audit</a></h2>
|
||
<p>Zcash has been subjected to a formal third-party security review. For security
|
||
announcements, audit results and other general security information, see
|
||
https://z.cash/support/security.html</p>
|
||
<h2 id="wallet-encryption"><a class="header" href="#wallet-encryption">Wallet Encryption</a></h2>
|
||
<p>Wallet encryption is disabled, for several reasons:</p>
|
||
<ul>
|
||
<li>
|
||
<p>Encrypted wallets are unable to correctly detect shielded spends (due to the
|
||
nature of unlinkability of JoinSplits) and can incorrectly show larger
|
||
available shielded balances until the next time the wallet is unlocked. This
|
||
problem was not limited to failing to recognize the spend; it was possible
|
||
for the shown balance to increase by the amount of change from a spend,
|
||
without deducting the spent amount.</p>
|
||
</li>
|
||
<li>
|
||
<p>While encrypted wallets prevent spending of funds, they do not maintain the
|
||
shielding properties of JoinSplits (due to the need to detect spends). That
|
||
is, someone with access to an encrypted wallet.dat has full visibility of
|
||
your entire transaction graph (other than newly-detected spends, which suffer
|
||
from the earlier issue).</p>
|
||
</li>
|
||
<li>
|
||
<p>We were concerned about the resistance of the algorithm used to derive wallet
|
||
encryption keys (inherited from
|
||
<a href="https://bitcoin.org/en/secure-your-wallet">Bitcoin</a>) to dictionary attacks
|
||
by a powerful attacker. If and when we re-enable wallet encryption, it is
|
||
likely to be with a modern passphrase-based key derivation algorithm designed
|
||
for greater resistance to dictionary attack, such as Argon2i.</p>
|
||
</li>
|
||
</ul>
|
||
<p>You should use full-disk encryption (or encryption of your home directory) to
|
||
protect your wallet at rest, and should assume (even unprivileged) users who
|
||
are running on your OS can read your wallet.dat file.</p>
|
||
<h2 id="side-channel-attacks"><a class="header" href="#side-channel-attacks">Side-Channel Attacks</a></h2>
|
||
<p>This implementation of Zcash is not resistant to side-channel attacks. You
|
||
should assume (even unprivileged) users who are running on the hardware, or who
|
||
are physically near the hardware, that your <code>zcashd</code> process is running on
|
||
will be able to:</p>
|
||
<ul>
|
||
<li>
|
||
<p>Determine the values of your secret spending keys, as well as which notes you
|
||
are spending, by observing cache side-channels as you perform a JoinSplit
|
||
operation. This is due to probable side-channel leakage in the libsnark
|
||
proving machinery.</p>
|
||
</li>
|
||
<li>
|
||
<p>Determine which notes you own by observing cache side-channel information
|
||
leakage from the incremental witnesses as they are updated with new notes.</p>
|
||
</li>
|
||
<li>
|
||
<p>Determine which notes you own by observing the trial decryption process of
|
||
each note ciphertext on the blockchain.</p>
|
||
</li>
|
||
</ul>
|
||
<p>You should ensure no other users have the ability to execute code (even
|
||
unprivileged) on the hardware your <code>zcashd</code> process runs on until these
|
||
vulnerabilities are fully analyzed and fixed.</p>
|
||
<h2 id="rest-interface"><a class="header" href="#rest-interface">REST Interface</a></h2>
|
||
<p>The REST interface is a feature inherited from upstream Bitcoin. By default,
|
||
it is disabled. We do not recommend you enable it until it has undergone a
|
||
security review.</p>
|
||
<h2 id="rpc-interface"><a class="header" href="#rpc-interface">RPC Interface</a></h2>
|
||
<p>Users should choose a strong RPC password. If no RPC username and password are
|
||
set, zcashd will not start and will print an error message with a suggestion
|
||
for a strong random password. If the client knows the RPC password, they have
|
||
at least full access to the node. In addition, certain RPC commands can be
|
||
misused to overwrite files and/or take over the account that is running zcashd.
|
||
(In the future we may restrict these commands, but full node access – including
|
||
the ability to spend from and export keys held by the wallet – would still be
|
||
possible unless wallet methods are disabled.)</p>
|
||
<p>Users should also refrain from changing the default setting that only allows
|
||
RPC connections from localhost. Allowing connections from remote hosts would
|
||
enable a MITM to execute arbitrary RPC commands, which could lead to compromise
|
||
of the account running zcashd and loss of funds. For multi-user services that
|
||
use one or more zcashd instances on the backend, the parameters passed in by
|
||
users should be controlled to prevent confused-deputy attacks which could spend
|
||
from any keys held by that zcashd.</p>
|
||
<h2 id="block-chain-reorganization-major-differences"><a class="header" href="#block-chain-reorganization-major-differences">Block Chain Reorganization: Major Differences</a></h2>
|
||
<p>Users should be aware of new behavior in Zcash that differs significantly from
|
||
Bitcoin: in the case of a block chain reorganization, Bitcoin's coinbase
|
||
maturity rule helps to ensure that any reorganization shorter than the maturity
|
||
interval will not invalidate any of the rolled-back transactions. Zcash keeps
|
||
Bitcoin's 100-block maturity interval for generation transactions, but because
|
||
JoinSplits must be anchored within a block, this provides more limited
|
||
protection against transactions becoming invalidated. In the case of a block
|
||
chain reorganization for Zcash, all JoinSplits which were anchored within the
|
||
reorganization interval and any transactions that depend on them will become
|
||
invalid, rolling back transactions and reverting funds to the original owner.
|
||
The transaction rebroadcast mechanism inherited from Bitcoin will not
|
||
successfully rebroadcast transactions depending on invalidated JoinSplits if
|
||
the anchor needs to change. The creator of an invalidated JoinSplit, as well as
|
||
the creators of all transactions dependent on it, must rebroadcast the
|
||
transactions themselves.</p>
|
||
<p>Receivers of funds from a JoinSplit can mitigate the risk of relying on funds
|
||
received from transactions that may be rolled back by using a higher minconf
|
||
(minimum number of confirmations).</p>
|
||
<h2 id="logging-z_-rpc-calls"><a class="header" href="#logging-z_-rpc-calls">Logging z_* RPC calls</a></h2>
|
||
<p>The option <code>-debug=zrpc</code> covers logging of the z_* calls. This will reveal
|
||
information about private notes which you might prefer not to disclose. For
|
||
example, when calling <code>z_sendmany</code> to create a shielded transaction, input
|
||
notes are consumed and new output notes are created.</p>
|
||
<p>The option <code>-debug=zrpcunsafe</code> covers logging of sensitive information in z_*
|
||
calls which you would only need for debugging and audit purposes. For example,
|
||
if you want to examine the memo field of a note being spent.</p>
|
||
<p>Private spending keys for z addresses are never logged.</p>
|
||
<h2 id="potentially-missing-required-modifications"><a class="header" href="#potentially-missing-required-modifications">Potentially-Missing Required Modifications</a></h2>
|
||
<p>In addition to potential mistakes in code we added to Bitcoin Core, and
|
||
potential mistakes in our modifications to Bitcoin Core, it is also possible
|
||
that there were potential changes we were supposed to make to Bitcoin Core but
|
||
didn't, either because we didn't even consider making those changes, or we ran
|
||
out of time. We have brainstormed and documented a variety of such
|
||
possibilities in <a href="https://github.com/zcash/zcash/issues/826">issue #826</a>, and
|
||
believe that we have changed or done everything that was necessary for the
|
||
1.0.0 launch. Users may want to review this list themselves.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="deprecated-features"><a class="header" href="#deprecated-features">Deprecated Features</a></h1>
|
||
<p>In order to support the continuous improvement of <code>zcashd</code>, features are
|
||
periodically deprecated and removed when they have been superseded or are no
|
||
longer useful. Deprecation follows a 3-stage process:</p>
|
||
<ol>
|
||
<li>Initially, a feature will be marked as DEPRECATED in the release notes and
|
||
user-facing documentation, but no other changes are made; the feature
|
||
continues to be available and function as normal. While features at this
|
||
stage remain enabled by default, they may be explicitly disabled by
|
||
specifying <code>-allowdeprecated=none</code> on the command line when starting the
|
||
node, or by including <code>allowdeprecated=none</code> as a line in the <code>zcash.conf</code>
|
||
file. </li>
|
||
<li>In the next stage of deprecation, the feature will be disabled by default.
|
||
Disabled features may be reenabled via use of the <code>-allowdeprecated</code> flag.</li>
|
||
<li>In the third stage, the feature is fully removed and is no longer available.</li>
|
||
</ol>
|
||
<p>Features that enter Stage 1 in a particular release will be disabled by default
|
||
after no fewer than 3 releases that update <code>zcashd</code>'s minor-version, and
|
||
features will only be fully removed after a total of at least 6 minor-version updates.
|
||
<code>zcashd</code>'s release schedule intends to produce a release that updates the minor
|
||
version every 6 weeks, so deprecated features remain accessible by default for
|
||
approximately 18 weeks, and then can be expected to be removed no less than 36
|
||
weeks after their initial deprecation. Deprecation and removal timelines might
|
||
be extended beyond this on a case-by-case basis to satisfy user requirements. </p>
|
||
<h1 id="currently-deprecated"><a class="header" href="#currently-deprecated">Currently Deprecated</a></h1>
|
||
<h2 id="stage-1"><a class="header" href="#stage-1">Stage 1</a></h2>
|
||
<p>The following features are deprecated, but remain enabled by default. These features
|
||
will be disabled if <code>-allowdeprecated=none</code> is added to the CLI arguments when starting
|
||
the node, or if an <code>allowdeprecated=none</code> line is added to <code>zcash.conf</code>.</p>
|
||
<div class="table-wrapper"><table><thead><tr><th><code>feature</code></th><th>Deprecated</th><th>Feature details</th></tr></thead><tbody>
|
||
<tr><td><code>z_getbalance</code></td><td>5.0.0</td><td>The <code>z_getbalance</code> RPC method.</td></tr>
|
||
<tr><td><code>z_gettotalbalance</code></td><td>5.0.0</td><td>The <code>z_gettotalbalance</code> RPC method.</td></tr>
|
||
<tr><td><code>gbt_oldhashes</code></td><td>5.4.0</td><td>The <code>finalsaplingroothash</code>, <code>lightclientroothash</code>, and <code>blockcommitmentshash</code> fields in the output of <code>getblocktemplate</code>, which are replaced by the <code>defaultroots</code> field.</td></tr>
|
||
<tr><td><code>deprecationinfo_deprecationheight</code></td><td>5.5.0</td><td>The <code>deprecationheight</code> field returned by the <code>getdeprecationinfo</code> RPC method has been replaced by the <code>end_of_service</code> object.</td></tr>
|
||
</tbody></table>
|
||
</div>
|
||
<h2 id="stage-2"><a class="header" href="#stage-2">Stage 2</a></h2>
|
||
<p>Each feature in the table below may be enabled by adding <code>-allowdeprecated=<feature></code>
|
||
to the CLI arguments when starting the node, or by adding an <code>allowdeprecated=<feature></code>
|
||
line to <code>zcash.conf</code>.</p>
|
||
<div class="table-wrapper"><table><thead><tr><th><code>feature</code></th><th>Deprecated</th><th>Feature details</th></tr></thead><tbody>
|
||
<tr><td><code>legacy_privacy</code></td><td>5.0.0</td><td>The default "legacy" privacy policy for <code>z_sendmany</code> has been replaced by the <code>FullPrivacy</code> directive.</td></tr>
|
||
<tr><td><code>getnewaddress</code></td><td>5.0.0</td><td>The <code>getnewaddress</code> RPC method.</td></tr>
|
||
<tr><td><code>getrawchangeaddress</code></td><td>5.0.0</td><td>The <code>getrawchangeaddress</code> RPC method.</td></tr>
|
||
<tr><td><code>z_getnewaddress</code></td><td>5.0.0</td><td>The <code>z_getnewaddress</code> RPC method.</td></tr>
|
||
<tr><td><code>z_listaddresses</code></td><td>5.0.0</td><td>The <code>z_listaddresses</code> RPC method.</td></tr>
|
||
<tr><td><code>addrtype</code></td><td>5.0.0</td><td>The <code>type</code> attribute is deprecated in the results of RPC methods that return address metadata. It is recommended that applications using this metadata be updated to use the <code>pool</code> or <code>address_type</code> attributes, which have replaced the <code>type</code> attribute, as appropriate.</td></tr>
|
||
<tr><td><code>wallettxvjoinsplit</code></td><td>5.1.0</td><td>The <code>vjoinsplit</code> attribute returned by the <code>gettransaction</code> RPC method.</td></tr>
|
||
</tbody></table>
|
||
</div><div style="break-before: page; page-break-before: always;"></div><h1 id="developer-documentation"><a class="header" href="#developer-documentation">Developer Documentation</a></h1>
|
||
<p>This section contains documentation aimed at contributors to the <code>zcashd</code> codebase.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="expectations-for-dns-seed-operators"><a class="header" href="#expectations-for-dns-seed-operators">Expectations for DNS Seed operators</a></h1>
|
||
<p>Zcash attempts to minimize the level of trust in DNS seeds,
|
||
but DNS seeds still pose a small amount of risk for the network.
|
||
As such, DNS seeds must be run by entities which have some minimum
|
||
level of trust within the Zcash community.</p>
|
||
<p>Other implementations of Zcash software may also use the same
|
||
seeds and may be more exposed. In light of this exposure, this
|
||
document establishes some basic expectations for operating DNS seeds.</p>
|
||
<ol start="0">
|
||
<li>
|
||
<p>A DNS seed operating organization or person is expected to follow good
|
||
host security practices, maintain control of applicable infrastructure,
|
||
and not sell or transfer control of the DNS seed. Any hosting services
|
||
contracted by the operator are equally expected to uphold these expectations.</p>
|
||
</li>
|
||
<li>
|
||
<p>The DNS seed results must consist exclusively of fairly selected and
|
||
functioning Zcash nodes from the public network to the best of the
|
||
operator's understanding and capability.</p>
|
||
</li>
|
||
<li>
|
||
<p>For the avoidance of doubt, the results may be randomized but must not
|
||
single out any group of hosts to receive different results unless due to an
|
||
urgent technical necessity and disclosed.</p>
|
||
</li>
|
||
<li>
|
||
<p>The results may not be served with a DNS TTL of less than one minute.</p>
|
||
</li>
|
||
<li>
|
||
<p>Any logging of DNS queries should be only that which is necessary
|
||
for the operation of the service or urgent health of the Zcash
|
||
network and must not be retained longer than necessary nor disclosed
|
||
to any third party.</p>
|
||
</li>
|
||
<li>
|
||
<p>Information gathered as a result of the operators node-spidering
|
||
(not from DNS queries) may be freely published or retained, but only
|
||
if this data was not made more complete by biasing node connectivity
|
||
(a violation of expectation (1)).</p>
|
||
</li>
|
||
<li>
|
||
<p>Operators are encouraged, but not required, to publicly document the
|
||
details of their operating practices.</p>
|
||
</li>
|
||
<li>
|
||
<p>A reachable email contact address must be published for inquiries
|
||
related to the DNS seed operation.</p>
|
||
</li>
|
||
</ol>
|
||
<p>If these expectations cannot be satisfied the operator should discontinue
|
||
providing services and contact the active Zcash development team as well as
|
||
creating an issue in the <a href="https://github.com/zcash/zcash">Zcash repository</a>.</p>
|
||
<p>Behavior outside of these expectations may be reasonable in some
|
||
situations but should be discussed in public in advance.</p>
|
||
<h2 id="see-also"><a class="header" href="#see-also">See also</a></h2>
|
||
<ul>
|
||
<li><a href="https://github.com/zcash/zcash-seeder">zcash-seeder</a> is a reference
|
||
implementation of a DNS seed.</li>
|
||
</ul>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="rust-in-zcashd"><a class="header" href="#rust-in-zcashd">Rust in <code>zcashd</code></a></h1>
|
||
<p><code>zcashd</code> is primarily a C++ codebase, but most new code is being written in Rust
|
||
where possible.</p>
|
||
<h2 id="auditing-rust-dependencies"><a class="header" href="#auditing-rust-dependencies">Auditing Rust dependencies</a></h2>
|
||
<p>We use <a href="https://github.com/mozilla/cargo-vet"><code>cargo-vet</code></a> to audit our Rust dependencies. This means that after
|
||
adding a new dependency, or updating existing dependencies with <code>cargo update</code>,
|
||
CI will fail until corresponding audits have been added.</p>
|
||
<p>We also have a significant number of pre-existing unaudited dependency versions
|
||
that are excluded from auditing checks. We aim to reduce this list over time.
|
||
New entries should not be added to the exclusion list without justification.</p>
|
||
<p>To audit a dependency, first <a href="https://mozilla.github.io/cargo-vet/install.html">install <code>cargo-vet</code></a> and then follow the
|
||
<a href="https://mozilla.github.io/cargo-vet/performing-audits.html">"Performing Audits" guide</a>. If you are updating a dependency then instead of
|
||
auditing the new version in its entirety, you can optionally just audit the
|
||
delta between the old and new versions - even if the old version is in the
|
||
"unaudited" exclusion list.</p>
|
||
<h2 id="adding-new-dependencies-in-online-rust-mode"><a class="header" href="#adding-new-dependencies-in-online-rust-mode">Adding new dependencies in online-Rust mode</a></h2>
|
||
<p>The <code>zcashd</code> build system pins all dependencies, and in order to facilitate
|
||
reproducible builds, <code>cargo</code> is configured to run in offline mode with vendored
|
||
crates. This means that if, for example, you add the <code>foobar</code> crate to
|
||
<code>Cargo.toml</code>, you will likely see an error similar to this:</p>
|
||
<pre><code>$ cargo check
|
||
error: no matching package named `foobar` found
|
||
location searched: registry `https://github.com/rust-lang/crates.io-index`
|
||
required by package `librustzcash v0.2.0 (/path/to/zcash)`
|
||
</code></pre>
|
||
<p>To add dependencies that are compatible with the reproducible build system, you need to follow these steps:</p>
|
||
<ol>
|
||
<li>First, if you've made changes to dependencies in <code>Cargo.toml</code>, these must be reverted before the next step:
|
||
<pre><code>git stash
|
||
</code></pre>
|
||
</li>
|
||
<li>Next, reconfigure the build system for "online" mode:
|
||
<pre><code>CONFIGURE_FLAGS=--enable-online-rust ./zcutil/build.sh
|
||
</code></pre>
|
||
</li>
|
||
<li>Now, introduce the dependency changes into <code>Cargo.toml</code>. If you saved changes in Step 1 with <code>git stash</code>, you can reapply them:
|
||
<pre><code>git stash pop
|
||
</code></pre>
|
||
</li>
|
||
<li>Update <code>Cargo.lock</code>:
|
||
<pre><code>cargo check
|
||
</code></pre>
|
||
</li>
|
||
<li>Commit the changes to <code>Cargo.toml</code> and <code>Cargo.lock</code> together:
|
||
<pre><code>git commit ./Cargo.{toml,lock}
|
||
</code></pre>
|
||
</li>
|
||
<li>Verify the reproducible build works in vendored/offline mode without the <code>--enable-online-rust</code> flag:
|
||
<pre><code>./zcutil/build.sh
|
||
</code></pre>
|
||
</li>
|
||
</ol>
|
||
<h2 id="using-an-unpublished-rust-dependency"><a class="header" href="#using-an-unpublished-rust-dependency">Using an unpublished Rust dependency</a></h2>
|
||
<p>Occasionally we may need to depend on an unpublished git revision of a crate.
|
||
We sometimes want to prove out API changes to the <code>zcash_*</code> Rust crates by
|
||
migrating <code>zcashd</code> to them first, before making a public crate release. Or we
|
||
might need to cut a <code>zcashd</code> release before some upstream dependency has
|
||
published a fix we need. In these cases, we use patch dependencies.</p>
|
||
<p>For example, to use an unpublished version of the <code>orchard</code> crate that includes
|
||
a new API, add the following patch to <code>Cargo.toml</code>:</p>
|
||
<pre><code>[dependencies]
|
||
# This dependency is listed with a version, meaning it comes from crates.io; the
|
||
# patch goes into a [patch.crates-io] section.
|
||
orchard = "0.4"
|
||
...
|
||
|
||
[patch.crates-io]
|
||
orchard = { git = "https://github.com/zcash/orchard.git", rev = "..." }
|
||
</code></pre>
|
||
<p>Note that if the git repository contains a workspace of interconnected crates
|
||
(for example, https://github.com/zcash/librustzcash), you will need to provide
|
||
patches for each of the dependencies that reference the same git revision.</p>
|
||
<p>You also need to update <code>.cargo/config.offline</code> to add a replacement definition
|
||
for each <code>(git, rev)</code> pair. Run <code>./test/lint/lint-cargo-patches.sh</code> to get the
|
||
lines that need to be present.</p>
|
||
<p>Finally, <code>./qa/supply-chain/config.toml</code> needs to be updated to ignore patched
|
||
dependencies. Run <code>cargo vet regenerate audit-as-crates-io</code>, and then ensure the
|
||
newly-added lines are of the form <code>audit-as-crates-io = false</code>.</p>
|
||
<h2 id="using-a-local-rust-dependency"><a class="header" href="#using-a-local-rust-dependency">Using a local Rust dependency</a></h2>
|
||
<p>During development, you can use a locally checked out version of a dependency
|
||
by applying a <a href="https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html#the-patch-section"><code>cargo</code> patch</a>.</p>
|
||
<p>For example, to use a local version of the <code>orchard</code> crate that includes a new
|
||
API, add the following patch to <code>Cargo.toml</code>:</p>
|
||
<pre><code>[dependencies]
|
||
# This dependency is listed with a version, meaning it comes from crates.io; the
|
||
# patch goes into a [patch.crates-io] section.
|
||
orchard = "0.0"
|
||
...
|
||
|
||
[patch.crates-io]
|
||
# Comment out any existing patch, if present.
|
||
# orchard = { git = "https://github.com/zcash/orchard.git", rev = "..." }
|
||
|
||
# Add this patch (both relative and absolute paths work):
|
||
orchard = { path = "../relative/path/to/orchard" }
|
||
</code></pre>
|
||
<p>Usually you can apply a patch to use a locally checked out dependency without
|
||
needing to build <code>zcashd</code> in online-Rust mode. However, if your local changes
|
||
include a new dependency, you will need to ensure you are in online-Rust mode.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="regtest"><a class="header" href="#regtest">Regtest</a></h1>
|
||
<p><em>Regtest</em> ("regression test") is one of the three <em>network types</em>
|
||
supported by Zcash, the others being <code>testnet</code> and <code>mainnet</code>.
|
||
Regtest is an entirely local, self-contained mode -- your node or nodes
|
||
do not talk with peers out in the world. It gives you complete
|
||
control of the state of the blockchain and the sequence of events.
|
||
You start with an empty blockchain (just the genesis block, block 0).
|
||
Blocks can be mined instantly, and must be created explicitly. </p>
|
||
<p>You can run one or more regtest nodes on the same system.
|
||
The <a href="https://github.com/zcash/zcash/tree/master/qa/rpc-tests">RPC tests</a>
|
||
use <code>regtest</code> mode (usually starting multiple nodes), but you may use it
|
||
manually and interactively to learn, test, and experiment. Most often
|
||
just one node is used in this case.</p>
|
||
<h2 id="example-session"><a class="header" href="#example-session">Example session</a></h2>
|
||
<p>Here's a sample session (after you've built <code>zcashd</code> and <code>zcash-cli</code>):</p>
|
||
<pre><code>$ mkdir /tmp/regtest-datadir
|
||
$ cat <<EOF >/tmp/regtest-datadir/zcash.conf
|
||
regtest=1
|
||
rpcuser=u
|
||
rpcpassword=p
|
||
rpcport=18132
|
||
EOF
|
||
$ src/zcashd -daemon -datadir=/tmp/regtest-datadir
|
||
</code></pre>
|
||
<p>Watch <code>tmp/regtest-datadir/regtest/debug.log</code> to see what <code>zcashd</code> is doing.
|
||
It may also be useful to start <code>zcashd</code> with <code>-debug</code> to generate much
|
||
more logging. Now we can send RPCs to the node:</p>
|
||
<pre><code>$ src/zcash-cli -datadir=/tmp/regtest-datadir getblockchaininfo
|
||
{
|
||
"chain": "regtest",
|
||
"blocks": 0,
|
||
"initial_block_download_complete": false,
|
||
"headers": 0,
|
||
(...)
|
||
}
|
||
# Generate (mine) three blocks:
|
||
$ src/zcash-cli -datadir=/tmp/regtest-datadir generate 3
|
||
[
|
||
"05040271f43f78e3870a88697eba201aa361ea5802c69eadaf920ff376787242",
|
||
"0469f2df43dda69d521c482679b2db3c637b1721222511302584ac75e057c859",
|
||
"0ab7a26e7b3b5dfca077728de90da0cfd1c49e1edbc130a52de4062b1aecac75"
|
||
]
|
||
$ src/zcash-cli -datadir=/tmp/regtest-datadir getblockchaininfo
|
||
{
|
||
"chain": "regtest",
|
||
"blocks": 3,
|
||
"initial_block_download_complete": true,
|
||
"headers": 3,
|
||
(...)
|
||
}
|
||
$ src/zcash-cli -datadir=/tmp/regtest-datadir stop
|
||
Zcash server stopping
|
||
$
|
||
</code></pre>
|
||
<h2 id="network-upgrades"><a class="header" href="#network-upgrades">Network upgrades</a></h2>
|
||
<p>Zcash has adopted a series of
|
||
<a href="https://github.com/zcash/zcash/blob/master/src/consensus/upgrades.cpp">network upgrades</a>.
|
||
On <code>mainnet</code> and <code>testnet</code>, these activate at
|
||
fixed, known block heights (<a href="https://github.com/zcash/zcash/blob/master/src/chainparams.cpp#L117">example</a>).
|
||
In <code>regtest</code> mode, you determine the activation heights. Upgrades may occur at
|
||
any height greater than 0, and multiple upgrades can occur at the same height. The upgrades
|
||
have a strict ordering (as shown in the upgrades source file); for example, Canopy can't
|
||
be activated before Blossom. </p>
|
||
<p>You specify the upgrade heights using multiple <code>-nuparams=</code><em><branch-id></em> arguments.
|
||
(The branch IDs are available in the
|
||
<a href="https://github.com/zcash/zcash/blob/master/src/consensus/upgrades.cpp">upgrades.cpp file</a>)
|
||
It's convenient to add these to the configuration file, for example:</p>
|
||
<pre><code>$ cat <<EOF >>/tmp/regtest-datadir/zcash.conf
|
||
nuparams=76b809bb:1
|
||
nuparams=f5b9230b:5
|
||
EOF
|
||
</code></pre>
|
||
<p>(Alternatively, you can specify these on the <code>zcashd</code> command line.)
|
||
You need not activate every upgrade explicitly. The example activates Sapling
|
||
(branchID 76b809bb) at height 1; activating Sapling implies activating Overwinter, so this
|
||
is done automatically. Similarly, activating Heartwood at height 5
|
||
also simultaneously activates Blossom. Since no later upgrades are specified, none
|
||
of them will activate, regardless of height reached.</p>
|
||
<p><strong>IMPORTANT</strong>: if you change the network upgrade heights from one
|
||
test run to the next, it's almost always necessary to start fresh
|
||
by removing the data directory, otherwise you'll encounter strange errors.</p>
|
||
<p>You can see which network upgrades are currently active and which are pending
|
||
(using the above <code>nuparams</code> settings as an example):</p>
|
||
<pre><code>$ src/zcash-cli -datadir=/tmp/regtest-datadir generate 2
|
||
$ src/zcash-cli -datadir=/tmp/regtest-datadir getblockchaininfo
|
||
{
|
||
"blocks": 2,
|
||
(...)
|
||
"upgrades": {
|
||
"5ba81b19": {
|
||
"name": "Overwinter",
|
||
"activationheight": 1,
|
||
"status": "active",
|
||
"info": "See https://z.cash/upgrade/overwinter/ for details."
|
||
},
|
||
"76b809bb": {
|
||
"name": "Sapling",
|
||
"activationheight": 1,
|
||
"status": "active",
|
||
"info": "See https://z.cash/upgrade/sapling/ for details."
|
||
},
|
||
"2bb40e60": {
|
||
"name": "Blossom",
|
||
"activationheight": 5,
|
||
"status": "pending",
|
||
"info": "See https://z.cash/upgrade/blossom/ for details."
|
||
},
|
||
"f5b9230b": {
|
||
"name": "Heartwood",
|
||
"activationheight": 5,
|
||
"status": "pending",
|
||
"info": "See https://z.cash/upgrade/heartwood/ for details."
|
||
}
|
||
},
|
||
(...)
|
||
}
|
||
</code></pre>
|
||
<h2 id="manual-testing-within-an-rpc-python-test-run"><a class="header" href="#manual-testing-within-an-rpc-python-test-run">Manual testing within an RPC (Python) test run</a></h2>
|
||
<p>It is often useful, either when debugging an issue or simply when you want to put
|
||
the node into a certain state, to use the RPC test framework to produce the desired
|
||
state and then be able to manually interrogate and modify that state using <code>zcash-cli</code>
|
||
to execute RPC calls. An easy way to do that is as follows:</p>
|
||
<p>Add the line <code>import time; time.sleep(999999)</code> (the units are seconds) somewhere
|
||
within an RPC test to pause its execution at that point. Start the test, and then:</p>
|
||
<pre><code>$ ps alx | grep zcashd
|
||
0 1000 96247 96246 20 0 1426304 123952 futex_ SLl+ pts/12 0:18 /g/zcash/src/zcashd -datadir=/tmp/test9d907s8a/96246/node0 -keypool=1 -discover=0 -rest -nuparams=5ba81b19:1 -nuparams=76b809bb:1 -debug=mempool -mempooltxcostlimit=8000
|
||
0 1000 96274 96246 20 0 744092 85568 - RLl+ pts/12 0:05 /g/zcash/src/zcashd -datadir=/tmp/test9d907s8a/96246/node1 -keypool=1 -discover=0 -rest -nuparams=5ba81b19:1 -nuparams=76b809bb:1 -debug=mempool -mempooltxcostlimit=8000
|
||
$
|
||
</code></pre>
|
||
<p>Now you can interact with the running test node by copy-and-pasting its
|
||
<code>-datadir</code> argument, for example:</p>
|
||
<pre><code>$ src/zcash-cli -datadir=/tmp/test9d907s8a/96246/node0 getblockchaininfo
|
||
</code></pre>
|
||
<p>(The other <code>zcashd</code> command-line arguments are generally not needed by
|
||
<code>zcash-cli</code>.) You can see the running node's debug log file:</p>
|
||
<pre><code>$ cat /tmp/test9d907s8a/96246/node0/regtest/debug.log
|
||
</code></pre>
|
||
<p>or look at its configuration file.</p>
|
||
<pre><code>$ cat /tmp/test9d907s8a/96246/node0/zcash.conf
|
||
</code></pre>
|
||
<p>In this way, the RPC test framework can teach us more about running <code>regtest</code> nodes.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="platform-tier-policy"><a class="header" href="#platform-tier-policy">Platform Tier Policy</a></h1>
|
||
<h2 id="general"><a class="header" href="#general">General</a></h2>
|
||
<p>ECC provides three tiers of platform support, modeled after the
|
||
<a href="https://doc.rust-lang.org/stable/rustc/platform-tier-policy.html">Rust Target Tier Policy</a>:</p>
|
||
<ul>
|
||
<li>The Zcash developers provide no guarantees about tier 3 platforms; they exist in the
|
||
codebase, but may or may not build.</li>
|
||
<li>ECC's continuous integration checks that tier 2 platforms will always build, but they
|
||
may or may not pass tests.</li>
|
||
<li>ECC's continuous integration checks that tier 1 platforms will always build and pass
|
||
tests.</li>
|
||
</ul>
|
||
<p>Adding a new tier 3 platform imposes minimal requirements; we focus primarily on avoiding
|
||
disruption to other ongoing Zcash development.</p>
|
||
<p>Tier 2 and tier 1 platforms place work on Zcash developers as a whole, to avoid breaking
|
||
the platform. The broader Zcash community may also feel more inclined to support
|
||
higher-tier platforms in their downstream uses of <code>zcashd</code> (though they are not obligated
|
||
to do so). Thus, these tiers require commensurate and ongoing efforts from the maintainers
|
||
of the platform, to demonstrate value and to minimize any disruptions to ongoing Zcash
|
||
development.</p>
|
||
<p>This policy defines the requirements for accepting a proposed platform at a given level of
|
||
support.</p>
|
||
<p>Each tier builds on all the requirements from the previous tier, unless overridden by a
|
||
stronger requirement.</p>
|
||
<p>While these criteria attempt to document the policy, that policy still involves human
|
||
judgment. Platforms must fulfill the spirit of the requirements as well, as determined by
|
||
the judgment of the approving reviewers. Reviewers and team members evaluating platforms
|
||
and platform-specific patches should always use their own best judgment regarding the
|
||
quality of work, and the suitability of a platform for the Zcash project. Neither this
|
||
policy nor any decisions made regarding platforms shall create any binding agreement or
|
||
estoppel by any party.</p>
|
||
<p>For a list of all supported platforms and their corresponding tiers ("tier 3", "tier 2",
|
||
or "tier 1"), see <a href="dev/../user/platform-support.html">Platform Support</a>.</p>
|
||
<p>The availability or tier of a platform in Zcash releases is not a hard stability guarantee
|
||
about the future availability or tier of that platform. Higher-level platform tiers are an
|
||
increasing commitment to the support of a platform, and we will take that commitment and
|
||
potential disruptions into account when evaluating the potential demotion or removal of a
|
||
platform that has been part of a stable release. The promotion or demotion of a platform
|
||
will not generally affect existing stable releases, only current development and future
|
||
releases.</p>
|
||
<p>In this policy, the words "MUST" and "MUST NOT" specify absolute requirements that a
|
||
platform must meet to qualify for a tier. The words "SHOULD" and "SHOULD NOT" specify
|
||
requirements that apply in almost all cases, but for which the approving teams may grant
|
||
an exception for good reason. The word "MAY" indicates something entirely optional, and
|
||
does not indicate guidance or recommendations. This language is based on
|
||
<a href="https://tools.ietf.org/html/rfc2119">IETF RFC 2119</a>.</p>
|
||
<h2 id="tier-3-platform-policy"><a class="header" href="#tier-3-platform-policy">Tier 3 platform policy</a></h2>
|
||
<p>At this tier, ECC provides no official support for a platform, so we place minimal
|
||
requirements on the introduction of platforms.</p>
|
||
<p>A proposed new tier 3 platform MUST be reviewed and approved by a member of the ECC core
|
||
team based on these requirements.</p>
|
||
<ul>
|
||
<li>The platform MUST provide documentation for the Zcash community explaining how to build
|
||
for the platform, using cross-compilation if possible. If the platform supports running
|
||
binaries, or running tests (even if they do not pass), the documentation MUST explain
|
||
how to run such binaries or tests for the platform, using emulation if possible or
|
||
dedicated hardware if necessary.</li>
|
||
<li>Tier 3 platforms MUST NOT impose burden on the authors of pull requests, or other
|
||
developers in the community, to maintain the platform. In particular, do not post
|
||
comments (automated or manual) on a PR that derail or suggest a block on the PR based on
|
||
a tier 3 platform. Do not send automated messages or notifications (via any medium,
|
||
including via @) to a PR author or others involved with a PR regarding a tier 3
|
||
platform, unless they have opted into such messages.</li>
|
||
<li>Patches adding or updating tier 3 platforms MUST NOT break any existing tier 2 or tier 1
|
||
platform, and MUST NOT knowingly break another tier 3 platform without approval of the
|
||
ECC core team.</li>
|
||
</ul>
|
||
<p>If a tier 3 platform stops meeting these requirements, or the platform shows no signs of
|
||
activity and has not built for some time, or removing the platform would improve the
|
||
quality of the Zcash codebase, we MAY post a PR to remove it.</p>
|
||
<h2 id="tier-2-platform-policy"><a class="header" href="#tier-2-platform-policy">Tier 2 platform policy</a></h2>
|
||
<p>At this tier, the Zcash developers guarantee that a platform builds, and will reject
|
||
patches that fail to build for a platform. Thus, we place requirements that ensure the
|
||
platform will not block forward progress of the Zcash project.</p>
|
||
<p>A proposed new tier 2 platform MUST be reviewed and approved by the ECC core team based
|
||
on these requirements.</p>
|
||
<p>In addition, the ECC infrastructure team MUST approve the integration of the platform into
|
||
Continuous Integration (CI), and the tier 2 CI-related requirements. This review and
|
||
approval MAY take place in a PR adding the platform to CI, or simply by an infrastructure
|
||
team member reporting the outcome of a team discussion.</p>
|
||
<ul>
|
||
<li>A tier 2 platform MUST have value to people other than its proponents. (It MAY still be
|
||
a niche platform, but it MUST NOT be exclusively useful for an inherently closed group.)</li>
|
||
<li>A tier 2 platform MUST have a designated team of developers (the "platform maintainers")
|
||
supporting it, without the need for a paid support contract.</li>
|
||
<li>The platform MUST NOT place undue burden on Zcash developers not specifically concerned
|
||
with that platform. Zcash developers are expected to not gratuitously break a tier 2
|
||
platform, but are not expected to become experts in every tier 2 platform, and are not
|
||
expected to provide platform-specific implementations for every tier 2 platform.</li>
|
||
<li>The platform MUST build reliably in CI, for all components that ECC's CI considers
|
||
mandatory.</li>
|
||
<li>All requirements for tier 3 apply.</li>
|
||
</ul>
|
||
<p>A tier 2 platform MAY be demoted or removed if it no longer meets these requirements.</p>
|
||
<h2 id="tier-1-platform-policy"><a class="header" href="#tier-1-platform-policy">Tier 1 platform policy</a></h2>
|
||
<p>At this tier, the Zcash developers guarantee that a platform builds and passes all tests,
|
||
and will reject patches that fail to build or pass the test suite on a platform. We hold
|
||
tier 1 platforms to our highest standard of requirements.</p>
|
||
<ul>
|
||
<li>Tier 1 platforms MUST have substantial, widespread interest within the Zcash community,
|
||
and MUST serve the ongoing needs of multiple production users of Zcash across multiple
|
||
organizations or projects. These requirements are subjective. A tier 1 platform MAY be
|
||
demoted or removed if it becomes obsolete or no longer meets this requirement.</li>
|
||
<li>The platform MUST build and pass tests reliably in CI, for all components that ECC's CI
|
||
considers mandatory.</li>
|
||
<li>Building the platform and running the test suite for the platform MUST NOT take
|
||
substantially longer than other platforms, and SHOULD NOT substantially raise the
|
||
maintenance burden of the CI infrastructure.</li>
|
||
<li>Tier 1 platforms MUST NOT have a hard requirement for signed, verified, or otherwise
|
||
"approved" binaries. Developers MUST be able to build, run, and test binaries for the
|
||
platform on systems they control, or provide such binaries for others to run. (Doing so
|
||
MAY require enabling some appropriate "developer mode" on such systems, but MUST NOT
|
||
require the payment of any additional fee or other consideration, or agreement to any
|
||
onerous legal agreements.)</li>
|
||
<li>All requirements for tier 2 apply.</li>
|
||
</ul>
|
||
<p>A tier 1 platform MAY be demoted or removed if it no longer meets these requirements but
|
||
still meets the requirements for a lower tier.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="deprecation-procedure"><a class="header" href="#deprecation-procedure">Deprecation Procedure</a></h1>
|
||
<p>From time to time, features of <code>zcashd</code> and its associated wallet and RPC API are
|
||
deprecated to allow eventual removal of functionality that has been superseded
|
||
by more recent improvements. Deprecation follows a process whereby deprecate
|
||
features can be explicitly turned on or off using the
|
||
<code>-allowdeprecated=<feature></code> CLI argument.</p>
|
||
<p><code>zcashd</code> internally supports two sets of deprecated feature flags in
|
||
<code>src/deprecation.h</code>:</p>
|
||
<ul>
|
||
<li><code>DEFAULT_ALLOW_DEPRECATED</code> contains the set of features that remain available
|
||
for use without having to be specifically enabled using <code>-allowdeprecated</code>.</li>
|
||
<li><code>DEFAULT_DENY_DEPRECATED</code> contains the set of features that are not enabled
|
||
by default, and must be explicitly enabled using <code>-allowdeprecated</code>.</li>
|
||
</ul>
|
||
<p>Deprecation of a feature occurs as a 3-step process:</p>
|
||
<ol>
|
||
<li>A deprecation flag is selected for the feature, and added to
|
||
<code>DEFAULT_ALLOW_DEPRECATED</code>. The fact of its deprecation is announced, and
|
||
any functionality that supersedes the deprecated feature (if any) is
|
||
documented, in the release notes. The string <code>DEPRECATED</code> is added to
|
||
user-facing API documentation and CLI help text.</li>
|
||
<li>The deprecation flag is removed from <code>DEFAULT_ALLOW_DEPRECATED</code> and added to
|
||
<code>DEFAULT_DENY_DEPRECATED</code>.</li>
|
||
<li>The deprecated feature is removed entirely, and its deprecation flag is
|
||
removed.</li>
|
||
</ol>
|
||
<p>Features that enter Stage 1 in a particular release should be disabled by
|
||
default after no fewer than 3 releases that update <code>zcashd</code>'s
|
||
minor-version, and features should only be fully removed after a total of 6 minor-version
|
||
updates. <code>zcashd</code>'s release schedule intends to produce a release that updates
|
||
the minor version every 6 weeks, so deprecated features remain accessible by
|
||
default for approximately 18 weeks, and then can be expected to be removed no
|
||
less than 36 weeks from their initial deprecation. The deprecation timeline for
|
||
each newly deprecated feature should be documented in
|
||
<a href="dev/../user/deprecation.html">../user/deprecation.md</a>.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="design"><a class="header" href="#design">Design</a></h1>
|
||
<p>Zcash was originally a fork of Bitcoin 0.11.2, and as such the <code>zcashd</code> node architecture
|
||
is very similar to <code>bitcoind</code>. There are however several differences, most notably the
|
||
addition of shielded pools to the consensus logic and full node state.</p>
|
||
<p>In this section of the book, we describe the overall architecture that we inherit from
|
||
<code>bitcoind</code>, the changes we have made to the inherited components, and the new components
|
||
we have introduced.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="chain-state"><a class="header" href="#chain-state">Chain state</a></h1>
|
||
<p>TBD</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="coins-view"><a class="header" href="#coins-view">"Coins" view</a></h1>
|
||
<p>TBD</p>
|
||
<h2 id="notes"><a class="header" href="#notes">Notes</a></h2>
|
||
<ul>
|
||
<li>This is the main context in which <code>CTxOut::IsNull()</code> is used. The other is a
|
||
single spot in the mempool code. Once we've backported the
|
||
<a href="https://github.com/bitcoin/bitcoin/pull/10195">per-txout CoinsDB</a> we can
|
||
hopefully eliminate this method.</li>
|
||
</ul>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="p2p-data-propagation"><a class="header" href="#p2p-data-propagation">P2P data propagation</a></h1>
|
||
<p>This page contains notes about how block and transaction data is tracked and propagated by
|
||
<code>zcashd</code>. Most of this behaviour is inherited from Bitcoin Core, but some differences have
|
||
developed.</p>
|
||
<p>Some of this content is duplicated from in-code comments, but assembling this summary in
|
||
one place is generally useful for understanding the overall dynamic :)</p>
|
||
<h2 id="recentrejects"><a class="header" href="#recentrejects"><code>recentRejects</code></a></h2>
|
||
<p>When a transaction is rejected by <code>AcceptToMemoryPool</code>, the transaction is added to the
|
||
<code>recentRejects</code> Bloom filter, so that we don't process it again. The Bloom filter resets
|
||
whenever the chain tip changes, as previously invalid transactions might become valid.</p>
|
||
<p>To prevent DoS attacks against wallets submitting transactions, <code>recentRejects</code> needs to
|
||
store a commitment to the entire transaction. This ensures that if a transaction is
|
||
malleated by a network peer to invalidate its authorizing data, the node will ignore
|
||
future advertisements of that specific transaction, but still request alternative versions
|
||
of the same txid (which might have valid authorizing data).</p>
|
||
<ul>
|
||
<li>For pre-v5 transactions, the txid commits to the entire transaction, and the wtxid is
|
||
the txid with a globally-fixed (all-ones) suffix.</li>
|
||
<li>For v5+ transactions, the wtxid commits to the entire transaction.</li>
|
||
</ul>
|
||
<h2 id="maporphantransactions"><a class="header" href="#maporphantransactions"><code>mapOrphanTransactions</code></a></h2>
|
||
<p>Upstream uses this map to store transactions that are rejected by <code>AcceptToMemoryPool</code>
|
||
because the node doesn't have their transparent inputs. <code>zcashd</code> inherits this behaviour
|
||
but limits it to purely-transparent transactions (that is, if a transaction contains any
|
||
shielded components, the node rejects it as invalid and adds it to <code>recentRejects</code>).</p>
|
||
<p><code>mapOrphanTransactions</code> indexes transactions by txid. This means that if an orphan
|
||
transaction is received (spending transparent UTXOs the node does not know about), and it
|
||
also happens to be invalid for other reasons (subsequent <code>AcceptToMemoryPool</code> rules that
|
||
haven't yet been checked), then the node will not request any v5+ transactions with the
|
||
same txid but different authorizing data. This does not create a DoS problem for wallets,
|
||
because an adversary that manipulated an orphan transaction to be invalid under the above
|
||
constraints would also need to prevent the orphan's parent from entering the mempool, and
|
||
eventually a parent is reached that is not an orphan. Once the orphan's direct parent is
|
||
accepted, the orphan is re-evaluated, and if it had been manipulated to be invalid, its
|
||
wtxid is added to <code>recentRejects</code> while its txid is removed from <code>mapOrphanTransactions</code>,
|
||
enabling the wallet to rebroadcast the unmodified transaction.</p>
|
||
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
|
||
|
||
<div style="clear: both"></div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||
|
||
</nav>
|
||
|
||
</div>
|
||
|
||
|
||
|
||
|
||
<script>
|
||
window.playground_copyable = true;
|
||
</script>
|
||
|
||
|
||
<script src="elasticlunr.min.js"></script>
|
||
<script src="mark.min.js"></script>
|
||
<script src="searcher.js"></script>
|
||
|
||
<script src="clipboard.min.js"></script>
|
||
<script src="highlight.js"></script>
|
||
<script src="book.js"></script>
|
||
|
||
<!-- Custom JS scripts -->
|
||
|
||
<script>
|
||
window.addEventListener('load', function() {
|
||
window.setTimeout(window.print, 100);
|
||
});
|
||
</script>
|
||
|
||
</div>
|
||
</body>
|
||
</html>
|