Skip to content

1.0 User Guide

Jump to bottom
tarrenj edited this page Sep 11, 2018 · 87 revisions

Horizen 1.0 Guide

Welcome! This guide is intended to get you running on the official Horizen network. Horizen currently has some limitations: it only officially supports Linux, requires 64-bit, and in some situations requires heavy memory and CPU consumption to create transactions.

Please let us know if you run into snags. We plan to make it less memory/CPU intensive and support more architectures and operating systems in the future.

Upgrading?

If you're on a Debian-based distribution, you can follow the Debian instructions to install Hoirzen on your system. Otherwise, you can update your local snapshot of our code:

git checkout master
git pull
./zcutil/fetch-params.sh
./zcutil/build.sh --disable-rust -j$(nproc)

Note: if you don't have nproc, then substitute the number of cores on your system. If the build runs out of memory, try again without the -j argument, i.e. just ./zcutil/build.sh --disable-rust.

If you are upgrading from testnet, make sure that your ~/.zen directory contains only zen.conf to start with, and that your ~/.zen/zen.conf does not contain testnet=1.

If the build fails, move aside your zen directory and try again by following the instructions in the Compile it yourself section below.

A quick note about terminology

Horizen supports two different kinds of addresses, a z-addr (which generally begins with zc and is 94 characters long) is an address that uses zero-knowledge proofs and other cryptography to protect user privacy. There are also t-addrs (which generally begin with zn and are 35 characters long) that are similar to Bitcoin's addresses.

Requirements

Currently, you will need:

  • Linux (easiest with a Debian-based distribution)
  • 64-bit processor and OS
  • 3 GB of free RAM
  • at least 10 GB of free disk space (the size of the block chain increases over time)

The interfaces are a commandline client (zen-cli) and a Remote Procedure Call (RPC) interface, which is documented here:

https://github.com/ZencashOfficial/zen/blob/master/doc/payment-api.md

Security

Before installing, upgrading, or running Horizen, ensure you have checked for any security issues. Please See our Security page:

https://z.cash/support/security.html

Get started

Binary packages for Debian-based operating systems

Follow the instructions here: https://github.com/ZencashOfficial/zen/wiki/Debian-binary-packages

Or, Compile it yourself

Install dependencies

On Ubuntu/Debian-based systems:

$ sudo apt-get install \
      build-essential pkg-config libc6-dev m4 g++-multilib \
      autoconf libtool ncurses-dev unzip git python python-zmq \
      zlib1g-dev wget curl bsdmainutils automake

On Fedora-based systems:

$ sudo dnf install \
      git pkgconfig automake autoconf ncurses-devel python \
      python-zmq wget curl gtest-devel gcc gcc-c++ libtool patch

On RHEL-based systems (including Scientific Linux):

  • Install devtoolset-3 and autotools-latest (if not previously installed).
  • Run scl enable devtoolset-3 'scl enable autotools-latest bash' and do the remainder of the build in the shell that this starts.

Check GCC version

gcc/g++ 4.9 or later is required. Zcash has been successfully built using gcc/g++ versions 4.9 to 7.x inclusive. Use g++ --version to check which version you have.

On Ubuntu Trusty, if your version is too old then you can install gcc/g++ 4.9 as follows:

$ sudo add-apt-repository ppa:ubuntu-toolchain-r/test
$ sudo apt-get update
$ sudo apt-get install g++-4.9
$ sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.9 40
$ sudo update-alternatives --install /usr/bin/cpp cpp /usr/bin/cpp-4.9 40
$ sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-4.9 40

Check binutils version

binutils 2.22 or later is required. Use as --version to check which version you have, and upgrade if necessary.

Fetch the software and parameter files

Fetch our repository with git and run fetch-params.sh like so:

$ git clone https://github.com/ZencashOfficial/zen.git
$ cd zen/
$ ./zcutil/fetch-params.sh

This will fetch our Sprout proving and verifying keys (the final ones created in the Parameter Generation Ceremony), and place them into ~/.zcash-params/. These keys are just under 911MB in size, so it may take some time to download them.

The message printed by git checkout about a "detached head" is normal and does not indicate a problem.

Build

Ensure you have successfully installed all system package dependencies as described above. Then run the build, e.g.:

$ ./zcutil/build.sh --disable-rust -j$(nproc)

This should compile our dependencies and build zend. (Note: if you don't have nproc, then substitute the number of cores on your system. If the build runs out of memory, try again without the -j argument, i.e. just ./zcutil/build.sh --disable-rust. )

Testing

The tests take a while to run and may require up to 8GB of RAM. If you would rather get started right away, you can skip to the next section. If you want to run the tests to make sure Horizen is working, run:

$ ./qa/zen/full_test_suite.sh

You can also run the RPC tests, which take much longer:

$ ./qa/pull-tester/rpc-tests.sh

The tests need a lot of memory to run successfully. An out-of-memory error will usually cause a FAIL or ERROR outcome with "std::bad_alloc" somewhere in the output.

Configuration

Create the ~/.zen directory and place a configuration file at ~/.zen/zen.conf using the following commands:

mkdir -p ~/.zen
echo "rpcuser=username" >>~/.zen/zen.conf
echo "rpcpassword=`head -c 32 /dev/urandom | base64`" >>~/.zen/zen.conf

Note that this will overwrite any zen.conf settings you may have added from testnet. (If you want to run on testnet, you can retain a zen.conf from testnet.) The commands above also assign a random password to avoid potential security issues with access to the RPC interface.

If you wish to run zend on testnet, change the lines in zen.conf indicating the network and node discovery: testnet=1 instead of mainnet=1.

Enabling CPU mining:

If you want to enable CPU mining, run these commands:

$ echo 'gen=1' >> ~/.zen/zen.conf
$ echo "genproclimit=-1" >> ~/.zen/zen.conf

Setting genproclimit=-1 mines on the maximum number of threads possible on your CPU. If you want to mine with a lower number of threads, set genproclimit equal to the number of threads you would like to mine on.

The default miner is not efficient, but has been well reviewed. To use a much more efficient but unreviewed solver, you can run this command:

$ echo 'equihashsolver=tromp' >> ~/.zen/zen.conf

Note, you probably want to read the Mining-Guide to learn more mining details.

Running Horizen:

Now, run zend!

$ ./src/zend

To run it in the background (without the node metrics screen that is normally displayed) use ./src/zend --daemon.

You should be able to use the RPC after it finishes loading. Here's a quick way to test:

$ ./src/zen-cli getinfo

NOTE: If you are familiar with bitcoind's RPC interface, you can use many of those calls to send ZEN between t-addr addresses. We do not support the 'Accounts' feature (which has also been deprecated in bitcoind) — only the empty string "" can be used as an account name.

To see the peers you are connected to:

$ ./src/zen-cli getpeerinfo

Using Horizen

First, you want to obtain Horizen. You can purchase them from an exchange, from other users, or sell goods and services for them! Exactly how to obtain Horizen (safely) is not in scope for this document, but you should be careful. Avoid scams!

Generating a t-addr

Let's generate a t-addr first.

$ ./src/zen-cli getnewaddress
znahSVzrqhyKFDmCHYkqtG9c6PU8CWpeeQz

Listing transparent addresses

$ ./src/zen-cli getaddressesbyaccount ""

This should show the address that was just created.

Receiving Zen with a z-addr

Now let's generate a z-addr.

$ ./src/zen-cli z_getnewaddress
zcYAwavpjRj9Qgkb7NU8h1H4mczLmbwc5UJm6eGmcVqkPi4kZfm5v1mPZ8n7aTXrH6apcW7oxfnv3vGzmA3c1dDiGzTsx7a

This creates a private address and stores its key in your local wallet file. Give this address to the sender!

A z-addr is pretty large, so it's easy to make mistakes with them. Let's put it in an environment variable to avoid mistakes:

$ ZADDR='zcBqWB8VDjVER7uLKb4oHp2v54v2a1jKd9o4FY7mdgQ3gDfG8MiZLvdQga8JK3t58yjXGjQHzMzkGUxSguSs6ZzqpgTNiZG'

To get a list of all addresses in your wallet for which you have a spending key, run this command:

$ ./src/zen-cli z_listaddresses

You should see something like:

[
    "zcA6qngiR3U7HxYopyTWkaDLwYBd83D5MT7Jb9gpgTzPLMZytzRbtdPP1Syv4RvRgHeoZrJWSask3DyfwXG9DGPMWMvX7aC",
    "zcBqWB8VDjVER7uLKb4oHp2v54v2a1jKd9o4FY7mdgQ3gDfG8MiZLvdQga8JK3t58yjXGjQHzMzkGUxSguSs6ZzqpgTNiZG"
]

Great! Now, send your z-addr to the sender. You should eventually see their transaction when checking:

$ ./src/zen-cli z_listreceivedbyaddress "$ZADDR"
[
    {
        "txid" : "af1665b317abe538148114a45322f28151925501c081949cc7a5207ef21cb750",
        "amount" : 1.23,
        "memo" : "48656c6c6f20ceb2210000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
    }
]

Sending coins with your z-addr

If someone gives you their z-addr...

$ FRIEND='zcCDe8krwEt1ozWmGZhBDWrcUfmK3Ue5D5z1f6u2EZLLCjQq7mBRkaAPb45FUH4Tca91rF4R1vf983ukR71kHyXeED4quGV'

You can send 0.8 ZEN by doing...

$ ./src/zen-cli z_sendmany "$ZADDR" "[{\"amount\": 0.8, \"address\": \"$FRIEND\"}]"

After waiting about a minute, you can check to see if the operation has finished and produced a result:

$ ./src/zen-cli z_getoperationresult
[
    {
        "id" : "opid-4eafcaf3-b028-40e0-9c29-137da5612f63",
        "status" : "success",
        "creation_time" : 1473439760,
        "result" : {
            "txid" : "3b85cab48629713cc0caae99a49557d7b906c52a4ade97b944f57b81d9b0852d"
        },
        "execution_secs" : 51.64785629
    }
]

Additional operations for zen-cli

As Horizen is an extension of bitcoin, zen-cli supports all commands that are part of the Bitcoin Core API (as of version 0.11.2), https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_calls_list

For a full list of new commands that are not part of bitcoin API (mostly addressing operations on z-addrs) see https://github.com/ZencashOfficial/zen/blob/master/doc/payment-api.md

To list all zen-cli commands, use ./src/zen-cli help.

To get help with a particular command, use ./src/zen-cli help <command>.

Known Security Issues

Each release contains a ./doc/security-warnings.md document describing security issues known to affect that release. You can find the most recent version of this document here:

https://github.com/ZenCashofficial/zen/blob/master/doc/security-warnings.md

Please also see our security page for recent notifications and other resources:

https://z.cash/support/security.html

Clone this wiki locally