change(docs): Update User Docs (#6733)
* Move releases info to `Building Zebra` * Move Zebra use-cases to `Using Zebra` * Point the links in Zebra use-cases to docs * Move the contents of `Release Candidates` * Refactor the `System Requirements` link * Update the syncing times * Update notes on performance * Move data usage to `System Requirements` * Remove "building Zebra" from lightwalletd docs I think we can assume people will follow the previous parts of the docs for how to build Zebra. * Move lightwalletd details from `README.md` to docs `README.md` already mentions lightwalletd from the `Using Zebra` section, and refers the reader to the docs where the details were moved and refactored. * Mention `lightwalletd` and mining in Running Zebra * Move Troubleshooting to its own file * Move "Improving Performance" to its own file * Move instructions for ARM to "Installing Zebra" * Reword the Testnet sync duration description Co-authored-by: Pili Guerra <mpguerra@users.noreply.github.com> * Move "Improving Performance" to "Troubleshooting" * Remove the Testnet unreliability caveat --------- Co-authored-by: Pili Guerra <mpguerra@users.noreply.github.com>
This commit is contained in:
Marek
GitHub
parent
ec2e9ca276
commit
0b8e73206f
57
README.md
57
README.md
|
|
@ -15,7 +15,6 @@
|
|||
- [Docker](#docker)
|
||||
- [Building Zebra](#building-zebra)
|
||||
- [Optional Features](#optional-features)
|
||||
- [Configuring JSON-RPC for lightwalletd](#configuring-json-rpc-for-lightwalletd)
|
||||
- [Network Ports](#network-ports)
|
||||
- [Known Issues](#known-issues)
|
||||
- [Future Work](#future-work)
|
||||
|
|
@ -46,30 +45,26 @@ You would want to run Zebra if you want to contribute to the
|
|||
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.
|
||||
|
||||
Zebra aims to be [faster, more secure, and more easily extensible](https://doc.zebra.zfnd.org/zebrad/index.html#zebra-advantages)
|
||||
than other Zcash implementations.
|
||||
|
||||
## Release Candidates
|
||||
|
||||
Every few weeks, we release a [new Zebra version](https://github.com/ZcashFoundation/zebra/releases).
|
||||
|
||||
Zebra's network stack is interoperable with `zcashd`,
|
||||
and Zebra implements all the features required to reach Zcash network consensus.
|
||||
Currently, Zebra validates all of the Zcash consensus rules for the NU5 network upgrade.
|
||||
|
||||
Zebra validates blocks and transactions, but needs extra software to generate them:
|
||||
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
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.
|
||||
|
||||
## Getting Started
|
||||
|
||||
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.
|
||||
see the [System Requirements](https://zebra.zfnd.org/user/requirements.html)
|
||||
section in the Zebra book for system requirements.
|
||||
|
||||
### Docker
|
||||
|
||||
|
|
@ -91,6 +86,9 @@ 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
|
||||
in Rust 1.68, or any later stable release.
|
||||
|
||||
Every few weeks, we release a [new Zebra
|
||||
version](https://github.com/ZcashFoundation/zebra/releases).
|
||||
|
||||
Below are quick summaries for installing the dependencies on your machine.
|
||||
|
||||
<details><summary><h4>General instructions for installing dependencies</h4></summary>
|
||||
|
|
@ -152,27 +150,6 @@ documentation](https://doc.zebra.zfnd.org/zebrad/index.html#zebra-feature-flags)
|
|||
Some debugging and monitoring features are disabled in release builds to increase
|
||||
performance.
|
||||
|
||||
### 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.
|
||||
|
||||
`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).
|
||||
|
||||
### Network Ports
|
||||
|
||||
Zebra uses the following inbound and outbound TCP ports:
|
||||
|
|
|
|||
|
|
@ -16,6 +16,7 @@
|
|||
- [Mining](user/mining.md)
|
||||
- [Testnet Mining with s-nomp](user/mining-testnet-s-nomp.md)
|
||||
- [Kibana blockchain explorer](user/elasticsearch.md)
|
||||
- [Troubleshooting](user/troubleshooting.md)
|
||||
- [Developer Documentation](dev.md)
|
||||
- [Contribution Guide](CONTRIBUTING.md)
|
||||
- [Design Overview](dev/overview.md)
|
||||
|
|
|
|||
|
|
@ -2,6 +2,12 @@
|
|||
|
||||
Follow the [Docker or compilation instructions in the README](https://github.com/ZcashFoundation/zebra#getting-started).
|
||||
|
||||
#### ARM
|
||||
|
||||
If you're using an ARM machine, [install the Rust compiler for
|
||||
ARM](https://rust-lang.github.io/rustup/installation/other.html). If you build
|
||||
using the x86_64 tools, Zebra might run really slowly.
|
||||
|
||||
#### Build Troubleshooting
|
||||
|
||||
If you're having trouble with:
|
||||
|
|
|
|||
|
|
@ -1,12 +1,15 @@
|
|||
# Running lightwalletd with zebra
|
||||
|
||||
Zebra's RPC methods can support a lightwalletd service backed by zebrad.
|
||||
Zebra's RPC methods can support a lightwalletd service backed by zebrad. We
|
||||
recommend using
|
||||
[adityapk00/lightwalletd](https://github.com/adityapk00/lightwalletd) because we
|
||||
use it in testing. Other `lightwalletd` forks have limited support, see the
|
||||
[Sync lightwalletd](#sync-lightwalletd) section for more info.
|
||||
|
||||
Contents:
|
||||
|
||||
- [Download and build Zebra](#download-and-build-zebra)
|
||||
- [Configure zebra for lightwalletd](#configure-zebra-for-lightwalletd)
|
||||
- [RPC section](#rpc-section)
|
||||
- [JSON-RPC](#json-rpc)
|
||||
- [Sync Zebra](#sync-zebra)
|
||||
- [Download and build lightwalletd](#download-and-build-lightwalletd)
|
||||
- [Sync lightwalletd](#sync-lightwalletd)
|
||||
|
|
@ -15,16 +18,8 @@ Contents:
|
|||
- [Download and build the cli-wallet](#download-and-build-the-cli-wallet)
|
||||
- [Run the wallet](#run-the-wallet)
|
||||
|
||||
## Download and build Zebra
|
||||
[#download-and-build-zebra]: #download-and-build-zebra
|
||||
|
||||
```console
|
||||
cargo install --locked --git https://github.com/ZcashFoundation/zebra zebrad
|
||||
```
|
||||
|
||||
Zebra binary will be at ` ~/.cargo/bin/zebrad`.
|
||||
|
||||
## Configure zebra for lightwalletd
|
||||
|
||||
[#configure-zebra-for-lightwalletd]: #configure-zebra-for-lightwalletd
|
||||
|
||||
We need a zebra configuration file. First, we create a file with the default settings:
|
||||
|
|
@ -37,17 +32,33 @@ The above command places the generated `zebrad.toml` config file in the default
|
|||
|
||||
Tweak the following option in order to prepare for lightwalletd setup.
|
||||
|
||||
### RPC section
|
||||
[#rpc-section]: #rpc-section
|
||||
### JSON-RPC
|
||||
|
||||
This change is required for zebra to behave as an RPC endpoint. The standard port for RPC endpoint is `8232`.
|
||||
[#rpc-section]: #json-rpc
|
||||
|
||||
```
|
||||
We need to configure Zebra to behave as an RPC endpoint. The standard RPC port
|
||||
for Zebra is:
|
||||
|
||||
- `8232` for Mainnet, and
|
||||
- `18323` for Testnet.
|
||||
|
||||
For example, to use Zebra as a `lightwalletd` backend on Mainnet, give it this
|
||||
`~/.config/zebrad.toml`:
|
||||
|
||||
```toml
|
||||
[rpc]
|
||||
listen_addr = "127.0.0.1:8232"
|
||||
# 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.
|
||||
|
||||
## Sync Zebra
|
||||
|
||||
[#sync-zebra]: #sync-zebra
|
||||
|
||||
With the configuration in place you can start synchronizing Zebra with the Zcash blockchain. This may take a while depending on your hardware.
|
||||
|
|
|
|||
|
|
@ -30,13 +30,20 @@ Zebra uses the following inbound and outbound TCP ports:
|
|||
- 8233 on Mainnet
|
||||
- 18233 on Testnet
|
||||
|
||||
Outbound connections are required to sync, inbound connections are optional.
|
||||
Zebra also needs access to the Zcash DNS seeders, via the OS DNS resolver
|
||||
(usually port 53).
|
||||
If you configure Zebra with a specific
|
||||
[`listen_addr`](https://doc.zebra.zfnd.org/zebra_network/struct.Config.html#structfield.listen_addr),
|
||||
it will advertise this address to other nodes for inbound connections. Outbound
|
||||
connections are required to sync, inbound connections are optional. Zebra also
|
||||
needs access to the Zcash DNS seeders, via the OS DNS resolver (usually port
|
||||
53).
|
||||
|
||||
The typical Mainnet network usage is:
|
||||
Zebra makes outbound connections to peers on any port. But `zcashd` prefers
|
||||
peers on the default ports, so that it can't be used for DDoS attacks on other
|
||||
networks.
|
||||
|
||||
- Initial sync: 300 GB download, as already noted, we expect the initial
|
||||
### Typical Mainnet Network Usage
|
||||
|
||||
- Initial sync: 300 GB download. As already noted, we expect the initial
|
||||
download to grow.
|
||||
- Ongoing updates: 10 MB - 10 GB upload and download per day, depending on
|
||||
user-created transaction size and peer requests.
|
||||
|
|
@ -51,40 +58,3 @@ ticket.](https://github.com/ZcashFoundation/zebra/issues/new/choose)
|
|||
## Sentry Production Monitoring
|
||||
|
||||
Compile Zebra with `--features sentry` to monitor it using Sentry in production.
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
We continuously test that our builds and tests pass on the _latest_ [GitHub
|
||||
Runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources)
|
||||
for:
|
||||
|
||||
- macOS,
|
||||
- Ubuntu,
|
||||
- Docker:
|
||||
- Debian Bullseye.
|
||||
|
||||
## Memory Issues
|
||||
|
||||
- If Zebra's build runs out of RAM, try setting `export CARGO_BUILD_JOBS=2`.
|
||||
- If Zebra's tests timeout or run out of RAM, try running `cargo test -- --test-threads=2`. Note that `cargo` uses all processor cores on your machine
|
||||
by default.
|
||||
|
||||
## Network Issues
|
||||
|
||||
- Some of Zebra's tests download Zcash blocks, so they might be unreliable
|
||||
depending on your network connection. You can set `ZEBRA_SKIP_NETWORK_TESTS=1`
|
||||
to skip the network tests.
|
||||
- Zebra may be unreliable on Testnet, and under less-than-perfect network
|
||||
conditions. See our [future
|
||||
work](https://github.com/ZcashFoundation/zebra#future-work) for details.
|
||||
|
||||
## Issues with Tests on macOS
|
||||
|
||||
Some of Zebra's tests deliberately cause errors that make Zebra panic. macOS
|
||||
records these panics as crash reports. If you are seeing "Crash Reporter"
|
||||
dialogs during Zebra tests, you can disable them using this Terminal.app
|
||||
command:
|
||||
|
||||
```sh
|
||||
defaults write com.apple.CrashReporter DialogType none
|
||||
```
|
||||
|
|
|
|||
|
|
@ -9,7 +9,12 @@ The configuration format is the TOML encoding of the internal config
|
|||
structure, and documentation for all of the config options can be found
|
||||
[here](https://doc.zebra.zfnd.org/zebrad/config/struct.ZebradConfig.html).
|
||||
|
||||
* `zebrad start` starts a full node.
|
||||
- `zebrad start` starts a full node.
|
||||
|
||||
You can run Zebra as a:
|
||||
|
||||
- [`lightwalletd` backend](https://zebra.zfnd.org/user/lightwalletd.html), and
|
||||
- experimental [mining backend](https://zebra.zfnd.org/user/mining.html).
|
||||
|
||||
## Supported versions
|
||||
|
||||
|
|
@ -21,79 +26,3 @@ Always run a supported version of Zebra, and upgrade it regularly, so it doesn't
|
|||
- `1`: Application exited unsuccessfully
|
||||
- `2`: Application crashed
|
||||
- `zebrad` may also return platform-dependent codes.
|
||||
|
||||
## Network Ports and Data Usage
|
||||
|
||||
`zebrad`'s default ports and network usage are
|
||||
[documented in the README.](https://github.com/ZcashFoundation/zebra#network-ports-and-data-usage)
|
||||
|
||||
If Zebra is configured with a specific [`listen_addr`](https://doc.zebra.zfnd.org/zebra_network/struct.Config.html#structfield.listen_addr),
|
||||
it will advertise this address to other nodes for inbound connections.
|
||||
|
||||
Zebra makes outbound connections to peers on any port.
|
||||
But `zcashd` prefers peers on the default ports,
|
||||
so that it can't be used for DDoS attacks on other networks.
|
||||
|
||||
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.
|
||||
|
||||
Zebra needs some peers which have a round-trip latency of 2 seconds or less.
|
||||
If this is a problem for you, please let us know!
|
||||
|
||||
## Improving Performance
|
||||
|
||||
Zebra usually syncs in around a day, depending on your network connection, and the overall Zcash network load.
|
||||
|
||||
If you're having trouble syncing, try the following config changes:
|
||||
|
||||
### Release Build
|
||||
|
||||
Make sure you're using a release build on your native architecture.
|
||||
|
||||
If you're using an ARM machine,
|
||||
[install the Rust compiler for ARM](https://rust-lang.github.io/rustup/installation/other.html).
|
||||
If you build using the x86_64 tools, Zebra might run really slowly.
|
||||
|
||||
Run a release build using the
|
||||
[`cargo install` command from the README.](https://github.com/ZcashFoundation/zebra#build-and-run-instructions)
|
||||
|
||||
### Syncer Lookahead Limit
|
||||
|
||||
If your connection is slow, try
|
||||
[downloading fewer blocks at a time](https://doc.zebra.zfnd.org/zebrad/config/struct.SyncSection.html#structfield.lookahead_limit):
|
||||
|
||||
```toml
|
||||
[sync]
|
||||
lookahead_limit = 1000
|
||||
max_concurrent_block_requests = 25
|
||||
```
|
||||
|
||||
### Peer Set Size
|
||||
|
||||
If your connection is slow, try [connecting to fewer peers](https://doc.zebra.zfnd.org/zebra_network/struct.Config.html#structfield.peerset_initial_target_size):
|
||||
|
||||
```toml
|
||||
[network]
|
||||
peerset_initial_target_size = 25
|
||||
```
|
||||
|
||||
### Turn off debug logging
|
||||
|
||||
Zebra logs at info level by default.
|
||||
|
||||
If Zebra is slow, make sure it is logging at info level:
|
||||
|
||||
```toml
|
||||
[tracing]
|
||||
filter = 'info'
|
||||
```
|
||||
|
||||
Or restrict debug logging to a specific Zebra component:
|
||||
|
||||
```toml
|
||||
[tracing]
|
||||
filter = 'info,zebra_network=debug'
|
||||
```
|
||||
|
||||
If you keep on seeing multiple info logs per second, please
|
||||
[open a bug.](https://github.com/ZcashFoundation/zebra/issues/new/choose)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,87 @@
|
|||
# Troubleshooting
|
||||
|
||||
We continuously test that our builds and tests pass on the _latest_ [GitHub
|
||||
Runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources)
|
||||
for:
|
||||
|
||||
- macOS,
|
||||
- Ubuntu,
|
||||
- Docker:
|
||||
- Debian Bullseye.
|
||||
|
||||
## Memory Issues
|
||||
|
||||
- If Zebra's build runs out of RAM, try setting `export CARGO_BUILD_JOBS=2`.
|
||||
- If Zebra's tests timeout or run out of RAM, try running `cargo test -- --test-threads=2`. Note that `cargo` uses all processor cores on your machine
|
||||
by default.
|
||||
|
||||
## Network Issues
|
||||
|
||||
Some of Zebra's tests download Zcash blocks, so they might be unreliable
|
||||
depending on your network connection. You can set `ZEBRA_SKIP_NETWORK_TESTS=1`
|
||||
to skip the network tests.
|
||||
|
||||
## Issues with Tests on macOS
|
||||
|
||||
Some of Zebra's tests deliberately cause errors that make Zebra panic. macOS
|
||||
records these panics as crash reports. If you are seeing "Crash Reporter"
|
||||
dialogs during Zebra tests, you can disable them using this Terminal.app
|
||||
command:
|
||||
|
||||
```sh
|
||||
defaults write com.apple.CrashReporter DialogType none
|
||||
```
|
||||
|
||||
## Improving Performance
|
||||
|
||||
Zebra usually syncs in around three days on Mainnet and half a day on
|
||||
Testnet. The sync speed depends on your network connection and the overall Zcash
|
||||
network load. 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. If you're having trouble syncing, try the following config
|
||||
changes.
|
||||
|
||||
### Release Build
|
||||
|
||||
Make sure you're using a release build on your native architecture.
|
||||
|
||||
### Syncer Lookahead Limit
|
||||
|
||||
If your connection is slow, try
|
||||
[downloading fewer blocks at a time](https://doc.zebra.zfnd.org/zebrad/config/struct.SyncSection.html#structfield.lookahead_limit):
|
||||
|
||||
```toml
|
||||
[sync]
|
||||
lookahead_limit = 1000
|
||||
max_concurrent_block_requests = 25
|
||||
```
|
||||
|
||||
### Peer Set Size
|
||||
|
||||
If your connection is slow, try [connecting to fewer peers](https://doc.zebra.zfnd.org/zebra_network/struct.Config.html#structfield.peerset_initial_target_size):
|
||||
|
||||
```toml
|
||||
[network]
|
||||
peerset_initial_target_size = 25
|
||||
```
|
||||
|
||||
### Turn off debug logging
|
||||
|
||||
Zebra logs at info level by default.
|
||||
|
||||
If Zebra is slow, make sure it is logging at info level:
|
||||
|
||||
```toml
|
||||
[tracing]
|
||||
filter = 'info'
|
||||
```
|
||||
|
||||
Or restrict debug logging to a specific Zebra component:
|
||||
|
||||
```toml
|
||||
[tracing]
|
||||
filter = 'info,zebra_network=debug'
|
||||
```
|
||||
|
||||
If you keep on seeing multiple info logs per second, please
|
||||
[open a bug.](https://github.com/ZcashFoundation/zebra/issues/new/choose)
|
||||
Loading…
Reference in New Issue