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

syntax = "proto3";

package storage;

import "get_with_proof.proto";
import "ledger_info.proto";
import "transaction.proto";
import "account_state_blob.proto";
import "proof.proto";

// -----------------------------------------------------------------------------
// ---------------- Service definition for storage
// -----------------------------------------------------------------------------
service Storage {
    // Write APIs.

    // Persist transactions. Called by Execution when either syncing nodes or
    // committing blocks during normal operation.
    rpc SaveTransactions(SaveTransactionsRequest)
    returns (SaveTransactionsResponse);

    // Read APIs.

    // Used to get a piece of data and return the proof of it. If the client
    // knows and trusts a ledger info at version v, it should pass v in as the
    // client_known_version and we will return the latest ledger info together
    // with the proof that it derives from v.
    rpc UpdateToLatestLedger(
    types.UpdateToLatestLedgerRequest)
    returns (types.UpdateToLatestLedgerResponse);

    // When we receive a request from a peer validator asking a list of
    // transactions for state synchronization, this API can be used to serve the
    // request. Note that the peer should specify a ledger version and all proofs
    // in the response will be relative to this given ledger version.
    rpc GetTransactions(GetTransactionsRequest) returns (GetTransactionsResponse);

    rpc GetAccountStateWithProofByVersion(
    GetAccountStateWithProofByVersionRequest)
    returns (GetAccountStateWithProofByVersionResponse);

    // Returns information needed for libra core to start up.
    rpc GetStartupInfo(GetStartupInfoRequest)
    returns (GetStartupInfoResponse);
}

message SaveTransactionsRequest {
    // Transactions to persist.
    repeated types.TransactionToCommit txns_to_commit = 1;

    // The version of the first transaction in `txns_to_commit`.
    uint64 first_version = 2;

    // If this is set, Storage will check its state after applying the above
    // transactions matches info in this LedgerInfo before committing otherwise
    // it denies the request.
    types.LedgerInfoWithSignatures ledger_info_with_signatures = 3;
}

message SaveTransactionsResponse {}

message GetTransactionsRequest {
    // The version to start with.
    uint64 start_version = 1;
    // The size of the transaction batch.
    uint64 batch_size = 2;
    // All the proofs returned in the response should be relative to this
    // given version.
    uint64 ledger_version = 3;
    // Used to return the events associated with each transaction
    bool fetch_events = 4;
}

message GetTransactionsResponse {
    types.TransactionListWithProof txn_list_with_proof = 1;
}

message GetAccountStateWithProofByVersionRequest {
    /// The account address to query with.
    bytes address = 1;

    /// The version the query is based on.
    uint64 version = 2;
}

message GetAccountStateWithProofByVersionResponse {
    /// The optional blob of account state blob.
    types.AccountStateBlob account_state_blob = 1;

    /// The state root hash the query is based on.
    types.SparseMerkleProof sparse_merkle_proof = 2;
}

message GetStartupInfoRequest {}

message GetStartupInfoResponse {
    // When this is empty, Storage needs to be bootstrapped via the bootstrap API
    StartupInfo info = 1;
}

message StartupInfo {
    // The latest LedgerInfo. Note that at start up storage can have more
    // transactions than the latest LedgerInfo indicates due to an incomplete
    // start up sync.
    types.LedgerInfo ledger_info = 1;
    // The latest version. All fields below are based on this version.
    uint64 latest_version = 2;
    // The latest account state root hash.
    bytes account_state_root_hash = 3;
    // From left to right, root hashes of all frozen subtrees.
    repeated bytes ledger_frozen_subtree_hashes = 4;
}