Merge pull request #1510 from tendermint/bucky/docs-and-fixes

JSON Indent and some docs

Gopkg.lock

@@ -5,7 +5,7 @@
   branch = "master"
   name = "github.com/btcsuite/btcd"
   packages = ["btcec"]
-  revision = "2be2f12b358dc57d70b8f501b00be450192efbc3"
+  revision = "675abc5df3c5531bc741b56a765e35623459da6d"
 
 [[projects]]
   name = "github.com/davecgh/go-spew"
@@ -254,8 +254,8 @@
 [[projects]]
   name = "github.com/tendermint/go-amino"
   packages = ["."]
-  revision = "42246108ff925a457fb709475070a03dfd3e2b5c"
-  version = "0.9.6"
+  revision = "3668c02a8feace009f80754a5e5a8541e5d7b996"
+  version = "0.9.8"
 
 [[projects]]
   name = "github.com/tendermint/go-crypto"
@@ -285,8 +285,8 @@
     "pubsub/query",
     "test"
   ]
-  revision = "97e1f1ad3f510048929a51475811a18686c894df"
-  version = "0.8.2-rc0"
+  revision = "d94e312673e16a11ea55d742cefb3e331228f898"
+  version = "v0.8.2"
 
 [[projects]]
   branch = "master"
@@ -301,13 +301,14 @@
     "ripemd160",
     "salsa20/salsa"
   ]
-  revision = "d6449816ce06963d9d136eee5a56fca5b0616e7e"
+  revision = "b49d69b5da943f7ef3c9cf91c8777c1f78a0cc3c"
 
 [[projects]]
   branch = "master"
   name = "golang.org/x/net"
   packages = [
     "context",
+    "http/httpguts",
     "http2",
     "http2/hpack",
     "idna",
@@ -315,13 +316,13 @@
     "lex/httplex",
     "trace"
   ]
-  revision = "61147c48b25b599e5b561d2e9c4f3e1ef489ca41"
+  revision = "5f9ae10d9af5b1c89ae6904293b14b064d4ada23"
 
 [[projects]]
   branch = "master"
   name = "golang.org/x/sys"
   packages = ["unix"]
-  revision = "3b87a42e500a6dc65dae1a55d0b641295971163e"
+  revision = "bb9c189858d91f42db229b04d45a4c3d23a7662a"
 
 [[projects]]
   name = "golang.org/x/text"
@@ -348,7 +349,7 @@
   branch = "master"
   name = "google.golang.org/genproto"
   packages = ["googleapis/rpc/status"]
-  revision = "51d0944304c3cbce4afe9e5247e21100037bff78"
+  revision = "7fd901a49ba6a7f87732eb344f6e3c5b19d1b200"
 
 [[projects]]
   name = "google.golang.org/grpc"
@@ -383,6 +384,6 @@
 [solve-meta]
   analyzer-name = "dep"
   analyzer-version = 1
-  inputs-digest = "e70f8692c825e80ae8510546e297840b9560d00e11b2272749a55cc2ffd147f0"
+  inputs-digest = "94cb2543199b0f4b6e9ac0e5b6469bdb77391da1c9f79f5b9792d7af936008ff"
   solver-name = "gps-cdcl"
   solver-version = 1

Gopkg.toml

@@ -79,7 +79,7 @@
 
 [[constraint]]
   name = "github.com/tendermint/go-amino"
-  version = "~0.9.6"
+  version = "~0.9.7"
 
 [[constraint]]
   name = "github.com/tendermint/tmlibs"

consensus/replay_file.go

@@ -29,6 +29,7 @@ const (
 //--------------------------------------------------------
 // replay messages interactively or all at once
 
+// replay the wal file
 func RunReplayFile(config cfg.BaseConfig, csConfig *cfg.ConsensusConfig, console bool) {
 	consensusState := newConsensusStateForReplay(config, csConfig)
 
@@ -262,7 +263,7 @@ func (pb *playback) replayConsoleLoop() int {
 				case "locked_block":
 					fmt.Printf("%v %v\n", rs.LockedBlockParts.StringShort(), rs.LockedBlock.StringShort())
 				case "votes":
-					fmt.Println(rs.Votes.StringIndented("    "))
+					fmt.Println(rs.Votes.StringIndented("  "))
 
 				default:
 					fmt.Println("Unknown option", tokens[1])

consensus/types/state.go

@@ -13,6 +13,7 @@ import (
 // RoundStepType enumerates the state of the consensus state machine
 type RoundStepType uint8 // These must be numeric, ordered.
 
+// RoundStepType
 const (
 	RoundStepNewHeight     = RoundStepType(0x01) // Wait til CommitTime + timeoutCommit
 	RoundStepNewRound      = RoundStepType(0x02) // Setup new round and go to RoundStepPropose
@@ -80,12 +81,12 @@ type RoundState struct {
 func (rs *RoundState) RoundStateEvent() types.EventDataRoundState {
 	// XXX: copy the RoundState
 	// if we want to avoid this, we may need synchronous events after all
-	rs_ := *rs
+	rsCopy := *rs
 	edrs := types.EventDataRoundState{
 		Height:     rs.Height,
 		Round:      rs.Round,
 		Step:       rs.Step.String(),
-		RoundState: &rs_,
+		RoundState: &rsCopy,
 	}
 	return edrs
 }
@@ -115,16 +116,16 @@ func (rs *RoundState) StringIndented(indent string) string {
 		indent, rs.Height, rs.Round, rs.Step,
 		indent, rs.StartTime,
 		indent, rs.CommitTime,
-		indent, rs.Validators.StringIndented(indent+"    "),
+		indent, rs.Validators.StringIndented(indent+"  "),
 		indent, rs.Proposal,
 		indent, rs.ProposalBlockParts.StringShort(), rs.ProposalBlock.StringShort(),
 		indent, rs.LockedRound,
 		indent, rs.LockedBlockParts.StringShort(), rs.LockedBlock.StringShort(),
 		indent, rs.ValidRound,
 		indent, rs.ValidBlockParts.StringShort(), rs.ValidBlock.StringShort(),
-		indent, rs.Votes.StringIndented(indent+"    "),
+		indent, rs.Votes.StringIndented(indent+"  "),
 		indent, rs.LastCommit.StringShort(),
-		indent, rs.LastValidators.StringIndented(indent+"    "),
+		indent, rs.LastValidators.StringIndented(indent+"  "),
 		indent)
 }
 

docs/specification/new-spec/encoding.md

@@ -277,9 +277,36 @@ func computeHashFromAunts(index, total int, leafHash []byte, innerHashes [][]byt
 }
 ```
 
-## AminoJSON
+## JSON
 
-Signed messages (eg. votes, proposals) in the consensus are encoded in AminoJSON, rather than binary Amino.
+### Amino
+
+TODO: improve this
+
+Amino also supports JSON encoding - registered types are simply encoded as:
+
+```
+{
+  "type": "<DisfixBytes>",
+  "value": <JSON>
+}
+
+For instance, an ED25519 PubKey would look like:
+
+```
+{
+  "type": "AC26791624DE60",
+  "value": "uZ4h63OFWuQ36ZZ4Bd6NF+/w9fWUwrOncrQsackrsTk="
+}
+```
+
+Where the `"value"` is the base64 encoding of the raw pubkey bytes, and the
+`"type"` is the full disfix bytes for Ed25519 pubkeys.
+
+
+### Signed Messages
+
+Signed messages (eg. votes, proposals) in the consensus are encoded using Amino-JSON, rather than in the standard binary format.
 
 When signing, the elements of a message are sorted by key and the sorted message is embedded in an
 outer JSON that includes a `chain_id` field.
@@ -291,6 +318,3 @@ like:
 ```
 
 Note how the fields within each level are sorted.
-
-
-

types/genesis.go

@@ -41,7 +41,7 @@ func (genDoc *GenesisDoc) AppState() json.RawMessage {
 
 // SaveAs is a utility method for saving GenensisDoc as a JSON file.
 func (genDoc *GenesisDoc) SaveAs(file string) error {
-	genDocBytes, err := cdc.MarshalJSON(genDoc)
+	genDocBytes, err := cdc.MarshalJSONIndent(genDoc, "", "  ")
 	if err != nil {
 		return err
 	}

types/priv_validator/priv_validator.go

@@ -120,7 +120,7 @@ func (pv *FilePV) save() {
 	if outFile == "" {
 		panic("Cannot save PrivValidator: filePath not set")
 	}
-	jsonBytes, err := cdc.MarshalJSON(pv)
+	jsonBytes, err := cdc.MarshalJSONIndent(pv, "", "  ")
 	if err != nil {
 		panic(err)
 	}

types/validator_set.go

@@ -69,6 +69,7 @@ func (valSet *ValidatorSet) IncrementAccum(times int) {
 	}
 }
 
+// Copy each validator into a new ValidatorSet
 func (valSet *ValidatorSet) Copy() *ValidatorSet {
 	validators := make([]*Validator, len(valSet.Validators))
 	for i, val := range valSet.Validators {
@@ -368,6 +369,7 @@ func (valSet *ValidatorSet) String() string {
 	return valSet.StringIndented("")
 }
 
+// String
 func (valSet *ValidatorSet) StringIndented(indent string) string {
 	if valSet == nil {
 		return "nil-ValidatorSet"
@@ -384,7 +386,7 @@ func (valSet *ValidatorSet) StringIndented(indent string) string {
 %s}`,
 		indent, valSet.GetProposer().String(),
 		indent,
-		indent, strings.Join(valStrings, "\n"+indent+"    "),
+		indent, strings.Join(valStrings, "\n"+indent+"  "),
 		indent)
 
 }
@@ -392,6 +394,7 @@ func (valSet *ValidatorSet) StringIndented(indent string) string {
 //-------------------------------------
 // Implements sort for sorting validators by address.
 
+// Sort validators by address
 type ValidatorsByAddress []*Validator
 
 func (vs ValidatorsByAddress) Len() int {