trillian_api.proto

syntax = "proto3";

option java_multiple_files = true;
option java_package = "com.google.trillian.proto";
option java_outer_classname = "TrillianApiProto";

package trillian;

import "trillian.proto";
import "google/protobuf/empty.proto";

// TrillianApiStatusCode is an application level status code
enum TrillianApiStatusCode {
    OK = 0;
    ERROR = 1;
}

// All operations return a TrillianApiStatus.
// TODO(Martin2112): Most of the operations are not fully defined yet. They will be implemented soon
message TrillianApiStatus {
    // The status code indicates the overall result of the operation.
    TrillianApiStatusCode status_code = 1;
    // Applications should not make assumptions about the contents of description. They
    // should use status_code only when making error handling decisions.
    string description = 2;
}

message LogLeaf {
    // merkle_leaf_hash is over leaf data and optional extra_data.
    bytes merkle_leaf_hash = 1;
    // leaf_value contains arbitrary data.
    bytes leaf_value = 2;
    // extra_data is optional metadata. e.g. a timestamp.
    bytes extra_data = 3;
    // leaf_index is optional. Trillian will assign the next available index when unset.
    // TODO: remove this into separate AddSequencedLeaves API.
    int64 leaf_index = 4;
    // leaf_identity_hash is a hash over the identity of this leaf.
    // It's intended to provide a mechanism for the personality to provide a
    // hint to Trillian that two leaves should be considered "duplicates" even
    // though their leaf_values differ.
    //
    // E.g. in a CT personality multiple add-chain calls for an identical
    // certificate would produce differing leaf_data bytes (due to the presence
    // of SCT elements), with just this information Trillian would be unable to
    // determine that, within the context of the personality, these entries are
    // dupes, so the CT personality sets leaf_identity_hash to H(cert),
    // which allows Trillian to detect the duplicates.
    //
    // Continuing the CT example, for a CT mirror personality (which must allow
    // dupes since the source log could contain them), the part of the
    // personality which fetches and submits the entries might set
    // leaf_identity_hash to H(seq||certdata).
    bytes leaf_identity_hash = 5;
}

message Node {
    bytes node_id = 1;
    bytes node_hash = 2;
    int64 node_revision = 3;
}

message Proof {
    int64 leaf_index = 1;
    repeated Node proof_node = 2;
}

message QueueLeavesRequest {
    int64 log_id = 1;
    repeated LogLeaf leaves = 2;
}

message QueueLeafRequest {
    int64 log_id = 1;
    LogLeaf leaf = 2;
}

// TODO(Martin2112): This will eventually contain the signed timestamps and stuff that we return for
// the queued leaves
message QueueLeavesResponse {
    TrillianApiStatus status = 1;
}

message GetInclusionProofRequest {
    int64 log_id = 1;
    int64 leaf_index = 2;
    int64 tree_size = 3;
}

message GetInclusionProofResponse {
    TrillianApiStatus status = 1;
    Proof proof = 2;
}

message GetInclusionProofByHashRequest {
    int64 log_id = 1;
    bytes leaf_hash = 2;
    int64 tree_size = 3;
    bool order_by_sequence = 4;
}

message GetInclusionProofByHashResponse {
    TrillianApiStatus status = 1;
    // Logs can potentially contain leaves with duplicate hashes so it's possible
    // for this to return multiple proofs.
    repeated Proof proof = 2;
}

message GetConsistencyProofRequest {
    int64 log_id = 1;
    int64 first_tree_size = 2;
    int64 second_tree_size = 3;
}

message GetConsistencyProofResponse {
    TrillianApiStatus status = 1;
    Proof proof = 2;
}

message GetLeavesByHashRequest {
    int64 log_id = 1;
    repeated bytes leaf_hash = 2;
    bool order_by_sequence = 3;
}

message GetLeavesByHashResponse {
    TrillianApiStatus status = 1;
    repeated LogLeaf leaves = 2;
}

message GetLeavesByIndexRequest {
    int64 log_id = 1;
    repeated int64 leaf_index = 2;
}

message GetLeavesByIndexResponse {
    TrillianApiStatus status = 1;
    repeated LogLeaf leaves = 2;
}

message GetSequencedLeafCountRequest {
    int64 log_id = 1;
}

message GetSequencedLeafCountResponse {
    TrillianApiStatus status = 1;
    int64 leaf_count = 2;
}

message GetLatestSignedLogRootRequest {
    int64 log_id = 1;
}

message GetLatestSignedLogRootResponse {
    TrillianApiStatus status = 1;
    SignedLogRoot signed_log_root = 2;
}

message GetEntryAndProofRequest {
    int64 log_id = 1;
    int64 leaf_index = 2;
    int64 tree_size = 3;
}

message GetEntryAndProofResponse {
    TrillianApiStatus status = 1;
    Proof proof = 2;
    LogLeaf leaf = 3;
}

// TrillianLog defines a service that can provide access to a Verifiable Log as defined in the
// Verifiable Data Structures paper. It provides direct access to a subset of storage APIs
// (for handling reads) and provides Log level ones such as being able to obtain proofs.
// Clients cannot directly modify the log data via this API.
service TrillianLog {
    // QueueLeaf adds a single leaf to the queue.
    rpc QueueLeaf (QueueLeafRequest) returns (google.protobuf.Empty) {}
    // Corresponds to the LeafQueuer API
    rpc QueueLeaves (QueueLeavesRequest) returns (QueueLeavesResponse) {
    }

    // No direct equivalent at the storage level
    rpc GetInclusionProof (GetInclusionProofRequest) returns (GetInclusionProofResponse) {
    }
    rpc GetInclusionProofByHash (GetInclusionProofByHashRequest) returns (GetInclusionProofByHashResponse) {
    }
    rpc GetConsistencyProof (GetConsistencyProofRequest) returns (GetConsistencyProofResponse) {
    }

    // Corresponds to the LogRootReader API
    rpc GetLatestSignedLogRoot (GetLatestSignedLogRootRequest) returns (GetLatestSignedLogRootResponse) {
    }

    // Corresponds to the LeafReader API
    rpc GetSequencedLeafCount (GetSequencedLeafCountRequest) returns (GetSequencedLeafCountResponse) {
    }
    rpc GetLeavesByIndex (GetLeavesByIndexRequest) returns (GetLeavesByIndexResponse) {
    }
    rpc GetLeavesByHash (GetLeavesByHashRequest) returns (GetLeavesByHashResponse) {
    }
    rpc GetEntryAndProof (GetEntryAndProofRequest) returns (GetEntryAndProofResponse) {
    }
}

// MapLeaf represents the data behind Map leaves.
message MapLeaf {
  // key_hash is the hash of the key for this leaf.
  bytes key_hash = 1;
  // leaf_hash is the tree hash of leaf_value.
  bytes leaf_hash = 2;
  // leaf_value is the data the tree commits to.
  bytes leaf_value = 3;
  // extra_data holds related contextual data, but is not covered by any hash.
  bytes extra_data = 4;
}

message KeyValue {
  bytes key = 1;
  MapLeaf value = 2;
}

message KeyValueInclusion {
  KeyValue key_value = 1;
  repeated bytes inclusion = 2;
}

message GetMapLeavesRequest {
  int64 map_id = 1;
  repeated bytes key = 2;
  int64 revision = 3;
}

message GetMapLeavesResponse {
  TrillianApiStatus status = 1;
  repeated KeyValueInclusion key_value = 2;
  SignedMapRoot map_root = 3;
}

message SetMapLeavesRequest {
  int64 map_id = 1;
  repeated KeyValue key_value = 2;
  MapperMetadata mapper_data = 3;
}

message SetMapLeavesResponse {
  TrillianApiStatus status = 1;
  SignedMapRoot map_root = 2;
}

message GetSignedMapRootRequest {
  int64 map_id = 1;
}

message GetSignedMapRootResponse {
  TrillianApiStatus status = 1;
  SignedMapRoot map_root = 2;
}

// TrillianMap defines a service which provides access to a Verifiable Map as
// defined in the Verifiable Data Structures paper.
service TrillianMap {
  rpc GetLeaves(GetMapLeavesRequest) returns(GetMapLeavesResponse) {}
  rpc SetLeaves(SetMapLeavesRequest) returns(SetMapLeavesResponse) {}
  rpc GetSignedMapRoot(GetSignedMapRootRequest) returns(GetSignedMapRootResponse) {}
}