From 3e61b8c17a4c3f6b89c7b430768bdcac41b4a846 Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Mon, 23 Oct 2017 18:47:13 -0400 Subject: [PATCH] docs: comb through step by step --- cmd/tendermint/commands/root_test.go | 4 +--- docs/abci-cli.rst | 17 ++++++++++++++--- docs/deploy-testnets.rst | 2 +- docs/getting-started.rst | 11 ++++++----- docs/install.rst | 2 +- docs/introduction.rst | 22 +++++++++++----------- docs/specification/genesis.rst | 2 +- docs/using-tendermint.rst | 16 +++++++--------- 8 files changed, 42 insertions(+), 34 deletions(-) diff --git a/cmd/tendermint/commands/root_test.go b/cmd/tendermint/commands/root_test.go index b89e7a19..7c3bf801 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/abci-cli.rst b/docs/abci-cli.rst index 071f671a..dcdcc20d 100644 --- a/docs/abci-cli.rst +++ b/docs/abci-cli.rst @@ -80,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: @@ -96,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 diff --git a/docs/deploy-testnets.rst b/docs/deploy-testnets.rst index e1aa7074..89fa4b79 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/getting-started.rst b/docs/getting-started.rst index fefd93ff..3235af8d 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -148,7 +148,7 @@ The result should look like: 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. +tuned for a future release that `makes this output more human-readable /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: @@ -315,9 +316,9 @@ 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. 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/install.rst b/docs/install.rst index 1d01b505..36865594 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 2187eb57..a7ec7a26 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/using-tendermint.rst b/docs/using-tendermint.rst index 2852b7c7..9076230e 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. @@ -388,7 +386,7 @@ Additionally, you must set ``addrbook_strict=false`` in the 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