zecfoundation
/
zcashd
mirror of https://github.com/ZcashFoundation/zcashd.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

removing and moving old files

This commit is contained in:
mdr0id 2018-04-25 15:32:02 -07:00
parent 78fa81be48
commit 9b892f22ee
20 changed files with 0 additions and 1811 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

123
doc/amqp.md
View File

@ -1,123 +0,0 @@
# Block and Transaction Broadcasting With AMQP 1.0 (Experimental Feature)
[AMQP](https://www.amqp.org/) is an enterprise-level message queuing
protocol for the reliable passing of real-time data and business
transactions between applications. AMQP supports both broker and
brokerless messaging. AMQP 1.0 is an open standard and has been
ratified as ISO/IEC 19464.
The Zcash daemon can be configured to act as a trusted "border
router", implementing the Zcash P2P protocol and relay, making
consensus decisions, maintaining the local blockchain database,
broadcasting locally generated transactions into the network, and
providing a queryable RPC interface to interact on a polled basis for
requesting blockchain related data. However, there exists only a
limited service to notify external software of events like the arrival
of new blocks or transactions.
The AMQP facility implements a notification interface through a set
of specific notifiers. Currently there are notifiers that publish
blocks and transactions. This read-only facility requires only the
connection of a corresponding AMQP subscriber port in receiving
software.
Currently the facility is not authenticated nor is there any two-way
protocol involvement. Therefore, subscribers should validate the
received data since it may be out of date, incomplete or even invalid.
Because AMQP is message oriented, subscribers receive transactions
and blocks all-at-once and do not need to implement any sort of
buffering or reassembly.
## Prerequisites
The AMQP feature in Zcash requires [Qpid Proton](https://qpid.apache.org/proton/)
version 0.17 or newer, which you will need to install if you are not
using the depends system. Typically, it is packaged by distributions as
something like *libqpid-proton*. The C++ wrapper for AMQP *is* required.
In order to run the example Python client scripts in contrib/ one must
also install *python-qpid-proton*, though this is not necessary for
daemon operation.
## Enabling
By default, the AMQP feature is automatically compiled in if the
necessary prerequisites are found. To disable, use --disable-proton
during the *configure* step of building zcashd:
$ ./configure --disable-proton (other options)
To actually enable operation, one must set the appropriate options on
the commandline or in the configuration file.
## Usage
AMQP support is currently an experimental feature, so you must pass
the option:
-experimentalfeatures
Currently, the following notifications are supported:
-amqppubhashtx=address
-amqppubhashblock=address
-amqppubrawblock=address
-amqppubrawtx=address
The address must be a valid AMQP address, where the same address can be
used in more than notification. Note that SSL and SASL addresses are
not currently supported.
Launch zcashd like this:
$ zcashd -amqppubhashtx=amqp://127.0.0.1:5672
Or this:
$ zcashd -amqppubhashtx=amqp://127.0.0.1:5672 \
-amqppubrawtx=amqp://127.0.0.1:5672 \
-amqppubrawblock=amqp://127.0.0.1:5672 \
-amqppubhashblock=amqp://127.0.0.1:5672 \
-debug=amqp
The debug category `amqp` enables AMQP-related logging.
Each notification has a topic and body, where the header corresponds
to the notification type. For instance, for the notification `-amqpubhashtx`
the topic is `hashtx` (no null terminator) and the body is the hexadecimal
transaction hash (32 bytes). This transaction hash and the block hash
found in `hashblock` are in RPC byte order.
These options can also be provided in zcash.conf.
Please see `contrib/amqp/amqp_sub.py` for a working example of an
AMQP server listening for messages.
## Remarks
From the perspective of zcashd, the local end of an AMQP link is write-only.
No information is broadcast that wasn't already received from the public
P2P network.
No authentication or authorization is done on peers that zcashd connects
to; it is assumed that the AMQP link is exposed only to trusted entities,
using other means such as firewalling.
TLS support may be added once OpenSSL has been removed from the Zcash
project and alternative TLS implementations have been evaluated.
SASL support may be added in a future update for secure communication.
Note that when the block chain tip changes, a reorganisation may occur
and just the tip will be notified. It is up to the subscriber to
retrieve the chain from the last known block to the new tip.
At present, zcashd does not try to resend a notification if there was
a problem confirming receipt. Support for delivery guarantees such as
*at-least-once* and *exactly-once* will be added in in a future update.
Currently, zcashd appends an up-counting sequence number to each notification
which allows listeners to detect lost notifications.

124
doc/authors.md
View File

@ -1,124 +0,0 @@
Zcash Contributors
==================
Jack Grigg (648)
Simon Liu (311)
Sean Bowe (193)
Daira Hopwood (107)
Wladimir J. van der Laan (77)
Taylor Hornby (65)
Jay Graber (62)
Nathan Wilcox (56)
Jonas Schnelli (49)
Kevin Gallagher (38)
Cory Fields (30)
Pieter Wuille (26)
syd (15)
Matt Corallo (12)
nomnombtc (9)
Paige Peterson (9)
fanquake (8)
Jonathan "Duke" Leto (8)
MarcoFalke (7)
Jeff Garzik (7)
Luke Dashjr (6)
kozyilmaz (5)
Johnathan Corgan (5)
Gregory Maxwell (5)
Ariel Gabizon (5)
Philip Kaufmann (4)
Peter Todd (4)
Pavel Janík (4)
Patrick Strateman (4)
Karl-Johan Alm (4)
Jorge Timón (4)
David Mercer (4)
Daniel Cousens (4)
lpescher (3)
Suhas Daftuar (3)
Patick Strateman (3)
João Barbosa (3)
Jason Davies (3)
James O'Beirne (3)
Daniel Kraft (3)
Ariel (3)
Alfie John (3)
str4d (2)
rofl0r (2)
paveljanik (2)
kpcyrd (2)
aniemerg (2)
Scott (2)
Robert C. Seacord (2)
Per Grön (2)
Pavel Vasin (2)
Joe Turgeon (2)
Jack Gavigan (2)
ITH4Coinomia (2)
Gavin Andresen (2)
Brad Miller (2)
Bjorn Hjortsberg (2)
Amgad Abdelhafez (2)
zathras-crypto (1)
unsystemizer (1)
practicalswift (1)
mruddy (1)
mrbandrews (1)
kazcw (1)
jc (1)
isle2983 (1)
instagibbs (1)
emilrus (1)
dexX7 (1)
daniel (1)
calebogden (1)
ayleph (1)
Tom Ritter (1)
Stephen (1)
S. Matthew English (1)
Ross Nicoll (1)
René Nyffenegger (1)
R E Broadley (1)
Paul Georgiou (1)
Paragon Initiative Enterprises, LLC (1)
Nicolas DORIER (1)
Nathaniel Mahieu (1)
Murilo Santana (1)
Maxwell Gubler (1)
Matt Quinn (1)
Mark Friedenbach (1)
Marius Kjærstad (1)
Louis Nyffenegger (1)
Leo Arias (1)
Lauda (1)
Lars-Magnus Skog (1)
Kevin Pan (1)
Jonas Nick (1)
Jeffrey Walton (1)
Ian Kelling (1)
Gaurav Rana (1)
Forrest Voight (1)
Florian Schmaus (1)
Ethan Heilman (1)
Eran Tromer (1)
Duke Leto (1)
Christian von Roques (1)
Chirag Davé (1)
Charlie O'Keefe (1)
Casey Rodarmor (1)
Cameron Boehmer (1)
Bryan Stitt (1)
Bruno Arueira (1)
Boris Hajduk (1)
Bob McElrath (1)
Bitcoin Error Log (1)
Ashley Holman (1)
Anthony Towns (1)
Allan Niemerg (1)
Alex van der Peet (1)
Alex Morcos (1)
Alex (1)
Adam Weiss (1)
Adam Brown (1)
4ZEC (1)
21E14 (1)

4
doc/bips.md
View File

@ -1,4 +0,0 @@
BIPs that are implemented by Zcash (up-to-date up to **v1.1.0**):
* Numerous historic BIPs were present in **v1.0.0** at launch; see [the protocol spec](https://github.com/zcash/zips/blob/master/protocol/protocol.pdf) for details.
* [`BIP 111`](https://github.com/bitcoin/bips/blob/master/bip-0111.mediawiki): `NODE_BLOOM` service bit added, but only enforced for peer versions `>=170004` as of **v1.1.0** ([PR #2814](https://github.com/zcash/zcash/pull/2814)).

183
doc/developer-notes.md
View File

@ -1,183 +0,0 @@
Coding
====================
Various coding styles have been used during the history of the codebase,
and the result is not very consistent. However, we're now trying to converge to
a single style, so please use it in new code. Old code will be converted
gradually.
- Basic rules specified in src/.clang-format. Use a recent clang-format-3.5 to format automatically.
- Braces on new lines for namespaces, classes, functions, methods.
- Braces on the same line for everything else.
- 4 space indentation (no tabs) for every block except namespaces.
- No indentation for public/protected/private or for namespaces.
- No extra spaces inside parenthesis; don't do ( this )
- No space after function names; one space after if, for and while.
Block style example:
```c++
namespace foo
{
class Class
{
bool Function(char* psz, int n)
{
// Comment summarising what this section of code does
for (int i = 0; i < n; i++) {
// When something fails, return early
if (!Something())
return false;
...
}
// Success return is usually at the end
return true;
}
}
}
```
Doxygen comments
-----------------
To facilitate the generation of documentation, use doxygen-compatible comment blocks for functions, methods and fields.
For example, to describe a function use:
```c++
/**
* ... text ...
* @param[in] arg1 A description
* @param[in] arg2 Another argument description
* @pre Precondition for function...
*/
bool function(int arg1, const char *arg2)
```
A complete list of `@xxx` commands can be found at http://www.stack.nl/~dimitri/doxygen/manual/commands.html.
As Doxygen recognizes the comments by the delimiters (`/**` and `*/` in this case), you don't
*need* to provide any commands for a comment to be valid; just a description text is fine.
To describe a class use the same construct above the class definition:
```c++
/**
* Alerts are for notifying old versions if they become too obsolete and
* need to upgrade. The message is displayed in the status bar.
* @see GetWarnings()
*/
class CAlert
{
```
To describe a member or variable use:
```c++
int var; //!< Detailed description after the member
```
Also OK:
```c++
///
/// ... text ...
///
bool function2(int arg1, const char *arg2)
```
Not OK (used plenty in the current source, but not picked up):
```c++
//
// ... text ...
//
```
A full list of comment syntaxes picked up by doxygen can be found at http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html,
but if possible use one of the above styles.
Development tips and tricks
---------------------------
**compiling for debugging**
Run configure with the --enable-debug option, then make. Or run configure with
CXXFLAGS="-g -ggdb -O0" or whatever debug flags you need.
**debug.log**
If the code is behaving strangely, take a look in the debug.log file in the data directory;
error and debugging messages are written there.
The -debug=... command-line option controls debugging; running with just -debug or -debug=1 will turn
on all categories (and give you a very large debug.log file).
**testnet and regtest modes**
Run with the -testnet option to run with "play zcash" on the test network, if you
are testing multi-machine code that needs to operate across the internet.
If you are testing something that can run on one machine, run with the -regtest option.
In regression test mode, blocks can be created on-demand; see qa/rpc-tests/ for tests
that run in -regtest mode.
**DEBUG_LOCKORDER**
Zcash is a multithreaded application, and deadlocks or other multithreading bugs
can be very difficult to track down. Compiling with -DDEBUG_LOCKORDER (configure
CXXFLAGS="-DDEBUG_LOCKORDER -g") inserts run-time checks to keep track of which locks
are held, and adds warnings to the debug.log file if inconsistencies are detected.
Locking/mutex usage notes
-------------------------
The code is multi-threaded, and uses mutexes and the
LOCK/TRY_LOCK macros to protect data structures.
Deadlocks due to inconsistent lock ordering (thread 1 locks cs_main
and then cs_wallet, while thread 2 locks them in the opposite order:
result, deadlock as each waits for the other to release its lock) are
a problem. Compile with -DDEBUG_LOCKORDER to get lock order
inconsistencies reported in the debug.log file.
Re-architecting the core code so there are better-defined interfaces
between the various components is a goal, with any necessary locking
done by the components (e.g. see the self-contained CKeyStore class
and its cs_KeyStore lock for example).
Threads
-------
- ThreadScriptCheck : Verifies block scripts.
- ThreadImport : Loads blocks from blk*.dat files or bootstrap.dat.
- StartNode : Starts other threads.
- ThreadDNSAddressSeed : Loads addresses of peers from the DNS.
- ThreadMapPort : Universal plug-and-play startup/shutdown
- ThreadSocketHandler : Sends/Receives data from peers on port 8233.
- ThreadOpenAddedConnections : Opens network connections to added nodes.
- ThreadOpenConnections : Initiates new connections to peers.
- ThreadMessageHandler : Higher-level message handling (sending and receiving).
- DumpAddresses : Dumps IP addresses of nodes to peers.dat.
- ThreadFlushWalletDB : Close the wallet.dat file if it hasn't been used in 500ms.
- ThreadRPCServer : Remote procedure call handler, listens on port 8232 for connections and services them.
- ZcashMiner : Generates zcash (if wallet is enabled).
- Shutdown : Does an orderly shutdown of everything.
Pull Request Terminology
------------------------
Concept ACK - Agree with the idea and overall direction, but have neither reviewed nor tested the code changes.
utACK (untested ACK) - Reviewed and agree with the code changes but haven't actually tested them.
Tested ACK - Reviewed the code changes and have verified the functionality or bug fix.
ACK - A loose ACK can be confusing. It's best to avoid them unless it's a documentation/comment only change in which case there is nothing to test/verify; therefore the tested/untested distinction is not there.
NACK - Disagree with the code changes/concept. Should be accompanied by an explanation.

54
doc/dnsseed-policy.md
View File

@ -1,54 +0,0 @@
Expectations for DNS Seed operators
====================================
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.
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.
0. 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.
1. 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.
2. 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.
3. The results may not be served with a DNS TTL of less than one minute.
4. 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.
5. 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)).
6. Operators are encouraged, but not required, to publicly document the
details of their operating practices.
7. A reachable email contact address must be published for inquiries
related to the DNS seed operation.
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 [Zcash repository](https://github.com/zcash/zcash).
Behavior outside of these expectations may be reasonable in some
situations but should be discussed in public in advance.
See also
----------
- [zcash-seeder](https://github.com/zcash/zcash-seeder) is a reference
implementation of a DNS seed.

14
doc/files.md
View File

@ -1,14 +0,0 @@
* zcash.conf: contains configuration settings for zcashd
* zcashd.pid: stores the process id of zcashd while running
* blocks/blk000??.dat: block data (custom, 128 MiB per file)
* blocks/rev000??.dat; block undo data (custom)
* blocks/index/*; block index (LevelDB)
* chainstate/*; block chain state database (LevelDB)
* database/*: BDB database environment
* db.log: wallet database log file
* debug.log: contains debug information and general logging generated by zcashd
* fee_estimates.dat: stores statistics used to estimate minimum transaction fees and priorities required for confirmation
* peers.dat: peer IP address database (custom format)
* wallet.dat: personal wallet (BDB) with keys and transactions
* .cookie: session RPC authentication cookie (written at start when cookie authentication is used, deleted on shutdown): since 0.12.0
* onion_private_key: cached Tor hidden service private key for `-listenonion`: since 0.12.0

74
doc/hotfix-process.md
View File

@ -1,74 +0,0 @@
Hotfix Release Process
======================
Hotfix releases are versioned by incrementing the build number of the latest
release. For example:
First hotfix: v1.0.11 -> v1.0.11-1
Second hotfix: v1.0.11-1 -> v1.0.11-2
In the commands below, <RELEASE> and <RELEASE_PREV> are prefixed with a v, ie.
v1.0.11 (not 1.0.11).
## Create a hotfix branch
Create a hotfix branch from the previous release tag, and push it to the main
repository:
$ git branch hotfix-<RELEASE> <RELEASE_PREV>
$ git push 'git@github.com:zcash/zcash' hotfix-<RELEASE>
## Implement hotfix changes
Hotfix changes are implemented the same way as regular changes (developers work
in separate branches per change, and push the branches to their own repositories),
except that the branches are based on the hotfix branch instead of master:
$ git checkout hotfix-<RELEASE>
$ git checkout -b <BRANCH_NAME>
## Merge hotfix PRs
Hotfix PRs are created like regular PRs, except using the hotfix branch as the
base instead of master. Each PR should be reviewed as normal, and then the
following process should be used to merge:
- A CI merge build is manually run by logging into the CI server, going to the
pr-merge builder, clicking the "force" button, and entering the following
values:
- Repository: https://github.com/<DevUser>/zcash
- <DevUser> must be in the set of "safe" users as-specified in the CI
config.
- Branch: name of the hotfix PR branch (not the hotfix release branch).
- A link to the build and its result is manually added to the PR as a comment.
- If the build was successful, the PR is merged via the GitHub button.
## Release process
The majority of this process is identical to the standard release process.
However, there are a few notable differences:
- When running the release script, use the `--hotfix` flag:
$ ./zcutil/make-release.py --hotfix <RELEASE> <RELEASE_PREV> <APPROX_RELEASE_HEIGHT>
- To review the automated changes in git:
$ git log hotfix-<RELEASE>..HEAD
- After the standard review process, use the hotfix merge process outlined above
instead of the regular merge process.
- When making the tag, check out the hotfix branch instead of master.
## Post-release
Once the hotfix release has been created, a new PR should be opened for merging
the hotfix release branch into master. This may require fixing merge conflicts
(e.g. changing the version number in the hotfix branch to match master, if
master is ahead). Such conflicts **MUST** be addressed with additional commits
to the hotfix branch; specifically, the branch **MUST NOT** be rebased on
master.

102
doc/init.md
View File

@ -1,102 +0,0 @@
*** Warning: This document has not been updated for Zcash and may be inaccurate. ***
Sample init scripts and service configuration for bitcoind
==========================================================
Sample scripts and configuration files for systemd, Upstart and OpenRC
can be found in the contrib/init folder.
contrib/init/bitcoind.service: systemd service unit configuration
contrib/init/bitcoind.openrc: OpenRC compatible SysV style init script
contrib/init/bitcoind.openrcconf: OpenRC conf.d file
contrib/init/bitcoind.conf: Upstart service configuration file
contrib/init/bitcoind.init: CentOS compatible SysV style init script
1. Service User
---------------------------------
All three startup configurations assume the existence of a "bitcoin" user
and group. They must be created before attempting to use these scripts.
2. Configuration
---------------------------------
At a bare minimum, bitcoind requires that the rpcpassword setting be set
when running as a daemon. If the configuration file does not exist or this
setting is not set, bitcoind will shutdown promptly after startup.
This password does not have to be remembered or typed as it is mostly used
as a fixed token that bitcoind and client programs read from the configuration
file, however it is recommended that a strong and secure password be used
as this password is security critical to securing the wallet should the
wallet be enabled.
If bitcoind is run with "-daemon" flag, and no rpcpassword is set, it will
print a randomly generated suitable password to stderr. You can also
generate one from the shell yourself like this:
bash -c 'tr -dc a-zA-Z0-9 < /dev/urandom | head -c32 && echo'
For an example configuration file that describes the configuration settings,
see contrib/debian/examples/bitcoin.conf.
3. Paths
---------------------------------
All three configurations assume several paths that might need to be adjusted.
Binary: /usr/bin/bitcoind
Configuration file: /etc/bitcoin/bitcoin.conf
Data directory: /var/lib/bitcoind
PID file: /var/run/bitcoind/bitcoind.pid (OpenRC and Upstart)
/var/lib/bitcoind/bitcoind.pid (systemd)
Lock file: /var/lock/subsys/bitcoind (CentOS)
The configuration file, PID directory (if applicable) and data directory
should all be owned by the bitcoin user and group. It is advised for security
reasons to make the configuration file and data directory only readable by the
bitcoin user and group. Access to bitcoin-cli and other bitcoind rpc clients
can then be controlled by group membership.
4. Installing Service Configuration
-----------------------------------
4a) systemd
Installing this .service file consists of just copying it to
/usr/lib/systemd/system directory, followed by the command
"systemctl daemon-reload" in order to update running systemd configuration.
To test, run "systemctl start bitcoind" and to enable for system startup run
"systemctl enable bitcoind"
4b) OpenRC
Rename bitcoind.openrc to bitcoind and drop it in /etc/init.d. Double
check ownership and permissions and make it executable. Test it with
"/etc/init.d/bitcoind start" and configure it to run on startup with
"rc-update add bitcoind"
4c) Upstart (for Debian/Ubuntu based distributions)
Drop bitcoind.conf in /etc/init. Test by running "service bitcoind start"
it will automatically start on reboot.
NOTE: This script is incompatible with CentOS 5 and Amazon Linux 2014 as they
use old versions of Upstart and do not supply the start-stop-daemon utility.
4d) CentOS
Copy bitcoind.init to /etc/init.d/bitcoind. Test by running "service bitcoind start".
Using this script, you can adjust the path and flags to the bitcoind program by
setting the BITCOIND and FLAGS environment variables in the file
/etc/sysconfig/bitcoind. You can also use the DAEMONOPTS environment variable here.
5. Auto-respawn
-----------------------------------
Auto respawning is currently only configured for Upstart and systemd.
Reasonable defaults have been chosen but YMMV.

175
doc/payment-api.md
View File

@ -1,175 +0,0 @@
# Zcash Payment API
## Overview
Zcash extends the Bitcoin Core API with new RPC calls to support private Zcash payments.
Zcash payments make use of two address formats:
* taddr - an address for transparent funds (just like a Bitcoin address, value stored in UTXOs)
* zaddr - an address for private funds (value stored in objects called notes)
When transferring funds from one taddr to another taddr, you can use either the existing Bitcoin RPC calls or the new Zcash RPC calls.
When a transfer involves zaddrs, you must use the new Zcash RPC calls.
## Compatibility with Bitcoin Core
Zcash supports all commands in the Bitcoin Core API (as of version 0.11.2). Where applicable, Zcash will extend commands in a backwards-compatible way to enable additional functionality.
We do not recommend use of accounts which are now deprecated in Bitcoin Core. Where the account parameter exists in the API, please use “” as its value, otherwise an error will be returned.
To support multiple users in a single node’s wallet, consider using getnewaddress or z_getnewaddress to obtain a new address for each user. Also consider mapping multiple addresses to each user.
## List of Zcash API commands
Optional parameters are denoted in [square brackets].
RPC calls by category:
* Accounting: z_getbalance, z_gettotalbalance
* Addresses : z_getnewaddress, z_listaddresses, z_validateaddress
* Keys : z_exportkey, z_importkey, z_exportwallet, z_importwallet
* Operation: z_getoperationresult, z_getoperationstatus, z_listoperationids
* Payment : z_listreceivedbyaddress, z_sendmany, z_shieldcoinbase
RPC parameter conventions:
* taddr : Transparent address
* zaddr : Private address
* address : Accepts both private and transparent addresses.
* amount : JSON format double-precision number with 1 ZC expressed as 1.00000000.
* memo : Metadata expressed in hexadecimal format. Limited to 512 bytes, the current size of the memo field of a private transaction. Zero padding is automatic.
### Accounting
Command | Parameters | Description
--- | --- | ---
z_getbalance<br>| address [minconf=1] | Returns the balance of a taddr or zaddr belonging to the node’s wallet.<br><br>Optionally set the minimum number of confirmations a private or transparent transaction must have in order to be included in the balance. Use 0 to count unconfirmed transactions.
z_gettotalbalance<br>| [minconf=1] | Return the total value of funds stored in the node’s wallet.<br><br>Optionally set the minimum number of confirmations a private or transparent transaction must have in order to be included in the balance. Use 0 to count unconfirmed transactions.<br><br>Output:<br>{<br>"transparent" : 1.23,<br>"private" : 4.56,<br>"total" : 5.79}
### Addresses
Command | Parameters | Description
--- | --- | ---
z_getnewaddress | | Return a new zaddr for sending and receiving payments. The spending key for this zaddr will be added to the node’s wallet.<br><br>Output:<br>zN68D8hSs3...
z_listaddresses | | Returns a list of all the zaddrs in this node’s wallet for which you have a spending key.<br><br>Output:<br>{ [“z123…”, “z456...”, “z789...”] }
z_validateaddress | zaddr | Return information about a given zaddr.<br><br>Output:<br>{"isvalid" : true,<br>"address" : "zcWsmq...",<br>"payingkey" : "f5bb3c...",<br>"transmissionkey" : "7a58c7...",<br>"ismine" : true}
### Key Management
Command | Parameters | Description
--- | --- | ---
z_exportkey | zaddr | _Requires an unlocked wallet or an unencrypted wallet._<br><br>Return a zkey for a given zaddr belonging to the node’s wallet.<br><br>The key will be returned as a string formatted using Base58Check as described in the Zcash protocol spec.<br><br>Output:AKWUAkypwQjhZ6LLNaMuuuLcmZ6gt5UFyo8m3jGutvALmwZKLdR5
z_importkey | zkey [rescan=true] | _Wallet must be unlocked._<br><br>Add a zkey as returned by z_exportkey to a node's wallet.<br><br>The key should be formatted using Base58Check as described in the Zcash protocol spec.<br><br>Set rescan to true (the default) to rescan the entire local block database for transactions affecting any address or pubkey script in the wallet (including transactions affecting the newly-added address for this spending key).
z_exportwallet | filename | _Requires an unlocked wallet or an unencrypted wallet._<br><br>Creates or overwrites a file with taddr private keys and zaddr private keys in a human-readable format.<br><br>Filename is the file in which the wallet dump will be placed. May be prefaced by an absolute file path. An existing file with that name will be overwritten.<br><br>No value is returned but a JSON-RPC error will be reported if a failure occurred.
z_importwallet | filename | _Requires an unlocked wallet or an unencrypted wallet._<br><br>Imports private keys from a file in wallet export file format (see z_exportwallet). These keys will be added to the keys currently in the wallet. This call may need to rescan all or parts of the block chain for transactions affecting the newly-added keys, which may take several minutes.<br><br>Filename is the file to import. The path is relative to zcashd’s working directory.<br><br>No value is returned but a JSON-RPC error will be reported if a failure occurred.
### Payment
Command | Parameters | Description
--- | --- | ---
z_listreceivedbyaddress<br> | zaddr [minconf=1] | Return a list of amounts received by a zaddr belonging to the node’s wallet.<br><br>Optionally set the minimum number of confirmations which a received amount must have in order to be included in the result. Use 0 to count unconfirmed transactions.<br><br>Output:<br>[{<br>“txid”: “4a0f…”,<br>“amount”: 0.54,<br>“memo”:”F0FF…”,}, {...}, {...}<br>]
z_sendmany<br> | fromaddress amounts [minconf=1] [fee=0.0001] | _This is an Asynchronous RPC call_<br><br>Send funds from an address to multiple outputs. The address can be either a taddr or a zaddr.<br><br>Amounts is a list containing key/value pairs corresponding to the addresses and amount to pay. Each output address can be in taddr or zaddr format.<br><br>When sending to a zaddr, you also have the option of attaching a memo in hexadecimal format.<br><br>**NOTE:**When sending coinbase funds to a zaddr, the node's wallet does not allow any change. Put another way, spending a partial amount of a coinbase utxo is not allowed. This is not a consensus rule but a local wallet rule due to the current implementation of z_sendmany. In future, this rule may be removed.<br><br>Example of Outputs parameter:<br>[{“address”:”t123…”, “amount”:0.005},<br>,{“address”:”z010…”,”amount”:0.03, “memo”:”f508af…”}]<br><br>Optionally set the minimum number of confirmations which a private or transparent transaction must have in order to be used as an input. When sending from a zaddr, minconf must be greater than zero.<br><br>Optionally set a transaction fee, which by default is 0.0001 ZEC.<br><br>Any transparent change will be sent to a new transparent address. Any private change will be sent back to the zaddr being used as the source of funds.<br><br>Returns an operationid. You use the operationid value with z_getoperationstatus and z_getoperationresult to obtain the result of sending funds, which if successful, will be a txid.
z_shieldcoinbase<br> | fromaddress toaddress [fee=0.0001] [limit=50] | _This is an Asynchronous RPC call_<br><br>Shield transparent coinbase funds by sending to a shielded z address. Utxos selected for shielding will be locked. If there is an error, they are unlocked. The RPC call `listlockunspent` can be used to return a list of locked utxos.<br><br>The number of coinbase utxos selected for shielding can be set with the limit parameter, which has a default value of 50. If the parameter is set to 0, the number of utxos selected is limited by the `-mempooltxinputlimit` option. Any limit is constrained by a consensus rule defining a maximum transaction size of 100000 bytes. <br><br>The from address is a taddr or "*" for all taddrs belonging to the wallet. The to address is a zaddr. The default fee is 0.0001.<br><br>Returns an object containing an operationid which can be used with z_getoperationstatus and z_getoperationresult, along with key-value pairs regarding how many utxos are being shielded in this transaction and what remains to be shielded.
### Operations
Asynchronous calls return an OperationStatus object which is a JSON object with the following defined key-value pairs:
* operationid : unique identifier for the async operation. Use this value with z_getoperationstatus or z_getoperationresult to poll and query the operation and obtain its result.
* status : current status of operation
* queued : operation is pending execution
* executing : operation is currently being executed
* cancelled
* failed.
* success
* result : result object if the status is ‘success’. The exact form of the result object is dependent on the call itself.
* error: error object if the status is ‘failed’. The error object has the following key-value pairs:
* code : number
* message: error message
Depending on the type of asynchronous call, there may be other key-value pairs. For example, a z_sendmany operation will also include the following in an OperationStatus object:
* method : name of operation e.g. z_sendmany
* params : an object containing the parameters to z_sendmany
Currently, as soon as you retrieve the operation status for an operation which has finished, that is it has either succeeded, failed, or been cancelled, the operation and any associated information is removed.
It is currently not possible to cancel operations.
Command | Parameters | Description
--- | --- | ---
z_getoperationresult <br>| [operationids] | Return OperationStatus JSON objects for all completed operations the node is currently aware of, and then remove the operation from memory.<br><br>Operationids is an optional array to filter which operations you want to receive status objects for.<br><br>Output is a list of operation status objects, where the status is either "failed", "cancelled" or "success".<br>[<br>{“operationid”: “opid-11ee…”,<br>“status”: “cancelled”},<br>{“operationid”: “opid-9876”, “status”: ”failed”},<br>{“operationid”: “opid-0e0e”,<br>“status”:”success”,<br>“execution_time”:”25”,<br>“result”: {“txid”:”af3887654…”,...}<br>},<br>]<br><br> Examples:<br>zcash-cli z_getoperationresult '["opid-8120fa20-5ee7-4587-957b-f2579c2d882b"]'<br> zcash-cli z_getoperationresult
z_getoperationstatus <br>| [operationids] | Return OperationStatus JSON objects for all operations the node is currently aware of.<br><br>Operationids is an optional array to filter which operations you want to receive status objects for.<br><br>Output is a list of operation status objects.<br>[<br>{“operationid”: “opid-12ee…”,<br>“status”: “queued”},<br>{“operationid”: “opd-098a…”, “status”: ”executing”},<br>{“operationid”: “opid-9876”, “status”: ”failed”}<br>]<br><br>When the operation succeeds, the status object will also include the result.<br><br>{“operationid”: “opid-0e0e”,<br>“status”:”success”,<br>“execution_time”:”25”,<br>“result”: {“txid”:”af3887654…”,...}<br>}
z_listoperationids <br>| [state] | Return a list of operationids for all operations which the node is currently aware of.<br><br>State is an optional string parameter to filter the operations you want listed by their state. Acceptable parameter values are ‘queued’, ‘executing’, ‘success’, ‘failed’, ‘cancelled’.<br><br>[“opid-0e0e…”, “opid-1af4…”, … ]
## Asynchronous RPC call Error Codes
Zcash error codes are defined in https://github.com/zcash/zcash/blob/master/src/rpcprotocol.h
### z_sendmany error codes
RPC_INVALID_PARAMETER (-8) | _Invalid, missing or duplicate parameter_
---------------------------| -------------------------------------------------
"Minconf cannot be zero when sending from zaddr" | Cannot accept minimum confirmation value of zero when sending from zaddr.
"Minconf cannot be negative" | Cannot accept negative minimum confirmation number.
"Minimum number of confirmations cannot be less than 0" | Cannot accept negative minimum confirmation number.
"From address parameter missing" | Missing an address to send funds from.
"No recipients" | Missing recipient addresses.
"Memo must be in hexadecimal format" | Encrypted memo field data must be in hexadecimal format.
"Memo size of __ is too big, maximum allowed is __ " | Encrypted memo field data exceeds maximum size of 512 bytes.
"From address does not belong to this node, zaddr spending key not found." | Sender address spending key not found.
"Invalid parameter, expected object" | Expected object.
"Invalid parameter, unknown key: __" | Unknown key.
"Invalid parameter, expected valid size" | Invalid size.
"Invalid parameter, expected hex txid" | Invalid txid.
"Invalid parameter, vout must be positive" | Invalid vout.
"Invalid parameter, duplicated address" | Address is duplicated.
"Invalid parameter, amounts array is empty" | Amounts array is empty.
"Invalid parameter, unknown key" | Key not found.
"Invalid parameter, unknown address format" | Unknown address format.
"Invalid parameter, size of memo" | Invalid memo field size.
"Invalid parameter, amount must be positive" | Invalid or negative amount.
"Invalid parameter, too many zaddr outputs" | z_address outputs exceed maximum allowed.
"Invalid parameter, expected memo data in hexadecimal format" | Encrypted memo field is not in hexadecimal format.
"Invalid parameter, size of memo is larger than maximum allowed __ " | Encrypted memo field data exceeds maximum size of 512 bytes.
RPC_INVALID_ADDRESS_OR_KEY (-5) | _Invalid address or key_
--------------------------------| ---------------------------
"Invalid from address, no spending key found for zaddr" | z_address spending key not found.
"Invalid output address, not a valid taddr." | Transparent output address is invalid.
"Invalid from address, should be a taddr or zaddr." | Sender address is invalid.
"From address does not belong to this node, zaddr spending key not found." | Sender address spending key not found.
RPC_WALLET_INSUFFICIENT_FUNDS (-6) | _Not enough funds in wallet or account_
-----------------------------------| ------------------------------------------
"Insufficient funds, no UTXOs found for taddr from address." | Insufficient funds for sending address.
"Could not find any non-coinbase UTXOs to spend. Coinbase UTXOs can only be sent to a single zaddr recipient." | Must send Coinbase UTXO to a single z_address.
"Could not find any non-coinbase UTXOs to spend." | No available non-coinbase UTXOs.
"Insufficient funds, no unspent notes found for zaddr from address." | Insufficient funds for sending address.
"Insufficient transparent funds, have __, need __ plus fee __" | Insufficient funds from transparent address.
"Insufficient protected funds, have __, need __ plus fee __" | Insufficient funds from shielded address.
RPC_WALLET_ERROR (-4) | _Unspecified problem with wallet_
----------------------| -------------------------------------
"Could not find previous JoinSplit anchor" | Try restarting node with `-reindex`.
"Error decrypting output note of previous JoinSplit: __" |
"Could not find witness for note commitment" | Try restarting node with `-rescan`.
"Witness for note commitment is null" | Missing witness for note commitment.
"Witness for spendable note does not have same anchor as change input" | Invalid anchor for spendable note witness.
"Not enough funds to pay miners fee" | Retry with sufficient funds.
"Missing hex data for raw transaction" | Raw transaction data is null.
"Missing hex data for signed transaction" | Hex value for signed transaction is null.
"Send raw transaction did not return an error or a txid." |
RPC_WALLET_ENCRYPTION_FAILED (-16) | _Failed to encrypt the wallet_
-------------------------------------------------------------------------| -------------------------------------
"Failed to sign transaction" | Transaction was not signed, sign transaction and retry.
RPC_WALLET_KEYPOOL_RAN_OUT (-12) | _Keypool ran out, call keypoolrefill first_
-------------------------------------------------------------------------| -----------------------------------------------
"Could not generate a taddr to use as a change address" | Call keypoolrefill and retry.

107
doc/payment-disclosure.md
View File

@ -1,107 +0,0 @@
# Payment Disclosure (Experimental Feature)
**Summary**
Use RPC calls `z_getpaymentdisclosure` and `z_validatepaymentdisclosure` to reveal details of a shielded payment.
**Who should read this document**
Frequent users of shielded transactions, payment processors, exchanges, block explorer
### Experimental Feature
This is an experimental feature. Enable it by launching `zcashd` with flags:
zcashd -experimentalfeatures -paymentdisclosure -debug=paymentdisclosure -txindex=1
These flags can also be set as options in `zcash.conf`.
All nodes that generate or validate payment disclosures must run with `txindex=1` enabled.
### Background
Payment Disclosure is an implementation of the work-in-progress Payment Disclosure ZIP [1].
The ZIP describes a method of proving that a payment was sent to a shielded address. In the typical case, this means enabling a sender to present a proof that they transferred funds to a recipient's shielded address.
[1] https://github.com/zcash/zips/pull/119
### Example Use Case
Alice the customer sends 10 ZEC to Bob the merchant at the shielded address shown on their website. However, Bob is not sure if he received the funds.
Alice's node is running with payment disclosure enabled, so Alice generates a payment disclosure and provides it to Bob, who verifies the payment was made.
If Bob is a bad merchant, Alice can present the payment disclosure to a third party to validate that payment was indeed made.
### Solution
A payment disclosure can be generated for any output of a JoinSplit using the RPC call:
z_getpaymentdisclosure txid js_index output_index (message)
An optional message can be supplied. This could be used for a refund address or some other reference, as currently it is not common practice to (ahead of time) include a refund address in the memo field when making a payment.
To validate a payment disclosure, the following RPC call can be used:
z_validatepaymentdisclosure hexdata
### Example
Generate a payment disclosure for the first joinsplit, second output (index starts from zero):
zcash-cli z_getpaymentdisclosure 79189528d611e811a1c7bb0358dd31343033d14b4c1e998d7c4799c40f8b652b 0 1 "Hello"
This returns a payment disclosure in the form of a hex string:
706462ff000a3722aafa8190cdf9710bfad6da2af6d3a74262c1fc96ad47df814b0cd5641c2b658b0fc499477c8d991e4c4bd133303431dd5803bbc7a111e811d6289518790000000000000000017e861adb829d8cb1cbcf6330b8c2e25fb0d08041a67a857815a136f0227f8a5342bce5b3c0d894e2983000eb594702d3c1580817d0374e15078528e56bb6f80c0548656c6c6f59a7085395c9e706d82afe3157c54ad4ae5bf144fcc774a8d9c921c58471402019c156ec5641e2173c4fb6467df5f28530dc4636fa71f4d0e48fc5c560fac500
To validate the payment disclosure:
zcash-cli z_validatepaymentdisclosure HEXDATA
This returns data related to the payment and the payment disclosure:
{
"txid": "79189528d611e811a1c7bb0358dd31343033d14b4c1e998d7c4799c40f8b652b",
"jsIndex": 0,
"outputIndex": 1,
"version": 0,
"onetimePrivKey": "1c64d50c4b81df47ad96fcc16242a7d3f62adad6fa0b71f9cd9081faaa22370a",
"message": "Hello",
"joinSplitPubKey": "d1c465d16166b602992479acfac18e87dc18065f6cefde6a002e70bc371b9faf",
"signatureVerified": true,
"paymentAddress": "ztaZJXy8iX8nrk2ytXKDBoTWqPkhQcj6E2ifARnD3wfkFwsxXs5SoX7NGmrjkzSiSKn8VtLHTJae48vX5NakvmDhtGNY5eb",
"memo": "f600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"value": 12.49900000,
"commitmentMatch": true,
"valid": true
}
The `signatureVerified` field confirms that the payment disclosure was generated and signed with the joinSplitPrivKey, which should only be known by the node generating and sending the transaction 7918...652b in question.
### Where is the data stored?
For all nodes, payment disclosure does not touch `wallet.dat` in any way.
For nodes that only validate payment disclosures, no data is stored locally.
For nodes that generate payment disclosures, a LevelDB database is created in the node's datadir. For most users, this would be in the folder:
$HOME/.zcash/paymentdisclosure
If you decide you don't want to use payment disclosure, it is safe to shut down your node and delete the database folder.
### Security Properties
Please consult the work-in-progress ZIP for details about the protocol, security properties and caveats.
### Reminder
Feedback is most welcome!
This is an experimental feature so there are no guarantees that the protocol, database format, RPC interface etc. will remain the same in the future.
### Notes
Currently there is no user friendly way to help senders identify which joinsplit output index maps to a given payment they made. It is possible to construct this from `debug.log`. Ideas and feedback are most welcome on how to improve the user experience.

8
doc/reducing-memory-usage.md
View File

@ -1,8 +0,0 @@
In-memory caches
----------------
The size of some in-memory caches can be reduced. As caches trade off memory usage for performance, usually reducing these have a negative effect on performance.
- `-dbcache=<n>` - the UTXO database cache size, this defaults to `450` (`100` before 1.0.15). The unit is MiB (where 1 GiB = 1024 MiB).
- The minimum value for `-dbcache` is 4.
- A lower dbcache make initial sync time much longer. After the initial sync, the effect is less pronounced for most use-cases, unless fast validation of blocks is important such as for mining.

48
doc/release-notes.md
View File

@ -1,48 +0,0 @@
(note: this is a temporary file, to be added-to by anybody, and moved to
release-notes at release time)
Notable changes
===============
zcash-cli: arguments privacy
----------------------------
The RPC command line client gained a new argument, `-stdin`
to read extra arguments from standard input, one per line until EOF/Ctrl-D.
For example:
$ src/zcash-cli -stdin walletpassphrase
mysecretcode
120
^D (Ctrl-D)
It is recommended to use this for sensitive information such as private keys, as
command-line arguments can usually be read from the process table by any user on
the system.
Asm representations of scriptSig signatures now contain SIGHASH type decodes
----------------------------------------------------------------------------
The `asm` property of each scriptSig now contains the decoded signature hash
type for each signature that provides a valid defined hash type.
The following items contain assembly representations of scriptSig signatures
and are affected by this change:
- RPC `getrawtransaction`
- RPC `decoderawtransaction`
- REST `/rest/tx/` (JSON format)
- REST `/rest/block/` (JSON format when including extended tx details)
- `zcash-tx -json`
For example, the `scriptSig.asm` property of a transaction input that
previously showed an assembly representation of:
304502207fa7a6d1e0ee81132a269ad84e68d695483745cde8b541e3bf630749894e342a022100c1f7ab20e13e22fb95281a870f3dcf38d782e53023ee313d741ad0cfbc0c509001
now shows as:
304502207fa7a6d1e0ee81132a269ad84e68d695483745cde8b541e3bf630749894e342a022100c1f7ab20e13e22fb95281a870f3dcf38d782e53023ee313d741ad0cfbc0c5090[ALL]
Note that the output of the RPC `decodescript` did not change because it is
configured specifically to process scriptPubKey and not scriptSig scripts.

149
doc/release-process.md
View File

@ -1,149 +0,0 @@
Release Process
====================
Meta: There should always be a single release engineer to disambiguate responsibility.
If this is a hotfix release, please see `./hotfix-process.md` before proceeding.
## Pre-release
### Github Milestone
Ensure all goals for the github milestone are met. If not, remove tickets
or PRs with a comment as to why it is not included. (Running out of time
is a common reason.)
### Pre-release checklist:
Check that dependencies are properly hosted by looking at the `check-depends` builder:
https://ci.z.cash/#/builders/1
Check that there are no surprising performance regressions:
https://speed.z.cash
Ensure that new performance metrics appear on that site.
### Protocol Safety Checks:
If this release changes the behavior of the protocol or fixes a serious
bug, verify that a pre-release PR merge updated `PROTOCOL_VERSION` in
`version.h` correctly.
If this release breaks backwards compatibility or needs to prevent
interaction with software forked projects, change the network magic
numbers. Set the four `pchMessageStart` in `CTestNetParams` in
`chainparams.cpp` to random values.
Both of these should be done in standard PRs ahead of the release
process. If these were not anticipated correctly, this could block the
release, so if you suspect this is necessary, double check with the
whole engineering team.
## Release dependencies
The release script has the following dependencies:
- `help2man`
- `debchange` (part of the devscripts Debian package)
You can optionally install the `progressbar2` Python module with pip to have a
progress bar displayed during the build process.
## Release process
In the commands below, <RELEASE> and <RELEASE_PREV> are prefixed with a v, ie.
v1.0.9 (not 1.0.9).
### Create the release branch
Run the release script, which will verify you are on the latest clean
checkout of master, create a branch, then commit standard automated
changes to that branch locally:
$ ./zcutil/make-release.py <RELEASE> <RELEASE_PREV> <RELEASE_FROM> <APPROX_RELEASE_HEIGHT>
Examples:
$ ./zcutil/make-release.py v1.0.9 v1.0.8-1 v1.0.8-1 120000
$ ./zcutil/make-release.py v1.0.13 v1.0.13-rc1 v1.0.12 222900
### Create, Review, and Merge the release branch pull request
Review the automated changes in git:
$ git log master..HEAD
Push the resulting branch to github:
$ git push 'git@github.com:$YOUR_GITHUB_NAME/zcash' $(git rev-parse --abbrev-ref HEAD)
Then create the PR on github. Complete the standard review process,
then merge, then wait for CI to complete.
## Make tag for the newly merged result
Checkout master and pull the latest version to ensure master is up to date with the release PR which was merged in before.
$ git checkout master
$ git pull --ff-only
Check the last commit on the local and remote versions of master to make sure they are the same:
$ git log -1
The output should include something like, which is created by Homu:
Auto merge of #4242 - nathan-at-least:release-v1.0.9, r=nathan-at-least
Then create the git tag. The `-s` means the release tag will be
signed. **CAUTION:** Remember the `v` at the beginning here:
$ git tag -s v1.0.9
$ git push origin v1.0.9
## Make and deploy deterministic builds
- Run the [Gitian deterministic build environment](https://github.com/zcash/zcash-gitian)
- Compare the uploaded [build manifests on gitian.sigs](https://github.com/zcash/gitian.sigs)
- If all is well, the DevOps engineer will build the Debian packages and update the
[apt.z.cash package repository](https://apt.z.cash).
## Add release notes to GitHub
- Go to the [GitHub tags page](https://github.com/zcash/zcash/tags).
- Click "Add release notes" beside the tag for this release.
- Copy the release blog post into the release description, and edit to suit
publication on GitHub. See previous release notes for examples.
- Click "Publish release" if publishing the release blog post now, or
"Save draft" to store the notes internally (and then return later to publish
once the blog post is up).
Note that some GitHub releases are marked as "Verified", and others as
"Unverified". This is related to the GPG signature on the release tag - in
particular, GitHub needs the corresponding public key to be uploaded to a
corresponding GitHub account. If this release is marked as "Unverified", click
the marking to see what GitHub wants to be done.
## Post Release Task List
### Deploy testnet
Notify the Zcash DevOps engineer/sysadmin that the release has been tagged. They update some variables in the company's automation code and then run an Ansible playbook, which:
* builds Zcash based on the specified branch
* deploys it as a public service (e.g. betatestnet.z.cash, mainnet.z.cash)
* often the same server can be re-used, and the role idempotently handles upgrades, but if not then they also need to update DNS records
* possible manual steps: blowing away the `testnet3` dir, deleting old parameters, restarting DNS seeder
Then, verify that nodes can connect to the testnet server, and update the guide on the wiki to ensure the correct hostname is listed in the recommended zcash.conf.
### Update the 1.0 User Guide
This also means updating [the translations](https://github.com/zcash/zcash-docs).
Coordinate with the translation team for now. Suggestions for improving this
part of the process should be added to #2596.
### Publish the release announcement (blog, github, zcash-dev, slack)
## Celebrate

110
doc/security-warnings.md
View File

@ -1,110 +0,0 @@
Security Warnings
====================
Security Audit
--------------
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
x86-64 Linux Only
-----------------------
There are [known bugs](https://github.com/scipr-lab/libsnark/issues/26) which
make proving keys generated on 64-bit systems unusable on 32-bit and big-endian
systems. It's unclear if a warning will be issued in this case, or if the
proving system will be silently compromised.
Wallet Encryption
-----------------
Wallet encryption is disabled, for several reasons:
- 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.
- 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).
- We were concerned about the resistance of the algorithm used to derive wallet
encryption keys (inherited from [Bitcoin](https://bitcoin.org/en/secure-your-wallet))
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.
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.
Side-Channel Attacks
--------------------
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 `zcashd` process is running on will
be able to:
- 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.
- Determine which notes you own by observing cache side-channel information
leakage from the incremental witnesses as they are updated with new notes.
- Determine which notes you own by observing the trial decryption process of
each note ciphertext on the blockchain.
You should ensure no other users have the ability to execute code (even
unprivileged) on the hardware your `zcashd` process runs on until these
vulnerabilities are fully analyzed and fixed.
REST Interface
--------------
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.
RPC Interface
---------------
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.)
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.
Block Chain Reorganization: Major Differences
-------------------------------------------------
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.
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).
Logging z_* RPC calls
---------------------
The option `-debug=zrpc` covers logging of the z_* calls. This will reveal information about private notes which you might prefer not to disclose. For example, when calling `z_sendmany` to create a shielded transaction, input notes are consumed and new output notes are created.
The option `-debug=zrpcunsafe` 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.
Private spending keys for z addresses are never logged.
Potentially-Missing Required Modifications
------------------------------------------
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 [issue #826](https://github.com/zcash/zcash/issues/826), 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.

101
doc/shield-coinbase.md
View File

@ -1,101 +0,0 @@
# Shielding Coinbase UTXOs
**Summary**
Use `z_shieldcoinbase` RPC call to shield coinbase UTXOs.
**Who should read this document**
Miners, Mining pools, Online wallets
## Background
The current Zcash protocol includes a consensus rule that coinbase rewards must be sent to a shielded address.
## User Experience Challenges
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.
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.
## Solution
The z_shieldcoinbase call makes it easy to sweep up coinbase rewards from multiple coinbase UTXOs across multiple coinbase reward addresses.
z_shieldcoinbase fromaddress toaddress (fee) (limit)
The default fee is 0.0010000 ZEC and the default limit on the maximum number of UTXOs to shield is 50.
## Examples
Sweep up coinbase UTXOs from a transparent address you use for mining:
zcash-cli z_shieldcoinbase tMyMiningAddress zMyPrivateAddress
Sweep up coinbase UTXOs from multiple transparent addresses to a shielded address:
zcash-cli z_shieldcoinbase "*" zMyPrivateAddress
Sweep up with a fee of 1.23 ZEC:
zcash-cli z_shieldcoinbase tMyMiningAddress zMyPrivateAddress 1.23
Sweep up with a fee of 0.1 ZEC and set limit on the maximum number of UTXOs to shield at 25:
zcash-cli z_shieldcoinbase "*" zMyPrivateAddress 0.1 25
### Asynchronous Call
The `z_shieldcoinbase` RPC call is an asynchronous call, so you can queue up multiple operations.
When you invoke
zcash-cli z_shieldcoinbase tMyMiningAddress zMyPrivateAddress
JSON will be returned immediately, with the following data fields populated:
- operationid: a temporary id to use with `z_getoperationstatus` and `z_getoperationresult` to get the status and result of the operation.
- shieldedUTXOs: number of coinbase UTXOs being shielded
- shieldedValue: value of coinbase UTXOs being shielded.
- remainingUTXOs: number of coinbase UTXOs still available for shielding.
- remainingValue: value of coinbase UTXOs still available for shielding
### Locking UTXOs
The `z_shieldcoinbase` 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 `z_shieldcoinbase` call fails, any locked UTXOs are unlocked.
You can use the RPC call `lockunspent` 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.
### Limits, Performance and Transaction Confirmation
The number of coinbase UTXOs selected for shielding can be adjusted by setting the limit parameter. The default value is 50.
If the limit parameter is set to zero, the zcashd `mempooltxinputlimit` option will be used instead, where the default value for `mempooltxinputlimit` is zero, which means no limit.
Any limit is constrained by a hard limit due to the consensus rule defining a maximum transaction size of 100,000 bytes.
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 `mempooltxinputlimit` option to reject transactions with a large number of UTXO inputs.
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.
### Anatomy of a z_shieldcoinbase transaction
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.
The number of coinbase UTXOs is determined by a user configured limit.
If no limit is set (in the case when limit parameter and `mempooltxinputlimit` options are set to zero) the behaviour of z_shieldcoinbase is to consume as many UTXOs as possible, with `z_shieldcoinbase` constructing a transaction up to the size limit of 100,000 bytes.
As a result, the maximum number of inputs that can be selected is:
- P2PKH coinbase UTXOs ~ 662
- 2-of-3 multisig P2SH coinbase UTXOs ~ 244.
Here is an example of using `z_shieldcoinbase` on testnet to shield multi-sig coinbase UTXOs.
- 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.
- https://explorer.testnet.z.cash/block/0050552a78e97c89f666713c8448d49ad1d7263274422272696187dedf6c0d03
- Drilling down into a transaction, you can see there is one joinsplit, with 244 inputs (vin) and 0 outputs (vout).
- https://explorer.testnet.z.cash/tx/cf4f3da2e434f68b6e361303403344e22a9ff9a8fda9abc180d9520d0ca6527d

149
doc/tor.md
View File

@ -1,149 +0,0 @@
*** Warning: Do not assume Tor support does the correct thing in Zcash; better Tor support is a future feature goal. ***
TOR SUPPORT IN ZCASH
====================
It is possible to run Zcash as a Tor hidden service, and connect to such services.
The following directions assume you have a Tor proxy running on port 9050. Many distributions default to having a SOCKS proxy listening on port 9050, but others may not. In particular, the Tor Browser Bundle defaults to listening on port 9150. See [Tor Project FAQ:TBBSocksPort](https://www.torproject.org/docs/faq.html.en#TBBSocksPort) for how to properly
configure Tor.
1. Run Zcash behind a Tor proxy
-------------------------------
The first step is running Zcash behind a Tor proxy. This will already make all
outgoing connections be anonymized, but more is possible.
-proxy=ip:port Set the proxy server. If SOCKS5 is selected (default), this proxy
server will be used to try to reach .onion addresses as well.
-onion=ip:port Set the proxy server to use for Tor hidden services. You do not
need to set this if it's the same as -proxy. You can use -noonion
to explicitly disable access to hidden service.
-listen When using -proxy, listening is disabled by default. If you want
to run a hidden service (see next section), you'll need to enable
it explicitly.
-connect=X When behind a Tor proxy, you can specify .onion addresses instead
-addnode=X of IP addresses or hostnames in these parameters. It requires
-seednode=X SOCKS5. In Tor mode, such addresses can also be exchanged with
other P2P nodes.
In a typical situation, this suffices to run behind a Tor proxy:
./zcashd -proxy=127.0.0.1:9050
2. Run a Zcash hidden server
----------------------------
If you configure your Tor system accordingly, it is possible to make your node also
reachable from the Tor network. Add these lines to your /etc/tor/torrc (or equivalent
config file):
HiddenServiceDir /var/lib/tor/zcash-service/
HiddenServicePort 8233 127.0.0.1:8233
HiddenServicePort 18233 127.0.0.1:18233
The directory can be different of course, but (both) port numbers should be equal to
your zcashd's P2P listen port (8233 by default).
-externalip=X You can tell Zcash about its publicly reachable address using
this option, and this can be a .onion address. Given the above
configuration, you can find your onion address in
/var/lib/tor/zcash-service/hostname. Onion addresses are given
preference for your node to advertize itself with, for connections
coming from unroutable addresses (such as 127.0.0.1, where the
Tor proxy typically runs).
-listen You'll need to enable listening for incoming connections, as this
is off by default behind a proxy.
-discover When -externalip is specified, no attempt is made to discover local
IPv4 or IPv6 addresses. If you want to run a dual stack, reachable
from both Tor and IPv4 (or IPv6), you'll need to either pass your
other addresses using -externalip, or explicitly enable -discover.
Note that both addresses of a dual-stack system may be easily
linkable using traffic analysis.
In a typical situation, where you're only reachable via Tor, this should suffice:
./zcashd -proxy=127.0.0.1:9050 -externalip=zctestseie6wxgio.onion -listen
(obviously, replace the Onion address with your own). It should be noted that you still
listen on all devices and another node could establish a clearnet connection, when knowing
your address. To mitigate this, additionally bind the address of your Tor proxy:
./zcashd ... -bind=127.0.0.1
If you don't care too much about hiding your node, and want to be reachable on IPv4
as well, use `discover` instead:
./zcashd ... -discover
and open port 8233 on your firewall (or use -upnp).
If you only want to use Tor to reach onion addresses, but not use it as a proxy
for normal IPv4/IPv6 communication, use:
./zcashd -onion=127.0.0.1:9050 -externalip=zctestseie6wxgio.onion -discover
3. Automatically listen on Tor
--------------------------------
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.
Zcash has been updated to make use of this.
This means that if Tor is running (and proper authentication has been configured),
Zcash automatically creates a hidden service to listen on. Zcash will also use Tor
automatically to connect to other .onion nodes if the control socket can be
successfully opened. This will positively affect the number of available .onion
nodes and their usage.
This new feature is enabled by default if Zcash is listening (`-listen`), and
requires a Tor connection to work. It can be explicitly disabled with `-listenonion=0`
and, if not disabled, configured using the `-torcontrol` and `-torpassword` settings.
To show verbose debugging information, pass `-debug=tor`.
Connecting to Tor's control socket API requires one of two authentication methods to be
configured. For cookie authentication the user running zcashd must have write access
to the `CookieAuthFile` 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 `-debug=tor` 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. An alternative authentication method is the use
of the `-torpassword` flag and a `hash-password` which can be enabled and specified in
Tor configuration.
4. Connect to a Zcash hidden server
-----------------------------------
To test your set-up, you might want to try connecting via Tor on a different computer to just a
a single Zcash hidden server. Launch zcashd as follows:
./zcashd -onion=127.0.0.1:9050 -connect=zctestseie6wxgio.onion
Now use zcash-cli to verify there is only a single peer connection.
zcash-cli getpeerinfo
[
{
"id" : 1,
"addr" : "zctestseie6wxgio.onion:18233",
...
"version" : 170002,
"subver" : "/MagicBean:1.0.0/",
...
}
]
To connect to multiple Tor nodes, use:
./zcashd -onion=127.0.0.1:9050 -addnode=zctestseie6wxgio.onion -dnsseed=0 -onlynet=onion

71
doc/translation_strings_policy.md
View File

@ -1,71 +0,0 @@
*** Warning: This document has not been updated for Zcash and may be inaccurate. ***
Translation Strings Policy
===========================
This document provides guidelines for internationalization of the Bitcoin Core software.
How to translate?
------------------
To mark a message as translatable
- In non-GUI source code (under `src`): use `_("...")`
No internationalization is used for e.g. developer scripts outside `src`.
Strings to be translated
-------------------------
On a high level, these strings are to be translated:
- GUI strings, anything that appears in a dialog or window
- Command-line option documentation
### GUI strings
Anything that appears to the user in the GUI is to be translated. This includes labels, menu items, button texts, tooltips and window titles.
This includes messages passed to the GUI through the UI interface through `InitMessage`, `ThreadSafeMessageBox` or `ShowProgress`.
### Command-line options
Documentation for the command line options in the output of `--help` should be translated as well.
Make sure that default values do not end up in the string, but use string formatting like `strprintf(_("Threshold for disconnecting misbehaving peers (default: %u)"), 100)`. Putting default values in strings has led to accidental translations in the past, and forces the string to be retranslated every time the value changes.
Do not translate messages that are only shown to developers, such as those that only appear when `--help-debug` is used.
General recommendations
------------------------
### Avoid unnecessary translation strings
Try not to burden translators with translating messages that are e.g. slight variations of other messages.
In the GUI, avoid the use of text where an icon or symbol will do.
Make sure that placeholder texts in forms don't end up in the list of strings to be translated (use `<string notr="true">`).
### Make translated strings understandable
Try to write translation strings in an understandable way, for both the user and the translator. Avoid overly technical or detailed messages
### Do not translate internal errors
Do not translate internal errors, or log messages, or messages that appear on the RPC interface. If an error is to be shown to the user,
use a generic message, then log the detailed message to the log. E.g. "Error: A fatal internal error occurred, see debug.log for details".
This helps troubleshooting; if the error is the same for everyone, the likelihood is increased that it can be found using a search engine.
### Avoid fragments
Avoid dividing up a message into fragments. Translators see every string separately, so may misunderstand the context if the messages are not self-contained.
### Avoid HTML in translation strings
There have been difficulties with use of HTML in translation strings; translators should not be able to accidentally affect the formatting of messages.
This may sometimes be at conflict with the recommendation in the previous section.
### String freezes
During a string freeze (often before a major release), no translation strings are to be added, modified or removed.
This can be checked by executing `make translate` in the `src` directory, then verifying that `bitcoin_en.ts` remains unchanged.

17
doc/unit-tests.md
View File

@ -1,17 +0,0 @@
Compiling/running automated tests
---------------------------------
Automated tests will be automatically compiled if dependencies were met in configure
and tests weren't explicitly disabled.
There are two scripts for running tests:
* ``qa/zcash/full-test-suite.sh``, to run the main test suite
* ``qa/pull-tester/rpc-tests.sh``, to run the RPC tests.
The main test suite uses two different testing frameworks. Tests using the Boost
framework are under ``src/test/``; tests using the Google Test/Google Mock
framework are under ``src/gtest/`` and ``src/wallet/gtest/``. The latter framework
is preferred for new Zcash unit tests.
RPC tests are implemented in Python under the ``qa/rpc-tests/`` directory.

91
doc/wallet-backup.md
View File

@ -1,91 +0,0 @@
# Wallet Backup Instructions
## Overview
Backing up your Zcash private keys is the best way to be proactive about preventing loss of access to your ZEC.
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).
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.
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.
## Instructions for backing up your wallet and/or private keys
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.
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.
For all methods, you will need to include an export directory setting in your config file (`zcash.conf` located in the data directory which is `~/.zcash/` unless it's been overridden with `datadir=` setting):
`exportdir=path/to/chosen/export/directory`
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.
Note that zcashd will need to be stopped and restarted for edits in the config file to take effect.
### Using `backupwallet`
To create a backup of your wallet, use:
`zcash-cli backupwallet <nameofbackup>`.
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.
If you generate a new Zcash address, it will not be reflected in the backup file.
If your original `wallet.dat` file becomes inaccessible for whatever reason, you can use your backup by copying it into your data directory and renaming the copy to `wallet.dat`.
### Using `z_exportwallet` & `z_importwallet`
If you prefer to have an export of your private keys in human readable format, you can use:
`zcash-cli z_exportwallet <nameofbackup>`
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.
To import keys into a wallet which were previously exported to a file, use:
`zcash-cli z_importwallet <path/to/exportdir/nameofbackup>`
### Using `z_exportkey`, `z_importkey`, `dumpprivkey` & `importprivkey`
If you prefer to export a single private key for a shielded address, you can use:
`zcash-cli z_exportkey <z-address>`
This will return the private key and will not create a new file.
For exporting a single private key for a transparent address, you can use the command inherited from Bitcoin:
`zcash-cli dumpprivkey <t-address>`
This will return the private key and will not create a new file.
To import a private key for a shielded address, use:
`zcash-cli z_importkey <z-priv-key>`
This will add the key to your wallet and rescan the wallet for associated transactions if it is not already part of the wallet.
The rescanning process can take a few minutes for a new private key. To skip it, instead use:
`zcash-cli z_importkey <z-private-key> no`
For other instructions on fine-tuning the wallet rescan, see the command's help documentation:
`zcash-cli help z_importkey`
To import a private key for a transparent address, use:
`zcash-cli importprivkey <t-priv-key>`
This has the same functionality as `z_importkey` but works with transparent addresses.
See the command's help documentation for instructions on fine-tuning the wallet rescan:
`zcash-cli help importprivkey`
### Using `dumpwallet`
This command inherited from Bitcoin is deprecated. It will export private keys in a similar fashion as `z_exportwallet` but only for transparent addresses.

107
doc/zmq.md
View File

@ -1,107 +0,0 @@
# Block and Transaction Broadcasting With ZeroMQ
[ZeroMQ](http://zeromq.org/) is a lightweight wrapper around TCP
connections, inter-process communication, and shared-memory,
providing various message-oriented semantics such as publish/subscribe,
request/reply, and push/pull.
The Zcash daemon can be configured to act as a trusted "border
router", implementing the Zcash wire protocol and relay, making
consensus decisions, maintaining the local blockchain database,
broadcasting locally generated transactions into the network, and
providing a queryable RPC interface to interact on a polled basis for
requesting blockchain related data. However, there exists only a
limited service to notify external software of events like the arrival
of new blocks or transactions.
The ZeroMQ facility implements a notification interface through a set
of specific notifiers. Currently there are notifiers that publish
blocks and transactions. This read-only facility requires only the
connection of a corresponding ZeroMQ subscriber port in receiving
software; it is not authenticated nor is there any two-way protocol
involvement. Therefore, subscribers should validate the received data
since it may be out of date, incomplete or even invalid.
ZeroMQ sockets are self-connecting and self-healing; that is,
connections made between two endpoints will be automatically restored
after an outage, and either end may be freely started or stopped in
any order.
Because ZeroMQ is message oriented, subscribers receive transactions
and blocks all-at-once and do not need to implement any sort of
buffering or reassembly.
## Prerequisites
The ZeroMQ feature in Zcash requires ZeroMQ API version 4.x or
newer, which you will need to install if you are not using the depends
system. Typically, it is packaged by distributions as something like
*libzmq5-dev*. The C++ wrapper for ZeroMQ is *not* needed.
In order to run the example Python client scripts in contrib/ one must
also install *python-zmq*, though this is not necessary for daemon
operation.
## Enabling
By default, the ZeroMQ feature is automatically compiled in if the
necessary prerequisites are found. To disable, use --disable-zmq
during the *configure* step of building zcashd:
$ ./configure --disable-zmq (other options)
To actually enable operation, one must set the appropriate options on
the commandline or in the configuration file.
## Usage
Currently, the following notifications are supported:
-zmqpubhashtx=address
-zmqpubhashblock=address
-zmqpubrawblock=address
-zmqpubrawtx=address
The socket type is PUB and the address must be a valid ZeroMQ socket
address. The same address can be used in more than one notification.
For instance:
$ zcashd -zmqpubhashtx=tcp://127.0.0.1:28332 \
-zmqpubrawtx=ipc:///tmp/zcashd.tx.raw
Each PUB notification has a topic and body, where the header
corresponds to the notification type. For instance, for the
notification `-zmqpubhashtx` the topic is `hashtx` (no null
terminator) and the body is the hexadecimal transaction hash (32
bytes).
These options can also be provided in zcash.conf.
ZeroMQ endpoint specifiers for TCP (and others) are documented in the
[ZeroMQ API](http://api.zeromq.org/4-0:_start).
Client side, then, the ZeroMQ subscriber socket must have the
ZMQ_SUBSCRIBE option set to one or either of these prefixes (for
instance, just `hash`); without doing so will result in no messages
arriving. Please see `contrib/zmq/zmq_sub.py` for a working example.
## Remarks
From the perspective of zcashd, the ZeroMQ socket is write-only; PUB
sockets don't even have a read function. Thus, there is no state
introduced into zcashd directly. Furthermore, no information is
broadcast that wasn't already received from the public P2P network.
No authentication or authorization is done on connecting clients; it
is assumed that the ZeroMQ port is exposed only to trusted entities,
using other means such as firewalling.
Note that when the block chain tip changes, a reorganisation may occur
and just the tip will be notified. It is up to the subscriber to
retrieve the chain from the last known block to the new tip.
There are several possibilities that ZMQ notification can get lost
during transmission depending on the communication type you are
using. Zcashd appends an up-counting sequence number to each
notification which allows listeners to detect lost notifications.