// Copyright (c) The Libra Core Contributors
// SPDX-License-Identifier: Apache-2.0

syntax = "proto3";

package execution;

import "get_with_proof.proto";
import "ledger_info.proto";
import "transaction.proto";
import "validator_set.proto";
import "vm_errors.proto";

// -----------------------------------------------------------------------------
// ---------------- Execution Service Definition
// -----------------------------------------------------------------------------
service Execution {
  // Execute a list of signed transactions given by consensus. Return the id
  // of the block and the root hash of the ledger after applying transactions
  // in this block.
  rpc ExecuteBlock(ExecuteBlockRequest) returns (ExecuteBlockResponse) {}

  // Commit a previously executed block that has been agreed by consensus.
  rpc CommitBlock(CommitBlockRequest) returns (CommitBlockResponse) {}

  // Execute and commit a list of signed transactions received from peer
  // during synchronization. Return the id of the block
  rpc ExecuteChunk(ExecuteChunkRequest) returns (ExecuteChunkResponse) {}
}

message ExecuteBlockRequest {
  // The list of transactions from consensus.
  repeated types.SignedTransaction transactions = 1;

  // Id of the parent block.
  // We're going to use a special GENESIS_BLOCK_ID constant defined in
  // crypto::hash module to refer to the block id of the Genesis block, which is
  // executed in a special way.
  bytes parent_block_id = 2;

  // Id of the current block.
  bytes block_id = 3;
}

// Result of transaction execution.
message ExecuteBlockResponse {
  // Root hash of the ledger after applying all the transactions in this
  // block.
  bytes root_hash = 1;

  // The execution result of the transactions. Each transaction has a status
  // field that indicates whether it should be included in the ledger once the
  // block is committed.
  repeated types.VMStatus status = 2;

  // The corresponding ledger version when this block is committed.
  uint64 version = 3;

  // If set, this field designates that if this block is committed, then the
  // next epoch will start immediately with the included set of validators.
  types.ValidatorSet validators = 4;
}

message CommitBlockRequest {
  // The ledger info with signatures from 2f+1 validators. It contains the id
  // of the block consensus wants to commit. This will cause the given block
  // and all the uncommitted ancestors to be committed to storage.
  types.LedgerInfoWithSignatures ledger_info_with_sigs = 1;
}

message CommitBlockResponse { CommitBlockStatus status = 1; }

enum CommitBlockStatus {
  // The block is persisted.
  SUCCEEDED = 0;

  // Something went wrong.
  FAILED = 1;
}

// Ask Execution service to execute and commit a chunk of contiguous
// transactions. All the transactions in this chunk should belong to the same
// epoch E. If the caller has a list of transactions that span two epochs, it
// should split the transactions.
message ExecuteChunkRequest {
  types.TransactionListWithProof txn_list_with_proof = 1;
  types.LedgerInfoWithSignatures ledger_info_with_sigs = 2;
}

// Either all transactions are successfully executed and persisted, or nothing
// happens.
message ExecuteChunkResponse {}