diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_completion_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_completion_service.proto index 1caad2eafec..8e940761331 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_completion_service.proto +++ b/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. diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_service.proto index 3db0bfe80f8..9e407d11209 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_service.proto +++ b/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: diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_submission_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_submission_service.proto index d2f6342d122..202d4d63b7b 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_submission_service.proto +++ b/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. diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/commands.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/commands.proto index c481bd3f3c8..2ba97e8258f 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/commands.proto +++ b/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; diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/event.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/event.proto index 7451d3d97e7..acb69076b83 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/event.proto +++ b/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 diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/ledger_configuration_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/ledger_configuration_service.proto index cd2ad38c537..cf7888486b3 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/ledger_configuration_service.proto +++ b/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; } diff --git a/ledger/ledger-configuration/protobuf/com/daml/ledger/configuration/ledger_configuration.proto b/ledger/ledger-configuration/protobuf/com/daml/ledger/configuration/ledger_configuration.proto index 4a35d47b1e7..824b0db5997 100644 --- a/ledger/ledger-configuration/protobuf/com/daml/ledger/configuration/ledger_configuration.proto +++ b/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;