From 84d2abd2b0b103052330ff6ca9ee4f48568d4b8d Mon Sep 17 00:00:00 2001 From: Henry de Valence Date: Fri, 16 Oct 2020 15:53:22 -0700 Subject: [PATCH] consensus: improve docs - remove no longer accurate documentation about transaction verifier; - add description of the role of the crate. --- zebra-consensus/src/lib.rs | 35 ++++++++++++++++++++++++------ zebra-consensus/src/transaction.rs | 19 +--------------- 2 files changed, 29 insertions(+), 25 deletions(-) diff --git a/zebra-consensus/src/lib.rs b/zebra-consensus/src/lib.rs index 02d53fca03d..442f56dc274 100644 --- a/zebra-consensus/src/lib.rs +++ b/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")] diff --git a/zebra-consensus/src/transaction.rs b/zebra-consensus/src/transaction.rs index 81daaf8075a..7ae9050dec8 100644 --- a/zebra-consensus/src/transaction.rs +++ b/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 { script_verifier: script::Verifier,