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