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

syntax = "proto3";

package admission_control;

import "get_with_proof.proto";
import "mempool_status.proto";
import "transaction.proto";
import "vm_errors.proto";

// -----------------------------------------------------------------------------
// ---------------- Submit transaction
// -----------------------------------------------------------------------------
// The request for transaction submission.
message SubmitTransactionRequest {
  // Transaction signed by wallet.
  types.SignedTransaction signed_txn = 1;
}

// AC response status containing code and optionally an error message.
message AdmissionControlStatus {
  AdmissionControlStatusCode code = 1;
  string message = 2;
}

// Additional statuses that are possible from admission control in addition
// to VM statuses.
enum AdmissionControlStatusCode {
  // Validator accepted the transaction.
  Accepted = 0;
  // The sender is blacklisted.
  Blacklisted = 1;
  // The transaction is rejected, e.g. due to incorrect signature.
  Rejected = 2;
}

// The response for transaction submission.
//
// How does a client know if their transaction was included?
// A response from the transaction submission only means that the transaction
// was successfully added to mempool, but not that it is guaranteed to be
// included in the chain.  Each transaction should include an expiration time in
// the signed transaction.  Let's call this T0.  As a client, I submit my
// transaction to a validator. I now need to poll for the transaction I
// submitted.  I can use the query that takes my account and sequence number. If
// I receive back that the transaction is completed, I will verify the proofs to
// ensure that this is the transaction I expected.  If I receive a response that
// my transaction is not yet completed, I must check the latest timestamp in the
// ledgerInfo that I receive back from the query.  If this time is greater than
// T0, I can be certain that my transaction will never be included.  If this
// time is less than T0, I need to continue polling.
message SubmitTransactionResponse {
  // The status of a transaction submission can either be a VM status, or
  // some other admission control/mempool specific status e.g. Blacklisted.
  oneof status {
    types.VMStatus vm_status = 1;
    AdmissionControlStatus ac_status = 2;
    mempool.MempoolAddTransactionStatus mempool_status = 3;
  }
  // Public key(id) of the validator that processed this transaction
  bytes validator_id = 4;
}

// -----------------------------------------------------------------------------
// ---------------- Service definition
// -----------------------------------------------------------------------------
service AdmissionControl {
  // Public API to submit transaction to a validator.
  rpc SubmitTransaction(SubmitTransactionRequest)
      returns (SubmitTransactionResponse) {}

  // This API is used to update the client to the latest ledger version and
  // optionally also request 1..n other pieces of data.  This allows for batch
  // queries.  All queries return proofs that a client should check to validate
  // the data. Note that if a client only wishes to update to the latest
  // LedgerInfo and receive the proof of this latest version, they can simply
  // omit the requested_items (or pass an empty list)
  rpc UpdateToLatestLedger(
      types.UpdateToLatestLedgerRequest)
      returns (types.UpdateToLatestLedgerResponse) {}
}