2022-03-27 16:42:47 -07:00
![Zebra logotype ](https://zfnd.org/wp-content/uploads/2022/03/zebra-logotype.png )
2019-10-25 09:48:46 -07:00
2020-04-21 23:48:18 -07:00
---
2022-10-20 19:57:04 -07:00
2023-05-21 12:29:09 -07:00
[![CI Docker ](https://github.com/ZcashFoundation/zebra/actions/workflows/continous-integration-docker.yml/badge.svg )](https://github.com/ZcashFoundation/zebra/actions/workflows/continous-integration-docker.yml) [![CI OSes ](https://github.com/ZcashFoundation/zebra/actions/workflows/continous-integration-os.yml/badge.svg )](https://github.com/ZcashFoundation/zebra/actions/workflows/continous-integration-os.yml) [![Continuous Delivery ](https://github.com/ZcashFoundation/zebra/actions/workflows/continous-delivery.yml/badge.svg )](https://github.com/ZcashFoundation/zebra/actions/workflows/continous-delivery.yml) [![codecov ](https://codecov.io/gh/ZcashFoundation/zebra/branch/main/graph/badge.svg )](https://codecov.io/gh/ZcashFoundation/zebra) [![Build docs ](https://github.com/ZcashFoundation/zebra/actions/workflows/docs.yml/badge.svg )](https://github.com/ZcashFoundation/zebra/actions/workflows/docs.yml)
2020-04-22 00:02:19 -07:00
![License ](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg )
2020-10-07 08:33:34 -07:00
2021-10-29 12:25:30 -07:00
## Contents
- [Contents ](#contents )
- [About ](#about )
2022-08-02 18:03:31 -07:00
- [Using Zebra ](#using-zebra )
2022-10-31 17:51:29 -07:00
- [Release Candidates ](#release-candidates )
2021-10-29 12:25:30 -07:00
- [Getting Started ](#getting-started )
2023-05-18 14:25:05 -07:00
- [Docker ](#docker )
2023-03-08 03:49:06 -08:00
- [Building Zebra ](#building-zebra )
- [Optional Features ](#optional-features )
2022-09-03 22:03:15 -07:00
- [Configuring JSON-RPC for lightwalletd ](#configuring-json-rpc-for-lightwalletd )
2023-05-18 14:25:05 -07:00
- [Network Ports ](#network-ports )
2021-10-29 12:25:30 -07:00
- [Known Issues ](#known-issues )
- [Future Work ](#future-work )
- [Documentation ](#documentation )
- [Security ](#security )
- [License ](#license )
2020-12-07 21:41:49 -08:00
## About
2020-10-07 08:33:34 -07:00
2020-10-06 23:53:22 -07:00
[Zebra ](https://zebra.zfnd.org/ ) is the Zcash Foundation's independent,
2021-10-29 12:25:30 -07:00
consensus-compatible implementation of a Zcash node, currently under
development. It can be used to join the Zcash peer-to-peer network, which helps
keeping Zcash working by validating and broadcasting transactions, and maintaining
the Zcash blockchain state in a distributed manner.
2022-06-28 15:15:01 -07:00
[Zcash ](https://doc.zebra.zfnd.org/zebrad/index.html#about-zcash )
is a cryptocurrency designed to preserve the user's privacy.
If you just want to send and receive Zcash then you don't need to use Zebra
directly. You can download a Zcash wallet application which will handle that
for you.
2021-10-29 12:25:30 -07:00
Please [join us on Discord ](https://discord.gg/na6QZNd ) if you'd
2020-10-06 23:53:22 -07:00
like to find out more or get involved!
2020-04-21 23:39:17 -07:00
2022-06-28 15:15:01 -07:00
### Using Zebra
2021-10-29 12:25:30 -07:00
2022-06-28 15:15:01 -07:00
You would want to run Zebra if you want to contribute to the
2021-10-29 12:25:30 -07:00
Zcash network: the more nodes are run, the more reliable the network will be
in terms of speed and resistance to denial of service attacks, for example.
2022-10-31 22:47:37 -07:00
Zebra aims to be [faster, more secure, and more easily extensible ](https://doc.zebra.zfnd.org/zebrad/index.html#zebra-advantages )
2022-06-28 15:15:01 -07:00
than other Zcash implementations.
2021-10-29 12:25:30 -07:00
2022-10-05 05:46:10 -07:00
## Release Candidates
2020-12-07 21:41:49 -08:00
2022-10-05 05:46:10 -07:00
Every few weeks, we release a [new Zebra version ](https://github.com/ZcashFoundation/zebra/releases ).
2020-12-07 21:41:49 -08:00
2021-11-02 02:59:13 -07:00
Zebra's network stack is interoperable with `zcashd` ,
and Zebra implements all the features required to reach Zcash network consensus.
2022-10-05 05:46:10 -07:00
Currently, Zebra validates all of the Zcash consensus rules for the NU5 network upgrade.
2020-12-07 21:41:49 -08:00
2022-11-22 22:01:34 -08:00
Zebra validates blocks and transactions, but needs extra software to generate them:
2023-02-24 15:08:16 -08:00
2022-11-22 22:01:34 -08:00
- to generate transactions, [configure `zebrad`'s JSON-RPC port ](https://github.com/ZcashFoundation/zebra#configuring-json-rpc-for-lightwalletd ),
and use a light wallet with `lightwalletd` and Zebra.
- to generate blocks, [compile `zebrad` with the `getblocktemplate-rpcs` feature ](https://doc.zebra.zfnd.org/zebrad/#json-rpc ), configure the JSON-RPC port,
and use a mining pool or miner with Zebra's mining JSON-RPCs.
Mining support is currently incomplete, experimental, and off by default.
2021-10-29 12:25:30 -07:00
## Getting Started
2020-12-07 21:41:49 -08:00
2023-05-18 14:25:05 -07:00
You can run Zebra using our Docker image or you can build it manually. Please
see the [requirements section of the Zebra Book ](https://zebra.zfnd.org/user/requirements.html ) for system
requirements.
### Docker
2022-10-05 05:46:10 -07:00
This command will run our latest release, and sync it to the tip:
2022-11-01 15:35:21 -07:00
```sh
2023-05-11 15:15:12 -07:00
docker run zfnd/zebra:1.0.0-rc.8
2022-10-05 05:46:10 -07:00
```
2022-10-31 22:47:37 -07:00
For more information, read our [Docker documentation ](book/src/user/docker.md ).
2023-03-08 03:49:06 -08:00
### Building Zebra
2023-02-24 15:08:16 -08:00
2023-03-08 03:49:06 -08:00
Building Zebra requires [Rust ](https://www.rust-lang.org/tools/install ),
[libclang ](https://clang.llvm.org/doxygen/group__CINDEX.html ),
[pkg-config ](http://pkgconf.org/ ), and a C++ compiler.
2022-10-05 05:46:10 -07:00
2023-03-08 03:49:06 -08:00
Zebra is tested with the latest `stable` Rust version. Earlier versions are not
supported or tested. Note that Zebra's code currently uses features introduced
2023-04-18 20:25:51 -07:00
in Rust 1.68, or any later stable release.
2020-12-08 16:22:42 -08:00
2023-03-08 03:49:06 -08:00
Below are quick summaries for installing the dependencies on your machine.
2021-10-29 12:25:30 -07:00
2023-03-08 03:49:06 -08:00
< details > < summary > < h4 > General instructions for installing dependencies< / h4 > < / summary >
2020-12-08 16:22:42 -08:00
2021-03-22 19:05:01 -07:00
1. Install [`cargo` and `rustc` ](https://www.rust-lang.org/tools/install ).
2023-03-08 03:49:06 -08:00
2020-12-08 16:22:42 -08:00
2. Install Zebra's build dependencies:
2020-12-07 21:41:49 -08:00
2023-03-08 03:49:06 -08:00
- **libclang** is a library that might have different names depending on your
package manager. Typical names are `libclang` , `libclang-dev` , `llvm` , or
`llvm-dev` .
- **clang** or another C++ compiler: `g++` (all platforms) or `Xcode` (macOS).
- **pkg-config**
< / details >
< details > < summary > < h4 > Dependencies on Arch< / h4 > < / summary >
```sh
sudo pacman -S rust clang pkgconf
```
Note that the package `clang` includes `libclang` as well as the C++ compiler.
< / details >
Once the dependencies are in place, you can build Zebra
```sh
2023-05-11 15:15:12 -07:00
cargo install --locked --git https://github.com/ZcashFoundation/zebra --tag v1.0.0-rc.8 zebrad
2023-03-08 03:49:06 -08:00
```
You can start Zebra by
```sh
zebrad start
```
See the [Running Zebra ](https://zebra.zfnd.org/user/run.html ) section in the
book for more details.
#### Optional Features
2023-05-21 12:29:09 -07:00
You can also build Zebra with additional [Cargo features ](https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options ):
- `sentry` for [Sentry monitoring ](https://zebra.zfnd.org/user/requirements.html#sentry-production-monitoring )
- `journald` for [`journald` logging ](https://zebra.zfnd.org/user/tracing.html#journald-logging )
- `prometheus` for [Prometheus metrics ](https://doc.zebra.zfnd.org/zebrad/#metrics )
- `getblocktemplate-rpcs` for [mining support ](https://zebra.zfnd.org/user/mining.html )
2023-03-08 03:49:06 -08:00
2023-05-21 12:29:09 -07:00
You can combine multiple features by listing them as parameters of the `--features` flag:
2023-03-08 03:49:06 -08:00
```sh
cargo install --features="< feature1 > < feature2 > ..." ...
```
2023-05-21 12:29:09 -07:00
Our full list of experimental and developer features is in [the API
2023-03-08 03:49:06 -08:00
documentation](https://doc.zebra.zfnd.org/zebrad/index.html#zebra-feature-flags).
2023-05-21 12:29:09 -07:00
Some debugging and monitoring features are disabled in release builds to increase
2023-03-08 03:49:06 -08:00
performance.
2020-12-08 16:22:42 -08:00
2022-09-03 22:03:15 -07:00
### Configuring JSON-RPC for lightwalletd
To use `zebrad` as a `lightwalletd` backend, give it this `~/.config/zebrad.toml` :
```toml
[rpc]
# listen for RPC queries on localhost
listen_addr = '127.0.0.1:8232'
# automatically use multiple CPU threads
parallel_cpu_threads = 0
```
**WARNING:** This config allows multiple Zebra instances to share the same RPC port.
See the [RPC config documentation ](https://doc.zebra.zfnd.org/zebra_rpc/config/struct.Config.html ) for details.
2023-02-01 19:26:51 -08:00
`lightwalletd` also requires a `zcash.conf` file.
It is recommended to use [adityapk00/lightwalletd ](https://github.com/adityapk00/lightwalletd ) because that is used in testing.
Other `lightwalletd` forks have limited support, see the [detailed `lightwalletd` instructions ](https://github.com/ZcashFoundation/zebra/blob/main/book/src/user/lightwalletd.md#sync-lightwalletd ).
2023-05-18 14:25:05 -07:00
### Network Ports
2021-06-23 04:10:21 -07:00
2022-11-08 14:54:58 -08:00
Zebra uses the following inbound and outbound TCP ports:
2022-08-31 15:00:46 -07:00
2021-06-23 04:10:21 -07:00
- 8233 on Mainnet
- 18233 on Testnet
2023-05-18 14:25:05 -07:00
Please see the [Network
Requirements](https://zebra.zfnd.org/user/requirements.html#network-requirements-and-ports)
section of the Zebra book for more details.
2022-02-16 16:09:12 -08:00
2021-10-29 12:25:30 -07:00
## Known Issues
2020-12-08 16:22:42 -08:00
2021-01-27 17:31:39 -08:00
There are a few bugs in Zebra that we're still working on fixing:
2022-08-31 15:00:46 -07:00
2023-01-09 19:48:03 -08:00
- If Zebra fails downloading the Zcash parameters, use [the Zcash parameters download script ](https://github.com/zcash/zcash/blob/master/zcutil/fetch-params.sh ) instead.
- Block download and verification sometimes times out during Zebra's initial sync [#5709 ](https://github.com/ZcashFoundation/zebra/issues/5709 ). The full sync still finishes reasonably quickly.
2022-12-06 13:35:44 -08:00
2023-01-09 19:48:03 -08:00
- No Windows support [#3801 ](https://github.com/ZcashFoundation/zebra/issues/3801 ). We used to test with Windows Server 2019, but not any more; see the issue for details.
2022-12-12 15:19:45 -08:00
2023-03-01 03:20:19 -08:00
- Experimental Tor support is disabled until [Zebra upgrades to the latest `arti-client` ](https://github.com/ZcashFoundation/zebra/issues/5492 ). This happened due to a Rust dependency conflict, which could only be resolved by `arti` upgrading to a version of `x25519-dalek` with the dependency fix.
2023-01-09 19:48:03 -08:00
- Output of `help` , `--help` flag, and usage of invalid commands or options are inconsistent [#5502 ](https://github.com/ZcashFoundation/zebra/issues/5502 ). See the issue for details.
2022-11-18 06:24:10 -08:00
2020-12-08 16:22:42 -08:00
## Future Work
2020-12-07 21:41:49 -08:00
2023-05-21 12:29:09 -07:00
The Zebra team is currently working towards an audited stable release.
2022-08-31 15:00:46 -07:00
2023-05-21 12:29:09 -07:00
We will continue to add new features as part of future network upgrades, and in response to community feedback.
2021-11-02 02:59:13 -07:00
2020-12-07 21:41:49 -08:00
## Documentation
The [Zebra website ](https://zebra.zfnd.org/ ) contains user documentation, such
as how to run or configure Zebra, set up metrics integrations, etc., as well as
2022-08-31 15:00:46 -07:00
developer documentation, such as design documents. We also render [API
2020-12-07 21:41:49 -08:00
documentation](https://doc.zebra.zfnd.org) for the external API of our crates,
as well as [internal documentation ](https://doc-internal.zebra.zfnd.org ) for
private APIs.
2021-01-31 16:59:30 -08:00
## Security
2021-02-15 17:34:49 -08:00
Zebra has a [responsible disclosure policy ](https://github.com/ZcashFoundation/zebra/blob/main/SECURITY.md ), which we encourage security researchers to follow.
2021-01-31 16:59:30 -08:00
2019-11-14 11:17:58 -08:00
## License
2019-11-14 11:22:23 -08:00
Zebra is distributed under the terms of both the MIT license
2019-11-14 11:17:58 -08:00
and the Apache License (Version 2.0).
See [LICENSE-APACHE ](LICENSE-APACHE ) and [LICENSE-MIT ](LICENSE-MIT ).