General Merkle Follow Up (#2510)

* tmlibs -> libs

* update changelog

* address some comments from review of #2298

crypto/merkle/proof.go

@@ -3,17 +3,19 @@ package merkle
 import (
 	"bytes"
 
-	cmn "github.com/tendermint/tmlibs/common"
+	cmn "github.com/tendermint/tendermint/libs/common"
 )
 
 //----------------------------------------
 // ProofOp gets converted to an instance of ProofOperator:
 
-// ProofOperator is a layer for calculating intermediate Merkle root
-// Run() takes a list of bytes because it can be more than one
-// for example in range proofs
-// ProofOp() defines custom encoding which can be decoded later with
-// OpDecoder
+// ProofOperator is a layer for calculating intermediate Merkle roots
+// when a series of Merkle trees are chained together.
+// Run() takes leaf values from a tree and returns the Merkle
+// root for the corresponding tree. It takes and returns a list of bytes
+// to allow multiple leaves to be part of a single proof, for instance in a range proof.
+// ProofOp() encodes the ProofOperator in a generic way so it can later be
+// decoded with OpDecoder.
 type ProofOperator interface {
 	Run([][]byte) ([][]byte, error)
 	GetKey() []byte
@@ -23,8 +25,8 @@ type ProofOperator interface {
 //----------------------------------------
 // Operations on a list of ProofOperators
 
-// ProofOperators is a slice of ProofOperator(s)
-// Each operator will be applied to the input value sequencially
+// ProofOperators is a slice of ProofOperator(s).
+// Each operator will be applied to the input value sequentially
 // and the last Merkle root will be verified with already known data
 type ProofOperators []ProofOperator
 
@@ -91,8 +93,8 @@ func (prt *ProofRuntime) Decode(pop ProofOp) (ProofOperator, error) {
 	return decoder(pop)
 }
 
-func (prt *ProofRuntime) DecodeProof(proof *Proof) (poz ProofOperators, err error) {
-	poz = ProofOperators(nil)
+func (prt *ProofRuntime) DecodeProof(proof *Proof) (ProofOperators, error) {
+	var poz ProofOperators
 	for _, pop := range proof.Ops {
 		operator, err := prt.Decode(pop)
 		if err != nil {
@@ -100,7 +102,7 @@ func (prt *ProofRuntime) DecodeProof(proof *Proof) (poz ProofOperators, err erro
 		}
 		poz = append(poz, operator)
 	}
-	return
+	return poz, nil
 }
 
 func (prt *ProofRuntime) VerifyValue(proof *Proof, root []byte, keypath string, value []byte) (err error) {

crypto/merkle/proof_key_path.go

@@ -35,6 +35,8 @@ import (
 	kp.AppendKey([]byte{0x01, 0x02, 0x03}, KeyEncodingURL)
 	kp.String() // Should return "/App/IBC/x:010203"
 
+	NOTE: Key paths must begin with a `/`.
+
 	NOTE: All encodings *MUST* work compatibly, such that you can choose to use
 	whatever encoding, and the decoded keys will always be the same.  In other
 	words, it's just as good to encode all three keys using URL encoding or HEX
@@ -52,7 +54,7 @@ type keyEncoding int
 const (
 	KeyEncodingURL keyEncoding = iota
 	KeyEncodingHex
-	KeyEncodingMax
+	KeyEncodingMax // Number of known encodings. Used for testing
 )
 
 type Key struct {
@@ -81,6 +83,8 @@ func (pth KeyPath) String() string {
 	return res
 }
 
+// Decode a path to a list of keys. Path must begin with `/`.
+// Each key must use a known encoding.
 func KeyPathToKeys(path string) (keys [][]byte, err error) {
 	if path == "" || path[0] != '/' {
 		return nil, cmn.NewError("key path string must start with a forward slash '/'")

crypto/merkle/proof_simple_value.go

@@ -25,7 +25,7 @@ type SimpleValueOp struct {
 	key []byte
 
 	// To encode in ProofOp.Data
-	Proof *SimpleProof `json:"simple-proof"`
+	Proof *SimpleProof `json:"simple_proof"`
 }
 
 var _ ProofOperator = SimpleValueOp{}