340 lines
19 KiB
HTML
340 lines
19 KiB
HTML
|
<!DOCTYPE HTML>
|
||
|
|
<html lang="en" class="sidebar-visible no-js light">
|
||
|
|
<head>
|
||
|
|
<!-- Book generated using mdBook -->
|
||
|
|
<meta charset="UTF-8">
|
||
|
|
<title>Regtest Tips And Hints - The zcashd Book</title>
|
||
|
|
|
||
|
|
|
||
|
|
<!-- 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" class="active"><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 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>
|
||
|
|
|
||
|
|
</main>
|
||
|
|
|
||
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
|
|
<!-- Mobile navigation buttons -->
|
||
|
|
<a rel="prev" href="../dev/rust.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
|
|
<i class="fa fa-angle-left"></i>
|
||
|
|
</a>
|
||
|
|
|
||
|
|
<a rel="next" href="../dev/platform-tier-policy.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||
|
|
<i class="fa fa-angle-right"></i>
|
||
|
|
</a>
|
||
|
|
|
||
|
|
<div style="clear: both"></div>
|
||
|
|
</nav>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||
|
|
<a rel="prev" href="../dev/rust.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
|
|
<i class="fa fa-angle-left"></i>
|
||
|
|
</a>
|
||
|
|
|
||
|
|
<a rel="next" href="../dev/platform-tier-policy.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||
|
|
<i class="fa fa-angle-right"></i>
|
||
|
|
</a>
|
||
|
|
</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 -->
|
||
|
|
|
||
|
|
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|