Begin working on rough draft for alpha section in README (#1462)

* Expand README * add more alpha release sections * split existing README into sections * reorder the sections based on reader priority * Be clearer about what Zebra doesn't do * Update known issues Co-authored-by: Deirdre Connolly <deirdre@zfnd.org> Co-authored-by: teor <teor@riseup.net>
2020-12-07 21:41:49 -08:00 · 2020-12-07 21:41:49 -08:00 · 65e38b3c74
parent 621dc23082
commit 65e38b3c74
1 changed files with 114 additions and 28 deletions
--- a/README.md
+++ b/README.md
@ -6,27 +6,115 @@
 [![codecov](https://codecov.io/gh/ZcashFoundation/zebra/branch/main/graph/badge.svg)](https://codecov.io/gh/ZcashFoundation/zebra)
 ![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)

-### 🚧 UNDER CONSTRUCTION 🚧
+## About

 [Zebra](https://zebra.zfnd.org/) is the Zcash Foundation's independent,
 consensus-compatible implementation of the Zcash protocol, currently under
 development.  Please [join us on Discord](https://discord.gg/na6QZNd) if you'd
 like to find out more or get involved!

+## Alpha Releases
+
+Our first alpha release is planned for December 8th, 2020.
+
+The goals of this release are to:
+- participate in the Zcash network,
+- replicate the Zcash chain state, and
+- implement the Zcash proof of work consensus rules,
+- 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. See
+our [current features](#current-features) and [roadmap](future-work) for
+details.
+
+### Getting Started
+
+Run `cargo ...` **TODO**
+
+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.
+
+### System Requirements
+
+**TBD**
+
+### Current Features
+
+Network:
+- synchronize the chain from peers
+- download gossipped blocks from peers
+- answer inbound peer requests for hashes, headers, and blocks
+
+State:
+- persist block, transaction, UTXO, and nullifier indexes
+- 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](#architecture) supports future work on a
+full validating node:
+- block and transaction structure
+- checkpoint-based verification up to Sapling
+- transaction validation (incomplete)
+- transaction cryptography (incomplete)
+- transaction scripts (incomplete)
+- batch verification (incomplete)
+
+### Future Work
+
+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
+rules, before asking users to entrust it with their funds.
+
+Features:
+- full consensus rule validation
+- transaction mempool
+- wallet functionality
+- RPC functionality
+
+Performance and Reliability:
+- reliable syncing on Testnet
+- reliable syncing under poor network conditions
+- batch verification
+- 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
+
+The [Zebra website](https://zebra.zfnd.org/) contains user documentation, such
+as how to run or configure Zebra, set up metrics integrations, etc., as well as
+developer documentation, such as design documents.  We also render [API
+documentation](https://doc.zebra.zfnd.org) for the external API of our crates,
+as well as [internal documentation](https://doc-internal.zebra.zfnd.org) for
+private APIs.
+
+## Architecture
+
 Unlike `zcashd`, which originated as a Bitcoin Core fork and inherited its
 monolithic architecture, Zebra has a modular, library-first design, with the
 intent that each component can be independently reused outside of the `zebrad`
-fullnode.  For instance, the `zebra-network` crate containing the network stack
+full node.  For instance, the `zebra-network` crate containing the network stack
 can also be used to implement anonymous transaction relay, network crawlers, or
 other functionality, without requiring a full node.

-Our first goal is to be able to participate in the network and replicate the
-Zcash chain state, and we intend to ship an alpha before the end of 2020 with
-this functionality.  In 2021, we intend to add RPC support and wallet
-integration.  This phased approach allows us to test the independent
-implementation of the consensus rules before asking users to entrust it with
-their funds.
-
 At a high level, the fullnode functionality required by `zebrad` is factored
 into several components:

@ -34,8 +122,9 @@ into several components:
  definitions of core data structures for Zcash, such as blocks, transactions,
  addresses, etc., and related functionality.  It also contains the
  implementation of the consensus-critical serialization formats used in Zcash.
-  The data structures in `zebra-chain` are defined to enforce [*structural
-  validity*](https://zebra.zfnd.org/dev/rfcs/0002-parallel-verification.html#verification-stages) by making invalid states unrepresentable.  For instance, the
+  The data structures in `zebra-chain` are defined to enforce
+  [*structural validity*](https://zebra.zfnd.org/dev/rfcs/0002-parallel-verification.html#verification-stages)
+  by making invalid states unrepresentable.  For instance, the
  `Transaction` enum has variants for each transaction version, and it's
  impossible to construct a transaction with, e.g., spend or output
  descriptions but no binding signature, or, e.g., a version 2 (Sprout)
@ -48,12 +137,13 @@ into several components:
  protocol inherited from Bitcoin.  In contrast to `zcashd`, each peer
  connection has a separate state machine, and the crate translates the
  external network protocol into a stateless, request/response-oriented
-  protocol for internal use.  The crate provides two interfaces: an
-  auto-managed connection pool that load-balances requests over available
-  peers, and a `connect_isolated` method that produces a peer connection
-  completely isolated from all other node state.  This can be used, for
-  instance, to safely relay data over Tor, without revealing distinguishing
-  information.
+  protocol for internal use.  The crate provides two interfaces:
+  - an auto-managed connection pool that load-balances local node requests
+    over available peers, and sends peer requests to a local inbound service,
+    and
+  - a `connect_isolated` method that produces a peer connection completely
+    isolated from all other node state.  This can be used, for instance, to
+    safely relay data over Tor, without revealing distinguishing information.

 - [`zebra-script`](https://doc.zebra.zfnd.org/zebra_script/index.html) provides
  script validation.  Currently, this is implemented by linking to the C++
@ -61,7 +151,8 @@ into several components:
  pure-Rust script implementation.

 - [`zebra-consensus`](https://doc.zebra.zfnd.org/zebra_consensus/index.html)
-  performs [*semantic validation*](https://zebra.zfnd.org/dev/rfcs/0002-parallel-verification.html#verification-stages) of blocks and transactions: all consensus
+  performs [*semantic validation*](https://zebra.zfnd.org/dev/rfcs/0002-parallel-verification.html#verification-stages)
+  of blocks and transactions: all consensus
  rules that can be checked independently of the chain state, such as
  verification of signatures, proofs, and scripts.  Internally, the library
  uses [`tower-batch`](https://doc.zebra.zfnd.org/tower_batch/index.html) to
@ -70,11 +161,12 @@ into several components:

 - [`zebra-state`](https://doc.zebra.zfnd.org/zebra_state/index.html) is
  responsible for storing, updating, and querying the chain state.  The state
-  service is responsible for [*contextual verification*](https://zebra.zfnd.org/dev/rfcs/0002-parallel-verification.html#verification-stages): all consensus rules
+  service is responsible for [*contextual verification*](https://zebra.zfnd.org/dev/rfcs/0002-parallel-verification.html#verification-stages):
+  all consensus rules
  that check whether a new block is a valid extension of an existing chain,
  such as updating the nullifier set or checking that transaction inputs remain
  unspent.
-  
+
 - [`zebrad`](https://doc.zebra.zfnd.org/zebrad/index.html) contains the full
  node, which connects these components together and implements logic to handle
  inbound requests from peers and the chain sync process.
@ -85,14 +177,8 @@ into several components:

 All of these components can be reused as independent libraries, and all
 communication between stateful components is handled internally by
-[internal asynchronous RPC abstraction](https://docs.rs/tower/) ("microservices in one process").
-
-The [Zebra website](https://zebra.zfnd.org/) contains user documentation, such
-as how to run or configure Zebra, set up metrics integrations, etc., as well as
-developer documentation, such as design documents.  We also render [API
-documentation](https://doc.zebra.zfnd.org) for the external API of our crates,
-as well as [internal documentation](https://doc-internal.zebra.zfnd.org) for
-private APIs.
+[internal asynchronous RPC abstraction](https://docs.rs/tower/)
+("microservices in one process").

 ## License