github.com/vipernet-xyz/tm@v0.34.24/spec/abci/abci.md (about) 1 --- 2 order: 1 3 title: Method and Types 4 --- 5 6 # Methods and Types 7 8 ## Connections 9 10 ABCI applications can run either within the _same_ process as the Tendermint 11 state-machine replication engine, or as a _separate_ process from the state-machine 12 replication engine. When run within the same process, Tendermint will call the ABCI 13 application methods directly as Go method calls. 14 15 When Tendermint and the ABCI application are run as separate processes, Tendermint 16 opens four connections to the application for ABCI methods. The connections each 17 handle a subset of the ABCI method calls. These subsets are defined as follows: 18 19 #### **Consensus** connection 20 21 * Driven by a consensus protocol and is responsible for block execution. 22 * Handles the `InitChain`, `BeginBlock`, `DeliverTx`, `EndBlock`, and `Commit` method 23 calls. 24 25 #### **Mempool** connection 26 27 * For validating new transactions, before they're shared or included in a block. 28 * Handles the `CheckTx` calls. 29 30 #### **Info** connection 31 32 * For initialization and for queries from the user. 33 * Handles the `Info` and `Query` calls. 34 35 #### **Snapshot** connection 36 37 * For serving and restoring [state sync snapshots](apps.md#state-sync). 38 * Handles the `ListSnapshots`, `LoadSnapshotChunk`, `OfferSnapshot`, and `ApplySnapshotChunk` calls. 39 40 Additionally, there is a `Flush` method that is called on every connection, 41 and an `Echo` method that is just for debugging. 42 43 More details on managing state across connections can be found in the section on 44 [ABCI Applications](apps.md). 45 46 ## Errors 47 48 The `Query`, `CheckTx` and `DeliverTx` methods include a `Code` field in their `Response*`. 49 This field is meant to contain an application-specific response code. 50 A response code of `0` indicates no error. Any other response code 51 indicates to Tendermint that an error occurred. 52 53 These methods also return a `Codespace` string to Tendermint. This field is 54 used to disambiguate `Code` values returned by different domains of the 55 application. The `Codespace` is a namespace for the `Code`. 56 57 The `Echo`, `Info`, `InitChain`, `BeginBlock`, `EndBlock`, `Commit` methods 58 do not return errors. An error in any of these methods represents a critical 59 issue that Tendermint has no reasonable way to handle. If there is an error in one 60 of these methods, the application must crash to ensure that the error is safely 61 handled by an operator. 62 63 The handling of non-zero response codes by Tendermint is described below 64 65 ### CheckTx 66 67 The `CheckTx` ABCI method controls what transactions are considered for inclusion in a block. 68 When Tendermint receives a `ResponseCheckTx` with a non-zero `Code`, the associated 69 transaction will be not be added to Tendermint's mempool or it will be removed if 70 it is already included. 71 72 ### DeliverTx 73 74 The `DeliverTx` ABCI method delivers transactions from Tendermint to the application. 75 When Tendermint recieves a `ResponseDeliverTx` with a non-zero `Code`, the response code is logged. 76 The transaction was already included in a block, so the `Code` does not influence 77 Tendermint consensus. 78 79 ### Query 80 81 The `Query` ABCI method query queries the application for information about application state. 82 When Tendermint receives a `ResponseQuery` with a non-zero `Code`, this code is 83 returned directly to the client that initiated the query. 84 85 ## Events 86 87 The `CheckTx`, `BeginBlock`, `DeliverTx`, `EndBlock` methods include an `Events` 88 field in their `Response*`. Applications may respond to these ABCI methods with a set of events. 89 Events allow applications to associate metadata about ABCI method execution with the 90 transactions and blocks this metadata relates to. 91 Events returned via these ABCI methods do not impact Tendermint consensus in any way 92 and instead exist to power subscriptions and queries of Tendermint state. 93 94 An `Event` contains a `type` and a list of `EventAttributes`, which are key-value 95 string pairs denoting metadata about what happened during the method's execution. 96 `Event` values can be used to index transactions and blocks according to what happened 97 during their execution. Note that the set of events returned for a block from 98 `BeginBlock` and `EndBlock` are merged. In case both methods return the same 99 key, only the value defined in `EndBlock` is used. 100 101 Each event has a `type` which is meant to categorize the event for a particular 102 `Response*` or `Tx`. A `Response*` or `Tx` may contain multiple events with duplicate 103 `type` values, where each distinct entry is meant to categorize attributes for a 104 particular event. Every key and value in an event's attributes must be UTF-8 105 encoded strings along with the event type itself. 106 107 ```protobuf 108 message Event { 109 string type = 1; 110 repeated EventAttribute attributes = 2; 111 } 112 ``` 113 114 The attributes of an `Event` consist of a `key`, a `value`, and an `index` flag. The 115 index flag notifies the Tendermint indexer to index the attribute. The value of 116 the `index` flag is non-deterministic and may vary across different nodes in the network. 117 118 ```protobuf 119 message EventAttribute { 120 bytes key = 1; 121 bytes value = 2; 122 bool index = 3; // nondeterministic 123 } 124 ``` 125 126 Example: 127 128 ```go 129 abci.ResponseDeliverTx{ 130 // ... 131 Events: []abci.Event{ 132 { 133 Type: "validator.provisions", 134 Attributes: []abci.EventAttribute{ 135 abci.EventAttribute{Key: []byte("address"), Value: []byte("..."), Index: true}, 136 abci.EventAttribute{Key: []byte("amount"), Value: []byte("..."), Index: true}, 137 abci.EventAttribute{Key: []byte("balance"), Value: []byte("..."), Index: true}, 138 }, 139 }, 140 { 141 Type: "validator.provisions", 142 Attributes: []abci.EventAttribute{ 143 abci.EventAttribute{Key: []byte("address"), Value: []byte("..."), Index: true}, 144 abci.EventAttribute{Key: []byte("amount"), Value: []byte("..."), Index: false}, 145 abci.EventAttribute{Key: []byte("balance"), Value: []byte("..."), Index: false}, 146 }, 147 }, 148 { 149 Type: "validator.slashed", 150 Attributes: []abci.EventAttribute{ 151 abci.EventAttribute{Key: []byte("address"), Value: []byte("..."), Index: false}, 152 abci.EventAttribute{Key: []byte("amount"), Value: []byte("..."), Index: true}, 153 abci.EventAttribute{Key: []byte("reason"), Value: []byte("..."), Index: true}, 154 }, 155 }, 156 // ... 157 }, 158 } 159 ``` 160 161 ## EvidenceType 162 163 Tendermint's security model relies on the use of "evidence". Evidence is proof of 164 malicious behaviour by a network participant. It is the responsibility of Tendermint 165 to detect such malicious behaviour. When malicious behavior is detected, Tendermint 166 will gossip evidence of the behavior to other nodes and commit the evidence to 167 the chain once it is verified by all validators. This evidence will then be 168 passed it on to the application through the ABCI. It is the responsibility of the 169 application to handle the evidence and exercise punishment. 170 171 EvidenceType has the following protobuf format: 172 173 ```proto 174 enum EvidenceType { 175 UNKNOWN = 0; 176 DUPLICATE_VOTE = 1; 177 LIGHT_CLIENT_ATTACK = 2; 178 } 179 ``` 180 181 There are two forms of evidence: Duplicate Vote and Light Client Attack. More 182 information can be found in either [data structures](https://github.com/vipernet-xyz/tm/blob/v0.34.x/spec/core/data_structures.md) 183 or [accountability](https://github.com/vipernet-xyz/tm/blob/v0.34.x/spec/light-client/accountability/) 184 185 ## Determinism 186 187 ABCI applications must implement deterministic finite-state machines to be 188 securely replicated by the Tendermint consensus engine. This means block execution 189 over the Consensus Connection must be strictly deterministic: given the same 190 ordered set of requests, all nodes will compute identical responses, for all 191 BeginBlock, DeliverTx, EndBlock, and Commit. This is critical, because the 192 responses are included in the header of the next block, either via a Merkle root 193 or directly, so all nodes must agree on exactly what they are. 194 195 For this reason, it is recommended that applications not be exposed to any 196 external user or process except via the ABCI connections to a consensus engine 197 like Tendermint Core. The application must only change its state based on input 198 from block execution (BeginBlock, DeliverTx, EndBlock, Commit), and not through 199 any other kind of request. This is the only way to ensure all nodes see the same 200 transactions and compute the same results. 201 202 If there is some non-determinism in the state machine, consensus will eventually 203 fail as nodes disagree over the correct values for the block header. The 204 non-determinism must be fixed and the nodes restarted. 205 206 Sources of non-determinism in applications may include: 207 208 * Hardware failures 209 * Cosmic rays, overheating, etc. 210 * Node-dependent state 211 * Random numbers 212 * Time 213 * Underspecification 214 * Library version changes 215 * Race conditions 216 * Floating point numbers 217 * JSON serialization 218 * Iterating through hash-tables/maps/dictionaries 219 * External Sources 220 * Filesystem 221 * Network calls (eg. some external REST API service) 222 223 See [#56](https://github.com/tendermint/abci/issues/56) for original discussion. 224 225 Note that some methods (`Query, CheckTx, DeliverTx`) return 226 explicitly non-deterministic data in the form of `Info` and `Log` fields. The `Log` is 227 intended for the literal output from the application's logger, while the 228 `Info` is any additional info that should be returned. These are the only fields 229 that are not included in block header computations, so we don't need agreement 230 on them. All other fields in the `Response*` must be strictly deterministic. 231 232 ## Block Execution 233 234 The first time a new blockchain is started, Tendermint calls 235 `InitChain`. From then on, the following sequence of methods is executed for each 236 block: 237 238 `BeginBlock, [DeliverTx], EndBlock, Commit` 239 240 where one `DeliverTx` is called for each transaction in the block. 241 The result is an updated application state. 242 Cryptographic commitments to the results of DeliverTx, EndBlock, and 243 Commit are included in the header of the next block. 244 245 ## State Sync 246 247 State sync allows new nodes to rapidly bootstrap by discovering, fetching, and applying 248 state machine snapshots instead of replaying historical blocks. For more details, see the 249 [state sync section](../spec/p2p/messages/state-sync.md). 250 251 New nodes will discover and request snapshots from other nodes in the P2P network. 252 A Tendermint node that receives a request for snapshots from a peer will call 253 `ListSnapshots` on its application to retrieve any local state snapshots. After receiving 254 snapshots from peers, the new node will offer each snapshot received from a peer 255 to its local application via the `OfferSnapshot` method. 256 257 Snapshots may be quite large and are thus broken into smaller "chunks" that can be 258 assembled into the whole snapshot. Once the application accepts a snapshot and 259 begins restoring it, Tendermint will fetch snapshot "chunks" from existing nodes. 260 The node providing "chunks" will fetch them from its local application using 261 the `LoadSnapshotChunk` method. 262 263 As the new node receives "chunks" it will apply them sequentially to the local 264 application with `ApplySnapshotChunk`. When all chunks have been applied, the application 265 `AppHash` is retrieved via an `Info` query. The `AppHash` is then compared to 266 the blockchain's `AppHash` which is verified via [light client verification](../spec/light-client/verification/README.md). 267 268 ## Messages 269 270 ### Echo 271 272 * **Request**: 273 * `Message (string)`: A string to echo back 274 * **Response**: 275 * `Message (string)`: The input string 276 * **Usage**: 277 * Echo a string to test an abci client/server implementation 278 279 ### Flush 280 281 * **Usage**: 282 * Signals that messages queued on the client should be flushed to 283 the server. It is called periodically by the client 284 implementation to ensure asynchronous requests are actually 285 sent, and is called immediately to make a synchronous request, 286 which returns when the Flush response comes back. 287 288 ### Info 289 290 * **Request**: 291 292 | Name | Type | Description | Field Number | 293 |---------------|--------|------------------------------------------|--------------| 294 | version | string | The Tendermint software semantic version | 1 | 295 | block_version | uint64 | The Tendermint Block Protocol version | 2 | 296 | p2p_version | uint64 | The Tendermint P2P Protocol version | 3 | 297 | abci_version | string | The Tendermint ABCI semantic version | 4 | 298 299 * **Response**: 300 301 | Name | Type | Description | Field Number | 302 |---------------------|--------|--------------------------------------------------|--------------| 303 | data | string | Some arbitrary information | 1 | 304 | version | string | The application software semantic version | 2 | 305 | app_version | uint64 | The application protocol version | 3 | 306 | last_block_height | int64 | Latest block for which the app has called Commit | 4 | 307 | last_block_app_hash | bytes | Latest result of Commit | 5 | 308 309 * **Usage**: 310 * Return information about the application state. 311 * Used to sync Tendermint with the application during a handshake 312 that happens on startup. 313 * The returned `app_version` will be included in the Header of every block. 314 * Tendermint expects `last_block_app_hash` and `last_block_height` to 315 be updated during `Commit`, ensuring that `Commit` is never 316 called twice for the same block height. 317 318 > Note: Semantic version is a reference to [semantic versioning](https://semver.org/). Semantic versions in info will be displayed as X.X.x. 319 320 ### InitChain 321 322 * **Request**: 323 324 | Name | Type | Description | Field Number | 325 |------------------|--------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|--------------| 326 | time | [google.protobuf.Timestamp](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp) | Genesis time | 1 | 327 | chain_id | string | ID of the blockchain. | 2 | 328 | consensus_params | [ConsensusParams](#consensusparams) | Initial consensus-critical parameters. | 3 | 329 | validators | repeated [ValidatorUpdate](#validatorupdate) | Initial genesis validators, sorted by voting power. | 4 | 330 | app_state_bytes | bytes | Serialized initial application state. JSON bytes. | 5 | 331 | initial_height | int64 | Height of the initial block (typically `1`). | 6 | 332 333 * **Response**: 334 335 | Name | Type | Description | Field Number | 336 |------------------|----------------------------------------------|-------------------------------------------------|--------------| 337 | consensus_params | [ConsensusParams](#consensusparams) | Initial consensus-critical parameters (optional | 1 | 338 | validators | repeated [ValidatorUpdate](#validatorupdate) | Initial validator set (optional). | 2 | 339 | app_hash | bytes | Initial application hash. | 3 | 340 341 * **Usage**: 342 * Called once upon genesis. 343 * If ResponseInitChain.Validators is empty, the initial validator set will be the RequestInitChain.Validators 344 * If ResponseInitChain.Validators is not empty, it will be the initial 345 validator set (regardless of what is in RequestInitChain.Validators). 346 * This allows the app to decide if it wants to accept the initial validator 347 set proposed by tendermint (ie. in the genesis file), or if it wants to use 348 a different one (perhaps computed based on some application specific 349 information in the genesis file). 350 351 ### Query 352 353 * **Request**: 354 355 | Name | Type | Description | Field Number | 356 |--------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| 357 | data | bytes | Raw query bytes. Can be used with or in lieu of Path. | 1 | 358 | path | string | Path field of the request URI. Can be used with or in lieu of `data`. Apps MUST interpret `/store` as a query by key on the underlying store. The key SHOULD be specified in the `data` field. Apps SHOULD allow queries over specific types like `/accounts/...` or `/votes/...` | 2 | 359 | height | int64 | The block height for which you want the query (default=0 returns data for the latest committed block). Note that this is the height of the block containing the application's Merkle root hash, which represents the state as it was after committing the block at Height-1 | 3 | 360 | prove | bool | Return Merkle proof with response if possible | 4 | 361 362 * **Response**: 363 364 | Name | Type | Description | Field Number | 365 |-----------|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| 366 | code | uint32 | Response code. | 1 | 367 | log | string | The output of the application's logger. **May be non-deterministic.** | 3 | 368 | info | string | Additional information. **May be non-deterministic.** | 4 | 369 | index | int64 | The index of the key in the tree. | 5 | 370 | key | bytes | The key of the matching data. | 6 | 371 | value | bytes | The value of the matching data. | 7 | 372 | proof_ops | [ProofOps](#proofops) | Serialized proof for the value data, if requested, to be verified against the `app_hash` for the given Height. | 8 | 373 | height | int64 | The block height from which data was derived. Note that this is the height of the block containing the application's Merkle root hash, which represents the state as it was after committing the block at Height-1 | 9 | 374 | codespace | string | Namespace for the `code`. | 10 | 375 376 * **Usage**: 377 * Query for data from the application at current or past height. 378 * Optionally return Merkle proof. 379 * Merkle proof includes self-describing `type` field to support many types 380 of Merkle trees and encoding formats. 381 382 ### BeginBlock 383 384 * **Request**: 385 386 | Name | Type | Description | Field Number | 387 |----------------------|---------------------------------------------|-------------------------------------------------------------------------------------------------------------------|--------------| 388 | hash | bytes | The block's hash. This can be derived from the block header. | 1 | 389 | header | [Header](../core/data_structures.md#header) | The block header. | 2 | 390 | last_commit_info | [LastCommitInfo](#lastcommitinfo) | Info about the last commit, including the round, and the list of validators and which ones signed the last block. | 3 | 391 | byzantine_validators | repeated [Evidence](#evidence) | List of evidence of validators that acted maliciously. | 4 | 392 393 * **Response**: 394 395 | Name | Type | Description | Field Number | 396 |--------|---------------------------|-------------------------------------|--------------| 397 | events | repeated [Event](#events) | type & Key-Value events for indexing | 1 | 398 399 * **Usage**: 400 * Signals the beginning of a new block. 401 * Called prior to any `DeliverTx` method calls. 402 * The header contains the height, timestamp, and more - it exactly matches the 403 Tendermint block header. We may seek to generalize this in the future. 404 * The `LastCommitInfo` and `ByzantineValidators` can be used to determine 405 rewards and punishments for the validators. 406 407 ### CheckTx 408 409 * **Request**: 410 411 | Name | Type | Description | Field Number | 412 |------|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| 413 | tx | bytes | The request transaction bytes | 1 | 414 | type | CheckTxType | One of `CheckTx_New` or `CheckTx_Recheck`. `CheckTx_New` is the default and means that a full check of the tranasaction is required. `CheckTx_Recheck` types are used when the mempool is initiating a normal recheck of a transaction. | 2 | 415 416 * **Response**: 417 418 | Name | Type | Description | Field Number | 419 |------------|---------------------------|-----------------------------------------------------------------------|--------------| 420 | code | uint32 | Response code. | 1 | 421 | data | bytes | Result bytes, if any. | 2 | 422 | log | string | The output of the application's logger. **May be non-deterministic.** | 3 | 423 | info | string | Additional information. **May be non-deterministic.** | 4 | 424 | gas_wanted | int64 | Amount of gas requested for transaction. | 5 | 425 | gas_used | int64 | Amount of gas consumed by transaction. | 6 | 426 | events | repeated [Event](#events) | Type & Key-Value events for indexing transactions (eg. by account). | 7 | 427 | codespace | string | Namespace for the `code`. | 8 | 428 | sender | string | The transaction's sender (e.g. the signer) | 9 | 429 | priority | int64 | The transaction's priority (for mempool ordering) | 10 | 430 431 * **Usage**: 432 433 * Technically optional - not involved in processing blocks. 434 * Guardian of the mempool: every node runs `CheckTx` before letting a 435 transaction into its local mempool. 436 * The transaction may come from an external user or another node 437 * `CheckTx` validates the transaction against the current state of the application, 438 for example, checking signatures and account balances, but does not apply any 439 of the state changes described in the transaction. 440 not running code in a virtual machine. 441 * Transactions where `ResponseCheckTx.Code != 0` will be rejected - they will not be broadcast to 442 other nodes or included in a proposal block. 443 * Tendermint attributes no other value to the response code 444 445 ### DeliverTx 446 447 * **Request**: 448 449 | Name | Type | Description | Field Number | 450 |------|-------|--------------------------------|--------------| 451 | tx | bytes | The request transaction bytes. | 1 | 452 453 * **Response**: 454 455 | Name | Type | Description | Field Number | 456 |------------|---------------------------|-----------------------------------------------------------------------|--------------| 457 | code | uint32 | Response code. | 1 | 458 | data | bytes | Result bytes, if any. | 2 | 459 | log | string | The output of the application's logger. **May be non-deterministic.** | 3 | 460 | info | string | Additional information. **May be non-deterministic.** | 4 | 461 | gas_wanted | int64 | Amount of gas requested for transaction. | 5 | 462 | gas_used | int64 | Amount of gas consumed by transaction. | 6 | 463 | events | repeated [Event](#events) | Type & Key-Value events for indexing transactions (eg. by account). | 7 | 464 | codespace | string | Namespace for the `code`. | 8 | 465 466 * **Usage**: 467 * [**Required**] The core method of the application. 468 * When `DeliverTx` is called, the application must execute the transaction in full before returning control to Tendermint. 469 * `ResponseDeliverTx.Code == 0` only if the transaction is fully valid. 470 471 ### EndBlock 472 473 * **Request**: 474 475 | Name | Type | Description | Field Number | 476 |--------|-------|------------------------------------|--------------| 477 | height | int64 | Height of the block just executed. | 1 | 478 479 * **Response**: 480 481 | Name | Type | Description | Field Number | 482 |-------------------------|----------------------------------------------|-----------------------------------------------------------------|--------------| 483 | validator_updates | repeated [ValidatorUpdate](#validatorupdate) | Changes to validator set (set voting power to 0 to remove). | 1 | 484 | consensus_param_updates | [ConsensusParams](#consensusparams) | Changes to consensus-critical time, size, and other parameters. | 2 | 485 | events | repeated [Event](#events) | Type & Key-Value events for indexing | 3 | 486 487 * **Usage**: 488 * Signals the end of a block. 489 * Called after all the transactions for the current block have been delivered, prior to the block's `Commit` message. 490 * Optional `validator_updates` triggered by block `H`. These updates affect validation 491 for blocks `H+1`, `H+2`, and `H+3`. 492 * Heights following a validator update are affected in the following way: 493 * `H+1`: `NextValidatorsHash` includes the new `validator_updates` value. 494 * `H+2`: The validator set change takes effect and `ValidatorsHash` is updated. 495 * `H+3`: `LastCommitInfo` is changed to include the altered validator set. 496 * `consensus_param_updates` returned for block `H` apply to the consensus 497 params for block `H+1`. For more information on the consensus parameters, 498 see the [application spec entry on consensus parameters](../spec/abci/apps.md#consensus-parameters). 499 500 ### Commit 501 502 * **Request**: 503 504 | Name | Type | Description | Field Number | 505 |--------|-------|------------------------------------|--------------| 506 507 Commit signals the application to persist application state. It takes no parameters. 508 * **Response**: 509 510 | Name | Type | Description | Field Number | 511 |---------------|-------|------------------------------------------------------------------------|--------------| 512 | data | bytes | The Merkle root hash of the application state. | 2 | 513 | retain_height | int64 | Blocks below this height may be removed. Defaults to `0` (retain all). | 3 | 514 515 * **Usage**: 516 * Signal the application to persist the application state. 517 * Return an (optional) Merkle root hash of the application state 518 * `ResponseCommit.Data` is included as the `Header.AppHash` in the next block 519 * it may be empty 520 * Later calls to `Query` can return proofs about the application state anchored 521 in this Merkle root hash 522 * Note developers can return whatever they want here (could be nothing, or a 523 constant string, etc.), so long as it is deterministic - it must not be a 524 function of anything that did not come from the 525 BeginBlock/DeliverTx/EndBlock methods. 526 * Use `RetainHeight` with caution! If all nodes in the network remove historical 527 blocks then this data is permanently lost, and no new nodes will be able to 528 join the network and bootstrap. Historical blocks may also be required for 529 other purposes, e.g. auditing, replay of non-persisted heights, light client 530 verification, and so on. 531 532 ### ListSnapshots 533 534 * **Request**: 535 536 | Name | Type | Description | Field Number | 537 |--------|-------|------------------------------------|--------------| 538 539 Empty request asking the application for a list of snapshots. 540 541 * **Response**: 542 543 | Name | Type | Description | Field Number | 544 |-----------|--------------------------------|--------------------------------|--------------| 545 | snapshots | repeated [Snapshot](#snapshot) | List of local state snapshots. | 1 | 546 547 * **Usage**: 548 * Used during state sync to discover available snapshots on peers. 549 * See `Snapshot` data type for details. 550 551 ### LoadSnapshotChunk 552 553 * **Request**: 554 555 | Name | Type | Description | Field Number | 556 |--------|--------|-----------------------------------------------------------------------|--------------| 557 | height | uint64 | The height of the snapshot the chunks belongs to. | 1 | 558 | format | uint32 | The application-specific format of the snapshot the chunk belongs to. | 2 | 559 | chunk | uint32 | The chunk index, starting from `0` for the initial chunk. | 3 | 560 561 * **Response**: 562 563 | Name | Type | Description | Field Number | 564 |-------|-------|-------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| 565 | chunk | bytes | The binary chunk contents, in an arbitray format. Chunk messages cannot be larger than 16 MB _including metadata_, so 10 MB is a good starting point. | 1 | 566 567 * **Usage**: 568 * Used during state sync to retrieve snapshot chunks from peers. 569 570 ### OfferSnapshot 571 572 * **Request**: 573 574 | Name | Type | Description | Field Number | 575 |----------|-----------------------|--------------------------------------------------------------------------|--------------| 576 | snapshot | [Snapshot](#snapshot) | The snapshot offered for restoration. | 1 | 577 | app_hash | bytes | The light client-verified app hash for this height, from the blockchain. | 2 | 578 579 * **Response**: 580 581 | Name | Type | Description | Field Number | 582 |--------|-------------------|-----------------------------------|--------------| 583 | result | [Result](#result) | The result of the snapshot offer. | 1 | 584 585 #### Result 586 587 ```proto 588 enum Result { 589 UNKNOWN = 0; // Unknown result, abort all snapshot restoration 590 ACCEPT = 1; // Snapshot is accepted, start applying chunks. 591 ABORT = 2; // Abort snapshot restoration, and don't try any other snapshots. 592 REJECT = 3; // Reject this specific snapshot, try others. 593 REJECT_FORMAT = 4; // Reject all snapshots with this `format`, try others. 594 REJECT_SENDER = 5; // Reject all snapshots from all senders of this snapshot, try others. 595 } 596 ``` 597 598 * **Usage**: 599 * `OfferSnapshot` is called when bootstrapping a node using state sync. The application may 600 accept or reject snapshots as appropriate. Upon accepting, Tendermint will retrieve and 601 apply snapshot chunks via `ApplySnapshotChunk`. The application may also choose to reject a 602 snapshot in the chunk response, in which case it should be prepared to accept further 603 `OfferSnapshot` calls. 604 * Only `AppHash` can be trusted, as it has been verified by the light client. Any other data 605 can be spoofed by adversaries, so applications should employ additional verification schemes 606 to avoid denial-of-service attacks. The verified `AppHash` is automatically checked against 607 the restored application at the end of snapshot restoration. 608 * For more information, see the `Snapshot` data type or the [state sync section](../spec/p2p/messages/state-sync.md). 609 610 ### ApplySnapshotChunk 611 612 * **Request**: 613 614 | Name | Type | Description | Field Number | 615 |--------|--------|-----------------------------------------------------------------------------|--------------| 616 | index | uint32 | The chunk index, starting from `0`. Tendermint applies chunks sequentially. | 1 | 617 | chunk | bytes | The binary chunk contents, as returned by `LoadSnapshotChunk`. | 2 | 618 | sender | string | The P2P ID of the node who sent this chunk. | 3 | 619 620 * **Response**: 621 622 | Name | Type | Description | Field Number | 623 |----------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| 624 | result | Result (see below) | The result of applying this chunk. | 1 | 625 | refetch_chunks | repeated uint32 | Refetch and reapply the given chunks, regardless of `result`. Only the listed chunks will be refetched, and reapplied in sequential order. | 2 | 626 | reject_senders | repeated string | Reject the given P2P senders, regardless of `Result`. Any chunks already applied will not be refetched unless explicitly requested, but queued chunks from these senders will be discarded, and new chunks or other snapshots rejected. | 3 | 627 628 ```proto 629 enum Result { 630 UNKNOWN = 0; // Unknown result, abort all snapshot restoration 631 ACCEPT = 1; // The chunk was accepted. 632 ABORT = 2; // Abort snapshot restoration, and don't try any other snapshots. 633 RETRY = 3; // Reapply this chunk, combine with `RefetchChunks` and `RejectSenders` as appropriate. 634 RETRY_SNAPSHOT = 4; // Restart this snapshot from `OfferSnapshot`, reusing chunks unless instructed otherwise. 635 REJECT_SNAPSHOT = 5; // Reject this snapshot, try a different one. 636 } 637 ``` 638 639 * **Usage**: 640 * The application can choose to refetch chunks and/or ban P2P peers as appropriate. Tendermint 641 will not do this unless instructed by the application. 642 * The application may want to verify each chunk, e.g. by attaching chunk hashes in 643 `Snapshot.Metadata` and/or incrementally verifying contents against `AppHash`. 644 * When all chunks have been accepted, Tendermint will make an ABCI `Info` call to verify that 645 `LastBlockAppHash` and `LastBlockHeight` matches the expected values, and record the 646 `AppVersion` in the node state. It then switches to fast sync or consensus and joins the 647 network. 648 * If Tendermint is unable to retrieve the next chunk after some time (e.g. because no suitable 649 peers are available), it will reject the snapshot and try a different one via `OfferSnapshot`. 650 The application should be prepared to reset and accept it or abort as appropriate. 651 652 ## Data Types 653 654 Most of the data structures used in ABCI are shared [common data structures](../spec/core/data_structures.md). In certain cases, ABCI uses different data structures which are documented here: 655 656 ### Validator 657 658 * **Fields**: 659 660 | Name | Type | Description | Field Number | 661 |---------|-------|---------------------------------------------------------------------|--------------| 662 | address | bytes | [Address](../core/data_structures.md#address) of validator | 1 | 663 | power | int64 | Voting power of the validator | 3 | 664 665 * **Usage**: 666 * Validator identified by address 667 * Used in RequestBeginBlock as part of VoteInfo 668 * Does not include PubKey to avoid sending potentially large quantum pubkeys 669 over the ABCI 670 671 ### ValidatorUpdate 672 673 * **Fields**: 674 675 | Name | Type | Description | Field Number | 676 |---------|--------------------------------------------------|-------------------------------|--------------| 677 | pub_key | [Public Key](../core/data_structures.md#pub_key) | Public key of the validator | 1 | 678 | power | int64 | Voting power of the validator | 2 | 679 680 * **Usage**: 681 * Validator identified by PubKey 682 * Used to tell Tendermint to update the validator set 683 684 ### VoteInfo 685 686 * **Fields**: 687 688 | Name | Type | Description | Field Number | 689 |-------------------|-------------------------|--------------------------------------------------------------|--------------| 690 | validator | [Validator](#validator) | A validator | 1 | 691 | signed_last_block | bool | Indicates whether or not the validator signed the last block | 2 | 692 693 * **Usage**: 694 * Indicates whether a validator signed the last block, allowing for rewards 695 based on validator availability 696 697 ### Evidence 698 699 * **Fields**: 700 701 | Name | Type | Description | Field Number | 702 |--------------------|--------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|--------------| 703 | type | [EvidenceType](#evidencetype) | Type of the evidence. An enum of possible evidence's. | 1 | 704 | validator | [Validator](#validator) | The offending validator | 2 | 705 | height | int64 | Height when the offense occurred | 3 | 706 | time | [google.protobuf.Timestamp](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp) | Time of the block that was committed at the height that the offense occurred | 4 | 707 | total_voting_power | int64 | Total voting power of the validator set at height `Height` | 5 | 708 709 #### EvidenceType 710 711 * **Fields** 712 713 EvidenceType is an enum with the listed fields: 714 715 | Name | Field Number | 716 |---------------------|--------------| 717 | UNKNOWN | 0 | 718 | DUPLICATE_VOTE | 1 | 719 | LIGHT_CLIENT_ATTACK | 2 | 720 721 ### LastCommitInfo 722 723 * **Fields**: 724 725 | Name | Type | Description | Field Number | 726 |-------|--------------------------------|-----------------------------------------------------------------------------------------------------------------------|--------------| 727 | round | int32 | Commit round. Reflects the total amount of rounds it took to come to consensus for the current block. | 1 | 728 | votes | repeated [VoteInfo](#voteinfo) | List of validators addresses in the last validator set with their voting power and whether or not they signed a vote. | 2 | 729 730 ### ConsensusParams 731 732 * **Fields**: 733 734 | Name | Type | Description | Field Number | 735 |-----------|---------------------------------------------------------------|------------------------------------------------------------------------------|--------------| 736 | block | [BlockParams](../core/data_structures.md#blockparams) | Parameters limiting the size of a block and time between consecutive blocks. | 1 | 737 | evidence | [EvidenceParams](../core/data_structures.md#evidenceparams) | Parameters limiting the validity of evidence of byzantine behaviour. | 2 | 738 | validator | [ValidatorParams](../core/data_structures.md#validatorparams) | Parameters limiting the types of public keys validators can use. | 3 | 739 | version | [VersionsParams](../core/data_structures.md#versionparams) | The ABCI application version. | 4 | 740 741 ### ProofOps 742 743 * **Fields**: 744 745 | Name | Type | Description | Field Number | 746 |------|------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| 747 | ops | repeated [ProofOp](#proofop) | List of chained Merkle proofs, of possibly different types. The Merkle root of one op is the value being proven in the next op. The Merkle root of the final op should equal the ultimate root hash being verified against.. | 1 | 748 749 ### ProofOp 750 751 * **Fields**: 752 753 | Name | Type | Description | Field Number | 754 |------|--------|------------------------------------------------|--------------| 755 | type | string | Type of Merkle proof and how it's encoded. | 1 | 756 | key | bytes | Key in the Merkle tree that this proof is for. | 2 | 757 | data | bytes | Encoded Merkle proof for the key. | 3 | 758 759 ### Snapshot 760 761 * **Fields**: 762 763 | Name | Type | Description | Field Number | 764 |----------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| 765 | height | uint64 | The height at which the snapshot was taken (after commit). | 1 | 766 | format | uint32 | An application-specific snapshot format, allowing applications to version their snapshot data format and make backwards-incompatible changes. Tendermint does not interpret this. | 2 | 767 | chunks | uint32 | The number of chunks in the snapshot. Must be at least 1 (even if empty). | 3 | 768 | hash | bytes | TAn arbitrary snapshot hash. Must be equal only for identical snapshots across nodes. Tendermint does not interpret the hash, it only compares them. | 3 | 769 | metadata | bytes | Arbitrary application metadata, for example chunk hashes or other verification data. | 3 | 770 771 * **Usage**: 772 * Used for state sync snapshots, see the [state sync section](../spec/p2p/messages/state-sync.md) for details. 773 * A snapshot is considered identical across nodes only if _all_ fields are equal (including 774 `Metadata`). Chunks may be retrieved from all nodes that have the same snapshot. 775 * When sent across the network, a snapshot message can be at most 4 MB.