Document syntactic restriction for ids in ledger-api proto (digital-a…

…sset#1585) * document syntactic restriction for ids in ledger-api proto * address Gerolf's comments
TuranDev · Jun 11, 2019 · 3618ca7 · 3618ca7
1 parent 8ed703e
commit 3618ca7
Show file tree

Hide file tree

Showing 17 changed files with 86 additions and 4 deletions.
diff --git a/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/active_contracts_service.proto b/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/active_contracts_service.proto
@@ -25,6 +25,7 @@ service ActiveContractsService {
 message GetActiveContractsRequest {
 
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string ledger_id = 1;
 
@@ -53,10 +54,12 @@ message GetActiveContractsResponse {
   string offset = 1;
 
   // The workflow that created the contracts.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Optional
   string workflow_id = 2;
 
   // The list of contracts that were introduced by the workflow with ``workflow_id`` at the offset.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Optional
   repeated CreatedEvent active_contracts = 3;
 

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
@@ -55,6 +55,7 @@ message ListKnownPackagesResponse {
 message PackageDetails {
 
   // The identity of the DAML-LF package.
+  // Must be a valid PackageIdString (as describe in ``value.proto``).
   // Required
   string package_id = 1;
 

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
@@ -66,6 +66,7 @@ message GetParticipantIdRequest {
 message GetParticipantIdResponse {
 
   // Identifier of the participant, which SHOULD be globally unique.
+  // Must be a valid LedgerString (as describe in ``value.proto``).
   string participant_id = 1;
 }
 
@@ -82,6 +83,7 @@ message ListKnownPartiesResponse {
 message PartyDetails {
 
   // The stable unique identifier of a DAML party.
+  // Must be a valid PartyIdString (as described in ``value.proto``).
   // Required
   string party = 1;
 
@@ -99,6 +101,7 @@ message AllocatePartyRequest {
 
   // A hint to the backing participant what party id to allocate. It can be
   // ignored.
+  // Must be a valid PartyIdString (as describe in ``value.proto``).
   // Optional
   string party_id_hint = 1;
 

diff --git a/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/command_completion_service.proto b/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/command_completion_service.proto
@@ -42,14 +42,17 @@ service CommandCompletionService {
 
 message CompletionStreamRequest {
   // Must correspond to the ledger id reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string ledger_id = 1;
 
   // Only completions of commands submitted with the same application_id will be visible in the stream.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string application_id = 2;
 
   // Non-empty list of parties whose data should be included.
+  // Must be a valid PartyIdString (as described in ``value.proto``).
   // Required
   repeated string parties = 3;
 
@@ -89,6 +92,7 @@ message Checkpoint {
 message CompletionEndRequest {
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
   // Required
+  // Must be a valid LedgerString (as described in ``value.proto``).
   string ledger_id = 1;
 
   // Server side tracing will be registered as a child of the submitted context.

diff --git a/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/command_service.proto b/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/command_service.proto
@@ -55,6 +55,7 @@ message SubmitAndWaitRequest {
 
 message SubmitAndWaitForTransactionIdResponse {
   // The id of the transaction that resulted from the submitted command.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string transaction_id = 1;
 }

diff --git a/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/commands.proto b/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/commands.proto
@@ -17,25 +17,30 @@ option java_package = "com.digitalasset.ledger.api.v1";
 message Commands {
 
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string ledger_id = 1;
 
   // Identifier of the on-ledger workflow that this command is a part of.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Optional
   string workflow_id = 2;
 
   // Uniquely identifies the application (or its part) that issued the command. This is used in tracing
   // across different components and to let applications subscribe to their own submissions only.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string application_id = 3;
 
-  // Unique command ID. This number should be unique for each new command within an application domain. It can be used for matching
-  // the requests with their respective completions.
+  // Uniquely identified the command. This identifier should be unique for each new command within an
+  // application domain. It can be used for matching the requests with their respective completions.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string command_id = 4;
 
   // Party on whose behalf the command should be executed. It is up to the server to verify that the
   // authorisation can be granted and that the connection has been authenticated for that party.
+  // Must be a valid PartyIdString (as described in ``value.proto``).
   // Required
   string party = 5;
 
@@ -82,10 +87,12 @@ message ExerciseCommand {
   Identifier template_id = 1;
 
   // The ID of the contract the client wants to exercise upon.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string contract_id = 2;
 
   // The name of the choice the client wants to exercise.
+  // Must be a valid NameString (as described in ``value.proto``)
   // Required
   string choice = 3;
 
@@ -96,7 +103,7 @@ message ExerciseCommand {
 
 // Create a contract and exercise a choice on it in the same transaction.
 message CreateAndExerciseCommand {
-  // The template of the contract the client wants to create
+  // The template of the contract the client wants to create.
   // Required
   Identifier template_id = 1;
 
@@ -105,6 +112,7 @@ message CreateAndExerciseCommand {
   Record create_arguments = 2;
 
   // The name of the choice the client wants to exercise.
+  // Must be a valid NameString (as described in ``value.proto``).
   // Required
   string choice = 3;
 

diff --git a/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/completion.proto b/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/completion.proto
@@ -15,6 +15,7 @@ option java_package = "com.digitalasset.ledger.api.v1";
 // A completion represents the status of a submitted command on the ledger: it can be successful or failed.
 message Completion {
   // The ID of the succeeded or failed command.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string command_id = 1;
 
@@ -26,6 +27,7 @@ message Completion {
 
   // The transaction_id of the transaction that resulted from the command with command_id.
   // Only set for successfully executed commands.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Optional
   string transaction_id = 3;
 

diff --git a/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/event.proto b/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/event.proto
@@ -35,10 +35,12 @@ message Event {
 message CreatedEvent {
 
   // The ID of this particular event.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string event_id = 1;
 
   // The ID of the created contract.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string contract_id = 2;
 
@@ -71,10 +73,12 @@ message CreatedEvent {
 message ArchivedEvent {
 
   // The ID of this particular event.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string event_id = 1;
 
   // The ID of the archived contract.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string contract_id = 2;
 
@@ -87,6 +91,8 @@ message ArchivedEvent {
   // question and the parties specified in the `TransactionFilter`. The
   // stakeholders are the union of the signatories and the observers of
   // the contract.
+  // Each one of its elements must be a valid PartyIdString (as descibed
+  // in ``value.proto``).
   // Required
   repeated string witness_parties = 4;
 }
@@ -95,10 +101,12 @@ message ArchivedEvent {
 message ExercisedEvent {
 
   // The ID of this particular event.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string event_id = 1;
 
   // The ID of the target contract.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string contract_id = 2;
 
@@ -107,10 +115,12 @@ message ExercisedEvent {
   Identifier template_id = 3;
 
   // The ID of the event in which the target contract has been created.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string contract_creating_event_id = 4;
 
   // The choice that's been exercised on the target contract.
+  // Must be a valid NameString (as described in ``value.proto``).
   // Required
   string choice = 5;
 
@@ -119,6 +129,7 @@ message ExercisedEvent {
   Value choice_argument = 6;
 
   // The parties that made the choice.
+  // Each element must be a valid PartyIdString (as described in ``value.proto``).
   // Required
   repeated string acting_parties = 7;
 
@@ -141,11 +152,16 @@ message ExercisedEvent {
   // `choice ... controller` syntax, and said controllers are not
   // explicitly marked as observers.
   //
+  // Each element must be a valid PartyIdString (as described in ``value.proto``).
+  //
   // Required
   repeated string witness_parties = 10;
 
   // References to further events in the same transaction that appeared as a result of this ``ExercisedEvent``.
   // It contains only the immediate children of this event, not all members of the subtree rooted at this node.
+  //
+  // Each element must be a valid PartyIdString (as described in ``value.proto``).
+  //
   // Optional
   repeated string child_event_ids = 11;
 

diff --git a/...er-api/grpc-definitions/com/digitalasset/ledger/api/v1/ledger_configuration_service.proto b/...er-api/grpc-definitions/com/digitalasset/ledger/api/v1/ledger_configuration_service.proto
@@ -23,6 +23,7 @@ service LedgerConfigurationService {
 message GetLedgerConfigurationRequest {
 
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string ledger_id = 1;
 

diff --git a/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/ledger_identity_service.proto b/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/ledger_identity_service.proto
@@ -32,6 +32,7 @@ message GetLedgerIdentityResponse {
 
   // The ID of the ledger exposed by the server.
   // Requests submitted with the wrong ledger ID will result in ``NOT_FOUND`` gRPC errors.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string ledger_id = 1;
 }
diff --git a/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/package_service.proto b/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/package_service.proto
@@ -28,6 +28,7 @@ service PackageService {
 message ListPackagesRequest {
 
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string ledger_id = 1;
 
@@ -40,17 +41,20 @@ message ListPackagesRequest {
 message ListPackagesResponse {
 
   // The IDs of all DAML-LF packages supported by the server.
+  // Each element must be a valid PackageIdString (as described in ``value.proto``).
   // Required
   repeated string package_ids = 1;
 }
 
 message GetPackageRequest {
 
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string ledger_id = 1;
 
   // The ID of the requested package.
+  // Must be a valid PackageIdString (as described in ``value.proto``).
   // Required
   string package_id = 2;
 
@@ -71,17 +75,20 @@ message GetPackageResponse {
   bytes archive_payload = 2;
 
   // The hash of the archive payload, can also used as a ``package_id``.
+  // Must be a valid PackageIdString (as described in ``value.proto``).
   // Required
   string hash = 3;
 }
 
 message GetPackageStatusRequest {
 
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string ledger_id = 1;
 
   // The ID of the requested package.
+  // Must be a valid PackageIdString (as described in ``value.proto``).
   // Required
   string package_id = 2;
 

diff --git a/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/testing/reset_service.proto b/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/testing/reset_service.proto
@@ -43,6 +43,7 @@ service ResetService {
 
 message ResetRequest {
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as describe in ``value.proto``).
   // Required
   string ledger_id = 1;
 }
diff --git a/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/testing/time_service.proto b/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/testing/time_service.proto
@@ -28,6 +28,7 @@ service TimeService {
 message GetTimeRequest {
 
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as describe in ``value.proto``).
   // Required
   string ledger_id = 1;
 }
@@ -41,6 +42,7 @@ message GetTimeResponse {
 message SetTimeRequest {
 
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as describe in ``value.proto``).
   // Required
   string ledger_id = 1;
 

diff --git a/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/transaction.proto b/ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/transaction.proto
@@ -18,14 +18,17 @@ option java_package = "com.digitalasset.ledger.api.v1";
 message TransactionTree {
 
   // Assigned by the server. Useful for correlating logs.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string transaction_id = 1;
 
   // The ID of the command which resulted in this transaction. Missing for everyone except the submitting party.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Optional
   string command_id = 2;
 
   // The workflow ID used in command submission. Only set if the ``workflow_id`` for the command was set.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Optional
   string workflow_id = 3;
 
@@ -40,10 +43,12 @@ message TransactionTree {
   string offset = 6;
 
   // Changes to the ledger that were caused by this transaction. Nodes of the transaction tree.
+  // Each key be a valid LedgerString (as describe in ``value.proto``).
   // Required
   map<string, TreeEvent> events_by_id = 7;
 
   // Roots of the transaction tree.
+  // Each element must be a valid LedgerString (as describe in ``value.proto``).
   // Required
   repeated string root_event_ids = 8;
 
@@ -71,18 +76,22 @@ message TreeEvent {
 message Transaction {
 
   // Assigned by the server. Useful for correlating logs.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string transaction_id = 1;
 
   // The ID of the command which resulted in this transaction. Missing for everyone except the submitting party.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Optional
   string command_id = 2;
 
   // The workflow ID used in command submission.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Optional
   string workflow_id = 3;
 
   // Ledger effective time.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   google.protobuf.Timestamp effective_at = 4;