octo
/
Zebra
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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 2023-05-23 15:18:57 +02:00 committed by GitHub
parent ec2e9ca276
commit 0b8e73206f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 157 additions and 176 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
README.md
View File

@ -15,7 +15,6 @@
- [Docker](#docker) - [Docker](#docker)
- [Building Zebra](#building-zebra) - [Building Zebra](#building-zebra)
- [Optional Features](#optional-features) - [Optional Features](#optional-features)
- [Configuring JSON-RPC for lightwalletd](#configuring-json-rpc-for-lightwalletd)
- [Network Ports](#network-ports) - [Network Ports](#network-ports)
- [Known Issues](#known-issues) - [Known Issues](#known-issues)
- [Future Work](#future-work) - [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 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. 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: 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), - To generate transactions, [run Zebra with
and use a light wallet with `lightwalletd` and Zebra. `lightwalletd`](https://zebra.zfnd.org/user/lightwalletd.html).
- to generate blocks, [compile `zebrad` with the `getblocktemplate-rpcs` feature](https://doc.zebra.zfnd.org/zebrad/#json-rpc), configure the JSON-RPC port, - To generate blocks, [enable mining
and use a mining pool or miner with Zebra's mining JSON-RPCs. support](https://zebra.zfnd.org/user/mining.html), and use a mining pool or
Mining support is currently incomplete, experimental, and off by default. 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 ## Getting Started
You can run Zebra using our Docker image or you can build it manually. Please 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 see the [System Requirements](https://zebra.zfnd.org/user/requirements.html)
requirements. section in the Zebra book for system requirements.
### Docker ### 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 supported or tested. Note that Zebra's code currently uses features introduced
in Rust 1.68, or any later stable release. 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. Below are quick summaries for installing the dependencies on your machine.
<details><summary><h4>General instructions for installing dependencies</h4></summary> <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 Some debugging and monitoring features are disabled in release builds to increase
performance. 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 ### Network Ports
Zebra uses the following inbound and outbound TCP ports: Zebra uses the following inbound and outbound TCP ports:

1
book/src/SUMMARY.md
View File

@ -16,6 +16,7 @@
- [Mining](user/mining.md) - [Mining](user/mining.md)
- [Testnet Mining with s-nomp](user/mining-testnet-s-nomp.md) - [Testnet Mining with s-nomp](user/mining-testnet-s-nomp.md)
- [Kibana blockchain explorer](user/elasticsearch.md) - [Kibana blockchain explorer](user/elasticsearch.md)
- [Troubleshooting](user/troubleshooting.md)
- [Developer Documentation](dev.md) - [Developer Documentation](dev.md)
- [Contribution Guide](CONTRIBUTING.md) - [Contribution Guide](CONTRIBUTING.md)
- [Design Overview](dev/overview.md) - [Design Overview](dev/overview.md)

6
book/src/user/install.md
View File

@ -2,6 +2,12 @@
Follow the [Docker or compilation instructions in the README](https://github.com/ZcashFoundation/zebra#getting-started). 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 #### Build Troubleshooting
If you're having trouble with: If you're having trouble with:

45
book/src/user/lightwalletd.md
View File

@ -1,12 +1,15 @@
# Running lightwalletd with zebra # 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: Contents:
- [Download and build Zebra](#download-and-build-zebra)
- [Configure zebra for lightwalletd](#configure-zebra-for-lightwalletd) - [Configure zebra for lightwalletd](#configure-zebra-for-lightwalletd)
- [RPC section](#rpc-section) - [JSON-RPC](#json-rpc)
- [Sync Zebra](#sync-zebra) - [Sync Zebra](#sync-zebra)
- [Download and build lightwalletd](#download-and-build-lightwalletd) - [Download and build lightwalletd](#download-and-build-lightwalletd)
- [Sync lightwalletd](#sync-lightwalletd) - [Sync lightwalletd](#sync-lightwalletd)
@ -15,16 +18,8 @@ Contents:
- [Download and build the cli-wallet](#download-and-build-the-cli-wallet) - [Download and build the cli-wallet](#download-and-build-the-cli-wallet)
- [Run the wallet](#run-the-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]: #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: 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. Tweak the following option in order to prepare for lightwalletd setup.
### RPC section ### JSON-RPC
[#rpc-section]: #rpc-section
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] [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]: #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. With the configuration in place you can start synchronizing Zebra with the Zcash blockchain. This may take a while depending on your hardware.

54
book/src/user/requirements.md
View File

@ -30,13 +30,20 @@ Zebra uses the following inbound and outbound TCP ports:
- 8233 on Mainnet - 8233 on Mainnet
- 18233 on Testnet - 18233 on Testnet
Outbound connections are required to sync, inbound connections are optional. If you configure Zebra with a specific
Zebra also needs access to the Zcash DNS seeders, via the OS DNS resolver [`listen_addr`](https://doc.zebra.zfnd.org/zebra_network/struct.Config.html#structfield.listen_addr),
(usually port 53). 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. download to grow.
- Ongoing updates: 10 MB - 10 GB upload and download per day, depending on - Ongoing updates: 10 MB - 10 GB upload and download per day, depending on
user-created transaction size and peer requests. user-created transaction size and peer requests.
@ -51,40 +58,3 @@ ticket.](https://github.com/ZcashFoundation/zebra/issues/new/choose)
## Sentry Production Monitoring ## Sentry Production Monitoring
Compile Zebra with `--features sentry` to monitor it using Sentry in production. 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
```

83
book/src/user/run.md
View File

@ -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 structure, and documentation for all of the config options can be found
[here](https://doc.zebra.zfnd.org/zebrad/config/struct.ZebradConfig.html). [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 ## 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 - `1`: Application exited unsuccessfully
- `2`: Application crashed - `2`: Application crashed
- `zebrad` may also return platform-dependent codes. - `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)

87
book/src/user/troubleshooting.md Normal file
View File

@ -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)