zecfoundation
/
zebra
mirror of https://github.com/ZcashFoundation/zebra.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: update readme (#1118) 

* docs: update readme

Fill in the README with:

- setting expectations about Zebra goals;
- explanation of the work we've done so far;
- suggestions from review comments;
- under construction sign.


Co-authored-by: Jane Lusby <jlusby42@gmail.com>


Co-authored-by: teor <teor@riseup.net>


Co-authored-by: teor <teor@riseup.net>
Co-authored-by: Jane Lusby <jlusby42@gmail.com>


Co-authored-by: Deirdre Connolly <deirdre@zfnd.org>

Co-authored-by: Jane Lusby <jlusby42@gmail.com>
Co-authored-by: teor <teor@riseup.net>
Co-authored-by: Deirdre Connolly <deirdre@zfnd.org>
This commit is contained in:
Henry de Valence 2020-10-06 23:53:22 -07:00 committed by GitHub
parent 8b8ef6dc4d
commit b2c3ba9d94
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 80 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
README.md
View File

@ -5,23 +5,92 @@
[![](https://github.com/ZcashFoundation/zebra/workflows/CI/badge.svg?branch=main)](https://github.com/ZcashFoundation/zebra/actions?query=workflow%3ACI+branch%3Amain)
[![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 🚧
[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!
Hello! I am Zebra, an ongoing Rust implementation of a Zcash node.
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
can also be used to implement anonymous transaction relay, network crawlers, or
other functionality, without requiring a full node.
Zebra is a work in progress. It is developed as a collection of `zebra-*`
libraries implementing the different components of a Zcash node (networking,
chain structures, consensus rules, etc), and a `zebrad` binary which uses them.
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.
Most of our work so far has gone into `zebra-network`, building a new
networking stack for Zcash, `zebra-chain`, building foundational data
structures, `zebra-consensus`, implementing consensus rules, and
`zebra-state`, providing chain state.
At a high level, the fullnode functionality required by `zebrad` is factored
into several components:
[Zebra Website](https://zebra.zfnd.org).
- [`zebra-chain`](https://doc.zebra.zfnd.org/zebra_chain/index.html), providing
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
`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)
transaction with Sapling proofs. Currently, `zebra-chain` is oriented
towards verifying transactions, but will be extended to support creating them
in the future.
[Rendered docs from the `main` branch](https://doc.zebra.zfnd.org).
- [`zebra-network`](https://doc.zebra.zfnd.org/zebra_network/index.html),
providing an asynchronous, multithreaded implementation of the Zcash network
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.
[Join us on Discord](https://discord.gg/na6QZNd).
- [`zebra-script`](https://doc.zebra.zfnd.org/zebra_script/index.html) provides
script validation. Currently, this is implemented by linking to the C++
script verification code from `zcashd`, but in the future we may implement a
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
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
perform automatic, transparent batch processing of contemporaneous
verification requests.
- [`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
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.
- `zebra-rpc` and `zebra-client` will eventually contain the RPC and wallet
functionality, but as mentioned above, our goal is to implement replication
of chain state first before asking users to entrust Zebra with their funds.
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.
## License