celestiaorg · adlerjohn · Nov 27, 2020 · Oct 27, 2020 · Oct 27, 2020 · Oct 28, 2020
diff --git a/specs/consensus.md b/specs/consensus.md
@@ -10,10 +10,15 @@ Consensus Rules
 - [Leader Selection](#leader-selection)
 - [Fork Choice](#fork-choice)
 - [Block Validity](#block-validity)
+  - [Block Structure](#block-structure)
+    - [`block.header`](#blockheader)
+    - [`block.availableDataHeader`](#blockavailabledataheader)
+    - [`block.lastCommit`](#blocklastcommit)
+    - [`block.availableData`](#blockavailabledata)
   - [State Transitions](#state-transitions)
+    - [`block.availableData.evidenceData`](#blockavailabledataevidencedata)
+    - [`block.availableData.transactionData`](#blockavailabledatatransactiondata)
     - [Validators and Delegations](#validators-and-delegations)
-  - [Formatting](#formatting)
-  - [Availability](#availability)
 
 ## System Parameters
 
@@ -30,18 +35,18 @@ Consensus Rules
 
 | name                                 | type     | value   | unit    | description                                                                                                                                                         |
 | ------------------------------------ | -------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `VERSION`                            | `uint64` | `1`     |         | Version of the LazyLedger chain. Breaking changes (hard forks) must update this parameter.                                                                          |
+| `AVAILABLE_DATA_ORIGINAL_SQUARE_MAX` | `uint64` |         | `share` | Maximum number of rows/columns of the original data [shares](data_structures.md#share) in [square layout](data_structures.md#arranging-available-data-into-shares). |
 | `CHAIN_ID`                           | `uint64` | `1`     |         | Chain ID. Each chain assigns itself a (unique) ID.                                                                                                                  |
+| `GENESIS_COIN_COUNT`                 | `uint64` | `10**8` | `4u`    | `(= 100000000)` Number of coins at genesis.                                                                                                                         |
+| `GRAFFITI_BYTES`                     | `uint64` | `32`    | `byte`  | Maximum size of transaction graffiti, in bytes.                                                                                                                     |
+| `MAX_VALIDATORS`                     | `uint16` | `64`    |         | Maximum number of active validators.                                                                                                                                |
 | `NAMESPACE_ID_BYTES`                 | `uint64` | `8`     | `byte`  | Size of namespace ID, in bytes.                                                                                                                                     |
 | `NAMESPACE_ID_MAX_RESERVED`          | `uint64` | `255`   |         | Value of maximum reserved namespace ID (inclusive). 1 byte worth of IDs.                                                                                            |
-| `SHARE_SIZE`                         | `uint64` | `256`   | `byte`  | Size of transaction and message [shares](data_structures.md#share), in bytes.                                                                                       |
 | `SHARE_RESERVED_BYTES`               | `uint64` | `1`     | `byte`  | Bytes reserved at the beginning of each [share](data_structures.md#share). Must be sufficient to represent `SHARE_SIZE`.                                            |
-| `AVAILABLE_DATA_ORIGINAL_SQUARE_MAX` | `uint64` |         | `share` | Maximum number of rows/columns of the original data [shares](data_structures.md#share) in [square layout](data_structures.md#arranging-available-data-into-shares). |
-| `GENESIS_COIN_COUNT`                 | `uint64` | `10**8` | `4u`    | `(= 100000000)` Number of coins at genesis.                                                                                                                         |
-| `UNBONDING_DURATION`                 | `uint32` |         | `block` | Duration, in blocks, for unbonding a validator or delegation.                                                                                                       |
-| `MAX_VALIDATORS`                     | `uint16` | `64`    |         | Maximum number of active validators.                                                                                                                                |
+| `SHARE_SIZE`                         | `uint64` | `256`   | `byte`  | Size of transaction and message [shares](data_structures.md#share), in bytes.                                                                                       |
 | `STATE_SUBTREE_RESERVED_BYTES`       | `uint64` | `1`     | `byte`  | Number of bytes reserved to identify state subtrees.                                                                                                                |
-| `GRAFFITI_BYTES`                     | `uint64` | `32`    | `byte`  | Maximum size of transaction graffiti, in bytes.                                                                                                                     |
+| `UNBONDING_DURATION`                 | `uint32` |         | `block` | Duration, in blocks, for unbonding a validator or delegation.                                                                                                       |
+| `VERSION`                            | `uint64` | `1`     |         | Version of the LazyLedger chain. Breaking changes (hard forks) must update this parameter.                                                                          |
 
 ### Reserved Namespace IDs
 
@@ -61,7 +66,6 @@ Consensus Rules
 | `ACTIVE_VALIDATORS_SUBTREE_ID`   | `StateSubtreeID` | `0x02` |
 | `INACTIVE_VALIDATORS_SUBTREE_ID` | `StateSubtreeID` | `0x03` |
 
-
 ### Rewards and Penalties
 
 | name                 | type     | value | unit | description                      |
@@ -71,12 +75,86 @@ Consensus Rules
 
 ## Leader Selection
 
+TODO
+
 ## Fork Choice
 
+TODO
+
 ## Block Validity
 
+This section specifies the entirety of the validity rules for a newly-seen block, `block`.
+
+### Block Structure
+
+Before executing [state transitions](#state-transitions), the structure of the [block](./data_structures.md#block) must be verified.
+
+The following block fields are acquired from the network and parsed (i.e. [deserialized](./data_structures.md#serialization)). If they cannot be parsed, the block is ignored but is not explicitly considered invalid by consensus rules. Further implications of ignoring a block are found in the [networking spec](./networking.md).
+1. [block.header](./data_structures.md#header)
+1. [block.availableDataHeader](./data_structures.md#availabledataheader)
+1. [block.lastCommit](./data_structures.md#commit)
+
+If the above fields are parsed successfully, the available data `block.availableData` is acquired in erasure-coded form as [a list of share rows](./networking.md#availabledata), then parsed. If it cannot be parsed, the block is ignored but not explicitly invalid, as above.
+
+#### `block.header`
+
+The [block header](./data_structures.md#header) `block.header` (`header` for short) is the first thing that is downloaded from the new block, and commits to everything inside the block in some way. For previous block `prev` (if `prev` is not known, then the block is ignored), and previous block header `prev.header`, the following checks must be `true`:
+
+`availableDataOriginalSquareSize` is computed as described [here](./data_structures.md#header).
+
+1. `header.height` == `prev.header.height + 1`.
+1. `header.timestamp` > `prev.header.timestamp`.
+1. `header.lastBlockID` == the [block ID](./data_structures.md#blockid) of `prev`.
+1. `header.lastCommitHash` == the [hash](./data_structures.md#hashing) of `lastCommit`.
+1. `header.consensusRoot` == the value computed [here](./data_structures.md#consensus-parameters).
+1. `header.stateCommitment` == the root of the state, computed [with the application of all state transitions in this block](#state-transitions).
+1. `availableDataOriginalSquareSize` <= [`AVAILABLE_DATA_ORIGINAL_SQUARE_MAX`](#constants).
+1. `header.availableDataRoot` == TODO available data root
+1. `header.proposerAddress` == the [leader](#leader-selection) for `header.height`.
+
+TODO define the genesis block
+
+#### `block.availableDataHeader`
+
+The [available data header](./data_structures.md#availabledataheader)) `block.availableDataHeader` (`availableDataHeader` for short) is then processed. This commits to the available data, which is only downloaded after the [consensus commit](#blocklastcommit) is processed. The following checks must be `true`:
+
+1. Length of `availableDataHeader.availableDataCommitments` == `2 * availableDataOriginalSquareSize`.
+1. The length of each element in `availableDataHeader.availableDataCommitments` must be [`32`](./consensus.md#hashing).
+
+#### `block.lastCommit`
+
+The last [commit](./data_structures.md#commit) `block.lastCommit` (`lastCommit` for short) is processed next. This is the Tendermint commit (i.e. polka of votes) _for the previous block_. For previous block `prev` and previous block header `prev.header`, the following checks must be `true`:
+
+1. `lastCommit.height` == `prev.header.height`.
+1. `lastCommit.round` >= `1`.
+1. `lastCommit.blockID` == the [block ID](./data_structures.md#blockid) of `prev`.
+1. Length of `lastCommit.signatures` <= [`MAX_VALIDATORS`](#constants).
+1. Each of `lastCommit.signatures` must be a valid [CommitSig](./data_structures.md#commitsig)
+1. The sum of the votes for `prev` in `lastCommit` must be at least 2/3 (rounded up) of the voting power of `prev`'s next validator set.
+
+TODO define specifically how to validate commitsigs
+
+#### `block.availableData`
+
+The block's [available data](./data_structures.md#availabledata) (analogous to transactions in contemporary blockchain designs) `block.availableData` (`availableData` for short) is finally processed. The [list of share rows](./networking.md#availabledata) is parsed into the [actual data structures](./data_structures.md#availabledata); if parsing fails here, the block is invalid.
+
+TODO define fraud proof for invalid block here
+
+Once parsed, the following checks must be `true`:
+
+1. The commitments of the [erasure-coded extended](./data_structures.md#2d-reed-solomon-encoding-scheme) `availableData` must match those in `header.availableDataHeader`. Implicitly, this means that both rows and columns must be ordered lexicographically by namespace ID since they are committed to in a [Namespace Merkle Tree](data_structures.md#namespace-merkle-tree).
+1. Length of `availableData.intermediateStateRootData` == length of `availableData.transactionData` + length of `availableData.evidenceData`.
+
 ### State Transitions
 
+#### `block.availableData.evidenceData`
+
+
+
+#### `block.availableData.transactionData`
+
+
+
 #### Validators and Delegations
 
 A transaction `tx` that requests a new validator initializes a new [Validator](data_structures.md#validator) leaf in the inactive validators subtree for that account as follows:
@@ -149,9 +227,3 @@ then updates the target validator's voting power:
 validator.delegatedCount -= 1
 validator.votingPower -= delegation.votingPower
 ```
-
-### Formatting
-
-Leaves in the message [Namespace Merkle Tree](data_structures.md#namespace-merkle-tree) must be ordered lexicographically by namespace ID.
-
-### Availability
diff --git a/specs/data_structures.md b/specs/data_structures.md
@@ -110,7 +110,7 @@ Block header, which is fully downloaded by both full clients and light clients.
 | `height`                          | [Height](#type-aliases)   | Block height. The genesis block is at height `1`.                                                                                                                  |
 | `timestamp`                       | [Timestamp](#timestamp)   | Timestamp of this block.                                                                                                                                           |
 | `lastBlockID`                     | [BlockID](#blockid)       | Previous block's ID.                                                                                                                                               |
-| `lastCommitRoot`                  | [HashDigest](#hashdigest) | Previous block's Tendermint commit root.                                                                                                                           |
+| `lastCommitHash`                  | [HashDigest](#hashdigest) | Previous block's Tendermint commit hash.                                                                                                                           |
 | `consensusRoot`                   | [HashDigest](#hashdigest) | Merkle root of [consensus parameters](#consensus-parameters) for this block.                                                                                       |
 | `stateCommitment`                 | [HashDigest](#hashdigest) | The [state root](#state) after this block's transactions are applied.                                                                                              |
 | `availableDataOriginalSharesUsed` | `uint64`                  | The number of shares used in the [original data square](#arranging-available-data-into-shares) that are not [tail padding](./consensus.md#reserved-namespace-ids). |
@@ -145,12 +145,12 @@ Data that is [erasure-coded](#erasure-coding) for [data availability checks](htt
 
 ### Commit
 
-| name         | type                        | description |
-| ------------ | --------------------------- | ----------- |
-| `height`     | [Height](#type-aliases)     |             |
-| `round`      | [Round](#type-aliases)      |             |
-| `blockID`    | [BlockID](#blockid)         |             |
-| `signatures` | [CommitSig](#commitsig)`[]` |             |
+| name         | type                        | description                        |
+| ------------ | --------------------------- | ---------------------------------- |
+| `height`     | [Height](#type-aliases)     | Block height.                      |
+| `round`      | [Round](#type-aliases)      | Round. Incremented on view change. |
+| `blockID`    | [BlockID](#blockid)         | Block ID of the previous block.    |
+| `signatures` | [CommitSig](#commitsig)`[]` | List of signatures.                |
 
 ### Timestamp
 
@@ -204,7 +204,11 @@ Output of the [signing](#public-key-cryptography) process.
 
 ## Serialization
 
-Objects that are committed to or signed over require a canonical serialization. This is done using TODO.
+Objects that are committed to or signed over require a canonical serialization. This is done using a deterministic (and thus, bijective) variant of protobuf defined [here](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/adr-027-deterministic-protobuf-serialization.md).
+
+Note: there are two requirements for a serialization scheme, should this need to be changed:
+1. Must be bijective.
+1. Serialization must include the length of dynamic structures (e.g. arrays with variable length).
 
 ## Hashing
 

diff --git a/specs/figures/block_data_structures.dot b/specs/figures/block_data_structures.dot
@@ -22,12 +22,12 @@ digraph G {
 
         subgraph cluster_header {
             label = "header";
-            struct1 [label = "height | timestamp | lastBlockID | <f3> lastCommitRoot | consensusRoot | stateCommitment | <f6> availableDataRoot | proposerAddress"];
+            struct1 [label = "height | timestamp | lastBlockID | <f3> lastCommitHash | consensusRoot | stateCommitment | availableDataOriginalSharesUsed | <f7> availableDataRoot | proposerAddress"];
         }
     }
 
     struct1:f3 -> struct2;
-    struct1:f6 -> struct4 [label = "Merkle root of"];
+    struct1:f7 -> struct4 [label = "Merkle root of"];
     struct4:f0 -> struct3 [label = "NMT roots to\nerasure-coded data"];
 
     edge [style = invis];