docs: add block validity rules specs (celestiaorg#1966)

## Overview Figured we could at least use this as a place holder as a high level summary of celestia-app, and to point to all the other portions of the application. part of and closes celestiaorg#743 part of celestiaorg#650 [rendered](https://github.com/celestiaorg/celestia-app/blob/b44960898f59ea3ed86430828606cdc72107a0be/specs/src/specs/block_validity_rules.md) ## Checklist - [x] New and updated code has appropriate documentation - [x] New and updated code has new and/or updated testing - [x] Required CI checks are passing - [x] Visual proof for any user facing features like CLI or documentation updates - [x] Linked issues closed with keywords --------- Co-authored-by: Callum Waters <[email protected]> Co-authored-by: Rootul P <[email protected]> Co-authored-by: Sanaz Taheri <[email protected]>
rootulp · Jul 6, 2023 · 5bcf4ad · 5bcf4ad
1 parent 65046dd
commit 5bcf4ad
Show file tree

Hide file tree

Showing 5 changed files with 78 additions and 1 deletion.
diff --git a/specs/src/README.md b/specs/src/README.md
@@ -7,6 +7,7 @@
   - [Consensus](./specs/consensus.md)
   - [Block Proposer](./specs/block_proposer.md)
   - [Block Validity Rules](./specs/block_validity_rules.md)
+  - [Fraud Proofs](./specs/fraud_proofs.md)
   - [Networking](./specs/networking.md)
   - [Public-Key Cryptography](./specs/public_key_cryptography.md)
   - [Data Square Layout](./specs/data_square_layout.md)

diff --git a/specs/src/SUMMARY.md b/specs/src/SUMMARY.md
@@ -9,6 +9,7 @@
   - [Consensus](./specs/consensus.md)
   - [Block Proposer](./specs/block_proposer.md)
   - [Block Validity Rules](./specs/block_validity_rules.md)
+  - [Fraud Proofs](./specs/fraud_proofs.md)
   - [Networking](./specs/networking.md)
   - [Public-Key Cryptography](./specs/public_key_cryptography.md)
   - [Data Square Layout](./specs/data_square_layout.md)

diff --git a/specs/src/specs/block_validity_rules.md b/specs/src/specs/block_validity_rules.md
@@ -1 +1,51 @@
 # Block Validity Rules
+
+## Introduction
+
+Unlike most blockchains, Celestia derives most of its functionality from
+stateless commitments to data rather than stateful transitions. This means that
+the protocol relies heavily on block validity rules. Notably, resource
+constrained light clients must be able to detect when a subset of these validity
+rules have not been followed in order to avoid making an honest majority
+assumption on the consensus network. This has a significant impact on thier
+design. More information on how light clients can check the invalidity of a
+block can be foud in the [Fraud Proofs](./fraud_proofs.md) spec.
+
+> **Note** Celestia relies on CometBFT (formerly tendermint) for consensus,
+> meaning that it has single slot finality and is fork-free. Therefore, in order
+> to ensure that an invalid block is never committed to, each validator must
+> check that each block follows all validity rules before voting. If over two
+> thirds of the voting power colludes to break a validity rule, then fraud
+> proofs are created for light clients. After light clients verify fraud proofs,
+> they halt.
+
+## Validity Rules
+
+Before any Celestia specific validation is performed, all CometBFT [block
+validation
+rules](https://github.com/cometbft/cometbft/blob/v0.34.28/spec/core/data_structures.md#block)
+must be followed.
+
+Notably, this includes verifying data availability. Consensus nodes verify data
+availabily by simply downloading the entire block.
+
+> **Note** Light clients only sample a fraction of the block. More details on
+> how sampling actually works can be found in the seminal ["Fraud and Data
+> Availability Proofs: Maximising Light Client Security and Scaling Blockchains
+> with Dishonest Majorities"](https://arxiv.org/abs/1809.09044) and in the
+> [`celestia-node`](https://github.com/celestiaorg/celestia-node) repo.
+
+Celestia specifc validity rules can be categorized into two groups:
+
+### Transaction Validity Rules
+
+All `BlobTx` transactions must be valid according to the [BlobTx validity rules](../../../x/blob/README.md#validity-rules)
+
+All remaining transaction types do not have to by valid if included in a block. For a complete list of modules see [state machine modules](./state_machine_modules.md).
+
+### Data Root Construction
+
+The data root must be calculated from a correctly constructed data square per the [data square layout rules](./data_square_layout.md)
+
+<img src="./figures/rs2d_extending.svg" alt="Figure 1: Erasure Encoding" width="400"/> <img
+src="./figures/rs2d_quadrants.svg" alt="Figure 2: rsmt2d" width="400"/> <img src="./figures/data_root.svg" alt="Figure 3: Data Root" width="400"/>
diff --git a/specs/src/specs/data_square_layout.md b/specs/src/specs/data_square_layout.md
@@ -4,7 +4,7 @@
 
 ## Preamble
 
-Celestia uses [a data availability scheme](https://arxiv.org/abs/1809.09044) that allows nodes to determine whether a block's data was published without downloading the whole block. The core of this scheme is arranging data in a two-dimensional matrix then applying erasure coding to each row and column. This document describes the rationale for how data—transactions, blobs, and other data—[is actually arranged](./data_structures.md#arranging-available-data-into-shares). Familiarity with the [originally proposed data layout format](https://arxiv.org/abs/1809.09044) is assumed.
+Celestia uses [a data availability scheme](https://arxiv.org/abs/1809.09044) that allows nodes to determine whether a block's data was published without downloading the whole block. The core of this scheme is arranging data in a two-dimensional matrix of [shares](./shares.md), then applying erasure coding to each row and column. This document describes the rationale for how data—transactions, blobs, and other data—[is actually arranged](./data_structures.md#arranging-available-data-into-shares). Familiarity with the [originally proposed data layout format](https://arxiv.org/abs/1809.09044) is assumed.
 
 ## Layout Rationale
 

diff --git a/specs/src/specs/fraud_proofs.md b/specs/src/specs/fraud_proofs.md
@@ -0,0 +1,25 @@
+# Fraud Proofs
+
+## Bad Encoding Fraud Proofs
+
+In order for data availability sampling to work, light clients must be convinced
+that erasure encoded parity data was encoded correctly. For light clients, this
+is ultimately enforced via [bad encoding fraud proofs
+(BEFPs)](https://github.com/celestiaorg/celestia-node/blob/v0.11.0-rc3/docs/adr/adr-006-fraud-service.md#detailed-design).
+Consensus nodes must verify this themselves before considering a block valid.
+This is done automatically by verifying the data root of the header, since that
+requires reconstructing the square from the block data, performing the erasure
+encoding, calculating the data root using that representation, and then
+comparing the data root found in the header.
+
+## Blob Inclusion
+
+TODO
+
+## State
+
+State fraud proofs allow light clients to avoid making an honest majority assumption for
+state validity. While these are not incorporated into the protocol as of v1.0.0,
+there are example implementations that can be found in
+[Rollkit](https://github.com/rollkit/rollkit). More info in
+[rollkit-ADR009](https://github.com/rollkit/rollkit/blob/4fd97ba8b8352771f2e66454099785d06fd0c31b/docs/lazy-adr/adr-009-state-fraud-proofs.md).