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.

571 lines
19 KiB

6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
  1. ---
  2. order: 2
  3. ---
  4. # Using Tendermint
  5. This is a guide to using the `tendermint` program from the command line.
  6. It assumes only that you have the `tendermint` binary installed and have
  7. some rudimentary idea of what Tendermint and ABCI are.
  8. You can see the help menu with `tendermint --help`, and the version
  9. number with `tendermint version`.
  10. ## Directory Root
  11. The default directory for blockchain data is `~/.tendermint`. Override
  12. this by setting the `TMHOME` environment variable.
  13. ## Initialize
  14. Initialize the root directory by running:
  15. ```sh
  16. tendermint init validator
  17. ```
  18. This will create a new private key (`priv_validator_key.json`), and a
  19. genesis file (`genesis.json`) containing the associated public key, in
  20. `$TMHOME/config`. This is all that's necessary to run a local testnet
  21. with one validator.
  22. For more elaborate initialization, see the testnet command:
  23. ```sh
  24. tendermint testnet --help
  25. ```
  26. ### Genesis
  27. The `genesis.json` file in `$TMHOME/config/` defines the initial
  28. TendermintCore state upon genesis of the blockchain ([see
  29. definition](https://github.com/tendermint/tendermint/blob/master/types/genesis.go)).
  30. #### Fields
  31. - `genesis_time`: Official time of blockchain start.
  32. - `chain_id`: ID of the blockchain. **This must be unique for
  33. every blockchain.** If your testnet blockchains do not have unique
  34. chain IDs, you will have a bad time. The ChainID must be less than 50 symbols.
  35. - `initial_height`: Height at which Tendermint should begin at. If a blockchain is conducting a network upgrade,
  36. starting from the stopped height brings uniqueness to previous heights.
  37. - `consensus_params` [spec](https://github.com/tendermint/spec/blob/master/spec/core/state.md#consensusparams)
  38. - `block`
  39. - `max_bytes`: Max block size, in bytes.
  40. - `max_gas`: Max gas per block.
  41. - `time_iota_ms`: Unused. This has been deprecated and will be removed in a future version.
  42. - `evidence`
  43. - `max_age_num_blocks`: Max age of evidence, in blocks. The basic formula
  44. for calculating this is: MaxAgeDuration / {average block time}.
  45. - `max_age_duration`: Max age of evidence, in time. It should correspond
  46. with an app's "unbonding period" or other similar mechanism for handling
  47. [Nothing-At-Stake
  48. attacks](https://github.com/ethereum/wiki/wiki/Proof-of-Stake-FAQ#what-is-the-nothing-at-stake-problem-and-how-can-it-be-fixed).
  49. - `max_num`: This sets the maximum number of evidence that can be committed
  50. in a single block. and should fall comfortably under the max block
  51. bytes when we consider the size of each evidence.
  52. - `validator`
  53. - `pub_key_types`: Public key types validators can use.
  54. - `version`
  55. - `app_version`: ABCI application version.
  56. - `validators`: List of initial validators. Note this may be overridden entirely by the
  57. application, and may be left empty to make explicit that the
  58. application will initialize the validator set with ResponseInitChain.
  59. - `pub_key`: The first element specifies the `pub_key` type. 1
  60. == Ed25519. The second element are the pubkey bytes.
  61. - `power`: The validator's voting power.
  62. - `name`: Name of the validator (optional).
  63. - `app_hash`: The expected application hash (as returned by the
  64. `ResponseInfo` ABCI message) upon genesis. If the app's hash does
  65. not match, Tendermint will panic.
  66. - `app_state`: The application state (e.g. initial distribution
  67. of tokens).
  68. > :warning: **ChainID must be unique to every blockchain. Reusing old chainID can cause issues**
  69. #### Sample genesis.json
  70. ```json
  71. {
  72. "genesis_time": "2020-04-21T11:17:42.341227868Z",
  73. "chain_id": "test-chain-ROp9KF",
  74. "initial_height": "0",
  75. "consensus_params": {
  76. "block": {
  77. "max_bytes": "22020096",
  78. "max_gas": "-1",
  79. "time_iota_ms": "1000"
  80. },
  81. "evidence": {
  82. "max_age_num_blocks": "100000",
  83. "max_age_duration": "172800000000000",
  84. "max_num": 50,
  85. },
  86. "validator": {
  87. "pub_key_types": [
  88. "ed25519"
  89. ]
  90. }
  91. },
  92. "validators": [
  93. {
  94. "address": "B547AB87E79F75A4A3198C57A8C2FDAF8628CB47",
  95. "pub_key": {
  96. "type": "tendermint/PubKeyEd25519",
  97. "value": "P/V6GHuZrb8rs/k1oBorxc6vyXMlnzhJmv7LmjELDys="
  98. },
  99. "power": "10",
  100. "name": ""
  101. }
  102. ],
  103. "app_hash": ""
  104. }
  105. ```
  106. ## Run
  107. To run a Tendermint node, use:
  108. ```bash
  109. tendermint start
  110. ```
  111. By default, Tendermint will try to connect to an ABCI application on
  112. `127.0.0.1:26658`. If you have the `kvstore` ABCI app installed, run it in
  113. another window. If you don't, kill Tendermint and run an in-process version of
  114. the `kvstore` app:
  115. ```bash
  116. tendermint start --proxy-app=kvstore
  117. ```
  118. After a few seconds, you should see blocks start streaming in. Note that blocks
  119. are produced regularly, even if there are no transactions. See _No Empty
  120. Blocks_, below, to modify this setting.
  121. Tendermint supports in-process versions of the `counter`, `kvstore`, and `noop`
  122. apps that ship as examples with `abci-cli`. It's easy to compile your app
  123. in-process with Tendermint if it's written in Go. If your app is not written in
  124. Go, run it in another process, and use the `--proxy-app` flag to specify the
  125. address of the socket it is listening on, for instance:
  126. ```bash
  127. tendermint start --proxy-app=/var/run/abci.sock
  128. ```
  129. You can find out what flags are supported by running `tendermint start --help`.
  130. ## Transactions
  131. To send a transaction, use `curl` to make requests to the Tendermint RPC
  132. server, for example:
  133. ```sh
  134. curl http://localhost:26657/broadcast_tx_commit?tx=\"abcd\"
  135. ```
  136. We can see the chain's status at the `/status` end-point:
  137. ```sh
  138. curl http://localhost:26657/status | json_pp
  139. ```
  140. and the `latest_app_hash` in particular:
  141. ```sh
  142. curl http://localhost:26657/status | json_pp | grep latest_app_hash
  143. ```
  144. Visit `http://localhost:26657` in your browser to see the list of other
  145. endpoints. Some take no arguments (like `/status`), while others specify
  146. the argument name and use `_` as a placeholder.
  147. > TIP: Find the RPC Documentation [here](https://docs.tendermint.com/master/rpc/)
  148. ### Formatting
  149. The following nuances when sending/formatting transactions should be
  150. taken into account:
  151. With `GET`:
  152. To send a UTF8 string byte array, quote the value of the tx parameter:
  153. ```sh
  154. curl 'http://localhost:26657/broadcast_tx_commit?tx="hello"'
  155. ```
  156. which sends a 5 byte transaction: "h e l l o" \[68 65 6c 6c 6f\].
  157. Note the URL must be wrapped with single quotes, else bash will ignore
  158. the double quotes. To avoid the single quotes, escape the double quotes:
  159. ```sh
  160. curl http://localhost:26657/broadcast_tx_commit?tx=\"hello\"
  161. ```
  162. Using a special character:
  163. ```sh
  164. curl 'http://localhost:26657/broadcast_tx_commit?tx="€5"'
  165. ```
  166. sends a 4 byte transaction: "€5" (UTF8) \[e2 82 ac 35\].
  167. To send as raw hex, omit quotes AND prefix the hex string with `0x`:
  168. ```sh
  169. curl http://localhost:26657/broadcast_tx_commit?tx=0x01020304
  170. ```
  171. which sends a 4 byte transaction: \[01 02 03 04\].
  172. With `POST` (using `json`), the raw hex must be `base64` encoded:
  173. ```sh
  174. curl --data-binary '{"jsonrpc":"2.0","id":"anything","method":"broadcast_tx_commit","params": {"tx": "AQIDBA=="}}' -H 'content-type:text/plain;' http://localhost:26657
  175. ```
  176. which sends the same 4 byte transaction: \[01 02 03 04\].
  177. Note that raw hex cannot be used in `POST` transactions.
  178. ## Reset
  179. > :warning: **UNSAFE** Only do this in development and only if you can
  180. afford to lose all blockchain data!
  181. To reset a blockchain, stop the node and run:
  182. ```sh
  183. tendermint unsafe_reset_all
  184. ```
  185. This command will remove the data directory and reset private validator and
  186. address book files.
  187. ## Configuration
  188. Tendermint uses a `config.toml` for configuration. For details, see [the
  189. config specification](./configuration.md).
  190. Notable options include the socket address of the application
  191. (`proxy-app`), the listening address of the Tendermint peer
  192. (`p2p.laddr`), and the listening address of the RPC server
  193. (`rpc.laddr`).
  194. Some fields from the config file can be overwritten with flags.
  195. ## No Empty Blocks
  196. While the default behavior of `tendermint` is still to create blocks
  197. approximately once per second, it is possible to disable empty blocks or
  198. set a block creation interval. In the former case, blocks will be
  199. created when there are new transactions or when the AppHash changes.
  200. To configure Tendermint to not produce empty blocks unless there are
  201. transactions or the app hash changes, run Tendermint with this
  202. additional flag:
  203. ```sh
  204. tendermint start --consensus.create_empty_blocks=false
  205. ```
  206. or set the configuration via the `config.toml` file:
  207. ```toml
  208. [consensus]
  209. create_empty_blocks = false
  210. ```
  211. Remember: because the default is to _create empty blocks_, avoiding
  212. empty blocks requires the config option to be set to `false`.
  213. The block interval setting allows for a delay (in time.Duration format [ParseDuration](https://golang.org/pkg/time/#ParseDuration)) between the
  214. creation of each new empty block. It can be set with this additional flag:
  215. ```sh
  216. --consensus.create_empty_blocks_interval="5s"
  217. ```
  218. or set the configuration via the `config.toml` file:
  219. ```toml
  220. [consensus]
  221. create_empty_blocks_interval = "5s"
  222. ```
  223. With this setting, empty blocks will be produced every 5s if no block
  224. has been produced otherwise, regardless of the value of
  225. `create_empty_blocks`.
  226. ## Broadcast API
  227. Earlier, we used the `broadcast_tx_commit` endpoint to send a
  228. transaction. When a transaction is sent to a Tendermint node, it will
  229. run via `CheckTx` against the application. If it passes `CheckTx`, it
  230. will be included in the mempool, broadcasted to other peers, and
  231. eventually included in a block.
  232. Since there are multiple phases to processing a transaction, we offer
  233. multiple endpoints to broadcast a transaction:
  234. ```md
  235. /broadcast_tx_async
  236. /broadcast_tx_sync
  237. /broadcast_tx_commit
  238. ```
  239. These correspond to no-processing, processing through the mempool, and
  240. processing through a block, respectively. That is, `broadcast_tx_async`,
  241. will return right away without waiting to hear if the transaction is
  242. even valid, while `broadcast_tx_sync` will return with the result of
  243. running the transaction through `CheckTx`. Using `broadcast_tx_commit`
  244. will wait until the transaction is committed in a block or until some
  245. timeout is reached, but will return right away if the transaction does
  246. not pass `CheckTx`. The return value for `broadcast_tx_commit` includes
  247. two fields, `check_tx` and `deliver_tx`, pertaining to the result of
  248. running the transaction through those ABCI messages.
  249. The benefit of using `broadcast_tx_commit` is that the request returns
  250. after the transaction is committed (i.e. included in a block), but that
  251. can take on the order of a second. For a quick result, use
  252. `broadcast_tx_sync`, but the transaction will not be committed until
  253. later, and by that point its effect on the state may change.
  254. Note the mempool does not provide strong guarantees - just because a tx passed
  255. CheckTx (ie. was accepted into the mempool), doesn't mean it will be committed,
  256. as nodes with the tx in their mempool may crash before they get to propose.
  257. For more information, see the [mempool
  258. write-ahead-log](../tendermint-core/running-in-production.md#mempool-wal)
  259. ## Tendermint Networks
  260. When `tendermint init` is run, both a `genesis.json` and
  261. `priv_validator_key.json` are created in `~/.tendermint/config`. The
  262. `genesis.json` might look like:
  263. ```json
  264. {
  265. "validators" : [
  266. {
  267. "pub_key" : {
  268. "value" : "h3hk+QE8c6QLTySp8TcfzclJw/BG79ziGB/pIA+DfPE=",
  269. "type" : "tendermint/PubKeyEd25519"
  270. },
  271. "power" : 10,
  272. "name" : ""
  273. }
  274. ],
  275. "app_hash" : "",
  276. "chain_id" : "test-chain-rDlYSN",
  277. "genesis_time" : "0001-01-01T00:00:00Z"
  278. }
  279. ```
  280. And the `priv_validator_key.json`:
  281. ```json
  282. {
  283. "last_step" : 0,
  284. "last_round" : "0",
  285. "address" : "B788DEDE4F50AD8BC9462DE76741CCAFF87D51E2",
  286. "pub_key" : {
  287. "value" : "h3hk+QE8c6QLTySp8TcfzclJw/BG79ziGB/pIA+DfPE=",
  288. "type" : "tendermint/PubKeyEd25519"
  289. },
  290. "last_height" : "0",
  291. "priv_key" : {
  292. "value" : "JPivl82x+LfVkp8i3ztoTjY6c6GJ4pBxQexErOCyhwqHeGT5ATxzpAtPJKnxNx/NyUnD8Ebv3OIYH+kgD4N88Q==",
  293. "type" : "tendermint/PrivKeyEd25519"
  294. }
  295. }
  296. ```
  297. The `priv_validator_key.json` actually contains a private key, and should
  298. thus be kept absolutely secret; for now we work with the plain text.
  299. Note the `last_` fields, which are used to prevent us from signing
  300. conflicting messages.
  301. Note also that the `pub_key` (the public key) in the
  302. `priv_validator_key.json` is also present in the `genesis.json`.
  303. The genesis file contains the list of public keys which may participate
  304. in the consensus, and their corresponding voting power. Greater than 2/3
  305. of the voting power must be active (i.e. the corresponding private keys
  306. must be producing signatures) for the consensus to make progress. In our
  307. case, the genesis file contains the public key of our
  308. `priv_validator_key.json`, so a Tendermint node started with the default
  309. root directory will be able to make progress. Voting power uses an int64
  310. but must be positive, thus the range is: 0 through 9223372036854775807.
  311. Because of how the current proposer selection algorithm works, we do not
  312. recommend having voting powers greater than 10\^12 (ie. 1 trillion).
  313. If we want to add more nodes to the network, we have two choices: we can
  314. add a new validator node, who will also participate in the consensus by
  315. proposing blocks and voting on them, or we can add a new non-validator
  316. node, who will not participate directly, but will verify and keep up
  317. with the consensus protocol.
  318. ### Peers
  319. #### Seed
  320. A seed node is a node who relays the addresses of other peers which they know
  321. of. These nodes constantly crawl the network to try to get more peers. The
  322. addresses which the seed node relays get saved into a local address book. Once
  323. these are in the address book, you will connect to those addresses directly.
  324. Basically the seed nodes job is just to relay everyones addresses. You won't
  325. connect to seed nodes once you have received enough addresses, so typically you
  326. only need them on the first start. The seed node will immediately disconnect
  327. from you after sending you some addresses.
  328. #### Persistent Peer
  329. Persistent peers are people you want to be constantly connected with. If you
  330. disconnect you will try to connect directly back to them as opposed to using
  331. another address from the address book. On restarts you will always try to
  332. connect to these peers regardless of the size of your address book.
  333. All peers relay peers they know of by default. This is called the peer exchange
  334. protocol (PeX). With PeX, peers will be gossiping about known peers and forming
  335. a network, storing peer addresses in the addrbook. Because of this, you don't
  336. have to use a seed node if you have a live persistent peer.
  337. #### Connecting to Peers
  338. To connect to peers on start-up, specify them in the
  339. `$TMHOME/config/config.toml` or on the command line. Use `seeds` to
  340. specify seed nodes, and
  341. `persistent-peers` to specify peers that your node will maintain
  342. persistent connections with.
  343. For example,
  344. ```sh
  345. tendermint start --p2p.seeds "f9baeaa15fedf5e1ef7448dd60f46c01f1a9e9c4@1.2.3.4:26656,0491d373a8e0fcf1023aaf18c51d6a1d0d4f31bd@5.6.7.8:26656"
  346. ```
  347. Alternatively, you can use the `/dial_seeds` endpoint of the RPC to
  348. specify seeds for a running node to connect to:
  349. ```sh
  350. curl 'localhost:26657/dial_seeds?seeds=\["f9baeaa15fedf5e1ef7448dd60f46c01f1a9e9c4@1.2.3.4:26656","0491d373a8e0fcf1023aaf18c51d6a1d0d4f31bd@5.6.7.8:26656"\]'
  351. ```
  352. Note, with PeX enabled, you
  353. should not need seeds after the first start.
  354. If you want Tendermint to connect to specific set of addresses and
  355. maintain a persistent connection with each, you can use the
  356. `--p2p.persistent-peers` flag or the corresponding setting in the
  357. `config.toml` or the `/dial_peers` RPC endpoint to do it without
  358. stopping Tendermint core instance.
  359. ```sh
  360. tendermint start --p2p.persistent-peers "429fcf25974313b95673f58d77eacdd434402665@10.11.12.13:26656,96663a3dd0d7b9d17d4c8211b191af259621c693@10.11.12.14:26656"
  361. curl 'localhost:26657/dial_peers?persistent=true&peers=\["429fcf25974313b95673f58d77eacdd434402665@10.11.12.13:26656","96663a3dd0d7b9d17d4c8211b191af259621c693@10.11.12.14:26656"\]'
  362. ```
  363. ### Adding a Non-Validator
  364. Adding a non-validator is simple. Just copy the original `genesis.json`
  365. to `~/.tendermint/config` on the new machine and start the node,
  366. specifying seeds or persistent peers as necessary. If no seeds or
  367. persistent peers are specified, the node won't make any blocks, because
  368. it's not a validator, and it won't hear about any blocks, because it's
  369. not connected to the other peer.
  370. ### Adding a Validator
  371. The easiest way to add new validators is to do it in the `genesis.json`,
  372. before starting the network. For instance, we could make a new
  373. `priv_validator_key.json`, and copy it's `pub_key` into the above genesis.
  374. We can generate a new `priv_validator_key.json` with the command:
  375. ```sh
  376. tendermint gen_validator
  377. ```
  378. Now we can update our genesis file. For instance, if the new
  379. `priv_validator_key.json` looks like:
  380. ```json
  381. {
  382. "address" : "5AF49D2A2D4F5AD4C7C8C4CC2FB020131E9C4902",
  383. "pub_key" : {
  384. "value" : "l9X9+fjkeBzDfPGbUM7AMIRE6uJN78zN5+lk5OYotek=",
  385. "type" : "tendermint/PubKeyEd25519"
  386. },
  387. "priv_key" : {
  388. "value" : "EDJY9W6zlAw+su6ITgTKg2nTZcHAH1NMTW5iwlgmNDuX1f35+OR4HMN88ZtQzsAwhETq4k3vzM3n6WTk5ii16Q==",
  389. "type" : "tendermint/PrivKeyEd25519"
  390. },
  391. "last_step" : 0,
  392. "last_round" : "0",
  393. "last_height" : "0"
  394. }
  395. ```
  396. then the new `genesis.json` will be:
  397. ```json
  398. {
  399. "validators" : [
  400. {
  401. "pub_key" : {
  402. "value" : "h3hk+QE8c6QLTySp8TcfzclJw/BG79ziGB/pIA+DfPE=",
  403. "type" : "tendermint/PubKeyEd25519"
  404. },
  405. "power" : 10,
  406. "name" : ""
  407. },
  408. {
  409. "pub_key" : {
  410. "value" : "l9X9+fjkeBzDfPGbUM7AMIRE6uJN78zN5+lk5OYotek=",
  411. "type" : "tendermint/PubKeyEd25519"
  412. },
  413. "power" : 10,
  414. "name" : ""
  415. }
  416. ],
  417. "app_hash" : "",
  418. "chain_id" : "test-chain-rDlYSN",
  419. "genesis_time" : "0001-01-01T00:00:00Z"
  420. }
  421. ```
  422. Update the `genesis.json` in `~/.tendermint/config`. Copy the genesis
  423. file and the new `priv_validator_key.json` to the `~/.tendermint/config` on
  424. a new machine.
  425. Now run `tendermint start` on both machines, and use either
  426. `--p2p.persistent-peers` or the `/dial_peers` to get them to peer up.
  427. They should start making blocks, and will only continue to do so as long
  428. as both of them are online.
  429. To make a Tendermint network that can tolerate one of the validators
  430. failing, you need at least four validator nodes (e.g., 2/3).
  431. Updating validators in a live network is supported but must be
  432. explicitly programmed by the application developer.
  433. ### Local Network
  434. To run a network locally, say on a single machine, you must change the `_laddr`
  435. fields in the `config.toml` (or using the flags) so that the listening
  436. addresses of the various sockets don't conflict. Additionally, you must set
  437. `addr_book_strict=false` in the `config.toml`, otherwise Tendermint's p2p
  438. library will deny making connections to peers with the same IP address.
  439. ### Upgrading
  440. See the
  441. [UPGRADING.md](https://github.com/tendermint/tendermint/blob/master/UPGRADING.md)
  442. guide. You may need to reset your chain between major breaking releases.
  443. Although, we expect Tendermint to have fewer breaking releases in the future
  444. (especially after 1.0 release).