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