[main] Update 2025-04-14.07 (#311)

Reference commit: d4a48308bb

Co-authored-by: Canton <[email protected]>

Author: canton-machine

UNRELEASED.md

@@ -3,12 +3,119 @@
 Canton CANTON_VERSION has been released on RELEASE_DATE. You can download the Daml Open Source edition from the Daml Connect [Github Release Section](https://github.com/digital-asset/daml/releases/tag/vCANTON_VERSION). The Enterprise edition is available on [Artifactory](https://digitalasset.jfrog.io/artifactory/canton-enterprise/canton-enterprise-CANTON_VERSION.zip).
 Please also consult the [full documentation of this release](https://docs.daml.com/CANTON_VERSION/canton/about.html).
 
+## Until 2025-04-16 (Exclusive)
+### `InvalidGivenCurrentSystemStateSeekAfterEnd` error category
+The description of existing error category `InvalidGivenCurrentSystemStateSeekAfterEnd` has been generalized.
+As such this error category now describes a failure due to requesting a resource using a parameter value that
+falls beyond the current upper bound (or 'end') defined by the system's state. For example, a request that asks
+for data at a ledger offset which is past the current ledger's end.
+
+With this change, the error category `InvalidGivenCurrentSystemStateSeekAfterEnd` has also been marked as
+`retryable`. Because, it makes sense to retry a failed request assuming the system has progressed in the meantime.
+For example, new ledger entries have been added; and thus a previously requested ledger offset has become valid.
+
+### Traffic fees
+A base event cost can now be added to every sequenced submission.
+The amount is controlled via a new optional field in the `TrafficControlParameters` called `base_event_cost`.
+If not set, the base event cost is 0.
+
+### Acknowledgements
+Sequencers will now conflate acknowledgements coming from a participant within a time window.
+This means that if 2 or more acknowledgements from a given member get submitted during the window,
+only the first will be sequenced and the others will be discarded, until the window has elapsed.
+The conflate time window can be configured with a key in the sequencer configuration.
+Defaults to 45 seconds.
+
+Example: `sequencers.sequencer1.acknowledgements-conflate-window = "1 minute"`
+
+### BREAKING CHANGE: Automatic Node Initialization and Configuration
+
+The node initialization has been modified to better support root namespace keys and using static identities
+for our documentation. Mainly, while before, we had the ``init.auto-init`` flag, we now support a bit more
+versatile configurations.
+
+The config structure looks like this now:
+```
+canton.participants.participant.init = {
+    identity = {
+        type = auto
+        identifier = {
+            type = config // random // explicit(name)
+        }
+    }
+    generate-intermediate-key = false
+    generate-topology-transactions-and-keys = true
+}
+```
+
+A manual identity can be specified via the GRPC API if the configuration is set to ``manual``.
+```
+identity = {
+    type = manual
+}
+```
+
+Alternatively, the identity can be defined in the configuration file, which is equivalent to an
+API based initialization using the ``external`` config:
+```
+    identity = {
+        type = external
+        identifier = name
+        namespace = "optional namespace"
+        delegations = ["namespace delegation files"]
+    }
+```
+
+The old behaviour of ``auto-init = false`` (or ``init.identity = null``) can be recovered using
+```
+canton.participants.participant1.init = {
+    generate-topology-transactions-and-keys = false
+    identity.type = manual
+}
+```
+
+This means that auto-init is now split into two parts: generating the identity and generating
+the subsequent topology transactions.
+
+Additionally, the console command ``node.topology.init_id`` has been changed slightly too:
+It now supports additional parameters ``delegations`` and ``delegationFiles``. These can be used
+to specify the delegations that are necessary to control the identity of the node, which means that
+the ``init_id`` call combined with ``identity.type = manual`` is equivalent to the
+``identity.type = external`` in the config, except that one is declarative via the config, the
+other is interactive via the console. In addition, on the API level, the ``InitId`` request now expects
+the ``unique_identifier`` as its components, ``identifier`` and ``namespace``.
+
+### Ledger API endpoint to submit-and-wait for reassignments
+- Added new endpoint SubmitAndWaitForReassignment to be able to submit a single composite reassignment command, and wait
+  for the reassignment to be returned.
+- The SubmitAndWaitForReassignmentRequest message was added that contains the reassignment commands to be submitted and
+  the event format that defines how the Reassignment will be presented.
+- The java bindings and the json api were extended accordingly.
+
+### NamespaceDelegation can be restricted to a specific set of topology mappings
+- Added field `NamespaceDelegation.restricted_to_mappings` to restrict the target key of a namespace delegation to only be allowed
+  to sign a set of topology mappings. See the documentation for the field in topology.proto.
+  **BREAKING CHANGE**
+- The console command `topology.namespace_delegation.propose_delegation` was changed. The parameter `isRootDelegation: Boolean` is replaced with the parameter
+  `delegationRestriction: DelegationRestriction`, which can be one of the following values:
+    - `CanSignAllMappings`: This is equivalent to the previously known "root delegation", meaning that the target key of the delegation can be used
+      to sign all topology mappings.
+    - `CanSignAllButNamespaceDelegations`: This is equivalent to the previously known "non-root delegation", meaning that the target key of the delegation
+      can be used to sign all topology mappings other than namespace delegations.
+    - `CanSignSpecificMappings(TopologyMapping.Code*)`: The target key of the delegation can only be used to sign the specified mappings.
+
 ## Until 2025-04-08 (Exclusive)
+- Json API: openapi.yaml generated using 3.0.3 version of specification.
 - Json API: http response status codes are based on the corresponding gRPC errors where applicable.
 - Json API: `/v2/users` and `/v2/parties` now support paging
 - Json API: Updated openapi.yaml to correctly represent Timestamps as strings in the JSON API schema
+- Json API: Fields that are mapped to Option, Seq or Map in gRPC are no longer required (default to empty).
 - The package vetting ledger-effective-time boundaries change to validFrom being inclusive and validUntil being exclusive
   whereas previously validFrom was exclusive and validUntil was inclusive.
+- Ledger Metering has been removed. This involved
+  - deleting MeteringReportService in the Ledger API
+  - deleting /v2/metering endpoint in the JSON API
+  - deleting the console ledger_api.metering.get_report command
 
 ### Ledger API topology transaction to represent addition for (party, participant)
 - The ParticipantAuthorizationAdded message was added to express the inception of a party in a participant.
@@ -17,6 +124,19 @@ Please also consult the [full documentation of this release](https://docs.daml.c
   state of the participant authorization (Added, Changed, Revoked)
 - The JSON api and the java bindings have changed accordingly to accommodate the changes.
 
+### Ledger API interface query upgrading
+Streaming and pointwise queries support for smart contract upgrading:
+- Dynamic upgrading of interface filters: on a query for interface `iface`, the Ledger API will deliver events
+  for all templates that can be upgraded to a template version that implements `iface`.
+  The interface filter resolution is dynamic throughout a stream's lifetime: it is re-evaluated on each DAR upload.
+  **Note**: No redaction of history: a DAR upload during an ongoing stream does not affect the already scanned ledger for the respective stream.
+  If clients are interested in re-reading the history in light of the upgrades introduced by a DAR upload,
+  the relevant portion of the ACS view of the client should be rebuilt by re-subscribing to the ACS stream
+  and continuing from there with an update subscription for the interesting interface filter.
+- Dynamic upgrading of interface views: rendering of interface view values is adapted to use
+  the latest infinitely-vetted (with no validUntil bound) package version of an interface instance.
+  **Note**: For performance considerations, the selected version to be rendered for an interface instance is memoized
+  per stream subscription and does not change as the vetting state evolves.
 
 ## Until 2025-04-05 (Exclusive)
 ### Breaking: New External Signing Hashing Scheme
@@ -33,6 +153,7 @@ Support for `V1` has been dropped and will not be supported in Canton 3.3 onward
 This is relevant for applications that re-compute the hash client-side.
 Such applications must update their implementation in order to use the interactive submission service on Canton 3.3.
 
+
 ## Until 2025-04-04 (Exclusive)
 ### ACS Export and Import
 The ACS export and import now use an ACS snapshot containing LAPI active contracts, as opposed to the Canton internal

base/errors/src/main/scala/com/digitalasset/base/error/BaseError.scala

@@ -50,9 +50,9 @@ trait BaseError extends LocationMixin {
   def resources: Seq[(ErrorResource, String)] = Seq()
 
   def logWithContext(extra: Map[String, String] = Map())(implicit
-      contextualizedErrorLogger: BaseErrorLogger
+      errorLoggingContext: BaseErrorLogger
   ): Unit =
-    contextualizedErrorLogger.logError(this, extra)
+    errorLoggingContext.logError(this, extra)
 
   /** Returns retryability information of this particular error
     *

base/errors/src/main/scala/com/digitalasset/base/error/ErrorCategory.scala

@@ -332,20 +332,28 @@ object ErrorCategory {
       )
       with ErrorCategory
 
-  /** The supplied offset is out of range
+  /** A failure due to requesting a resource using a parameter value that falls beyond the current
+    * upper bound (or 'end') defined by the system's state.
     */
   @Description(
-    """This error is only used by the Ledger API server in connection with invalid offsets."""
+    """The request failed because it resulted in an operation beyond the current upper bound (or 'end')
+      |defined by the system's state. For example, supplying a ledger offset which is larger than the current
+      |ledger end, or a record time that is in the future."""
+  )
+  @RetryStrategy(
+    """Wait and retry. For example, retry a limited number of times with potentially increasing backoff.
+      |Hint: Inspect the retryable value of the error code to decide on the particular retry duration."""
   )
-  @RetryStrategy("""Retry after application operator intervention.""")
   @Resolution(
-    """Expectation: this error is only used by the Ledger API server in connection with invalid offsets."""
+    """Resolution can occur naturally as the system progresses. The requested operation may become valid
+      |eventually once the system's state has advanced further. For example, when new ledger entries are added.
+      |If however the situation does not resolve as expected, operator intervention may be required."""
   )
   case object InvalidGivenCurrentSystemStateSeekAfterEnd
       extends ErrorCategoryImpl(
         grpcCode = Some(Code.OUT_OF_RANGE),
         logLevel = Level.INFO,
-        retryable = None,
+        retryable = Some(ErrorCategoryRetry(1.second)),
         redactDetails = false,
         asInt = 12,
         rank = 3,

base/errors/src/main/scala/com/digitalasset/base/error/ErrorResource.scala

@@ -16,6 +16,7 @@ object ErrorResource {
   lazy val ContractIds: ErrorResource = ErrorResource("CONTRACT_IDS")
   lazy val ContractKey: ErrorResource = ErrorResource("CONTRACT_KEY")
   lazy val ContractArg: ErrorResource = ErrorResource("CONTRACT_ARG")
+  lazy val CryptoValue: ErrorResource = ErrorResource("CRYPTO_VALUE")
   lazy val TransactionId: ErrorResource = ErrorResource("TRANSACTION_ID")
   lazy val UpdateId: ErrorResource = ErrorResource("UPDATE_ID")
   lazy val DalfPackage: ErrorResource = ErrorResource("PACKAGE")
@@ -45,6 +46,7 @@ object ErrorResource {
     ContractIds,
     ContractKey,
     ContractKeyHash,
+    CryptoValue,
     DalfPackage,
     DevErrorType,
     ExceptionText,

community/admin-api/src/main/protobuf/com/digitalasset/canton/admin/participant/v30/party_management_service.proto

@@ -5,6 +5,9 @@ syntax = "proto3";
 
 package com.digitalasset.canton.admin.participant.v30;
 
+import "google/protobuf/timestamp.proto";
+import "scalapb/scalapb.proto";
+
 /**
  * The PartyManagementService allows modifying party hosting on participants.
  */
@@ -14,14 +17,27 @@ service PartyManagementService {
   // Performs some checks synchronously and then starts the replication asynchronously.
   rpc AddPartyAsync(AddPartyAsyncRequest) returns (AddPartyAsyncResponse);
 
+  // Status endpoint that given an add_party_request_id returns status information about progress,
+  // completion, or errors of a previous call to AddPartyAsync on the source or target
+  // participant.
+  //
+  // Note that the status reflects the state as perceived by the local participant and does not
+  // imply the state of remote participants. The status on the target participant is more
+  // authoritative as the target participant drives the process of adding the party. For example
+  // when the target participant status indicates "completed", the party has been added
+  // successfully.
+  rpc GetAddPartyStatus(GetAddPartyStatusRequest) returns (GetAddPartyStatusResponse);
+
   // Export the ACS for the given parties from the participant
   rpc ExportAcs(ExportAcsRequest) returns (stream ExportAcsResponse);
 }
 
 message AddPartyAsyncRequest {
+  option (scalapb.message).companion_extends = "com.digitalasset.canton.version.AlphaProtoVersion";
+
   // The party to replicate
   // Required
-  string party_uid = 1;
+  string party_id = 1;
   // The synchronizer in which to replicate the party
   // Required
   string synchronizer_id = 2;
@@ -36,8 +52,92 @@ message AddPartyAsyncRequest {
 }
 
 message AddPartyAsyncResponse {
-  // A identifier used to uniquely track add party activity
-  string party_replication_id = 1;
+  option (scalapb.message).companion_extends = "com.digitalasset.canton.version.AlphaProtoVersion";
+
+  // The identifier used to uniquely track the add party request.
+  string add_party_request_id = 1;
+}
+
+message GetAddPartyStatusRequest {
+  option (scalapb.message).companion_extends = "com.digitalasset.canton.version.AlphaProtoVersion";
+
+  // The add party request ID returned by AddPartyAsync
+  // Required
+  string add_party_request_id = 1;
+}
+
+message GetAddPartyStatusResponse {
+  option (scalapb.message).companion_extends = "com.digitalasset.canton.version.AlphaProtoVersion";
+
+  string party_id = 1;
+  string synchronizer_id = 2;
+  string source_participant_uid = 3;
+  string target_participant_uid = 4;
+
+  message Status {
+    // The add-party request has been submitted by the target participant, or accepted by the
+    // source participant.
+    message ProposalProcessed {
+      optional uint32 topology_serial = 1;
+    }
+    // The add-party request has been observed as agreed to by all participants.
+    message AgreementAccepted {
+      string sequencer_uid = 1;
+      optional uint32 topology_serial = 2;
+    }
+    // The PartyToParticipant topology transaction has been authorized by all party and
+    // participant signers.
+    message TopologyAuthorized {
+      string sequencer_uid = 1;
+      uint32 topology_serial = 2;
+      // The timestamp at which the ACS snapshot for replication is taken.
+      google.protobuf.Timestamp timestamp = 3;
+    }
+    // The local participant has connected to the sequencer channel for ACS replication.
+    message ConnectionEstablished {
+      string sequencer_uid = 1;
+      uint32 topology_serial = 2;
+      google.protobuf.Timestamp timestamp = 3;
+    }
+    // The local participant is ready for ACS replication or has started replicating the ACS.
+    message ReplicatingAcs {
+      string sequencer_uid = 1;
+      uint32 topology_serial = 2;
+      google.protobuf.Timestamp timestamp = 3;
+      uint32 contracts_replicated = 4;
+    }
+    // The local participant has completed its part of the ACS replication.
+    message Completed {
+      string sequencer_uid = 1;
+      uint32 topology_serial = 2;
+      google.protobuf.Timestamp timestamp = 3;
+      uint32 contracts_replicated = 4;
+    }
+    // The add-party request has failed after the specified last successful status.
+    message Error {
+      string error_message = 1;
+      Status status_prior_to_error = 2;
+    }
+
+    oneof status {
+      // Party Replication Daml admin workflow proposal and agreement handling
+      ProposalProcessed proposal_processed = 1;
+      AgreementAccepted agreement_accepted = 2;
+
+      // Topology management
+      TopologyAuthorized topology_authorized = 3;
+
+      // Party Replication ACS replication
+      ConnectionEstablished connection_established = 4;
+      ReplicatingAcs replicating_acs = 5;
+      Completed completed = 6;
+
+      // Error indicating that party replication has failed.
+      Error error = 7;
+    }
+  }
+
+  Status status = 5;
 }
 
 message ExportAcsTargetSynchronizer {