Skip to content

Commit

Permalink
change(docs): Update User Docs (#6733)
Browse files Browse the repository at this point in the history 
* 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>
  • Loading branch information
@upbqdn @mpguerra
upbqdn and mpguerra authored May 23, 2023
1 parent ec2e9ca commit 0b8e732
Show file tree
Hide file tree
Showing 7 changed files with 157 additions and 176 deletions.
57 changes: 17 additions & 40 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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

Expand All @@ -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>
Expand Down Expand Up @@ -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:
Expand Down
1 change: 1 addition & 0 deletions book/src/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
6 changes: 6 additions & 0 deletions book/src/user/install.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
45 changes: 28 additions & 17 deletions book/src/user/lightwalletd.md
View file
Original file line number Diff line number Diff line change
@@ -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)
Expand All @@ -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:
Expand All @@ -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.
Expand Down
54 changes: 12 additions & 42 deletions book/src/user/requirements.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
```
83 changes: 6 additions & 77 deletions book/src/user/run.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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)
Loading

0 comments on commit 0b8e732

Please sign in to comment.