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.

474 lines
15 KiB

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