Update Daml Documentation to reflect command deduplication related changes [KVL-1094] (#10852)

* Minor tweaks.

* Use deduplication period instead of deduplication time.

* Introduced change ID and consistent use of deduplication duration/period.

* Consistent use of deduplication duration/period.

* Added ALREADY_EXISTS to the described gRPC errors.

* Minor tweak.

CHANGELOG_BEGIN
CHANGELOG_END

* Emphasize that applications should not change the deduplication time upon a resubmission

* Fix definition of change ID and always refer to it

* Try to clarify "Application-specific IDs"

* Make command deduplication explanation unspecific w.r.t. direction

Co-authored-by: Fabio Tudone <fabio.tudone@digitalasset.com>

docs/source/app-dev/app-arch.rst

@@ -138,14 +138,14 @@ There are several things that can fail during this time window: the application
 If you want to make sure that a command is not executed twice, your application needs to robustly handle all the various failure scenarios.
 Daml ledgers provide a mechanism for :ref:`command deduplication <command-submission-service-deduplication>` to help deal with this problem.
 
-For each command application provide a command ID and an optional parameter that specifies the deduplication time. If the latter parameter is not specified in the command submission itself, the ledger will fall back to using the configured maximum deduplication time.
-The ledger will then guarantee that commands for the same submitting party and command ID will be ignored within the deduplication time window.
+For each command the application provides a command ID and an optional parameter that specifies the deduplication period. If the latter parameter is not specified in the command submission itself, the ledger will fall back to using the configured maximum deduplication period.
+The ledger will then guarantee that commands with the same :ref:`change ID <change-id>` will be ignored within the deduplication period.
 
 To use command deduplication, you should:
 
-- Use generous values for the deduplication time. It should be large enough such that you can assume the command was permanently lost if the deduplication time has passed and you still don’t observe any effect of the command on the ledger (i.e. you don't see a transaction with the command ID via the :ref:`transaction service <transaction-service>`).
+- Use generous values for the deduplication duration. It should be large enough such that you can assume the command was permanently lost if the deduplication period has passed and you still don’t observe any effect of the command on the ledger (i.e. you don't see a transaction with the command ID via the :ref:`transaction service <transaction-service>`).
 - Make sure you set command IDs deterministically, that is to say: the "same" command must use the same command ID. This is useful for the recovery procedure after an application crash/restart, in which the application inspects the state of the ledger (e.g. via the :ref:`Active contracts service <active-contract-service>`) and sends commands to the ledger. When using deterministic command IDs, any commands that had been sent before the application restart will be discarded by the ledger to avoid duplicate submissions.
-- If you are not sure whether a command was submitted successfully, just resubmit it. If the new command was submitted within the deduplication time window, the duplicate submission will safely be ignored. If the deduplication time window has passed, you can assume the command was lost or rejected and a new submission is justified.
+- If you are not sure whether a command was submitted successfully, just resubmit it with the same deduplication duration. If the new command was submitted within the deduplication period, the duplicate submission will safely be ignored. If the deduplication period has passed, you can assume the command was lost or rejected and a new submission is justified.
 
 
 For more details on command deduplication, see the :ref:`Ledger API Services <command-submission-service-deduplication>` documentation.

docs/source/app-dev/grpc/index.rst

@@ -66,12 +66,14 @@ For information on how Daml types and contracts are represented by the Ledger AP
 Error handling
 **************
 
-Tor the standard error codes that the server or the client might return, see the `gRPC documentation <https://github.com/grpc/grpc/blob/600272c826b48420084c2ff76dfb0d34324ec296/doc/statuscodes.md>`__ .
+For the standard error codes that the server or the client might return, see the `gRPC documentation <https://github.com/grpc/grpc/blob/600272c826b48420084c2ff76dfb0d34324ec296/doc/statuscodes.md>`__ .
 
 For submitted commands, there are these response codes:
 
 ABORTED
    The platform failed to record the result of the command due to a transient server-side error or a time constraint violation. You can retry the submission. In case of a time constraint violation, please refer to the section :ref:`Dealing with time <dealing-with-time>` on how to handle commands with long processing times.
+ALREADY_EXISTS
+   The command was rejected because it was sent within the deduplication period of a previous command with the same change ID.
 INVALID_ARGUMENT
    The submission failed because of a client error. The platform will definitely reject resubmissions of the same command.
 OK, INTERNAL, UNKNOWN (when returned by the Command Submission Service)

docs/source/app-dev/services.rst

@@ -56,9 +56,20 @@ A call to the command submission service will return as soon as the ledger serve
 
 The on-ledger effect of the command execution will be reported via the `transaction service <#transaction-service>`__, described below. The completion status of the command is reported via the `command completion service <#command-completion-service>`__. Your application should receive completions, correlate them with command submission, and handle errors and failed commands. Alternatively, you can use the `command service <#command-service>`__, which conveniently wraps the command submission and completion services.
 
-Commands can be labeled with two application-specific IDs, both of which are returned in completion events:
+.. _change-id:
 
-- A :ref:`commandId <com.daml.ledger.api.v1.Commands.command_id>`, returned to the submitting application only. It is generally used to implement this correlation between commands and completions. 
+Change ID
+---------
+
+Each intended ledger change is identified by its **change ID**, consisting of of the submitting parties (i.e., the union of :ref:`party <com.daml.ledger.api.v1.Commands.party>` and :ref:`act_as <com.daml.ledger.api.v1.Commands.act_as>`), :ref:`application ID <com.daml.ledger.api.v1.Commands.application_id>` and :ref:`command ID <com.daml.ledger.api.v1.Commands.command_id>`.
+
+Application-specific IDs
+------------------------
+
+The following application-specific IDs, all of which are included in completion events, can be set in commands:
+
+- A :ref:`submissionId <com.daml.ledger.api.v1.Commands.submission_id>`, returned to the submitting application only. It may be used to correlate specific submissions to specific completions.
+- A :ref:`commandId <com.daml.ledger.api.v1.Commands.command_id>`, returned to the submitting application only; it can be used to correlate commands to completions.
 - A :ref:`workflowId <com.daml.ledger.api.v1.Commands.workflow_id>`, returned as part of the resulting transaction to all applications receiving it. It can be used to track workflows between parties, consisting of several transactions.
 
 For full details, see :ref:`the proto documentation for the service <com.daml.ledger.api.v1.CommandSubmissionService>`.
@@ -68,16 +79,16 @@ For full details, see :ref:`the proto documentation for the service <com.daml.le
 Command deduplication
 ---------------------
 
-The command submission service deduplicates submitted commands based on the submitting :ref:`party <com.daml.ledger.api.v1.Commands.party>` and :ref:`command ID <com.daml.ledger.api.v1.Commands.command_id>`:
+The command submission service deduplicates submitted commands based on their :ref`change ID <change-id>`:
 
-- Applications can provide a :ref:`deduplication time <com.daml.ledger.api.v1.Commands.deduplication_time>` for each command. If this parameter is not set, the default maximum deduplication time is used.
-- A command submission is considered a duplicate submission if the ledger server receives the command within the deduplication time of a previous command with the same command ID from the same submitting party.
-- Duplicate command submissions will be ignored until either the deduplication time of the original command has elapsed or the original submission was rejected (i.e. the command failed and resulted in a rejected transaction), whichever comes first.
+- Applications can provide a :ref:`deduplication duration <com.daml.ledger.api.v1.Commands.deduplication_duration>` for each command. If this parameter is not set, the default maximum deduplication period is used.
+- A command submission is considered a duplicate submission if the ledger API server is aware of another command within the deduplication period and with the same :ref`change ID <change-id>`.
+- Duplicate command submissions will be ignored until either the deduplication period of the original command has passed or the original submission was rejected (i.e. the command failed and resulted in a rejected transaction), whichever comes first.
 - Command deduplication is only *guaranteed* to work if all commands are submitted to the same participant. Ledgers are free to perform additional command deduplication across participants. Consult the respective ledger's manual for more details.
 - A command submission will return:
 
-  - The result of the submission (``Empty`` or a gRPC error), if the command was submitted outside of the deduplication time of a previous command with the same command ID on the same participant.
-  - The status error ``ALREADY_EXISTS``, if the command was discarded by the ledger server because it was sent within the deduplication time of a previous command with the same command ID.
+  - The result of the submission (``Empty`` or a gRPC error), if the command was submitted outside of the deduplication period of a previous command with the same :ref`change ID <change-id>` on the same participant.
+  - The status error ``ALREADY_EXISTS``, if the command was discarded by the ledger server because it was sent within the deduplication period of a previous command with the same :ref`change ID <change-id>`.
 
 - If the ledger provides additional command deduplication across participants, the initial command submission might be successful, but ultimately the command can be rejected if the deduplication check fails on the ledger.
 
@@ -215,7 +226,7 @@ Ledger configuration service
 
 Use the **ledger configuration service** to subscribe to changes in ledger configuration.
 
-This configuration includes the maximum command deduplication time (see `Command Deduplication <#command-submission-service-deduplication>`__ for details).
+This configuration includes the maximum command deduplication period (see `Command Deduplication <#command-submission-service-deduplication>`__ for details).
 
 For full details, see :ref:`the proto documentation for the service <com.daml.ledger.api.v1.LedgerConfigurationService>`.