Browse Source

Merge pull request #772 from tendermint/docs/flow

moar docs updates
pull/773/head
Zach 7 years ago
committed by GitHub
parent
commit
8ac430813d
9 changed files with 45 additions and 37 deletions
  1. +1
    -3
      cmd/tendermint/commands/root_test.go
  2. +14
    -3
      docs/abci-cli.rst
  3. +1
    -1
      docs/deploy-testnets.rst
  4. +6
    -5
      docs/getting-started.rst
  5. +2
    -2
      docs/index.rst
  6. +1
    -1
      docs/install.rst
  7. +11
    -11
      docs/introduction.rst
  8. +1
    -1
      docs/specification/genesis.rst
  9. +8
    -10
      docs/using-tendermint.rst

+ 1
- 3
cmd/tendermint/commands/root_test.go View File

@ -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},


+ 14
- 3
docs/abci-cli.rst View File

@ -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 <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


+ 1
- 1
docs/deploy-testnets.rst View File

@ -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:


+ 6
- 5
docs/getting-started.rst View File

@ -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 <https://github.com/tendermint/abci/issues/32`__.
Now let's try setting a different key and value:
@ -170,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.
@ -198,7 +198,7 @@ a flag:
::
counter --serial
abci-cli counter --serial
In another window, reset then start Tendermint:
@ -282,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:
@ -315,9 +316,9 @@ 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.
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


+ 2
- 2
docs/index.rst View File

@ -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


+ 1
- 1
docs/install.rst View File

@ -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
^^^^^^^^^^


+ 11
- 11
docs/introduction.rst View File

@ -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


+ 1
- 1
docs/specification/genesis.rst View File

@ -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>`__).


+ 8
- 10
docs/using-tendermint.rst View File

@ -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.
@ -387,8 +385,8 @@ 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.
Ugrading
~~~~~~~~
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


Loading…
Cancel
Save