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