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
- [About ](#about )
- [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 )
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,
2023-05-26 02:59:34 -07:00
consensus-compatible implementation of a Zcash node.
2022-06-28 15:15:01 -07:00
2023-05-26 02:59:34 -07:00
Zebra's network stack is interoperable with `zcashd` , and Zebra implements all
the features required to reach Zcash network consensus, including the validation
of all the consensus rules for the NU5 network upgrade.
[Here ](https://doc.zebra.zfnd.org/zebrad/index.html#zebra-advantages ) are some
benefits of Zebra.
2021-10-29 12:25:30 -07:00
2023-05-26 02:59:34 -07:00
Zebra validates blocks and transactions, but needs extra software to generate
them:
2023-02-24 15:08:16 -08:00
2023-05-23 06:18:57 -07:00
- To generate transactions, [run Zebra with
`lightwalletd` ](https://zebra.zfnd.org/user/lightwalletd.html).
- To generate blocks, [enable mining
support](https://zebra.zfnd.org/user/mining.html), and use a mining pool or
miner with Zebra's mining JSON-RPCs. Mining support is currently incomplete,
experimental, and off by default.
2023-05-26 02:59:34 -07:00
Please [join us on Discord ](https://discord.gg/na6QZNd ) if you'd like to find
out more or get involved!
2022-11-22 22:01:34 -08:00
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
2023-05-23 06:18:57 -07:00
see the [System Requirements ](https://zebra.zfnd.org/user/requirements.html )
section in the Zebra book for system requirements.
2023-05-18 14:25:05 -07:00
### 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-05-23 06:18:57 -07:00
Every few weeks, we release a [new Zebra
version](https://github.com/ZcashFoundation/zebra/releases).
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 ):
2023-05-26 02:59:34 -07:00
2023-05-21 12:29:09 -07:00
- `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
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 ).