Update README troubleshooting and beta scope (#2996)

* Add troubleshooting and remove outdated section from README

* Fix typo

* Add macOS crash reporter troubleshooting

* Remove outdated beta summary
This commit is contained in:
teor 2021-11-02 19:59:13 +10:00 committed by GitHub
parent a9f1c189d9
commit d7286f5d46
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 40 additions and 42 deletions

View File

@ -12,7 +12,6 @@
- [About](#about) - [About](#about)
- [Beta Releases](#beta-releases) - [Beta Releases](#beta-releases)
- [Getting Started](#getting-started) - [Getting Started](#getting-started)
- [Current Features](#current-features)
- [Known Issues](#known-issues) - [Known Issues](#known-issues)
- [Future Work](#future-work) - [Future Work](#future-work)
- [Documentation](#documentation) - [Documentation](#documentation)
@ -76,17 +75,10 @@ These are some of advantages or benefits of Zebra:
Every few weeks, we release a new Zebra beta [release](https://github.com/ZcashFoundation/zebra/releases). Every few weeks, we release a new Zebra beta [release](https://github.com/ZcashFoundation/zebra/releases).
The goals of the beta release series are for Zebra to act as a fully validating Canopy and NU5 node, except for: Zebra's network stack is interoperable with `zcashd`,
and Zebra implements all the features required to reach Zcash network consensus.
- Mempool transactions
- Block subsidies
- Transaction fees
- Some undocumented rules derived from Bitcoin
- Some consensus rules removed before Canopy activation (Zebra checkpoints on Canopy activation)
Zebra's network stack is interoperable with zcashd.
Zebra implements all the features required to reach Zcash network consensus.
The goals of the beta release series are for Zebra to act as a fully validating Canopy and NU5 node.
Currently, Zebra does not validate the following Zcash consensus rules: Currently, Zebra does not validate the following Zcash consensus rules:
#### NU5 #### NU5
@ -116,10 +108,9 @@ Currently, Zebra does not validate the following Zcash consensus rules:
- Validation of transaction lock times - Validation of transaction lock times
- Validation of sprout note commitment trees - Validation of sprout note commitment trees
It may be #### Other
unreliable on Testnet, and under less-than-perfect network conditions. See - Undocumented rules derived from Bitcoin
our [current features](#current-features) and [roadmap](#future-work) for - Undocumented network protocol requirements
details.
## Getting Started ## Getting Started
@ -158,11 +149,35 @@ We continuously test that our builds and tests pass on:
- Ubuntu 18.04 / the latest LTS - Ubuntu 18.04 / the latest LTS
- Debian Buster - Debian Buster
Zebra's tests can take over an hour, depending on your machine.
We're working on making them faster.
`zebrad` might build and run fine on smaller and slower systems - we haven't `zebrad` might build and run fine on smaller and slower systems - we haven't
tested its exact limits yet. tested its exact limits yet.
For more detailed requirements, refer to the [documentation](https://zebra.zfnd.org/user/requirements.html). For more detailed requirements, refer to the [documentation](https://zebra.zfnd.org/user/requirements.html).
#### Memory Troubleshooting
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`
(cargo uses all the processor cores on your machine by default.)
#### macOS Test Troubleshooting
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
```
### Network Ports and Data Usage ### Network Ports and Data Usage
By default, Zebra uses the following inbound TCP listener ports: By default, Zebra uses the following inbound TCP listener ports:
@ -175,35 +190,13 @@ By default, Zebra uses the following inbound TCP listener ports:
For more detailed information, refer to the [documentation](https://zebra.zfnd.org/user/run.html). For more detailed information, refer to the [documentation](https://zebra.zfnd.org/user/run.html).
## Current Features #### Network Troubleshooting
Network: Some of Zebra's tests download Zcash blocks, so they might be unreliable depending on your network connection.
- Synchronize the chain from peers You can set `ZEBRA_SKIP_NETWORK_TESTS=1` to skip the network tests.
- Maintain a transaction mempool
- Download gossiped blocks and transactions from peers
- Answer inbound peer requests for hashes, headers, blocks and transactions
State: Zebra may be unreliable on Testnet, and under less-than-perfect network conditions.
- Persist block, transaction, UTXO, and nullifier indexes See our [roadmap](#future-work) for details.
- Handle chain reorganizations
Proof of Work:
- Validate equihash, block difficulty threshold, and difficulty adjustment
- Validate transaction merkle roots
Validating proof of work increases the cost of creating a consensus split
between `zebrad` and `zcashd`.
This release also implements some other Zcash consensus rules, to check that
Zebra's [validation architecture](https://zebra.zfnd.org/dev/overview.html#architecture)
supports future work on a
full validating node:
- Block and transaction structure
- Checkpoint-based verification up to and including Canopy activation
- Transaction validation (incomplete)
- Transaction cryptography (incomplete)
- Transaction scripts (incomplete)
- Batch verification (incomplete)
## Known Issues ## Known Issues
@ -241,6 +234,11 @@ Performance and Reliability:
- Batch verification - Batch verification
- Performance tuning - Performance tuning
Currently, the following features are out of scope:
- Mining support
- Optional Zcash network protocol messages
- Consensus rules removed before Canopy activation (Zebra checkpoints on Canopy activation)
## Documentation ## Documentation
The [Zebra website](https://zebra.zfnd.org/) contains user documentation, such The [Zebra website](https://zebra.zfnd.org/) contains user documentation, such