consensus: improve docs

- remove no longer accurate documentation about transaction verifier;
- add description of the role of the crate.

zebra-consensus/src/lib.rs

@@ -1,13 +1,34 @@
-//! Consensus handling for Zebra.
+//! Implementation of Zcash consensus checks.
 //!
-//! `verify::BlockVerifier` verifies blocks and their transactions, then adds them to
-//! `zebra_state::ZebraState`.
+//! More specifically, this crate implements *semantic* validity checks,
+//! as defined below.
 //!
-//! `mempool::MempoolTransactionVerifier` verifies transactions, and adds them to
-//! `mempool::ZebraMempoolState`.
+//! ## Verification levels.
 //!
-//! Consensus handling is provided using `tower::Service`s, to support backpressure
-//! and batch verification.
+//! Zebra's implementation of the Zcash consensus rules is oriented
+//! around three telescoping notions of validity:
+//!
+//! 1. *Structural Validity*, or whether the format and structure of the
+//!    object are valid.  For instance, Sprout-on-BCTV14 proofs are not
+//!    allowed in version 4 transactions, and a transaction with a spend
+//!    or output description must include a binding signature.
+//!
+//! 2. *Semantic Validity*, or whether the object could potentially be
+//!    valid, depending on the chain state.  For instance, a transaction
+//!    that spends a UTXO must supply a valid unlock script; a shielded
+//!    transaction must have valid proofs, etc.
+//!
+//! 3. *Contextual Validity*, or whether a semantically valid
+//!    transaction is actually valid in the context of a particular
+//!    chain state.  For instance, a transaction that spends a
+//!    UTXO is only valid if the UTXO remains unspent; a
+//!    shielded transaction spending some note must reveal a nullifier
+//!    not already in the nullifier set, etc.
+//!
+//! *Structural validity* is enforced by the definitions of data
+//! structures in `zebra-chain`.  *Semantic validity* is enforced by the
+//! code in this crate.  *Contextual validity* is enforced in
+//! `zebra-state` when objects are committed to the chain state.
 
 #![doc(html_favicon_url = "https://www.zfnd.org/images/zebra-favicon-128.png")]
 #![doc(html_logo_url = "https://www.zfnd.org/images/zebra-icon.png")]

zebra-consensus/src/transaction.rs

@@ -1,17 +1,3 @@
-//! Transaction verification for Zebra.
-//!
-//! Verification occurs in multiple stages:
-//!   - getting transactions from blocks or the mempool (disk- or network-bound)
-//!   - context-free verification of signatures, proofs, and scripts (CPU-bound)
-//!   - context-dependent verification of transactions against the chain state
-//!     (awaits an up-to-date chain)
-//!
-//! Verification is provided via a `tower::Service`, to support backpressure and batch
-//! verification.
-//!
-//! This is an internal module. Use `verify::BlockVerifier` for blocks and their
-//! transactions, or `mempool::MempoolTransactionVerifier` for mempool transactions.
-
 use std::{
     future::Future,
     pin::Pin,
@@ -37,10 +23,7 @@ use zebra_state as zs;
 
 use crate::{script, BoxError};
 
-/// Internal transaction verification service.
-///
-/// After verification, the transaction future completes. State changes are
-/// handled by `BlockVerifier` or `MempoolTransactionVerifier`.
+/// Asynchronous transaction verification.
 #[derive(Debug, Clone)]
 pub struct Verifier<ZS> {
     script_verifier: script::Verifier<ZS>,