Add download, build and run instructions to the README (#1478)
Zebra first alpha release The goals of this release are to: - participate in the Zcash network, - replicate the Zcash chain state, - implement the Zcash proof of work consensus rules, and - sync on Mainnet under excellent network conditions. Currently, Zebra does not validate all the Zcash consensus rules. It may be unreliable on Testnet, and under less-than-perfect network conditions. Co-authored-by: teor <teor@riseup.net> Co-authored-by: Deirdre Connolly <deirdre@zfnd.org> Co-authored-by: Jane Lusby <jlusby42@gmail.com>
This commit is contained in:
parent
444002d7a3
commit
85c7eea444
88
README.md
88
README.md
|
@ -30,14 +30,64 @@ details.
|
||||||
|
|
||||||
### Getting Started
|
### Getting Started
|
||||||
|
|
||||||
Run `cargo ...` **TODO**
|
Building `zebrad` requires [Rust](https://www.rust-lang.org/tools/install),
|
||||||
|
[libclang](https://clang.llvm.org/get_started.html), and a C++ compiler.
|
||||||
|
|
||||||
|
#### Detailed Build and Run Instructions
|
||||||
|
|
||||||
|
1. Install [`cargo` and `rustc`](https://www.rust-lang.org/tools/install).
|
||||||
|
- Using `rustup` installs the stable Rust toolchain, which `zebrad` targets.
|
||||||
|
2. Install Zebra's build dependencies:
|
||||||
|
- **libclang:** the `libclang`, `libclang-dev`, `llvm`, or `llvm-dev` packages, depending on your package manager
|
||||||
|
- **a C++ compiler:** use `clang`, `g++`, `Xcode`, `MSVC`, or similar
|
||||||
|
3. Run `cargo install --git https://github.com/ZcashFoundation/zebra --tag v1.0.0-alpha.0 zebrad`
|
||||||
|
4. Run `zebrad start`
|
||||||
|
|
||||||
If you're interested in testing out `zebrad` please feel free, but keep in mind
|
If you're interested in testing out `zebrad` please feel free, but keep in mind
|
||||||
that there is a lot of key functionality still missing.
|
that there is a lot of key functionality still missing.
|
||||||
|
|
||||||
|
#### Build Troubleshooting
|
||||||
|
|
||||||
|
If you're having trouble with:
|
||||||
|
- **dependencies:** use `cargo install --locked ...` to build with the exact crate versions used for the release
|
||||||
|
- **libclang:** check out the [clang-sys documentation](https://github.com/KyleMayes/clang-sys#dependencies)
|
||||||
|
- **g++ or MSVC++:** try using clang or Xcode instead
|
||||||
|
- **rustc:** use rustc 1.48 or later
|
||||||
|
- Zebra does not have a minimum supported Rust version (MSRV) policy yet
|
||||||
|
|
||||||
### System Requirements
|
### System Requirements
|
||||||
|
|
||||||
**TBD**
|
We usually build `zebrad` on systems with:
|
||||||
|
- 2+ CPU cores
|
||||||
|
- 7+ GB RAM
|
||||||
|
- 14+ GB of disk space
|
||||||
|
|
||||||
|
On many-core machines (like, 32-core) the build is very fast; on 2-core machines
|
||||||
|
it's less fast.
|
||||||
|
|
||||||
|
We continuously test that our builds and tests pass on:
|
||||||
|
- Windows Server 2019
|
||||||
|
- macOS Big Sur 11.0
|
||||||
|
- Ubuntu 18.04 / the latest LTS
|
||||||
|
- Debian Buster
|
||||||
|
|
||||||
|
We usually run `zebrad` on systems with:
|
||||||
|
- 4+ CPU cores
|
||||||
|
- 16+ GB RAM
|
||||||
|
- 50GB+ available disk space for finalized state
|
||||||
|
- 100+ Mbps network connections
|
||||||
|
|
||||||
|
`zebrad` might build and run fine on smaller and slower systems - we haven't
|
||||||
|
tested its exact limits yet.
|
||||||
|
|
||||||
|
### Network Usage
|
||||||
|
|
||||||
|
`zebrad`'s typical network usage is:
|
||||||
|
- initial sync: 30 GB download
|
||||||
|
- ongoing updates: 10-50 MB upload and download per day, depending on peer requests
|
||||||
|
|
||||||
|
The major constraint we've found on `zebrad` performance is the network weather,
|
||||||
|
especially the ability to make good connections to other Zcash network peers.
|
||||||
|
|
||||||
### Current Features
|
### Current Features
|
||||||
|
|
||||||
|
@ -67,7 +117,27 @@ full validating node:
|
||||||
- transaction scripts (incomplete)
|
- transaction scripts (incomplete)
|
||||||
- batch verification (incomplete)
|
- batch verification (incomplete)
|
||||||
|
|
||||||
### Future Work
|
### Dependencies
|
||||||
|
|
||||||
|
Zebra primarily depends on pure Rust crates, and some Rust/C++ crates:
|
||||||
|
- [rocksdb](https://crates.io/crates/rocksdb)
|
||||||
|
- [zcash_script](https://crates.io/crates/zcash_script)
|
||||||
|
|
||||||
|
### Known Issues
|
||||||
|
|
||||||
|
There are a few bugs in the Zebra alpha release that we're still working on
|
||||||
|
fixing:
|
||||||
|
- [Occasional panics in the `tokio` time wheel implementation #1452](https://github.com/ZcashFoundation/zebra/issues/1452)
|
||||||
|
- workaround: restart `zebrad`
|
||||||
|
- [Occasional panics during client requests #1471](https://github.com/ZcashFoundation/zebra/issues/1471)
|
||||||
|
- workaround: restart `zebrad`
|
||||||
|
- [Peer connections sometimes fail permanently #1435](https://github.com/ZcashFoundation/zebra/issues/1435)
|
||||||
|
- these permanent failures can happen after a network disconnection, sleep, or individual peer disconnections
|
||||||
|
- workaround: use `Control-C` to exit `zebrad`, and then restart `zebrad`
|
||||||
|
- [Duplicate block errors #1372](https://github.com/ZcashFoundation/zebra/issues/1372)
|
||||||
|
- these errors can be ignored, unless they happen frequently
|
||||||
|
|
||||||
|
## Future Work
|
||||||
|
|
||||||
In 2021, we intend to add RPC support and wallet integration. This phased
|
In 2021, we intend to add RPC support and wallet integration. This phased
|
||||||
approach allows us to test Zebra's independent implementation of the consensus
|
approach allows us to test Zebra's independent implementation of the consensus
|
||||||
|
@ -85,18 +155,6 @@ Performance and Reliability:
|
||||||
- batch verification
|
- batch verification
|
||||||
- performance tuning
|
- performance tuning
|
||||||
|
|
||||||
### Known Issues
|
|
||||||
|
|
||||||
There are a few bugs in the Zebra alpha release that we're still working on
|
|
||||||
fixing:
|
|
||||||
- [Occasional panics in the `tokio` time wheel implementation #1452](https://github.com/ZcashFoundation/zebra/issues/1452)
|
|
||||||
- workaround: restart `zebrad`
|
|
||||||
- [Peer connections sometimes fail permanently #1435](https://github.com/ZcashFoundation/zebra/issues/1435)
|
|
||||||
- these permanent failures can happen after a network disconnection, sleep, or individual peer disconnections
|
|
||||||
- workaround: use `Control-C` to exit `zebrad`, and then restart `zebrad`
|
|
||||||
- [Duplicate block errors #1372](https://github.com/ZcashFoundation/zebra/issues/1372)
|
|
||||||
- these errors can be ignored, unless they happen frequently
|
|
||||||
|
|
||||||
## Documentation
|
## Documentation
|
||||||
|
|
||||||
The [Zebra website](https://zebra.zfnd.org/) contains user documentation, such
|
The [Zebra website](https://zebra.zfnd.org/) contains user documentation, such
|
||||||
|
|
Loading…
Reference in New Issue