Merge pull request #773 from tendermint/docs-staging

docs improvements

cmd/tendermint/commands/root_test.go

@@ -28,8 +28,6 @@ const (
 func isolate(cmds ...*cobra.Command) cli.Executable {
 	os.Unsetenv("TMHOME")
 	os.Unsetenv("TM_HOME")
-	os.Unsetenv("TMROOT")
-	os.Unsetenv("TM_ROOT")
 
 	viper.Reset()
 	config = cfg.DefaultConfig()
@@ -70,7 +68,7 @@ func TestRootConfig(t *testing.T) {
 		{nil, nil, defaultRoot, defaults.Moniker, defaults.FastSync, dmax},
 		// try multiple ways of setting root (two flags, cli vs. env)
 		{[]string{"--home", conf}, nil, conf, cvals["moniker"], cfast, dmax},
-		{nil, map[string]string{"TMROOT": conf}, conf, cvals["moniker"], cfast, dmax},
+		{nil, map[string]string{"TMHOME": conf}, conf, cvals["moniker"], cfast, dmax},
 		// check setting p2p subflags two different ways
 		{[]string{"--p2p.max_num_peers", "420"}, nil, defaultRoot, defaults.Moniker, defaults.FastSync, 420},
 		{nil, map[string]string{"TM_P2P_MAX_NUM_PEERS": "17"}, defaultRoot, defaults.Moniker, defaults.FastSync, 17},

docs/_static/custom_collapsible_code.css

@@ -0,0 +1,17 @@
+.toggle {
+    padding-bottom: 1em ;
+}
+
+.toggle .header {
+    display: block;
+    clear: both;
+    cursor: pointer;
+}
+
+.toggle .header:after {
+    content: " ▼";
+}
+
+.toggle .header.open:after {
+    content: " ▲";
+}

docs/_static/custom_collapsible_code.js

@@ -0,0 +1,10 @@
+let makeCodeBlocksCollapsible = function() {
+    $(".toggle > *").hide();
+    $(".toggle .header").show();
+    $(".toggle .header").click(function() {
+        $(this).parent().children().not(".header").toggle({"duration": 400});
+        $(this).parent().children(".header").toggleClass("open");
+    });
+};
+// we could use the }(); way if we would have access to jQuery in HEAD, i.e. we would need to force the theme
+// to load jQuery before our custom scripts

docs/_templates/layout.html

@@ -0,0 +1,20 @@
+{% extends "!layout.html" %}
+
+{% set css_files = css_files + ["_static/custom_collapsible_code.css"] %}
+
+# sadly, I didn't find a css style way to add custom JS to a list that is automagically added to head like CSS (above) #}
+{% block extrahead %}
+<script type="text/javascript" src="_static/custom_collapsible_code.js"></script>
+{% endblock %}
+
+{% block footer %}
+<script type="text/javascript">
+    $(document).ready(function() {
+        // using this approach as we don't have access to the jQuery selectors
+        // when executing the function on load in HEAD
+        makeCodeBlocksCollapsible();
+    });
+</script>
+{% endblock %}
+
+

docs/abci-cli.rst

@@ -14,7 +14,7 @@ Next, install the ``abci-cli`` tool and example applications:
 
 ::
 
-    go get -u github.com/tendermint/abci/cmd/...
+    go get -u github.com/tendermint/abci/cmd/abci-cli
 
 If this fails, you may need to use ``glide`` to get vendored
 dependencies:
@@ -24,27 +24,37 @@ dependencies:
     go get github.com/Masterminds/glide
     cd $GOPATH/src/github.com/tendermint/abci
     glide install
-    go install ./cmd/...
+    go install ./cmd/abci-cli
 
-Now run ``abci-cli --help`` to see the list of commands:
+Now run ``abci-cli`` to see the list of commands:
 
 ::
 
-    COMMANDS:
-       batch        Run a batch of ABCI commands against an application
-       console      Start an interactive console for multiple commands
-       echo         Have the application echo a message
-       info         Get some info about the application
-       set_option   Set an option on the application
-       deliver_tx    Append a new tx to application
-       check_tx     Validate a tx
-       commit       Get application Merkle root hash
-       help, h      Shows a list of commands or help for one command
-
-    GLOBAL OPTIONS:
-       --address "tcp://127.0.0.1:46658"    address of application socket
-       --help, -h                           show help
-       --version, -v                        print the version
+    Usage:
+      abci-cli [command]
+
+    Available Commands:
+      batch       Run a batch of abci commands against an application
+      check_tx    Validate a tx
+      commit      Commit the application state and return the Merkle root hash
+      console     Start an interactive abci console for multiple commands
+      counter     ABCI demo example
+      deliver_tx  Deliver a new tx to the application
+      dummy       ABCI demo example
+      echo        Have the application echo a message
+      help        Help about any command
+      info        Get some info about the application
+      query       Query the application state
+      set_option  Set an options on the application
+
+    Flags:
+          --abci string      socket or grpc (default "socket")
+          --address string   address of application socket (default "tcp://127.0.0.1:46658")
+      -h, --help             help for abci-cli
+      -v, --verbose          print the command and results as if it were a console session
+
+                                          Use "abci-cli [command] --help" for more information about a command.
+
 
 Dummy - First Example
 ---------------------
@@ -61,7 +71,7 @@ Let's start a dummy application, which was installed at the same time as
 
 ::
 
-    dummy
+    abci-cli dummy
 
 In another terminal, run
 
@@ -70,8 +80,19 @@ In another terminal, run
     abci-cli echo hello
     abci-cli info
 
-The application should echo ``hello`` and give you some information
-about itself.
+You'll see something like:
+
+::
+
+    -> data: hello
+    -> data.hex: 68656C6C6F
+
+and:
+
+::
+
+    -> data: {"size":0}
+    -> data.hex: 7B2273697A65223A307D
 
 An ABCI application must provide two things:
 
@@ -86,7 +107,7 @@ The server may be generic for a particular language, and we provide a
 `reference implementation in
 Golang <https://github.com/tendermint/abci/tree/master/server>`__. See
 the `list of other ABCI
-implementations <https://tendermint.com/ecosystem>`__ for servers in
+implementations <./ecosystem.html>`__ for servers in
 other languages.
 
 The handler is specific to the application, and may be arbitrary, so
@@ -109,36 +130,50 @@ Try running these commands:
 ::
 
     > echo hello
+    -> code: OK
     -> data: hello
-
+    -> data.hex: 0x68656C6C6F
+    
     > info
+    -> code: OK
     -> data: {"size":0}
-
+    -> data.hex: 0x7B2273697A65223A307D
+    
     > commit
-    -> data: 0x
-
+    -> code: OK
+    
     > deliver_tx "abc"
     -> code: OK
-
+    
     > info
+    -> code: OK
     -> data: {"size":1}
-
+    -> data.hex: 0x7B2273697A65223A317D
+    
     > commit
-    -> data: 0x750502FC7E84BBD788ED589624F06CFA871845D1
-
+    -> code: OK
+    -> data.hex: 0x49DFD15CCDACDEAE9728CB01FBB5E8688CA58B91
+    
     > query "abc"
     -> code: OK
-    -> data: {"index":0,"value":"abc","exists":true}
-
+    -> log: exists
+    -> height: 0
+    -> value: abc
+    -> value.hex: 616263
+    
     > deliver_tx "def=xyz"
     -> code: OK
-
+    
     > commit
-    -> data: 0x76393B8A182E450286B0694C629ECB51B286EFD5
-
+    -> code: OK
+    -> data.hex: 0x70102DB32280373FBF3F9F89DA2A20CE2CD62B0B
+    
     > query "def"
     -> code: OK
-    -> data: {"index":1,"value":"xyz","exists":true}
+    -> log: exists
+    -> height: 0
+    -> value: xyz
+    -> value.hex: 78797A
 
 Note that if we do ``deliver_tx "abc"`` it will store ``(abc, abc)``,
 but if we do ``deliver_tx "abc=efg"`` it will store ``(abc, efg)``.
@@ -181,37 +216,39 @@ app:
 
 ::
 
-    counter
+    abci-cli counter
 
 In another window, start the ``abci-cli console``:
 
 ::
 
     > set_option serial on
-    -> data: serial=on
-
+    -> code: OK
+    
     > check_tx 0x00
     -> code: OK
-
+    
     > check_tx 0xff
     -> code: OK
-
+    
     > deliver_tx 0x00
     -> code: OK
-
+    
     > check_tx 0x00
     -> code: BadNonce
     -> log: Invalid nonce. Expected >= 1, got 0
-
+    
     > deliver_tx 0x01
     -> code: OK
-
+    
     > deliver_tx 0x04
     -> code: BadNonce
     -> log: Invalid nonce. Expected 2, got 4
-
+    
     > info
+    -> code: OK
     -> data: {"hashes":0,"txs":2}
+    -> data.hex: 0x7B22686173686573223A302C22747873223A327D
 
 This is a very simple application, but between ``counter`` and
 ``dummy``, its easy to see how you can build out arbitrary application

docs/app-development.rst

@@ -194,11 +194,37 @@ through all transactions in the mempool, removing any that were included
 in the block, and re-run the rest using CheckTx against the post-Commit
 mempool state.
 
-::
+.. container:: toggle
 
-    func (app *DummyApplication) CheckTx(tx []byte) types.Result {
-      return types.OK
-    }
+    .. container:: header
+
+        **Show/Hide Go Example**
+
+    .. code-block:: go
+
+        func (app *DummyApplication) CheckTx(tx []byte) types.Result {
+          return types.OK
+        }
+
+.. container:: toggle
+
+    .. container:: header
+
+        **Show/Hide Java Example**
+
+    .. code-block:: java
+
+        ResponseCheckTx requestCheckTx(RequestCheckTx req) {
+            byte[] transaction = req.getTx().toByteArray();
+
+            // validate transaction
+
+            if (notValid) {
+                return ResponseCheckTx.newBuilder().setCode(CodeType.BadNonce).setLog("invalid tx").build();
+            } else {
+                return ResponseCheckTx.newBuilder().setCode(CodeType.OK).build();
+            }
+        }
 
 Consensus Connection
 ~~~~~~~~~~~~~~~~~~~~
@@ -228,18 +254,48 @@ The block header will be updated (TODO) to include some commitment to
 the results of DeliverTx, be it a bitarray of non-OK transactions, or a
 merkle root of the data returned by the DeliverTx requests, or both.
 
-::
+.. container:: toggle
 
-    // tx is either "key=value" or just arbitrary bytes
-    func (app *DummyApplication) DeliverTx(tx []byte) types.Result {
-      parts := strings.Split(string(tx), "=")
-      if len(parts) == 2 {
-        app.state.Set([]byte(parts[0]), []byte(parts[1]))
-      } else {
-        app.state.Set(tx, tx)
-      }
-      return types.OK
-    }
+    .. container:: header
+
+        **Show/Hide Go Example**
+
+    .. code-block:: go
+
+        // tx is either "key=value" or just arbitrary bytes
+        func (app *DummyApplication) DeliverTx(tx []byte) types.Result {
+          parts := strings.Split(string(tx), "=")
+          if len(parts) == 2 {
+            app.state.Set([]byte(parts[0]), []byte(parts[1]))
+          } else {
+            app.state.Set(tx, tx)
+          }
+          return types.OK
+        }
+
+.. container:: toggle
+
+    .. container:: header
+
+        **Show/Hide Java Example**
+
+    .. code-block:: java
+
+        /**
+         * Using Protobuf types from the protoc compiler, we always start with a byte[]
+         */
+        ResponseDeliverTx deliverTx(RequestDeliverTx request) {
+            byte[] transaction  = request.getTx().toByteArray();
+
+            // validate your transaction
+
+            if (notValid) {
+                return ResponseDeliverTx.newBuilder().setCode(CodeType.BadNonce).setLog("transaction was invalid").build();
+            } else {
+                ResponseDeliverTx.newBuilder().setCode(CodeType.OK).build();
+            }
+
+        }
 
 Commit
 ^^^^^^
@@ -263,12 +319,35 @@ It is expected that the app will persist state to disk on Commit. The
 option to have all transactions replayed from some previous block is the
 job of the `Handshake <#handshake>`__.
 
-::
+.. container:: toggle
+
+    .. container:: header
+
+        **Show/Hide Go Example**
+
+    .. code-block:: go
+
+        func (app *DummyApplication) Commit() types.Result {
+          hash := app.state.Hash()
+          return types.NewResultOK(hash, "")
+        }
+
+.. container:: toggle
+
+    .. container:: header
+
+        **Show/Hide Java Example**
 
-    func (app *DummyApplication) Commit() types.Result {
-      hash := app.state.Hash()
-      return types.NewResultOK(hash, "")
-    }
+    .. code-block:: java
+
+        ResponseCommit requestCommit(RequestCommit requestCommit) {
+
+            // update the internal app-state
+            byte[] newAppState = calculateAppState();
+
+            // and return it to the node
+            return ResponseCommit.newBuilder().setCode(CodeType.OK).setData(ByteString.copyFrom(newAppState)).build();
+        }
 
 BeginBlock
 ^^^^^^^^^^
@@ -281,16 +360,45 @@ The app should remember the latest height and header (ie. from which it
 has run a successful Commit) so that it can tell Tendermint where to
 pick up from when it restarts. See information on the Handshake, below.
 
-::
+.. container:: toggle
+
+    .. container:: header
+
+        **Show/Hide Go Example**
+
+    .. code-block:: go
+
+        // Track the block hash and header information
+        func (app *PersistentDummyApplication) BeginBlock(params types.RequestBeginBlock) {
+          // update latest block info
+          app.blockHeader = params.Header
+
+          // reset valset changes
+          app.changes = make([]*types.Validator, 0)
+        }
+
+.. container:: toggle
+
+    .. container:: header
+
+        **Show/Hide Java Example**
+
+    .. code-block:: java
 
-    // Track the block hash and header information
-    func (app *PersistentDummyApplication) BeginBlock(params types.RequestBeginBlock) {
-      // update latest block info
-      app.blockHeader = params.Header
+        /*
+         * all types come from protobuf definition
+         */
+        ResponseBeginBlock requestBeginBlock(RequestBeginBlock req) {
 
-      // reset valset changes
-      app.changes = make([]*types.Validator, 0)
-    }
+            Header header = req.getHeader();
+            byte[] prevAppHash = header.getAppHash().toByteArray();
+            long prevHeight = header.getHeight();
+            long numTxs = header.getNumTxs();
+
+            // run your pre-block logic. Maybe prepare a state snapshot, message components, etc
+
+            return ResponseBeginBlock.newBuilder().build();
+        }
 
 EndBlock
 ^^^^^^^^
@@ -304,12 +412,39 @@ EndBlock response. To remove one, include it in the list with a
 validator set. Note validator set changes are only available in v0.8.0
 and up.
 
-::
+.. container:: toggle
+
+    .. container:: header
+
+        **Show/Hide Go Example**
+
+    .. code-block:: go
+
+        // Update the validator set
+        func (app *PersistentDummyApplication) EndBlock(height uint64) (resEndBlock types.ResponseEndBlock) {
+          return types.ResponseEndBlock{Diffs: app.changes}
+        }
+
+.. container:: toggle
+
+    .. container:: header
+
+        **Show/Hide Java Example**
+
+    .. code-block:: java
 
-    // Update the validator set
-    func (app *PersistentDummyApplication) EndBlock(height uint64) (resEndBlock types.ResponseEndBlock) {
-      return types.ResponseEndBlock{Diffs: app.changes}
-    }
+        /*
+         * Assume that one validator changes. The new validator has a power of 10
+         */
+        ResponseEndBlock requestEndBlock(RequestEndBlock req) {
+            final long currentHeight = req.getHeight();
+            final byte[] validatorPubKey = getValPubKey();
+
+            ResponseEndBlock.Builder builder = ResponseEndBlock.newBuilder();
+            builder.addDiffs(1, Types.Validator.newBuilder().setPower(10L).setPubKey(ByteString.copyFrom(validatorPubKey)).build());
+
+            return builder.build();
+        }
 
 Query Connection
 ~~~~~~~~~~~~~~~~
@@ -332,33 +467,72 @@ cause Tendermint to not connect to the corresponding peer:
 
 Note: these query formats are subject to change!
 
-::
-
-    func (app *DummyApplication) Query(reqQuery types.RequestQuery) (resQuery types.ResponseQuery) {
-      if reqQuery.Prove {
-        value, proof, exists := app.state.Proof(reqQuery.Data)
-        resQuery.Index = -1 // TODO make Proof return index
-        resQuery.Key = reqQuery.Data
-        resQuery.Value = value
-        resQuery.Proof = proof
-        if exists {
-          resQuery.Log = "exists"
-        } else {
-          resQuery.Log = "does not exist"
+.. container:: toggle
+
+    .. container:: header
+
+        **Show/Hide Go Example**
+
+    .. code-block:: go
+
+        func (app *DummyApplication) Query(reqQuery types.RequestQuery) (resQuery types.ResponseQuery) {
+          if reqQuery.Prove {
+            value, proof, exists := app.state.Proof(reqQuery.Data)
+            resQuery.Index = -1 // TODO make Proof return index
+            resQuery.Key = reqQuery.Data
+            resQuery.Value = value
+            resQuery.Proof = proof
+            if exists {
+              resQuery.Log = "exists"
+            } else {
+              resQuery.Log = "does not exist"
+            }
+            return
+          } else {
+            index, value, exists := app.state.Get(reqQuery.Data)
+            resQuery.Index = int64(index)
+            resQuery.Value = value
+            if exists {
+              resQuery.Log = "exists"
+            } else {
+              resQuery.Log = "does not exist"
+            }
+            return
+          }
         }
-        return
-      } else {
-        index, value, exists := app.state.Get(reqQuery.Data)
-        resQuery.Index = int64(index)
-        resQuery.Value = value
-        if exists {
-          resQuery.Log = "exists"
-        } else {
-          resQuery.Log = "does not exist"
+
+.. container:: toggle
+
+    .. container:: header
+
+        **Show/Hide Java Example**
+
+    .. code-block:: java
+
+        ResponseQuery requestQuery(RequestQuery req) {
+            final boolean isProveQuery = req.getProve();
+            final ResponseQuery.Builder responseBuilder = ResponseQuery.newBuilder();
+
+            if (isProveQuery) {
+                com.app.example.ProofResult proofResult = generateProof(req.getData().toByteArray());
+                final byte[] proofAsByteArray = proofResult.getAsByteArray();
+
+                responseBuilder.setProof(ByteString.copyFrom(proofAsByteArray));
+                responseBuilder.setKey(req.getData());
+                responseBuilder.setValue(ByteString.copyFrom(proofResult.getData()));
+                responseBuilder.setLog(result.getLogValue());
+            } else {
+                byte[] queryData = req.getData().toByteArray();
+
+                final com.app.example.QueryResult result = generateQueryResult(queryData);
+
+                responseBuilder.setIndex(result.getIndex());
+                responseBuilder.setValue(ByteString.copyFrom(result.getValue()));
+                responseBuilder.setLog(result.getLogValue());
+            }
+
+            return responseBuilder.build();
         }
-        return
-      }
-    }
 
 Handshake
 ~~~~~~~~~
@@ -377,11 +551,31 @@ the app are synced to the latest block height.
 If the app returns a LastBlockHeight of 0, Tendermint will just replay
 all blocks.
 
-::
+.. container:: toggle
+
+    .. container:: header
+
+        **Show/Hide Go Example**
+
+    .. code-block:: go
+
+        func (app *DummyApplication) Info(req types.RequestInfo) (resInfo types.ResponseInfo) {
+          return types.ResponseInfo{Data: cmn.Fmt("{\"size\":%v}", app.state.Size())}
+        }
+
+.. container:: toggle
+
+    .. container:: header
+
+        **Show/Hide Java Example**
 
-    func (app *DummyApplication) Info(req types.RequestInfo) (resInfo types.ResponseInfo) {
-      return types.ResponseInfo{Data: cmn.Fmt("{\"size\":%v}", app.state.Size())}
-    }
+    .. code-block:: java
+
+        ResponseInfo requestInfo(RequestInfo req) {
+            final byte[] lastAppHash = getLastAppHash();
+            final long lastHeight = getLastHeight();
+            return ResponseInfo.newBuilder().setLastBlockAppHash(ByteString.copyFrom(lastAppHash)).setLastBlockHeight(lastHeight).build();
+        }
 
 Genesis
 ~~~~~~~
@@ -390,14 +584,45 @@ Genesis
 initial validator set. Later on, it may be extended to take parts of the
 consensus params.
 
-::
+.. container:: toggle
+
+    .. container:: header
+
+        **Show/Hide Go Example**
+
+    .. code-block:: go
+
+        // Save the validators in the merkle tree
+        func (app *PersistentDummyApplication) InitChain(params types.RequestInitChain) {
+          for _, v := range params.Validators {
+            r := app.updateValidator(v)
+            if r.IsErr() {
+              app.logger.Error("Error updating validators", "r", r)
+            }
+          }
+        }
+
+.. container:: toggle
+
+    .. container:: header
+
+        **Show/Hide Java Example**
+
+    .. code-block:: java
+
+        /*
+         * all types come from protobuf definition
+         */
+        ResponseInitChain requestInitChain(RequestInitChain req) {
+            final int validatorsCount = req.getValidatorsCount();
+            final List<Types.Validator> validatorsList = req.getValidatorsList();
+
+            validatorsList.forEach((validator) -> {
+                long power = validator.getPower();
+                byte[] validatorPubKey = validator.getPubKey().toByteArray();
+
+                // do somehing for validator setup in app
+            });
 
-    // Save the validators in the merkle tree
-    func (app *PersistentDummyApplication) InitChain(params types.RequestInitChain) {
-      for _, v := range params.Validators {
-        r := app.updateValidator(v)
-        if r.IsErr() {
-          app.logger.Error("Error updating validators", "r", r)
+            return ResponseInitChain.newBuilder().build();
         }
-      }
-    }

docs/deploy-testnets.rst

@@ -13,7 +13,7 @@ It's relatively easy to setup a Tendermint cluster manually. The only
 requirements for a particular Tendermint node are a private key for the
 validator, stored as ``priv_validator.json``, and a list of the public
 keys of all validators, stored as ``genesis.json``. These files should
-be stored in ``~/.tendermint``, or wherever the ``$TMROOT`` variable
+be stored in ``~/.tendermint``, or wherever the ``$TMHOME`` variable
 might be set to.
 
 Here are the steps to setting up a testnet manually:

docs/ecosystem.rst

@@ -115,3 +115,8 @@ Deployment Tools
 See `deploy testnets <./deploy-testnets.html>`__ for information about all the tools built by Tendermint. We have Kubernetes, Ansible, and Terraform integrations.
 
 Cloudsoft built `brooklyn-tendermint <https://github.com/cloudsoft/brooklyn-tendermint>`__ for deploying a tendermint testnet in docker continers. It uses Clocker for Apache Brooklyn.
+
+Dev Tools
+---------
+
+For upgrading from older to newer versions of tendermint and to migrate your chain data, see `tm-migrator <https://github.com/hxzqlh/tm-tools>`__ written by @hxzqlh.

docs/getting-started.rst

@@ -25,7 +25,7 @@ Then run
 
 ::
 
-    go get -u github.com/tendermint/abci/cmd/...
+    go get -u github.com/tendermint/abci/cmd/abci-cli
 
 If there is an error, install and run the ``glide`` tool to pin the
 dependencies:
@@ -35,20 +35,12 @@ dependencies:
     go get github.com/Masterminds/glide
     cd $GOPATH/src/github.com/tendermint/abci
     glide install
-    go install ./cmd/...
+    go install ./cmd/abci-cli
 
-Now you should have the ``abci-cli`` plus two apps installed:
-
-::
-
-    dummy --help
-    counter --help
-
-These binaries are installed on ``$GOPATH/bin`` and all come from within
-the ``./cmd/...`` directory of the abci repository.
-
-Both of these example applications are in Go. See below for an
-application written in Javascript.
+Now you should have the ``abci-cli`` installed; you'll see
+a couple of commands (``counter`` and ``dummy``) that are
+example applications written in Go. See below for an application
+written in Javascript.
 
 Now, let's run some apps!
 
@@ -66,7 +58,7 @@ Let's start a dummy application.
 
 ::
 
-    dummy
+    abci-cli dummy
 
 In another terminal, we can start Tendermint. If you have never run
 Tendermint before, use:
@@ -126,10 +118,6 @@ like:
       }
     }
 
-The ``98`` is a type-byte, and can be ignored (it's useful for
-serializing and deserializing arbitrary json). Otherwise, this result is
-empty - there's nothing to report on and everything is OK.
-
 We can confirm that our transaction worked and the value got stored by
 querying the app:
 
@@ -157,11 +145,10 @@ The result should look like:
       }
     }
 
-Again, the ``112`` is the type-byte. Note the ``value`` in the result
-(``61626364``); this is the hex-encoding of the ASCII of ``abcd``. You
-can verify this in a python shell by running
-``"61626364".decode('hex')``. Stay tuned for a future release that makes
-this output more human-readable ;).
+Note the ``value`` in the result (``61626364``); this is the
+hex-encoding of the ASCII of ``abcd``. You can verify this in
+a python shell by running ``"61626364".decode('hex')``. Stay
+tuned for a future release that `makes this output more human-readable <https://github.com/tendermint/abci/issues/32>`__.
 
 Now let's try setting a different key and value:
 
@@ -183,7 +170,7 @@ Counter - Another Example
 -------------------------
 
 Now that we've got the hang of it, let's try another application, the
-"counter" app.
+**counter** app.
 
 The counter app doesn't use a Merkle tree, it just counts how many times
 we've sent a transaction, or committed the state.
@@ -211,7 +198,7 @@ a flag:
 
 ::
 
-    counter --serial
+    abci-cli counter --serial
 
 In another window, reset then start Tendermint:
 
@@ -295,6 +282,7 @@ keep all our code under the ``$GOPATH``, so run:
     go get github.com/tendermint/js-abci &> /dev/null
     cd $GOPATH/src/github.com/tendermint/js-abci/example
     npm install
+    cd ..
 
 Kill the previous ``counter`` and ``tendermint`` processes. Now run the
 app:
@@ -325,12 +313,12 @@ Neat, eh?
 Basecoin - A More Interesting Example
 -------------------------------------
 
-We saved the best for last; the `Cosmos SDK <https://github.com/cosmos/cosmos-sdk>`__ is a general purpose framework for building cryptocurrencies. Unlike the``dummy`` and ``counter``, which are strictly for example purposes. The reference implementation of Cosmos SDK is ``basecoin``, which demonstrates how to use the building blocks of the Cosmos SDK.
+We saved the best for last; the `Cosmos SDK <https://github.com/cosmos/cosmos-sdk>`__ is a general purpose framework for building cryptocurrencies. Unlike the ``dummy`` and ``counter``, which are strictly for example purposes. The reference implementation of Cosmos SDK is ``basecoin``, which demonstrates how to use the building blocks of the Cosmos SDK.
 
 The default ``basecoin`` application is a multi-asset cryptocurrency
-that supports inter-blockchain communication. For more details on how
+that supports inter-blockchain communication (IBC). For more details on how
 basecoin works and how to use it, see our `basecoin
-guide <https://github.com/cosmos/cosmos-sdk/blob/develop/docs/guide/basecoin-basics.md>`__
+guide <http://cosmos-sdk.readthedocs.io/en/latest/basecoin-basics.html>`__
 
 In this tutorial you learned how to run applications using Tendermint
 on a single node. You saw how applications could be written in different

docs/index.rst

@@ -8,8 +8,8 @@ Welcome to Tendermint!
 
 
 .. image:: assets/tmint-logo-blue.png
-   :height: 500px
-   :width: 500px
+   :height: 200px
+   :width: 200px
    :align: center
 
 Tendermint 101

docs/install.rst

@@ -9,7 +9,7 @@ To download pre-built binaries, see the `Download page <https://tendermint.com/d
 From Source
 -----------
 
-You'll need `go`, maybe `glide` and the tendermint source code.
+You'll need ``go``, maybe ``glide``, and the tendermint source code.
 
 Install Go
 ^^^^^^^^^^

docs/introduction.rst

@@ -146,11 +146,11 @@ The ABCI consists of 3 primary message types that get delivered from the core to
 
 The messages are specified here: `ABCI Message Types <https://github.com/tendermint/abci#message-types>`__.
 
-The `DeliverTx` message is the work horse of the application.  Each transaction in the blockchain is delivered with this message. The application needs to validate each transaction received with the `DeliverTx` message against the current state, application protocol, and the cryptographic credentials of the transaction. A validated transaction then needs to update the application state — by binding a value into a key values store, or by updating the UTXO database, for instance.
+The **DeliverTx** message is the work horse of the application. Each transaction in the blockchain is delivered with this message. The application needs to validate each transaction received with the **DeliverTx** message against the current state, application protocol, and the cryptographic credentials of the transaction. A validated transaction then needs to update the application state — by binding a value into a key values store, or by updating the UTXO database, for instance.
 
-The `CheckTx` message is similar to `DeliverTx`, but it's only for validating transactions.  Tendermint Core's mempool first checks the validity of a transaction with `CheckTx`, and only relays valid transactions to its peers.  For instance, an application may check an incrementing sequence number in the transaction and return an error upon `CheckTx` if the sequence number is old. Alternatively, they might use a capabilities based system that requires capabilities to be renewed with every transaction.
+The **CheckTx** message is similar to **DeliverTx**, but it's only for validating transactions. Tendermint Core's mempool first checks the validity of a transaction with **CheckTx**, and only relays valid transactions to its peers. For instance, an application may check an incrementing sequence number in the transaction and return an error upon **CheckTx** if the sequence number is old. Alternatively, they might use a capabilities based system that requires capabilities to be renewed with every transaction.
 
-The `Commit` message is used to compute a cryptographic commitment to the current application state, to be placed into the next block header. This has some handy properties. Inconsistencies in updating that state will now appear as blockchain forks which catches a whole class of programming errors. This also simplifies the development of secure lightweight clients, as Merkle-hash proofs can be verified by checking against the block hash, and that the block hash is signed by a quorum.
+The **Commit** message is used to compute a cryptographic commitment to the current application state, to be placed into the next block header. This has some handy properties. Inconsistencies in updating that state will now appear as blockchain forks which catches a whole class of programming errors. This also simplifies the development of secure lightweight clients, as Merkle-hash proofs can be verified by checking against the block hash, and that the block hash is signed by a quorum.
 
 There can be multiple ABCI socket connections to an application. Tendermint Core creates three ABCI connections to the application; one for the validation of transactions when broadcasting in the mempool, one for the consensus engine to run block proposals, and one more for querying the application state.
 
@@ -169,7 +169,7 @@ Solidity on Ethereum is a great language of choice for blockchain applications b
  * race conditions on threads (or avoiding threads altogether)
  * the system clock
  * uninitialized memory (in unsafe programming languages like C or C++)
- * `floating point arithmetic <http://gafferongames.com/networking-for-game-programmers/floating-point-determinism/>`__.
+ * `floating point arithmetic <http://gafferongames.com/networking-for-game-programmers/floating-point-determinism/>`__
  * language features that are random (e.g. map iteration in Go)
 
 While programmers can avoid non-determinism by being careful, it is also possible to create a special linter or static analyzer for each language to check for determinism.  In the future we may work with partners to create such tools.
@@ -182,17 +182,17 @@ The protocol follows a simple state machine that looks like this:
 
 .. figure:: assets/consensus_logic.png
 
-Participants in the protocol are called "validators";
+Participants in the protocol are called **validators**;
 they take turns proposing blocks of transactions and voting on them.
-Blocks are committed in a chain, with one block at each "height".
-A block may fail to be committed, in which case the protocol moves to the next "round",
+Blocks are committed in a chain, with one block at each **height**.
+A block may fail to be committed, in which case the protocol moves to the next **round**,
 and a new validator gets to propose a block for that height.
 Two stages of voting are required to successfully commit a block;
-we call them "pre-vote" and "pre-commit".
+we call them **pre-vote** and **pre-commit**.
 A block is committed when more than 2/3 of validators pre-commit for the same block in the same round.
 
 There is a picture of a couple doing the polka because validators are doing something like a polka dance.
-When more than two-thirds of the validators pre-vote for the same block, we call that a "polka".
+When more than two-thirds of the validators pre-vote for the same block, we call that a **polka**.
 Every pre-commit must be justified by a polka in the same round.
 
 Validators may fail to commit a block for a number of reasons; 
@@ -204,8 +204,8 @@ However, the rest of the protocol is asynchronous, and validators only make prog
 A simplifying element of Tendermint is that it uses the same mechanism to commit a block as it does to skip to the next round.
 
 Assuming less than one-third of the validators are Byzantine, Tendermint guarantees that safety will never be violated - that is, validators will never commit conflicting blocks at the same height.
-To do this it introduces a few "locking" rules which modulate which paths can be followed in the flow diagram.
-Once a validator precommits a block, it is "locked" on that block. 
+To do this it introduces a few **locking** rules which modulate which paths can be followed in the flow diagram.
+Once a validator precommits a block, it is locked on that block.
 Then, 
 
 1) it must prevote for the block it is locked on

docs/specification/genesis.rst

@@ -1,7 +1,7 @@
 Genesis
 =======
 
-The genesis.json file in ``$TMROOT`` defines the initial TendermintCore
+The genesis.json file in ``$TMHOME`` defines the initial TendermintCore
 state upon genesis of the blockchain (`see
 definition <https://github.com/tendermint/tendermint/blob/master/types/genesis.go>`__).
 

docs/specification/validators.rst

@@ -4,7 +4,7 @@ Validators
 Validators are responsible for committing new blocks in the blockchain.
 These validators participate in the consensus protocol by broadcasting
 *votes* which contain cryptographic signatures signed by each
-validator's public key.
+validator's private key.
 
 Some Proof-of-Stake consensus algorithms aim to create a "completely"
 decentralized system where all stakeholders (even those who are not

docs/using-tendermint.rst

@@ -12,7 +12,7 @@ Directory Root
 --------------
 
 The default directory for blockchain data is ``~/.tendermint``. Override
-this by setting the ``TMROOT`` environment variable.
+this by setting the ``TMHOME`` environment variable.
 
 Initialize
 ----------
@@ -39,7 +39,7 @@ To run a tendermint node, use
 
     tendermint node
 
-By default, Tendermint will try to connect to a abci appliction on
+By default, Tendermint will try to connect to an ABCI application on
 `127.0.0.1:46658 <127.0.0.1:46658>`__. If you have the ``dummy`` ABCI
 app installed, run it in another window. If you don't, kill tendermint
 and run an in-process version with
@@ -49,9 +49,7 @@ and run an in-process version with
     tendermint node --proxy_app=dummy
 
 After a few seconds you should see blocks start streaming in. Note that
-blocks are produced regularly, even if there are no transactions. This
-changes `with this pull
-request <https://github.com/tendermint/tendermint/pull/584>`__.
+blocks are produced regularly, even if there are no transactions. See *No Empty Blocks*, below, to modify this setting.
 
 Tendermint supports in-process versions of the dummy, counter, and nil
 apps that ship as examples in the `ABCI
@@ -59,7 +57,7 @@ repository <https://github.com/tendermint/abci>`__. It's easy to compile
 your own app in-process with tendermint if it's written in Go. If your
 app is not written in Go, simply run it in another process, and use the
 ``--proxy_app`` flag to specify the address of the socket it is
-listening on, for instance
+listening on, for instance:
 
 ::
 
@@ -117,7 +115,7 @@ Configuration
 -------------
 
 Tendermint uses a ``config.toml`` for configuration. For details, see
-`the documentation <./specification/configuration.html>`__.
+`the config specification <./specification/configuration.html>`__.
 
 Notable options include the socket address of the application
 (``proxy_app``), the listenting address of the tendermint peer
@@ -283,7 +281,7 @@ specify peers for a running node to connect to:
 
 Additionally, the peer-exchange protocol can be enabled using the
 ``--pex`` flag, though this feature is `still under
-development <https://github.com/tendermint/tendermint/issues/598>`__ If
+development <https://github.com/tendermint/tendermint/issues/598>`__. If
 ``--pex`` is enabled, peers will gossip about known peers and form a
 more resilient network.
 
@@ -386,3 +384,11 @@ the listening addresses of the various sockets don't conflict.
 Additionally, you must set ``addrbook_strict=false`` in the
 ``config.toml``, otherwise Tendermint's p2p library will deny making
 connections to peers with the same IP address.
+
+Upgrading
+~~~~~~~~~
+
+The tendermint development cycle includes a lot of breaking changes. Upgrading from
+an old version to a new version usually means throwing away the chain data. Try out
+the `tm-migrate <https://github.com/hxzqlh/tm-tools>`__ tool written by @hxqlh if
+you are keen to preserve the state of your chain when upgrading to newer versions.

types/block.go

@@ -169,7 +169,7 @@ type Header struct {
 }
 
 // Hash returns the hash of the header.
-// NOTE: hash is nil if required fields are missing.
+// Returns nil if ValidatorHash is missing.
 func (h *Header) Hash() data.Bytes {
 	if len(h.ValidatorsHash) == 0 {
 		return nil