Merge branch 'develop' into 864-distinguish-between-seeds-and-manual-peers

docs/using-tendermint.rst

@@ -24,7 +24,8 @@ Initialize the root directory by running:
     tendermint init
 
 This will create a new private key (``priv_validator.json``), and a
-genesis file (``genesis.json``) containing the associated public key.
+genesis file (``genesis.json``) containing the associated public key,
+in ``$TMHOME/config``.
 This is all that's necessary to run a local testnet with one validator.
 
 For more elaborate initialization, see our `testnet deployment
@@ -127,10 +128,14 @@ Some fields from the config file can be overwritten with flags.
 No Empty Blocks
 ---------------
 
-This much requested feature was implemented in version 0.10.3. While the default behaviour of ``tendermint`` is still to create blocks approximately once per second, it is possible to disable empty blocks or set a block creation interval. In the former case, blocks will be created when there are new transactions or when the AppHash changes.
+This much requested feature was implemented in version 0.10.3. While the
+default behaviour of ``tendermint`` is still to create blocks approximately
+once per second, it is possible to disable empty blocks or set a block creation
+interval. In the former case, blocks will be created when there are new
+transactions or when the AppHash changes.
 
-To configure tendermint to not produce empty blocks unless there are txs or the app hash changes,
-run tendermint with this additional flag:
+To configure tendermint to not produce empty blocks unless there are
+transactions or the app hash changes, run tendermint with this additional flag:
 
 ::
 
@@ -153,8 +158,7 @@ The block interval setting allows for a delay (in seconds) between the creation
     create_empty_blocks_interval = 5
 
 With this setting, empty blocks will be produced every 5s if no block has been produced otherwise,
-regardless of the value of `create_empty_blocks`.
-
+regardless of the value of ``create_empty_blocks``.
 
 Broadcast API
 -------------
@@ -196,7 +200,7 @@ Tendermint Networks
 -------------------
 
 When ``tendermint init`` is run, both a ``genesis.json`` and
-``priv_validator.json`` are created in ``~/.tendermint``. The
+``priv_validator.json`` are created in ``~/.tendermint/config``. The
 ``genesis.json`` might look like:
 
 ::
@@ -246,13 +250,17 @@ conflicting messages.
 Note also that the ``pub_key`` (the public key) in the
 ``priv_validator.json`` is also present in the ``genesis.json``.
 
-The genesis file contains the list of public keys which may participate
-in the consensus, and their corresponding voting power. Greater than 2/3
-of the voting power must be active (ie. the corresponding private keys
-must be producing signatures) for the consensus to make progress. In our
-case, the genesis file contains the public key of our
-``priv_validator.json``, so a tendermint node started with the default
-root directory will be able to make new blocks, as we've already seen.
+The genesis file contains the list of public keys which may participate in the
+consensus, and their corresponding voting power. Greater than 2/3 of the voting
+power must be active (ie. the corresponding private keys must be producing
+signatures) for the consensus to make progress. In our case, the genesis file
+contains the public key of our ``priv_validator.json``, so a tendermint node
+started with the default root directory will be able to make progress. Voting
+power uses an `int64` but must be positive, thus the range is: 0 through
+9223372036854775807. Because of how the current proposer selection algorithm works,
+we do not recommend having voting powers greater than 10^12 (ie. 1 trillion)
+(see `Proposals section of Byzantine Consensus Algorithm
+<./specification/byzantine-consensus-algorithm.html#proposals>`__ for details).
 
 If we want to add more nodes to the network, we have two choices: we can
 add a new validator node, who will also participate in the consensus by
@@ -263,10 +271,10 @@ with the consensus protocol.
 Peers
 ~~~~~
 
-If you are starting Tendermint core for the first time, it will need some peers.
-
-You can provide a list of seeds (nodes, whole purpose is providing you with
-peers) in the ``config.toml`` or on the command line.
+To connect to peers on start-up, specify them in the ``$TMHOME/config/config.toml`` or
+on the command line. Use `seeds` to specify seed nodes from which you can get many other
+peer addresses, and ``persistent_peers`` to specify peers that your node will maintain
+persistent connections with.
 
 For instance,
 
@@ -299,11 +307,11 @@ core instance.
 Adding a Non-Validator
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Adding a non-validator is simple. Just copy the original ``genesis.json`` to
-``~/.tendermint`` on the new machine and start the node, specifying seeds or
-persistent peers. If no seeds or persistent peers are specified, the node won't
-make any blocks, because it's not a validator, and it won't hear about any
-blocks, because it's not connected to the other peers.
+Adding a non-validator is simple. Just copy the original
+``genesis.json`` to ``~/.tendermint/config`` on the new machine and start the
+node, specifying seeds or persistent peers as necessary. If no seeds or persistent
+peers are specified, the node won't make any blocks, because it's not a validator,
+and it won't hear about any blocks, because it's not connected to the other peer.
 
 Adding a Validator
 ~~~~~~~~~~~~~~~~~~
@@ -369,8 +377,8 @@ then the new ``genesis.json`` will be:
         ]
     }
 
-Update the ``genesis.json`` in ``~/.tendermint``. Copy the genesis file
-and the new ``priv_validator.json`` to the ``~/.tendermint`` on a new
+Update the ``genesis.json`` in ``~/.tendermint/config``. Copy the genesis file
+and the new ``priv_validator.json`` to the ``~/.tendermint/config`` on a new
 machine.
 
 Now run ``tendermint node`` on both machines, and use either