From 3c500b7daf4f0ddbbc41b4374685971f7b445e1c Mon Sep 17 00:00:00 2001
From: Jeremiah Andrews <jlandrews@berkeley.edu>
Date: Wed, 8 Aug 2018 16:25:17 -0700
Subject: [PATCH] Add docs changes

---
 docs/spec/blockchain/blockchain.md      | 26 ++++++++++++++++++++++++-
 docs/tendermint-core/block-structure.md |  2 +-
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/docs/spec/blockchain/blockchain.md b/docs/spec/blockchain/blockchain.md
index eab3acdf9..73a24f649 100644
--- a/docs/spec/blockchain/blockchain.md
+++ b/docs/spec/blockchain/blockchain.md
@@ -10,6 +10,7 @@ The Tendermint blockchains consists of a short list of basic data types:
 - `Header`
 - `Vote`
 - `BlockID`
+- `Commit`
 - `Signature`
 - `Evidence`
 
@@ -22,7 +23,7 @@ and a list of evidence of malfeasance (ie. signing conflicting votes).
 type Block struct {
     Header      Header
     Txs         [][]byte
-    LastCommit  []Vote
+    LastCommit  Commit
     Evidence    []Evidence
 }
 ```
@@ -107,6 +108,29 @@ There are two types of votes:
 a *prevote* has `vote.Type == 1` and
 a *precommit* has `vote.Type == 2`.
 
+## Commit
+
+A Commit contains enough data to verify that a BlockID was committed to at a certain
+height and round by a sufficient set of validators.
+
+```go
+type Commit struct {
+	BlockID    BlockID
+	Precommits []*CommitSig
+	RoundNum   int
+	HeightNum  int64
+}
+```
+
+The `CommitSig` values of the `Precommits` array contain the data for each validator needed to reconstruct and verify their precommit vote. For each entry, if the validator did not vote for the committed `BlockID`, their `CommitSig` value is `nil`. The only data unique to each vote is the `Timestamp` and `Signature`, all other data can be stored once in the `Commit` struct.
+
+```go
+type CommitSig struct {
+	Signature []byte
+	Timestamp time.Time
+}
+```
+
 ## Signature
 
 Tendermint allows for multiple signature schemes to be used by prepending a single type-byte
diff --git a/docs/tendermint-core/block-structure.md b/docs/tendermint-core/block-structure.md
index 803805529..375c9c0d5 100644
--- a/docs/tendermint-core/block-structure.md
+++ b/docs/tendermint-core/block-structure.md
@@ -73,7 +73,7 @@ they are commited to the chain.
 
 The
 [Commit](https://godoc.org/github.com/tendermint/tendermint/types#Commit)
-contains a set of
+contains the information needed to reconstruct the set of
 [Votes](https://godoc.org/github.com/tendermint/tendermint/types#Vote)
 that were made by the validator set to reach consensus on this block.
 This is the key to the security in any PoS system, and actually no data