// Specification of the user facing gRPC API.
syntax = "proto3";
package rpc;

import "requests.proto";
import "responses.proto";

service Api {
    // Returns a nullifier proof for each of the requested nullifiers.
    rpc CheckNullifiers(requests.CheckNullifiersRequest) returns (responses.CheckNullifiersResponse) {}

    // Returns a list of nullifiers that match the specified prefixes and are recorded in the node.
    //
    // Note that only 16-bit prefixes are supported at this time.
    rpc CheckNullifiersByPrefix(requests.CheckNullifiersByPrefixRequest) returns (responses.CheckNullifiersByPrefixResponse) {}

    // Returns the latest state of an account with the specified ID.
    rpc GetAccountDetails(requests.GetAccountDetailsRequest) returns (responses.GetAccountDetailsResponse) {}

    // Returns the latest state proofs of the specified accounts.
    rpc GetAccountProofs(requests.GetAccountProofsRequest) returns (responses.GetAccountProofsResponse) {}

    // Returns delta of the account states in the range from `from_block_num` (exclusive) to
    // `to_block_num` (inclusive).
    rpc GetAccountStateDelta(requests.GetAccountStateDeltaRequest) returns (responses.GetAccountStateDeltaResponse) {}

    // Returns raw block data for the specified block number.
    rpc GetBlockByNumber(requests.GetBlockByNumberRequest) returns (responses.GetBlockByNumberResponse) {}

    // Retrieves block header by given block number. Optionally, it also returns the MMR path
    // and current chain length to authenticate the block's inclusion.
    rpc GetBlockHeaderByNumber(requests.GetBlockHeaderByNumberRequest) returns (responses.GetBlockHeaderByNumberResponse) {}

    // Returns a list of notes matching the provided note IDs.
    rpc GetNotesById(requests.GetNotesByIdRequest) returns (responses.GetNotesByIdResponse) {}

    // Submits proven transaction to the Miden network.
    rpc SubmitProvenTransaction(requests.SubmitProvenTransactionRequest) returns (responses.SubmitProvenTransactionResponse) {}

    // Returns info which can be used by the client to sync up to the tip of chain for the notes they are interested in.
    //
    // Client specifies the `note_tags` they are interested in, and the block height from which to search for new for
    // matching notes for. The request will then return the next block containing any note matching the provided tags.
    //
    // The response includes each note's metadata and inclusion proof.
    //
    // A basic note sync can be implemented by repeatedly requesting the previous response's block until reaching the
    // tip of the chain. 
    rpc SyncNotes(requests.SyncNoteRequest) returns (responses.SyncNoteResponse) {}

    // Returns info which can be used by the client to sync up to the latest state of the chain
    // for the objects (accounts and notes) the client is interested in.
    //
    // This request returns the next block containing requested data. It also returns `chain_tip`
    // which is the latest block number in the chain. Client is expected to repeat these requests
    // in a loop until `response.block_header.block_num == response.chain_tip`, at which point
    // the client is fully synchronized with the chain.
    //
    // Each update response also contains info about new notes, accounts etc. created. It also returns
    // Chain MMR delta that can be used to update the state of Chain MMR. This includes both chain
    // MMR peaks and chain MMR nodes.
    //
    // For preserving some degree of privacy, note tags contain only high
    // part of hashes. Thus, returned data contains excessive notes, client can make
    // additional filtering of that data on its side.
    rpc SyncState(requests.SyncStateRequest) returns (responses.SyncStateResponse) {}
}
