spec: fixes from review

docs/specification/new-spec/README.md

@@ -10,7 +10,47 @@ It contains the following components:
 - [Blockchain](blockchain.md)
 - [State](state.md)
 
-TODO:
+## Overview
+
+Tendermint provides Byzantine Fault Tolerant State Machine Replication using
+hash-linked batches of transactions. Such transaction batches are called "blocks".
+Hence Tendermint defines a "blockchain".
+
+Each block in Tendermint has a unique index - its Height.
+A block at `Height == H` can only be committed *after* the
+block at `Height == H-1`.
+Each block is committed by a known set of weighted Validators.
+Membership and weighting within this set may change over time.
+Tendermint guarantees the safety and liveness of the blockchain
+so long as less than 1/3 of the total weight of the Validator set
+is malicious.
+
+A commit in Tendermint is a set of signed messages from more than 2/3 of
+the total weight of the current Validator set. Validators take turns proposing
+blocks and voting on them. Once enough votes are received, the block is considered
+committed. These votes are included in the *next* block as proof that the previous block
+was committed - they cannot be included in the current block, as that block has already been
+created.
+
+Once a block is committed, it can be executed against an application.
+The application returns results for each of the transactions in the block.
+The application can also return changes to be made to the validator set,
+as well as a cryptographic digest of its latest state.
+
+Tendermint is designed to enable efficient verification and authentication
+of the latest state of the blockchain. To achieve this, it embeds
+cryptographic commitments to certain information in the block "header".
+This information includes the contents of the block (eg. the transactions),
+the validator set committing the block, as well as the various results returned by the application.
+Note, however, that block execution only occurs *after* a block is committed.
+Thus, application results can only be included in the *next* block.
+
+Also note that information like the transaction results and the validator set are never
+directly included in the block - only their cryptographic digests (Merkle roots) are.
+Hence, verification of a block requires a separate data structure to store this information.
+We call this the `State`. Block verification also requires access to the previous block.
+
+## TODO
 
 - Light Client
 - P2P

docs/specification/new-spec/blockchain.md

@@ -184,7 +184,9 @@ The height is an incrementing integer. The first block has `block.Header.Height
 
 The median of the timestamps of the valid votes in the block.LastCommit.
 Corresponds to the number of nanoseconds, with millisecond resolution, since January 1, 1970.
-Increments with every new block.
+
+Note the timestamp in a vote must be greater by at least one millisecond than that of the
+block being voted on.
 
 ### NumTxs
 
@@ -226,12 +228,12 @@ The first block has `block.Header.TotalTxs = block.Header.NumberTxs`.
 ### LastBlockID
 
 ```
-parts := MakeParts(block, state.ConsensusParams.BlockGossip.BlockPartSize)
-block.HeaderLastBlockID == BlockID{
-    SimpleMerkleRoot(block.Header),
+prevBlockParts := MakeParts(prevBlock, state.LastConsensusParams.BlockGossip.BlockPartSize)
+block.Header.LastBlockID == BlockID {
+    Hash: SimpleMerkleRoot(prevBlock.Header),
     PartsHeader{
-        SimpleMerkleRoot(parts),
-        len(parts),
+        Hash: SimpleMerkleRoot(prevBlockParts),
+        Total: len(prevBlockParts),
     },
 }
 ```
@@ -274,7 +276,7 @@ May be updated by the application.
 ### ConsensusParamsHash
 
 ```
-block.ValidatorsHash == SimpleMerkleRoot(state.ConsensusParams)
+block.ConsensusParamsHash == SimpleMerkleRoot(state.ConsensusParams)
 ```
 
 Simple Merkle root of the consensus parameters.