types.proto

syntax = "proto3";
package tendermint.abci;

option go_package = "github.com/tendermint/tendermint/abci/types";

import "tendermint/crypto/proof.proto";
import "tendermint/crypto/keys.proto";
import "tendermint/types/params.proto";
import "tendermint/types/types.proto";
import "google/protobuf/timestamp.proto";
import "gogoproto/gogo.proto";

// This file is copied from http://github.com/tendermint/abci
// NOTE: When using custom types, mind the warnings.
// https://github.com/gogo/protobuf/blob/master/custom_types.md#warnings-and-issues

//----------------------------------------
// Request types

message Request {
  oneof value {
    RequestEcho                echo                  = 1;
    RequestFlush               flush                 = 2;
    RequestInfo                info                  = 3;
    RequestInitChain           init_chain            = 4;
    RequestQuery               query                 = 5;
    RequestCheckTx             check_tx              = 7;
    RequestCommit              commit                = 10;
    RequestListSnapshots       list_snapshots        = 11;
    RequestOfferSnapshot       offer_snapshot        = 12;
    RequestLoadSnapshotChunk   load_snapshot_chunk   = 13;
    RequestApplySnapshotChunk  apply_snapshot_chunk  = 14;
    RequestPrepareProposal     prepare_proposal      = 15;
    RequestProcessProposal     process_proposal      = 16;
    RequestExtendVote          extend_vote           = 17;
    RequestVerifyVoteExtension verify_vote_extension = 18;
    RequestFinalizeBlock       finalize_block        = 19;
    RequestBeginBlock         begin_block          = 20;
    RequestDeliverTx          deliver_tx           = 21;
    RequestEndBlock           end_block            = 22;
    RequestLoadLatest load_latest = 23;
  }
  reserved 6, 8, 9; // RequestBeginBlock, RequestDeliverTx, RequestEndBlock
}

message RequestEcho {
  string message = 1;
}

message RequestFlush {}

message RequestInfo {
  string version       = 1;
  uint64 block_version = 2;
  uint64 p2p_version   = 3;
  string abci_version  = 4;
}

message RequestInitChain {
  google.protobuf.Timestamp        time             = 1 [(gogoproto.nullable) = false, (gogoproto.stdtime) = true];
  string                           chain_id         = 2;
  tendermint.types.ConsensusParams consensus_params = 3;
  repeated ValidatorUpdate         validators       = 4 [(gogoproto.nullable) = false];
  bytes                            app_state_bytes  = 5;
  int64                            initial_height   = 6;
}

message RequestQuery {
  bytes  data   = 1;
  string path   = 2;
  int64  height = 3;
  bool   prove  = 4;
}

enum CheckTxType {
  NEW     = 0 [(gogoproto.enumvalue_customname) = "New"];
  RECHECK = 1 [(gogoproto.enumvalue_customname) = "Recheck"];
}

message RequestCheckTx {
  bytes       tx   = 1;
  CheckTxType type = 2;
}

message RequestCommit {}

// lists available snapshots
message RequestListSnapshots {}

// offers a snapshot to the application
message RequestOfferSnapshot {
  Snapshot snapshot = 1;  // snapshot offered by peers
  bytes    app_hash = 2;  // light client-verified app hash for snapshot height
}

// loads a snapshot chunk
message RequestLoadSnapshotChunk {
  uint64 height = 1;
  uint32 format = 2;
  uint32 chunk  = 3;
}

// Applies a snapshot chunk
message RequestApplySnapshotChunk {
  uint32 index  = 1;
  bytes  chunk  = 2;
  string sender = 3;
}

message RequestPrepareProposal {
  // the modified transactions cannot exceed this size.
  int64 max_tx_bytes = 1;
  // txs is an array of transactions that will be included in a block,
  // sent to the app for possible modifications.
  repeated bytes            txs                  = 2;
  ExtendedCommitInfo        local_last_commit    = 3 [(gogoproto.nullable) = false];
  repeated Misbehavior      byzantine_validators = 4 [(gogoproto.nullable) = false];
  int64                     height               = 5;
  google.protobuf.Timestamp time                 = 6 [(gogoproto.nullable) = false, (gogoproto.stdtime) = true];
  bytes                     next_validators_hash = 7;
  // address of the public key of the validator proposing the block.
  bytes proposer_address = 8;
  bytes app_hash = 9;
  bytes validators_hash = 10;
  bytes consensus_hash = 11;
  bytes data_hash = 12;
  bytes evidence_hash = 13;
  bytes last_block_hash = 14;
  int64 last_block_part_set_total = 15;
  bytes last_block_part_set_hash = 16;
  bytes last_commit_hash = 17;
  bytes last_results_hash = 18;
}

message RequestProcessProposal {
  repeated bytes       txs                  = 1;
  CommitInfo           proposed_last_commit = 2 [(gogoproto.nullable) = false];
  repeated Misbehavior byzantine_validators = 3 [(gogoproto.nullable) = false];
  // hash is the merkle root hash of the fields of the proposed block.
  bytes                     hash                 = 4;
  int64                     height               = 5;
  google.protobuf.Timestamp time                 = 6 [(gogoproto.nullable) = false, (gogoproto.stdtime) = true];
  bytes                     next_validators_hash = 7;
  // address of the public key of the original proposer of the block.
  bytes proposer_address = 8;
  bytes app_hash = 10;
  bytes validators_hash = 11;
  bytes consensus_hash = 12;
  bytes data_hash = 13;
  bytes evidence_hash = 14;
  bytes last_block_hash = 15;
  int64 last_block_part_set_total = 16;
  bytes last_block_part_set_hash = 17;
  bytes last_commit_hash = 18;
  bytes last_results_hash = 19;
}

// Extends a vote with application-side injection
message RequestExtendVote {
  bytes hash   = 1;
  int64 height = 2;
}

// Verify the vote extension
message RequestVerifyVoteExtension {
  bytes hash              = 1;
  bytes validator_address = 2;
  int64 height            = 3;
  bytes vote_extension    = 4;
}

message RequestFinalizeBlock {
  repeated bytes       txs                  = 1;
  CommitInfo           decided_last_commit  = 2 [(gogoproto.nullable) = false];
  repeated Misbehavior byzantine_validators = 3 [(gogoproto.nullable) = false];
  // hash is the merkle root hash of the fields of the proposed block.
  bytes                     hash                 = 4;
  int64                     height               = 5;
  google.protobuf.Timestamp time                 = 6 [(gogoproto.nullable) = false, (gogoproto.stdtime) = true];
  bytes                     next_validators_hash = 7;
  // proposer_address is the address of the public key of the original proposer of the block.
  bytes proposer_address = 8;
  bytes app_hash = 10;
  bytes validators_hash = 11;
  bytes consensus_hash = 12;
  bytes data_hash = 13;
  bytes evidence_hash = 14;
  bytes last_block_hash = 15;
  int64 last_block_part_set_total = 16;
  bytes last_block_part_set_hash = 17;
  bytes last_commit_hash = 18;
  bytes last_results_hash = 19;
}

message RequestBeginBlock {
  bytes                   hash                 = 1;
  tendermint.types.Header header               = 2 [(gogoproto.nullable) = false];
  LastCommitInfo          last_commit_info     = 3 [(gogoproto.nullable) = false];
  repeated Evidence       byzantine_validators = 4 [(gogoproto.nullable) = false];
  bool                    simulate             = 5;
}

message RequestDeliverTx {
  bytes tx = 1;
  bool sig_verified = 2;
}

message RequestEndBlock {
  int64 height = 1;
  int64 block_gas_used = 2;
}

message RequestLoadLatest {}

//----------------------------------------
// Response types

message Response {
  oneof value {
    ResponseException           exception             = 1;
    ResponseEcho                echo                  = 2;
    ResponseFlush               flush                 = 3;
    ResponseInfo                info                  = 4;
    ResponseInitChain           init_chain            = 5;
    ResponseQuery               query                 = 6;
    ResponseCheckTx             check_tx              = 8;
    ResponseCommit              commit                = 11;
    ResponseListSnapshots       list_snapshots        = 12;
    ResponseOfferSnapshot       offer_snapshot        = 13;
    ResponseLoadSnapshotChunk   load_snapshot_chunk   = 14;
    ResponseApplySnapshotChunk  apply_snapshot_chunk  = 15;
    ResponsePrepareProposal     prepare_proposal      = 16;
    ResponseProcessProposal     process_proposal      = 17;
    ResponseExtendVote          extend_vote           = 18;
    ResponseVerifyVoteExtension verify_vote_extension = 19;
    ResponseFinalizeBlock       finalize_block        = 20;
    ResponseBeginBlock         begin_block          = 21;
    ResponseDeliverTx          deliver_tx           = 22;
    ResponseEndBlock           end_block            = 23;
    ResponseLoadLatest load_latest = 24;
  }
  reserved 7, 9, 10; // ResponseBeginBlock, ResponseDeliverTx, ResponseEndBlock
}

// nondeterministic
message ResponseException {
  string error = 1;
}

message ResponseEcho {
  string message = 1;
}

message ResponseFlush {}

message ResponseInfo {
  string data = 1;

  // this is the software version of the application. TODO: remove?
  string version     = 2;
  uint64 app_version = 3;

  int64 last_block_height   = 4;
  bytes last_block_app_hash = 5;
  string minimum_gas_prices = 6;
}

message ResponseInitChain {
  tendermint.types.ConsensusParams consensus_params = 1;
  repeated ValidatorUpdate         validators       = 2 [(gogoproto.nullable) = false];
  bytes                            app_hash         = 3;
}

message ResponseQuery {
  uint32 code = 1;
  // bytes data = 2; // use "value" instead.
  string                     log       = 3;  // nondeterministic
  string                     info      = 4;  // nondeterministic
  int64                      index     = 5;
  bytes                      key       = 6;
  bytes                      value     = 7;
  tendermint.crypto.ProofOps proof_ops = 8;
  int64                      height    = 9;
  string                     codespace = 10;
}

message ResponseBeginBlock {
  repeated Event events = 1
      [(gogoproto.nullable) = false, (gogoproto.jsontag) = "events,omitempty"];
}

message ResponseCheckTx {
  uint32         code       = 1;
  bytes          data       = 2;
  string         log        = 3;  // nondeterministic
  int64          gas_wanted = 5;
  string         codespace  = 8;
  string         sender     = 9;
  int64          priority   = 10;
  int64          gas_estimated = 12;

  reserved 4, 6, 7, 11; // see https://github.com/tendermint/tendermint/issues/8543
}

message ResponseDeliverTx {
  uint32         code       = 1;
  bytes          data       = 2;
  string         log        = 3;  // nondeterministic
  string         info       = 4;  // nondeterministic
  int64          gas_wanted = 5 [json_name = "gas_wanted"];
  int64          gas_used   = 6 [json_name = "gas_used"];
  repeated Event events     = 7
      [(gogoproto.nullable) = false, (gogoproto.jsontag) = "events,omitempty"];  // nondeterministic
  string codespace = 8;
  EvmTxInfo evm_tx_info = 9;
}

message ResponseEndBlock {
  repeated ValidatorUpdate validator_updates = 1
      [(gogoproto.nullable) = false];
  ConsensusParams consensus_param_updates = 2;
  repeated Event  events                  = 3
      [(gogoproto.nullable) = false, (gogoproto.jsontag) = "events,omitempty"];
}

message ResponseCommit {
  // reserve 1
  int64 retain_height = 3;
}

message ResponseListSnapshots {
  repeated Snapshot snapshots = 1;
}

message ResponseOfferSnapshot {
  Result result = 1;

  enum Result {
    UNKNOWN       = 0;  // Unknown result, abort all snapshot restoration
    ACCEPT        = 1;  // Snapshot accepted, apply chunks
    ABORT         = 2;  // Abort all snapshot restoration
    REJECT        = 3;  // Reject this specific snapshot, try others
    REJECT_FORMAT = 4;  // Reject all snapshots of this format, try others
    REJECT_SENDER = 5;  // Reject all snapshots from the sender(s), try others
  }
}

message ResponseLoadSnapshotChunk {
  bytes chunk = 1;
}

message ResponseApplySnapshotChunk {
  Result          result         = 1;
  repeated uint32 refetch_chunks = 2;  // Chunks to refetch and reapply
  repeated string reject_senders = 3;  // Chunk senders to reject and ban

  enum Result {
    UNKNOWN         = 0;  // Unknown result, abort all snapshot restoration
    ACCEPT          = 1;  // Chunk successfully accepted
    ABORT           = 2;  // Abort all snapshot restoration
    RETRY           = 3;  // Retry chunk (combine with refetch and reject)
    RETRY_SNAPSHOT  = 4;  // Retry snapshot (combine with refetch and reject)
    REJECT_SNAPSHOT = 5;  // Reject this snapshot, try others
  }
}

message ResponsePrepareProposal {
  repeated TxRecord                tx_records              = 1;
  bytes                            app_hash                = 2;
  repeated ExecTxResult            tx_results              = 3;
  repeated ValidatorUpdate         validator_updates       = 4;
  tendermint.types.ConsensusParams consensus_param_updates = 5;
}

message ResponseProcessProposal {
  ProposalStatus                   status                  = 1;
  bytes                            app_hash                = 2;
  repeated ExecTxResult            tx_results              = 3;
  repeated ValidatorUpdate         validator_updates       = 4;
  tendermint.types.ConsensusParams consensus_param_updates = 5;

  enum ProposalStatus {
    UNKNOWN = 0;
    ACCEPT  = 1;
    REJECT  = 2;
  }
}

message ResponseExtendVote {
  bytes vote_extension = 1;
}

message ResponseVerifyVoteExtension {
  VerifyStatus status = 1;

  enum VerifyStatus {
    UNKNOWN = 0;
    ACCEPT  = 1;
    REJECT  = 2;
  }
}

message ResponseFinalizeBlock {
  repeated Event events = 1
      [(gogoproto.nullable) = false, (gogoproto.jsontag) = "events,omitempty"];
  repeated ExecTxResult            tx_results              = 2;
  repeated ValidatorUpdate         validator_updates       = 3 [(gogoproto.nullable) = false];
  tendermint.types.ConsensusParams consensus_param_updates = 4;
  bytes                            app_hash                = 5;
}

message ResponseLoadLatest {}

//----------------------------------------
// Misc.

message CommitInfo {
  int32             round = 1;
  repeated VoteInfo votes = 2 [(gogoproto.nullable) = false];
}

message LastCommitInfo {
  int32             round = 1;
  repeated VoteInfo votes = 2 [(gogoproto.nullable) = false];
}

// ExtendedCommitInfo is similar to CommitInfo except that it is only used in
// the PrepareProposal request such that Tendermint can provide vote extensions
// to the application.
message ExtendedCommitInfo {
  // The round at which the block proposer decided in the previous height.
  int32 round = 1;
  // List of validators' addresses in the last validator set with their voting
  // information, including vote extensions.
  repeated ExtendedVoteInfo votes = 2 [(gogoproto.nullable) = false];
}

// Event allows application developers to attach additional information to
// ResponseFinalizeBlock, ResponseDeliverTx, ExecTxResult
// Later, transactions may be queried using these events.
message Event {
  string                  type       = 1;
  repeated EventAttribute attributes = 2 [(gogoproto.nullable) = false, (gogoproto.jsontag) = "attributes,omitempty"];
}

// EventAttribute is a single key-value pair, associated with an event.
message EventAttribute {
  bytes  key   = 1;
  bytes  value = 2;
  bool   index = 3;  // nondeterministic
}

// ExecTxResult contains results of executing one individual transaction.
//
// * Its structure is equivalent to #ResponseDeliverTx which will be deprecated/deleted
message ExecTxResult {
  uint32         code       = 1;
  bytes          data       = 2;
  string         log        = 3;  // nondeterministic
  string         info       = 4;  // nondeterministic
  int64          gas_wanted = 5;
  int64          gas_used   = 6;
  repeated Event events     = 7
      [(gogoproto.nullable) = false, (gogoproto.jsontag) = "events,omitempty"];  // nondeterministic
  string codespace = 8;
  EvmTxInfo evm_tx_info = 9;
}

// TxResult contains results of executing the transaction.
//
// One usage is indexing transaction results.
message TxResult {
  int64        height = 1;
  uint32       index  = 2;
  bytes        tx     = 3;
  ExecTxResult result = 4 [(gogoproto.nullable) = false];
}

message TxRecord {
  TxAction action = 1;
  bytes    tx     = 2;

  // TxAction contains App-provided information on what to do with a transaction that is part of a raw proposal
  // Deprecate entire usage: https://github.com/tendermint/tendermint/pull/9283
  enum TxAction {
    UNMODIFIED = 0;  // The Application did not modify this transaction.
  }
}

message BlockParams {
  // Note: must be greater than 0
  int64 max_bytes = 1;
  // Note: must be greater or equal to -1
  int64 max_gas = 2;
  // Minimum txs to include in a block regardless of gas limit
  int64 min_txs_in_block = 3;
}

message ConsensusParams {
  BlockParams                      block     = 1;
  tendermint.types.EvidenceParams  evidence  = 2;
  tendermint.types.ValidatorParams validator = 3;
  tendermint.types.VersionParams   version   = 4;
}

//----------------------------------------
// Blockchain Types

// Validator
message Validator {
  bytes address = 1;  // The first 20 bytes of SHA256(public key)
  // PubKey pub_key = 2 [(gogoproto.nullable)=false];
  int64 power = 3;  // The voting power
}

// ValidatorUpdate
message ValidatorUpdate {
  tendermint.crypto.PublicKey pub_key = 1 [(gogoproto.nullable) = false];
  int64                       power   = 2;
}

// VoteInfo
message VoteInfo {
  Validator validator         = 1 [(gogoproto.nullable) = false];
  bool      signed_last_block = 2;
}

// ExtendedVoteInfo
message ExtendedVoteInfo {
  // The validator that sent the vote.
  Validator validator = 1 [(gogoproto.nullable) = false];
  // Indicates whether the validator signed the last block, allowing for rewards based on validator availability.
  bool signed_last_block = 2;
  // Non-deterministic extension provided by the sending validator's application.
  bytes vote_extension = 3;
}

enum MisbehaviorType {
  UNKNOWN             = 0;
  DUPLICATE_VOTE      = 1;
  LIGHT_CLIENT_ATTACK = 2;
}

message Misbehavior {
  MisbehaviorType type = 1;
  // The offending validator
  Validator validator = 2 [(gogoproto.nullable) = false];
  // The height when the offense occurred
  int64 height = 3;
  // The corresponding time where the offense occurred
  google.protobuf.Timestamp time = 4 [(gogoproto.nullable) = false, (gogoproto.stdtime) = true];
  // Total voting power of the validator set in case the ABCI application does
  // not store historical validators.
  // https://github.com/tendermint/tendermint/issues/4581
  int64 total_voting_power = 5;
}

message Evidence {
  MisbehaviorType type = 1;
  // The offending validator
  Validator validator = 2 [(gogoproto.nullable) = false];
  // The height when the offense occurred
  int64 height = 3;
  // The corresponding time where the offense occurred
  google.protobuf.Timestamp time = 4 [
    (gogoproto.nullable) = false,
    (gogoproto.stdtime)  = true
  ];
  // Total voting power of the validator set in case the ABCI application does
  // not store historical validators.
  // https://github.com/tendermint/tendermint/issues/4581
  int64 total_voting_power = 5;
}

message EvmTxInfo {
  string senderAddress = 1;
  uint64 nonce = 2;
  string txHash = 3;
  string vmError = 4;
}

//----------------------------------------
// State Sync Types

message Snapshot {
  uint64 height   = 1;  // The height at which the snapshot was taken
  uint32 format   = 2;  // The application-specific snapshot format
  uint32 chunks   = 3;  // Number of chunks in the snapshot
  bytes  hash     = 4;  // Arbitrary snapshot hash, equal only if identical
  bytes  metadata = 5;  // Arbitrary application metadata
}

//----------------------------------------
// Service Definition

service ABCIApplication {
  rpc Echo(RequestEcho) returns (ResponseEcho);
  rpc Flush(RequestFlush) returns (ResponseFlush);
  rpc Info(RequestInfo) returns (ResponseInfo);
  rpc CheckTx(RequestCheckTx) returns (ResponseCheckTx);
  rpc Query(RequestQuery) returns (ResponseQuery);
  rpc Commit(RequestCommit) returns (ResponseCommit);
  rpc InitChain(RequestInitChain) returns (ResponseInitChain);
  rpc ListSnapshots(RequestListSnapshots) returns (ResponseListSnapshots);
  rpc OfferSnapshot(RequestOfferSnapshot) returns (ResponseOfferSnapshot);
  rpc LoadSnapshotChunk(RequestLoadSnapshotChunk) returns (ResponseLoadSnapshotChunk);
  rpc ApplySnapshotChunk(RequestApplySnapshotChunk) returns (ResponseApplySnapshotChunk);
  rpc PrepareProposal(RequestPrepareProposal) returns (ResponsePrepareProposal);
  rpc ProcessProposal(RequestProcessProposal) returns (ResponseProcessProposal);
  rpc ExtendVote(RequestExtendVote) returns (ResponseExtendVote);
  rpc VerifyVoteExtension(RequestVerifyVoteExtension) returns (ResponseVerifyVoteExtension);
  rpc FinalizeBlock(RequestFinalizeBlock) returns (ResponseFinalizeBlock);
  rpc LoadLatest(RequestLoadLatest) returns (ResponseLoadLatest);
}