Update Ledger API's proto documentation [KVL-1094] (#10815)

CHANGELOG_BEGIN
CHANGELOG_END

ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_completion_service.proto

@@ -19,10 +19,11 @@ option csharp_namespace = "Com.Daml.Ledger.Api.V1";
 //
 // Commands may fail in 2 distinct manners:
 //
-// 1. Failure communicated in the gRPC error of the submission.
-// 2. Failure communicated in a Completion.
+// 1. Failure communicated synchronously in the gRPC error of the submission.
+// 2. Failure communicated asynchronously in a Completion, see ``completion.proto``.
 //
-// Only successfully submitted commands may produce a completion event.
+// Note that not only successfully submitted commands MAY produce a completion event. For example, the participant MAY
+// choose to produce a completion event for a rejection of a duplicate command.
 //
 // Clients that do not receive a successful completion about their submission MUST NOT assume that it was successful.
 // Clients SHOULD subscribe to the CompletionStream before starting to submit commands to prevent race conditions.

ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_service.proto

@@ -15,8 +15,10 @@ option csharp_namespace = "Com.Daml.Ledger.Api.V1";
 
 // Command Service is able to correlate submitted commands with completion data, identify timeouts, and return contextual
 // information with each tracking result. This supports the implementation of stateless clients.
+//
+// Note that submitted commands generally produce completion events as well, even in case a command gets rejected.
+// For example, the participant MAY choose to produce a completion event for a rejection of a duplicate command.
 service CommandService {
-
   // Submits a single composite command and waits for its result.
   // Propagates the gRPC error of failed submissions including Daml interpretation errors.
   // Errors:

ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_submission_service.proto

@@ -18,10 +18,11 @@ option csharp_namespace = "Com.Daml.Ledger.Api.V1";
 //
 // Commands may fail in 2 distinct manners:
 //
-// 1. Failure communicated in the gRPC error of the submission.
-// 2. Failure communicated in a Completion.
+// 1. Failure communicated synchronously in the gRPC error of the submission.
+// 2. Failure communicated asynchronously in a Completion, see ``completion.proto``.
 //
-// Only successfully submitted commands may produce a completion event.
+// Note that not only successfully submitted commands MAY produce a completion event. For example, the participant MAY
+// choose to produce a completion event for a rejection of a duplicate command.
 //
 // Clients that do not receive a successful completion about their submission MUST NOT assume that it was successful.
 // Clients SHOULD subscribe to the CompletionStream before starting to submit commands to prevent race conditions.

ledger-api/grpc-definitions/com/daml/ledger/api/v1/commands.proto

@@ -17,7 +17,6 @@ option csharp_namespace = "Com.Daml.Ledger.Api.V1";
 
 // A composite command that groups multiple commands together.
 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
@@ -34,9 +33,10 @@ message Commands {
   // Required
   string application_id = 3;
 
-  // Uniquely identified the command. This identifier should be unique for each new command within an
-  // application domain, i.e., the triple (application_id, party, command_id) must be unique.
-  // It can be used for matching the requests with their respective completions.
+  // Uniquely identifies the command.
+  // The triple (application_id, party + act_as, command_id) constitutes the change ID for the intended ledger change,
+  // where party + act_as is interpreted as a set of party names.
+  // The change ID can be used for matching the intended ledger changes with their respective completions.
   // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string command_id = 4;
@@ -57,20 +57,27 @@ message Commands {
   // Required
   repeated Command commands = 8;
 
+  // Specifies the deduplication period for the change ID.
+  // If omitted, the participant chooses a deduplication period at its discretion.
   oneof deduplication_period {
-      // Same semantics apply as for `deduplication_duration`.
-      google.protobuf.Duration deduplication_time = 9 [deprecated = true];
+    // Specifies the length of the deduplication period.
+    // Same semantics apply as for `deduplication_duration`.
+    //
+    // Must be non-negative.
+    google.protobuf.Duration deduplication_time = 9 [deprecated = true];
 
-      // Specifies the start of the deduplication period by a completion stream offset.
-      //
-      // Must be a valid LedgerString (as described in ``value.proto``).
-      string deduplication_offset = 15;
+    // Specifies the start of the deduplication period by a completion stream offset.
+    //
+    // Must be a valid LedgerString (as described in ``value.proto``).
+    string deduplication_offset = 15;
 
-      // Specifies the length of the deduplication period.
-      // It is interpreted relative to the local clock at some point during the submission's processing.
-      //
-      // Must be non-negative.
-      google.protobuf.Duration deduplication_duration = 16;
+    // Specifies the length of the deduplication period.
+    // It is interpreted relative to the local clock at some point during the submission's processing.
+    // If omitted, the participant will assume the configured maximum deduplication time (see
+    // ``ledger_configuration_service.proto``).
+    //
+    // Must be non-negative.
+    google.protobuf.Duration deduplication_duration = 16;
   }
 
   // Lower bound for the ledger time assigned to the resulting transaction.
@@ -128,7 +135,6 @@ message Command {
 
 // Create a new contract instance based on a template.
 message CreateCommand {
-
   // The template of contract the client wants to create.
   // Required
   Identifier template_id = 1;
@@ -140,7 +146,6 @@ message CreateCommand {
 
 // Exercise a choice on an existing contract.
 message ExerciseCommand {
-
   // The template of contract the client wants to exercise.
   // Required
   Identifier template_id = 1;
@@ -162,7 +167,6 @@ message ExerciseCommand {
 
 // Exercise a choice on an existing contract specified by its key.
 message ExerciseByKeyCommand {
-
   // The template of contract the client wants to exercise.
   // Required
   Identifier template_id = 1;

ledger-api/grpc-definitions/com/daml/ledger/api/v1/event.proto

@@ -57,11 +57,11 @@ message CreatedEvent {
   // Required
   Record create_arguments = 4;
 
-  // The parties that are notified of this event. When a `CreatedEvent`
+  // The parties that are notified of this event. When a ``CreatedEvent``
   // is returned as part of a transaction tree, this will include all
-  // the parties specified in the `TransactionFilter` that are informees
+  // the parties specified in the ``TransactionFilter`` that are informees
   // of the event. If served as part of a flat transaction those will
-  // be limited to all parties specified in the `TransactionFilter` that
+  // be limited to all parties specified in the ``TransactionFilter`` that
   // are stakeholders of the contract (i.e. either signatories or observers).
   // Required
   repeated string witness_parties = 5;
@@ -101,12 +101,12 @@ message ArchivedEvent {
   // Required
   Identifier template_id = 3;
 
-  // The parties that are notified of this event. For `ArchivedEvent`s,
+  // The parties that are notified of this event. For ``ArchivedEvent``s,
   // these are the intersection of the stakeholders of the contract in
-  // question and the parties specified in the `TransactionFilter`. The
+  // 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
+  // Each one of its elements must be a valid PartyIdString (as described
   // in ``value.proto``).
   // Required
   repeated string witness_parties = 4;
@@ -159,7 +159,7 @@ message ExercisedEvent {
   // the actors. Note that the actors might not necessarily be observers
   // and thus signatories. This is the case when the controllers of a
   // choice are specified using "flexible controllers", using the
-  // `choice ... controller` syntax, and said controllers are not
+  // ``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

ledger-api/grpc-definitions/com/daml/ledger/api/v1/ledger_configuration_service.proto

@@ -43,8 +43,10 @@ message LedgerConfiguration {
   reserved 1; // was min_ttl
   reserved 2; // was max_ttl
 
-  // The maximum value for the ``deduplication_time`` parameter of command submissions
-  // (as described in ``commands.proto``). This defines the maximum time window during which
-  // commands can be deduplicated.
+  // If a command submission specifies a deduplication period of length up to ``max_deduplication_time``,
+  // the submission SHOULD not be rejected with ``NOT_FOUND`` because the deduplication period start is too early.
+  // The deduplication period is measured on a local clock of the participant or Daml ledger,
+  // and therefore subject to clock skews and clock drifts.
+  // Command submissions with longer periods MAY get accepted though.
   google.protobuf.Duration max_deduplication_time = 3;
 }

ledger/ledger-configuration/protobuf/com/daml/ledger/configuration/ledger_configuration.proto

@@ -32,7 +32,7 @@ message LedgerConfiguration {
   // ledger effective time and maximum record time of transactions.
   LedgerTimeModel time_model = 3;
 
-  // The maximum value for the ``deduplication_time`` parameter of command submissions
+  // The maximum value for the ``deduplication_duration`` parameter of command submissions
   // (as described in ``commands.proto``). This defines the maximum time window during which
   // commands can be deduplicated.
   google.protobuf.Duration max_deduplication_time = 4;