provide initial definitions for party management and package manageme…

…nt (digital-asset#1264) * provide initial definitions for party management and package management protobuf interfaces * incorporate feedback from the three rounds of reviews
TuranDev · May 24, 2019 · f085af0 · f085af0
1 parent d704874
commit f085af0
Show file tree

Hide file tree

Showing 2 changed files with 195 additions and 0 deletions.
diff --git a/...pi/grpc-definitions/com/digitalasset/ledger/api/v1/admin/package_management_service.proto b/...pi/grpc-definitions/com/digitalasset/ledger/api/v1/admin/package_management_service.proto
@@ -0,0 +1,86 @@
+// Copyright (c) 2019 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package com.digitalasset.ledger.api.v1.admin;
+
+import "google/protobuf/timestamp.proto";
+
+option java_outer_classname = "PackageManagementServiceOuterClass";
+option java_package = "com.digitalasset.ledger.api.v1.admin";
+
+// Status: experimental interface, will change before it is deemed production
+// ready
+
+// Query the DAML-LF packages supported by the ledger participant and upload
+// DAR files. We use 'backing participant' to refer to this specific participant
+// in the methods of this API.
+// When the participant is run in mode requiring authentication, all the calls 
+// in this interface will respond with UNAUTHENTICATED, if the caller fails
+// to provide a valid access token, and will respond with PERMISSION_DENIED, if
+// the claims in the token are insufficient to perform a given operation.
+// Subsequently, only specific errors of individual calls not related to 
+// authorization will be described.
+service PackageManagementService {
+
+  // Returns the details of all DAML-LF packages known to the backing
+  // participant.
+  // This request will always succeed.
+  rpc ListKnownPackages (ListKnownPackagesRequest) returns
+    (ListKnownPackagesResponse);
+
+  // Upload a DAR file to the backing participant.
+  // Depending on the ledger implementation this might also make the package 
+  // available on the whole ledger. This call might not be supported by some 
+  // ledger implementations. Canton could be an example, where uploading a DAR
+  // is not sufficient to render it usable, it must be activated first.
+  // This method will return UNIMPLEMENTED, if DAR package uploading is not
+  // supported by the backing participant. If DAR file is too big or is 
+  // malformed, the backing participant will respond with INVALID_ARGUMENT.
+  // The maximum supported size is implementation specific.
+  rpc UploadDarFile (UploadDarFileRequest) returns (UploadDarFileResponse);
+}
+
+message ListKnownPackagesRequest {
+}
+
+message ListKnownPackagesResponse {
+
+  // The details of all DAML-LF packages known to backing participant.
+  // Required
+  repeated PackageDetails package_details = 1;
+}
+
+message PackageDetails {
+
+  // The identity of the DAML-LF package.
+  // Required
+  string package_id = 1;
+
+  // Size of the package in bytes.
+  // Required
+  uint64 package_size = 2;
+
+  // Indicates since when the package is known to the backing participant.
+  // Required
+  google.protobuf.Timestamp known_since = 3;
+
+  // Descrioption provided by the backing participant descnribing where
+  // it got the package from.
+  // Optional
+  string source_description = 4;
+}
+
+message UploadDarFileRequest {
+
+  // Contains a DAML archive DAR file, which in turn is a jar like zipped
+  // container for ``daml_lf`` archives. See further details in
+  // ``daml_lf.proto``.
+  // Required
+  bytes dar_file = 1;
+}
+
+// An empty message that is received when the upload operation succeeded.
+message UploadDarFileResponse {
+}
diff --git a/...-api/grpc-definitions/com/digitalasset/ledger/api/v1/admin/party_management_service.proto b/...-api/grpc-definitions/com/digitalasset/ledger/api/v1/admin/party_management_service.proto
@@ -0,0 +1,109 @@
+
+// Copyright (c) 2019 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package com.digitalasset.ledger.api.v1.admin;
+
+option java_outer_classname = "PartyManagementServiceOuterClass";
+option java_package = "com.digitalasset.ledger.api.v1.admin";
+
+// Status: experimental interface, will change before it is deemed production
+// ready
+
+// Inspect the party management state of a ledger participant and modify the
+// parts that are modifiable. We use 'backing participant' to refer to this
+// specific participant in the methods of this API.
+// When the participant is run in mode requiring authentication, all the calls 
+// in this interface will respond with UNAUTHENTICATED, if the caller fails
+// to provide a valid access token, and will respond with PERMISSION_DENIED, if
+// the claims in the token are insufficient to perform a given operation.
+// Subsequently, only specific errors of individual calls not related to 
+// authorization will be described.
+service PartyManagementService {
+
+  // Return the identifier of the backing participant.
+  // All horizontally scaled replicas should return the same id.
+  // This method is expected to succeed provided the backing participant is 
+  // healthy, otherwise it responds with INTERNAL grpc error.
+  // daml-on-sql: returns an identifier supplied on command line at launch time
+  // daml-on-kv-ledger: as above
+  // canton: returns globally unique identifier of the backing participant
+  rpc GetParticipantId (GetParticipantIdRequest) returns
+    (GetParticipantIdResponse);
+
+  // List the parties known by the backing participant.
+  // The list returned contains parties whose ledger access is facilitated by
+  // backing participant and the ones maintained elsewhere.
+  // This request will always succeed.
+  rpc ListKnownParties (ListKnownPartiesRequest) returns
+    (ListKnownPartiesResponse);
+
+  // Adds a new party to the set managed by the backing participant.
+  // Caller specifies a party identifier suggestion, the actual identifier
+  // allocated might be different and is implementation specific.
+  // This call will either succeed or respond with UNIMPLEMENTED if synchronous
+  // party allocation is not supported by the backing participant.
+  // daml-on-sql: suggestion's uniqueness is checked and call rejected if the
+  // identifier is already present
+  // daml-on-kv-ledger: suggestion's uniqueness is checked bby the validators in
+  // the consensus layer and call rejected if the identifier is already present.
+  // canton: completely different globally unique identifier is allocated.
+  // Behind the scenes calls to an internal protocol are made. As that protocol
+  // is richer than the the surface protocol, the arguments take implicit values
+  rpc AllocateParty (AllocatePartyRequest) returns (AllocatePartyResponse);
+}
+
+message GetParticipantIdRequest {
+}
+
+message GetParticipantIdResponse {
+
+  // Identifier of the participant, which SHOULD be globally unique.
+  string participant_id = 1;
+}
+
+message ListKnownPartiesRequest {
+}
+
+message ListKnownPartiesResponse {
+
+  // The details of all DAML parties hosted by the participant.
+  // Required
+  repeated PartyDetails party_details = 1;
+}
+
+message PartyDetails {
+
+  // The stable unique identifier of a DAML party.
+  // Required
+  string party = 1;
+
+  // Human readable name associated with the party. Caution, it might not be
+  // unique.
+  // Optional
+  string display_name = 2;
+
+  // true if party is hosted by the backing participant.
+  // Required
+  bool is_local = 3;
+}
+
+message AllocatePartyRequest {
+
+  // A hint to the backing participant what party id to allocate. It can be
+  // ignored.
+  // Optional
+  string party_id_hint = 1;
+
+  // Human readable name of the party to be added to the participant. It doesn't
+  // have to be unique.
+  // Optional
+  string display_name = 2;
+}
+
+message AllocatePartyResponse {
+
+  PartyDetails party_details = 1;
+}