github.com/lukehinds/trillian@v1.2.1/trillian_map_api.proto (about)

     1  // Copyright 2016 Google Inc. All Rights Reserved.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  syntax = "proto3";
    16  
    17  option java_multiple_files = true;
    18  option java_package = "com.google.trillian.proto";
    19  option java_outer_classname = "TrillianMapApiProto";
    20  option go_package = "github.com/google/trillian";
    21  
    22  package trillian;
    23  
    24  import "trillian.proto";
    25  import "google/api/annotations.proto";
    26  
    27  // MapLeaf represents the data behind Map leaves.
    28  message MapLeaf {
    29    // index is the location of this leaf.
    30    // All indexes for a given Map must contain a constant number of bits.
    31    // These are not numeric indices. Note that this is typically derived using a
    32    // hash and thus the length of all indices in the map will match the number
    33    // of bits in the hash function. Map entries do not have a well defined
    34    // ordering and it's not possible to sequentially iterate over them.
    35    bytes index = 1;
    36    // leaf_hash is the tree hash of leaf_value.  This does not need to be set
    37    // on SetMapLeavesRequest; the server will fill it in.
    38    bytes leaf_hash = 2;
    39    // leaf_value is the data the tree commits to.
    40    bytes leaf_value = 3;
    41    // extra_data holds related contextual data, but is not covered by any hash.
    42    bytes extra_data = 4;
    43  }
    44  
    45  message MapLeafInclusion {
    46    MapLeaf leaf = 1;
    47    repeated bytes inclusion = 2;
    48  }
    49  
    50  message GetMapLeavesRequest {
    51    int64 map_id = 1;
    52    repeated bytes index = 2;
    53    reserved 3;  // was 'revision'
    54  }
    55  
    56  // This message replaces the current implementation of GetMapLeavesRequest
    57  // with the difference that revision must be >=0.
    58  message GetMapLeavesByRevisionRequest {
    59    int64 map_id = 1;
    60    repeated bytes index = 2;
    61    // revision >= 0.
    62    int64 revision = 3;
    63  }
    64  
    65  message GetMapLeavesResponse {
    66    repeated MapLeafInclusion map_leaf_inclusion = 2;
    67    SignedMapRoot map_root = 3;
    68  }
    69  
    70  message SetMapLeavesRequest {
    71    int64 map_id = 1;
    72    // The leaves being set must have unique Index values within the request.
    73    repeated MapLeaf leaves = 2;
    74    reserved 3;  // was MapperMetadata (removed, replaced by metadata).
    75    // Metadata that the Map should associate with the new Map root after
    76    // incorporating the leaf changes.  The metadata will be reflected in the
    77    // Map Root returned in the map's SetLeaves response.
    78    // Map personalities should use metadata to persist any state needed later
    79    // to continue mapping from an external data source.
    80    reserved 4;
    81    bytes metadata = 5;
    82  }
    83  
    84  message SetMapLeavesResponse {
    85    SignedMapRoot map_root = 2;
    86  }
    87  
    88  message GetSignedMapRootRequest {
    89    int64 map_id = 1;
    90  }
    91  
    92  message GetSignedMapRootByRevisionRequest {
    93    int64 map_id = 1;
    94    int64 revision = 2;
    95  }
    96  
    97  message GetSignedMapRootResponse {
    98    SignedMapRoot map_root = 2;
    99  }
   100  
   101  message InitMapRequest {
   102    int64 map_id = 1;
   103  }
   104  
   105  message InitMapResponse {
   106    SignedMapRoot created = 1;
   107  }
   108  
   109  // TrillianMap defines a service which provides access to a Verifiable Map as
   110  // defined in the Verifiable Data Structures paper.
   111  service TrillianMap {
   112    // GetLeaves returns an inclusion proof for each index requested.
   113    // For indexes that do not exist, the inclusion proof will use nil for the empty leaf value.
   114    rpc GetLeaves(GetMapLeavesRequest) returns(GetMapLeavesResponse) {}
   115    rpc GetLeavesByRevision(GetMapLeavesByRevisionRequest) returns(GetMapLeavesResponse) {}
   116    // SetLeaves sets the values for the provided leaves, and returns the new map root if successful.
   117    // Note that if a SetLeaves request fails for a server-side reason (i.e. not an invalid request),
   118    // the API user is required to retry the request before performing a different SetLeaves request.
   119    rpc SetLeaves(SetMapLeavesRequest) returns(SetMapLeavesResponse) {}
   120    rpc GetSignedMapRoot(GetSignedMapRootRequest) returns(GetSignedMapRootResponse) {
   121        option (google.api.http) = {
   122          get: "/v1beta1/maps/{map_id}/roots:latest"
   123        };
   124    }
   125    rpc GetSignedMapRootByRevision(GetSignedMapRootByRevisionRequest) returns(GetSignedMapRootResponse) {
   126        option (google.api.http) = {
   127          get: "/v1beta1/maps/{map_id}/roots/{revision}"
   128        };
   129    }
   130    rpc InitMap(InitMapRequest) returns(InitMapResponse) {
   131        option (google.api.http) = {
   132          post: "/v1beta1/maps/{map_id}:init"
   133      };
   134    }
   135  }