You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

460 lines
15 KiB

7 years ago
  1. Using Tendermint
  2. ================
  3. This is a guide to using the ``tendermint`` program from the command
  4. line. It assumes only that you have the ``tendermint`` binary installed
  5. and have some rudimentary idea of what Tendermint and ABCI are.
  6. You can see the help menu with ``tendermint --help``, and the version
  7. number with ``tendermint version``.
  8. Directory Root
  9. --------------
  10. The default directory for blockchain data is ``~/.tendermint``. Override
  11. this by setting the ``TMHOME`` environment variable.
  12. Initialize
  13. ----------
  14. Initialize the root directory by running:
  15. ::
  16. tendermint init
  17. This will create a new private key (``priv_validator.json``), and a
  18. genesis file (``genesis.json``) containing the associated public key,
  19. in ``$TMHOME/config``.
  20. This is all that's necessary to run a local testnet with one validator.
  21. For more elaborate initialization, see our `testnet deployment
  22. tool <https://github.com/tendermint/tools/tree/master/mintnet-kubernetes>`__.
  23. Run
  24. ---
  25. To run a Tendermint node, use
  26. ::
  27. tendermint node
  28. By default, Tendermint will try to connect to an ABCI application on
  29. `127.0.0.1:46658 <127.0.0.1:46658>`__. If you have the ``kvstore`` ABCI
  30. app installed, run it in another window. If you don't, kill Tendermint
  31. and run an in-process version of the ``kvstore`` app:
  32. ::
  33. tendermint node --proxy_app=kvstore
  34. After a few seconds you should see blocks start streaming in. Note that
  35. blocks are produced regularly, even if there are no transactions. See *No Empty Blocks*, below, to modify this setting.
  36. Tendermint supports in-process versions of the ``counter``, ``kvstore`` and ``nil``
  37. apps that ship as examples in the `ABCI
  38. repository <https://github.com/tendermint/abci>`__. It's easy to compile
  39. your own app in-process with Tendermint if it's written in Go. If your
  40. app is not written in Go, simply run it in another process, and use the
  41. ``--proxy_app`` flag to specify the address of the socket it is
  42. listening on, for instance:
  43. ::
  44. tendermint node --proxy_app=/var/run/abci.sock
  45. Transactions
  46. ------------
  47. To send a transaction, use ``curl`` to make requests to the Tendermint
  48. RPC server, for example:
  49. ::
  50. curl http://localhost:46657/broadcast_tx_commit?tx=\"abcd\"
  51. We can see the chain's status at the ``/status`` end-point:
  52. ::
  53. curl http://localhost:46657/status | json_pp
  54. and the ``latest_app_hash`` in particular:
  55. ::
  56. curl http://localhost:46657/status | json_pp | grep latest_app_hash
  57. Visit http://localhost:46657 in your browser to see the list of other
  58. endpoints. Some take no arguments (like ``/status``), while others
  59. specify the argument name and use ``_`` as a placeholder.
  60. Formatting
  61. ~~~~~~~~~~
  62. The following nuances when sending/formatting transactions should
  63. be taken into account:
  64. With ``GET``:
  65. To send a UTF8 string byte array, quote the value of the tx pramater:
  66. ::
  67. curl 'http://localhost:46657/broadcast_tx_commit?tx="hello"'
  68. which sends a 5 byte transaction: "h e l l o" [68 65 6c 6c 6f].
  69. Note the URL must be wrapped with single quoes, else bash will ignore the double quotes.
  70. To avoid the single quotes, escape the double quotes:
  71. ::
  72. curl http://localhost:46657/broadcast_tx_commit?tx=\"hello\"
  73. Using a special character:
  74. ::
  75. curl 'http://localhost:46657/broadcast_tx_commit?tx="€5"'
  76. sends a 4 byte transaction: "€5" (UTF8) [e2 82 ac 35].
  77. To send as raw hex, omit quotes AND prefix the hex string with ``0x``:
  78. ::
  79. curl http://localhost:46657/broadcast_tx_commit?tx=0x01020304
  80. which sends a 4 byte transaction: [01 02 03 04].
  81. With ``POST`` (using ``json``), the raw hex must be ``base64`` encoded:
  82. ::
  83. curl --data-binary '{"jsonrpc":"2.0","id":"anything","method":"broadcast_tx_commit","params": {"tx": "AQIDBA=="}}' -H 'content-type:text/plain;' http://localhost:46657
  84. which sends the same 4 byte transaction: [01 02 03 04].
  85. Note that raw hex cannot be used in ``POST`` transactions.
  86. Reset
  87. -----
  88. **WARNING: UNSAFE** Only do this in development and only if you can
  89. afford to lose all blockchain data!
  90. To reset a blockchain, stop the node, remove the ``~/.tendermint/data``
  91. directory and run
  92. ::
  93. tendermint unsafe_reset_priv_validator
  94. This final step is necessary to reset the ``priv_validator.json``, which
  95. otherwise prevents you from making conflicting votes in the consensus
  96. (something that could get you in trouble if you do it on a real
  97. blockchain). If you don't reset the ``priv_validator.json``, your fresh
  98. new blockchain will not make any blocks.
  99. Configuration
  100. -------------
  101. Tendermint uses a ``config.toml`` for configuration. For details, see
  102. `the config specification <./specification/configuration.html>`__.
  103. Notable options include the socket address of the application
  104. (``proxy_app``), the listening address of the Tendermint peer
  105. (``p2p.laddr``), and the listening address of the RPC server
  106. (``rpc.laddr``).
  107. Some fields from the config file can be overwritten with flags.
  108. No Empty Blocks
  109. ---------------
  110. This much requested feature was implemented in version 0.10.3. While the
  111. default behaviour of ``tendermint`` is still to create blocks approximately
  112. once per second, it is possible to disable empty blocks or set a block creation
  113. interval. In the former case, blocks will be created when there are new
  114. transactions or when the AppHash changes.
  115. To configure Tendermint to not produce empty blocks unless there are
  116. transactions or the app hash changes, run Tendermint with this additional flag:
  117. ::
  118. tendermint node --consensus.create_empty_blocks=false
  119. or set the configuration via the ``config.toml`` file:
  120. ::
  121. [consensus]
  122. create_empty_blocks = false
  123. Remember: because the default is to *create empty blocks*, avoiding empty blocks requires the config option to be set to ``false``.
  124. The block interval setting allows for a delay (in seconds) between the creation of each new empty block. It is set via the ``config.toml``:
  125. ::
  126. [consensus]
  127. create_empty_blocks_interval = 5
  128. With this setting, empty blocks will be produced every 5s if no block has been produced otherwise,
  129. regardless of the value of ``create_empty_blocks``.
  130. Broadcast API
  131. -------------
  132. Earlier, we used the ``broadcast_tx_commit`` endpoint to send a
  133. transaction. When a transaction is sent to a Tendermint node, it will
  134. run via ``CheckTx`` against the application. If it passes ``CheckTx``,
  135. it will be included in the mempool, broadcast to other peers, and
  136. eventually included in a block.
  137. Since there are multiple phases to processing a transaction, we offer
  138. multiple endpoints to broadcast a transaction:
  139. ::
  140. /broadcast_tx_async
  141. /broadcast_tx_sync
  142. /broadcast_tx_commit
  143. These correspond to no-processing, processing through the mempool, and
  144. processing through a block, respectively. That is,
  145. ``broadcast_tx_async``, will return right away without waiting to hear
  146. if the transaction is even valid, while ``broadcast_tx_sync`` will
  147. return with the result of running the transaction through ``CheckTx``.
  148. Using ``broadcast_tx_commit`` will wait until the transaction is
  149. committed in a block or until some timeout is reached, but will return
  150. right away if the transaction does not pass ``CheckTx``. The return
  151. value for ``broadcast_tx_commit`` includes two fields, ``check_tx`` and
  152. ``deliver_tx``, pertaining to the result of running the transaction
  153. through those ABCI messages.
  154. The benefit of using ``broadcast_tx_commit`` is that the request returns
  155. after the transaction is committed (i.e. included in a block), but that
  156. can take on the order of a second. For a quick result, use
  157. ``broadcast_tx_sync``, but the transaction will not be committed until
  158. later, and by that point its effect on the state may change.
  159. Note: see the Transactions => Formatting section for details about
  160. transaction formating.
  161. Tendermint Networks
  162. -------------------
  163. When ``tendermint init`` is run, both a ``genesis.json`` and
  164. ``priv_validator.json`` are created in ``~/.tendermint/config``. The
  165. ``genesis.json`` might look like:
  166. ::
  167. {
  168. "validators" : [
  169. {
  170. "pub_key" : {
  171. "value" : "h3hk+QE8c6QLTySp8TcfzclJw/BG79ziGB/pIA+DfPE=",
  172. "type" : "AC26791624DE60"
  173. },
  174. "power" : 10,
  175. "name" : ""
  176. }
  177. ],
  178. "app_hash" : "",
  179. "chain_id" : "test-chain-rDlYSN",
  180. "genesis_time" : "0001-01-01T00:00:00Z"
  181. }
  182. And the ``priv_validator.json``:
  183. ::
  184. {
  185. "last_step" : 0,
  186. "last_round" : 0,
  187. "address" : "B788DEDE4F50AD8BC9462DE76741CCAFF87D51E2",
  188. "pub_key" : {
  189. "value" : "h3hk+QE8c6QLTySp8TcfzclJw/BG79ziGB/pIA+DfPE=",
  190. "type" : "AC26791624DE60"
  191. },
  192. "last_height" : 0,
  193. "priv_key" : {
  194. "value" : "JPivl82x+LfVkp8i3ztoTjY6c6GJ4pBxQexErOCyhwqHeGT5ATxzpAtPJKnxNx/NyUnD8Ebv3OIYH+kgD4N88Q==",
  195. "type" : "954568A3288910"
  196. }
  197. }
  198. The ``priv_validator.json`` actually contains a private key, and should
  199. thus be kept absolutely secret; for now we work with the plain text.
  200. Note the ``last_`` fields, which are used to prevent us from signing
  201. conflicting messages.
  202. Note also that the ``pub_key`` (the public key) in the
  203. ``priv_validator.json`` is also present in the ``genesis.json``.
  204. The genesis file contains the list of public keys which may participate in the
  205. consensus, and their corresponding voting power. Greater than 2/3 of the voting
  206. power must be active (i.e. the corresponding private keys must be producing
  207. signatures) for the consensus to make progress. In our case, the genesis file
  208. contains the public key of our ``priv_validator.json``, so a Tendermint node
  209. started with the default root directory will be able to make progress. Voting
  210. power uses an `int64` but must be positive, thus the range is: 0 through
  211. 9223372036854775807. Because of how the current proposer selection algorithm works,
  212. we do not recommend having voting powers greater than 10^12 (ie. 1 trillion)
  213. (see `Proposals section of Byzantine Consensus Algorithm
  214. <./specification/byzantine-consensus-algorithm.html#proposals>`__ for details).
  215. If we want to add more nodes to the network, we have two choices: we can
  216. add a new validator node, who will also participate in the consensus by
  217. proposing blocks and voting on them, or we can add a new non-validator
  218. node, who will not participate directly, but will verify and keep up
  219. with the consensus protocol.
  220. Peers
  221. ~~~~~
  222. To connect to peers on start-up, specify them in the ``$TMHOME/config/config.toml`` or
  223. on the command line. Use `seeds` to specify seed nodes from which you can get many other
  224. peer addresses, and ``persistent_peers`` to specify peers that your node will maintain
  225. persistent connections with.
  226. For instance,
  227. ::
  228. tendermint node --p2p.seeds "f9baeaa15fedf5e1ef7448dd60f46c01f1a9e9c4@1.2.3.4:46656,0491d373a8e0fcf1023aaf18c51d6a1d0d4f31bd@5.6.7.8:46656"
  229. Alternatively, you can use the ``/dial_seeds`` endpoint of the RPC to
  230. specify seeds for a running node to connect to:
  231. ::
  232. curl 'localhost:46657/dial_seeds?seeds=\["f9baeaa15fedf5e1ef7448dd60f46c01f1a9e9c4@1.2.3.4:46656","0491d373a8e0fcf1023aaf18c51d6a1d0d4f31bd@5.6.7.8:46656"\]'
  233. Note, if the peer-exchange protocol (PEX) is enabled (default), you should not
  234. normally need seeds after the first start. Peers will be gossipping about known
  235. peers and forming a network, storing peer addresses in the addrbook.
  236. If you want Tendermint to connect to specific set of addresses and maintain a
  237. persistent connection with each, you can use the ``--p2p.persistent_peers``
  238. flag or the corresponding setting in the ``config.toml`` or the
  239. ``/dial_peers`` RPC endpoint to do it without stopping Tendermint
  240. core instance.
  241. ::
  242. tendermint node --p2p.persistent_peers "429fcf25974313b95673f58d77eacdd434402665@10.11.12.13:46656,96663a3dd0d7b9d17d4c8211b191af259621c693@10.11.12.14:46656"
  243. curl 'localhost:46657/dial_peers?persistent=true&peers=\["429fcf25974313b95673f58d77eacdd434402665@10.11.12.13:46656","96663a3dd0d7b9d17d4c8211b191af259621c693@10.11.12.14:46656"\]'
  244. Adding a Non-Validator
  245. ~~~~~~~~~~~~~~~~~~~~~~
  246. Adding a non-validator is simple. Just copy the original
  247. ``genesis.json`` to ``~/.tendermint/config`` on the new machine and start the
  248. node, specifying seeds or persistent peers as necessary. If no seeds or persistent
  249. peers are specified, the node won't make any blocks, because it's not a validator,
  250. and it won't hear about any blocks, because it's not connected to the other peer.
  251. Adding a Validator
  252. ~~~~~~~~~~~~~~~~~~
  253. The easiest way to add new validators is to do it in the
  254. ``genesis.json``, before starting the network. For instance, we could
  255. make a new ``priv_validator.json``, and copy it's ``pub_key`` into the
  256. above genesis.
  257. We can generate a new ``priv_validator.json`` with the command:
  258. ::
  259. tendermint gen_validator
  260. Now we can update our genesis file. For instance, if the new
  261. ``priv_validator.json`` looks like:
  262. ::
  263. {
  264. "address" : "5AF49D2A2D4F5AD4C7C8C4CC2FB020131E9C4902",
  265. "pub_key" : {
  266. "value" : "l9X9+fjkeBzDfPGbUM7AMIRE6uJN78zN5+lk5OYotek=",
  267. "type" : "AC26791624DE60"
  268. },
  269. "priv_key" : {
  270. "value" : "EDJY9W6zlAw+su6ITgTKg2nTZcHAH1NMTW5iwlgmNDuX1f35+OR4HMN88ZtQzsAwhETq4k3vzM3n6WTk5ii16Q==",
  271. "type" : "954568A3288910"
  272. },
  273. "last_step" : 0,
  274. "last_round" : 0,
  275. "last_height" : 0
  276. }
  277. then the new ``genesis.json`` will be:
  278. ::
  279. {
  280. "validators" : [
  281. {
  282. "pub_key" : {
  283. "value" : "h3hk+QE8c6QLTySp8TcfzclJw/BG79ziGB/pIA+DfPE=",
  284. "type" : "AC26791624DE60"
  285. },
  286. "power" : 10,
  287. "name" : ""
  288. },
  289. {
  290. "pub_key" : {
  291. "value" : "l9X9+fjkeBzDfPGbUM7AMIRE6uJN78zN5+lk5OYotek=",
  292. "type" : "AC26791624DE60"
  293. },
  294. "power" : 10,
  295. "name" : ""
  296. }
  297. ],
  298. "app_hash" : "",
  299. "chain_id" : "test-chain-rDlYSN",
  300. "genesis_time" : "0001-01-01T00:00:00Z"
  301. }
  302. Update the ``genesis.json`` in ``~/.tendermint/config``. Copy the genesis file
  303. and the new ``priv_validator.json`` to the ``~/.tendermint/config`` on a new
  304. machine.
  305. Now run ``tendermint node`` on both machines, and use either
  306. ``--p2p.persistent_peers`` or the ``/dial_peers`` to get them to peer up. They
  307. should start making blocks, and will only continue to do so as long as
  308. both of them are online.
  309. To make a Tendermint network that can tolerate one of the validators
  310. failing, you need at least four validator nodes (> 2/3).
  311. Updating validators in a live network is supported but must be
  312. explicitly programmed by the application developer. See the `application
  313. developers guide <./app-development.html>`__ for more
  314. details.
  315. Local Network
  316. ~~~~~~~~~~~~~
  317. To run a network locally, say on a single machine, you must change the
  318. ``_laddr`` fields in the ``config.toml`` (or using the flags) so that
  319. the listening addresses of the various sockets don't conflict.
  320. Additionally, you must set ``addrbook_strict=false`` in the
  321. ``config.toml``, otherwise Tendermint's p2p library will deny making
  322. connections to peers with the same IP address.
  323. Upgrading
  324. ~~~~~~~~~
  325. The Tendermint development cycle includes a lot of breaking changes. Upgrading from
  326. an old version to a new version usually means throwing away the chain data. Try out
  327. the `tm-migrate <https://github.com/hxzqlh/tm-tools>`__ tool written by @hxqlh if
  328. you are keen to preserve the state of your chain when upgrading to newer versions.