diff --git a/cmd/tendermint/commands/root_test.go b/cmd/tendermint/commands/root_test.go index b89e7a199..7c3bf801b 100644 --- a/cmd/tendermint/commands/root_test.go +++ b/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}, diff --git a/docs/_static/custom_collapsible_code.css b/docs/_static/custom_collapsible_code.css new file mode 100644 index 000000000..695268a83 --- /dev/null +++ b/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: " ▲"; +} \ No newline at end of file diff --git a/docs/_static/custom_collapsible_code.js b/docs/_static/custom_collapsible_code.js new file mode 100644 index 000000000..f4ff22adc --- /dev/null +++ b/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 diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 000000000..736460bc0 --- /dev/null +++ b/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 %} + +{% endblock %} + +{% block footer %} + +{% endblock %} + + diff --git a/docs/abci-cli.rst b/docs/abci-cli.rst index 5ca672c8a..9a5ba833c 100644 --- a/docs/abci-cli.rst +++ b/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 `__. See the `list of other ABCI -implementations `__ 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 diff --git a/docs/app-development.rst b/docs/app-development.rst index 1d2db8fdc..2614a264c 100644 --- a/docs/app-development.rst +++ b/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 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(); } - } - } diff --git a/docs/deploy-testnets.rst b/docs/deploy-testnets.rst index e1aa7074d..89fa4b799 100644 --- a/docs/deploy-testnets.rst +++ b/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: diff --git a/docs/ecosystem.rst b/docs/ecosystem.rst index 2bc390c90..dc643c5bd 100644 --- a/docs/ecosystem.rst +++ b/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 `__ 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 `__ written by @hxzqlh. diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 4a7e4b1ba..a9a391b0e 100644 --- a/docs/getting-started.rst +++ b/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 `__. 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 `__ 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 `__ 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 `__ +guide `__ In this tutorial you learned how to run applications using Tendermint on a single node. You saw how applications could be written in different diff --git a/docs/index.rst b/docs/index.rst index 4c226516f..3ad3c4c59 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/install.rst b/docs/install.rst index 1d01b505a..36865594e 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -9,7 +9,7 @@ To download pre-built binaries, see the `Download page `__. -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 `__. + * `floating point arithmetic `__ * 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 diff --git a/docs/specification/genesis.rst b/docs/specification/genesis.rst index 2187eb572..a7ec7a268 100644 --- a/docs/specification/genesis.rst +++ b/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 `__). diff --git a/docs/specification/validators.rst b/docs/specification/validators.rst index 528ebab7e..fb6bbbaca 100644 --- a/docs/specification/validators.rst +++ b/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 diff --git a/docs/using-tendermint.rst b/docs/using-tendermint.rst index cc94245cd..9076230ea 100644 --- a/docs/using-tendermint.rst +++ b/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 `__. +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 `__. 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 `__ If +development `__. 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 `__ tool written by @hxqlh if +you are keen to preserve the state of your chain when upgrading to newer versions. diff --git a/types/block.go b/types/block.go index 2291de316..738e5a009 100644 --- a/types/block.go +++ b/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