canton v3.4.10

Release of Canton 3.4.10

Canton 3.4.10 has been released on January 07, 2026.

Summary

This is a maintenance release focused on stability improvements.
Notably, it upgrades gRPC to version 1.77.0 to address a known vulnerability (CVE-2025-58057).

What’s New

Minor Improvements

• Protect the admin participant from self lock-out. It is now impossible for an admin to remove own admin rights or
  delete itself.
• LedgerAPI ListKnownParties supports an optional prefix filter argument filterParty.
  The respective JSON API endpoint now additionally supports identity-provider-id as
  an optional argument, as well as filter-party.

The following Canton protocol versions are supported:

Dependency	Version
Canton protocol versions	34

Canton has been tested against the following versions of its dependencies:

Dependency	Version
Java Runtime	OpenJDK 64-Bit Server VM (build 21.0.5+1-nixos, mixed mode, sharing)
Postgres	Recommended: PostgreSQL 17.7 (Debian 17.7-3.pgdg13+1) – Also tested: PostgreSQL 14.20 (Debian 14.20-1.pgdg13+1), PostgreSQL 15.15 (Debian 15.15-1.pgdg13+1), PostgreSQL 16.11 (Debian 16.11-1.pgdg13+1)

canton v2.10.3

Release of Canton 2.10.3

Canton 2.10.3 has been released on January 12, 2026. You can download the Daml Open Source edition from the Daml Connect Github Release Section. The Enterprise edition is available on Artifactory.
Please also consult the full documentation of this release.

Summary

This maintenance release updates internal dependencies to address security vulnerabilities.
We recommend upgrading during your next scheduled maintenance window.

What’s New

Addressed security vulnerabilities

Notably, this maintenance release upgrades gRPC to version 1.75.0 and Netty to version 4.1.130.Final to address known
vulnerabilities (CVE-2025-55163 and CVE-2025-58057). Additionally, Flyway has been updated to 9.22.3, which includes
an upgrade to Jackson 2.15.2 to resolve a security vulnerability.

New gRPC Client Configuration Options

We have introduced keepAliveWithoutCalls and idleTimeout settings for gRPC client keep-alive configurations.
Please refer to the https://grpc.io/docs/guides/keepalive/#keepalive-configuration-specification for a detailed breakdown
of these parameters.

Backward compatibility note: These two configurations are disabled by default to maintain existing behavior.

Usage note: If keepAliveWithoutCalls is enabled on the client, you must ensure that permitKeepAliveWithoutCalls is
also enabled on the server side. Additionally, permitKeepAliveTime may need adjustment to accommodate the increased
frequency of keep-alive pings from the client.

Example Configuration:

Participant config:

canton.participants.participant.sequencer-client.keep-alive-client.keep-alive-without-calls = true
# And / Or
canton.participants.participant.sequencer-client.keep-alive-client.idle-timeout = 5 minutes

Domain config:

# Must be enabled if keep-alive-without-calls is enabled on the client side
# Single domain
canton.domains.mydomain.public-api.keep-alive-server.permit-keep-alive-without-calls = true
canton.domains.mydomain.public-api.keep-alive-server.permit-keep-alive-time = 5 minutes
# Sequencer node
canton.sequencers.sequencer.public-api.keep-alive-server.permit-keep-alive-without-calls = true
canton.sequencers.sequencer.public-api.keep-alive-server.permit-keep-alive-time = 5 minutes

Compatibility

The following Canton protocol versions are supported:

Dependency	Version
Canton protocol versions	5, 7

Canton has been tested against the following versions of its dependencies:

Dependency	Version
Java Runtime	OpenJDK 64-Bit Server VM Zulu11.72+19-CA (build 11.0.23+9-LTS, mixed mode)
Postgres	Recommended: PostgreSQL 12.22 (Debian 12.22-1.pgdg120+1) – Also tested: PostgreSQL 11.16 (Debian 11.16-1.pgdg90+1), PostgreSQL 13.23 (Debian 13.23-1.pgdg13+1), PostgreSQL 14.20 (Debian 14.20-1.pgdg13+1), PostgreSQL 15.15 (Debian 15.15-1.pgdg13+1)
Oracle	19.20.0

canton v3.4.9

Release of Canton 3.4.9

Canton 3.4.9 has been released on December 01, 2025.

Summary

This is a maintenance release focused on critical stability improvements and bugfixes for participant nodes,
primarily related to data pruning and the Ledger API's Interactive Submission Service.

What’s New

Minor Improvements

• Made the config option ...topology.use-time-proofs-to-observe-effective-time to work and changed the default to false.
  Disabling this option activates a more robust time advancement broadcast mechanism on the sequencers,
  which however still does not tolerate crashes or big gaps in block sequencing times. The parameters can be configured
  in the sequencer via canton.sequencers.<sequencer>.parameters.time-advancing-topology.
• Batching configuration now allows setting different parallelism for pruning (currently only for Sequencer pruning):
  New option canton.sequencers.sequencer.parameters.batching.pruning-parallelism (defaults to 2) can be used
  separately from the general canton.sequencers.sequencer.parameters.batching.parallelism setting.
• The PrepareSubmission RPC in the InteractiveSubmissionService now rejects requests with multiple commands.
  Such requests were never and are still not supported, but previously failed later in the transaction processing.
  This provides earlier feedback and better UX.
  This behavior can be reverted by setting ledger-api.interactive-submission-service.enforce-single-root-node = false in the participant node config object.
• The ExecuteSubmission RPC in the InteractiveSubmissionService now rejects requests with transactions containing multiple root nodes.
  Such requests were never and are still not supported, but previously failed later in the transaction processing.
  This provides earlier feedback and better UX.
  This behavior can be reverted by setting ledger-api.interactive-submission-service.enforce-single-root-node = false in the participant node config object.
• Fixed an issue preventing clearing of the onboarding flag for new external parties created on Canton 3.4.8 using the clearPartyOnboardingFlag endpoint.

Bugfixes

(25-012, Low): Ledger prune call erroneously emits an UNSAFE_TO_PRUNE error

Issue Description

Pruning bug that wrongly issues errors, but does not delete data that is not safe to prune. When no offset is safe to
prune, i.e., the first unsafe offset is 1 (the first ledger offset), Canton pruning indicates in logs that it is safe to
prune up to ledger end, which is wrong. However, the prune call subsequently logs an UNSAFE_TO_PRUNE error and the
pruning call fails. Note that this is not a safety bug: validation checks still prevent Canton from actually pruning
unsafe data.

Affected Deployments

Participant nodes

Affected Versions

All 3.x < 3.4.9

Impact

Minor: An error is logged when calling prune, which may alert an operator.

Symptom

Pruning logs that it is safe to prune up to some offset, but the pruning call fails when it tries to prune at that offset.

Workaround

Calls to prune eventually succeed when the unsafe to prune boundary advances.

Likelihood

Possible

Recommendation

Upgrade to >= 3.4.9

(25-013, Critical): Incorrect contract-store pruning related to immediately divulged events

Issue Description

Participant pruning is incorrectly removing stored contracts if certain conditions are met.
Pruning of participant events which are immediately divulged to the participant (create events with no locally hosted stakeholders)
leads to unconditional removal of the contract instance from the participant contract store. This is problematic for
the following scenario (the 3 steps need to be after each other in real time):

• Participant observes Immediately divulged contract C at offset O1.
• Participant starts hosting one of the stakeholders at offset O3 (this leads to offline party replication, which adds the same created event again).
• Participant is being pruned at offset O2.

Offset conditions: O1 < O2 < O3.

Affected Deployments

Participant nodes

Affected Versions

All 3.4.x < 3.4.9

Impact

Grave: Ledger API operations (command submission, pointwise/streaming update retrieval) related to the respective contracts fail with internal error due to the contract being removed from the store.

Symptom

If the conditions are met, the respective contract is removed from the participant contract store leading to (non-exhaustive list):

• Ledger API pointwise/streaming endpoints (Update, ACS) fail with internal error in case the respective import event is included in the results.
• Ledger API command submission fails with "contract not found" for interpretations that have the respective contract as an input.

Workaround

Not using ACS import/repair service which adds contracts after bootstrapping, or not pruning the participant.

Likelihood

Possible

Recommendation

Upgrade to >= 3.4.9

Compatibility

The following Canton protocol versions are supported:

Dependency	Version
Canton protocol versions	34

Canton has been tested against the following versions of its dependencies:

Dependency	Version
Java Runtime	OpenJDK 64-Bit Server VM (build 21.0.5+1-nixos, mixed mode, sharing)
Postgres	Recommended: PostgreSQL 17.7 (Debian 17.7-3.pgdg13+1) – Also tested: PostgreSQL 14.20 (Debian 14.20-1.pgdg13+1), PostgreSQL 15.15 (Debian 15.15-1.pgdg13+1), PostgreSQL 16.11 (Debian 16.11-1.pgdg13+1)

canton v3.4.8

Release of Canton 3.4.8

Canton 3.4.8 has been released on November 14, 2025.

Summary

This is a maintenance release that fixes automatic synchronization of protocol feature flags.

What’s New

Minor Improvements

• The generateExternalPartyTopology endpoint on the Ledger API now returns a single PartyToParticipant topology transaction to onboard the party.
  The transaction contains signing threshold and signing keys. This effectively deprecate the usage of PartyToKeyMapping.
  For parties with signing keys both in PartyToParticipant and PartyToKeyMapping, the keys from PartyToParticipant take precedence.

Bugfixes

• Fixed a bug preventing automatic synchronization of protocol feature flags.
  Automatic synchronization can be disabled by setting parameters.auto-sync-protocol-feature-flags = false in the participant's configuration object.

Compatibility

The following Canton protocol versions are supported:

Dependency	Version
Canton protocol versions	34

Canton has been tested against the following versions of its dependencies:

Dependency	Version
Java Runtime	OpenJDK 64-Bit Server VM (build 21.0.5+1-nixos, mixed mode, sharing)
Postgres	Recommended: PostgreSQL 17.7 (Debian 17.7-3.pgdg13+1) – Also tested: PostgreSQL 14.20 (Debian 14.20-1.pgdg13+1), PostgreSQL 15.15 (Debian 15.15-1.pgdg13+1), PostgreSQL 16.11 (Debian 16.11-1.pgdg13+1)

canton v3.4.7

Release of Canton 3.4.7

Canton 3.4.7 has been released on November 10, 2025.

Summary

This is a maintenance release that fixes an issue when replaying too many ACS changes during connection to a synchronizer.

Compatibility

The following Canton protocol versions are supported:

Dependency	Version
Canton protocol versions	34

Canton has been tested against the following versions of its dependencies:

Dependency	Version
Java Runtime	OpenJDK 64-Bit Server VM (build 21.0.5+1-nixos, mixed mode, sharing)
Postgres	Recommended: PostgreSQL 17.6 (Debian 17.6-2.pgdg13+1) – Also tested: PostgreSQL 14.19 (Debian 14.19-1.pgdg13+1), PostgreSQL 15.14 (Debian 15.14-1.pgdg13+1), PostgreSQL 16.10 (Debian 16.10-1.pgdg13+1)

canton v3.4.6

Release of Canton 3.4.6

Canton 3.4.6 has been released on November 07, 2025.

Summary

This is a maintenance release that fixes an issue of importing of existing topology transactions.

Compatibility

The following Canton protocol versions are supported:

Dependency	Version
Canton protocol versions	34

Canton has been tested against the following versions of its dependencies:

Dependency	Version
Java Runtime	OpenJDK 64-Bit Server VM (build 21.0.5+1-nixos, mixed mode, sharing)
Postgres	Recommended: PostgreSQL 17.6 (Debian 17.6-2.pgdg13+1) – Also tested: PostgreSQL 14.19 (Debian 14.19-1.pgdg13+1), PostgreSQL 15.14 (Debian 15.14-1.pgdg13+1), PostgreSQL 16.10 (Debian 16.10-1.pgdg13+1)

canton v2.10.2

Release of Canton 2.10.2

Canton 2.10.2 has been released on July 23, 2025. You can download the Daml Open Source edition from the Daml Connect Github Release Section. The Enterprise edition is available on Artifactory.
Please also consult the full documentation of this release.

Summary

This is a maintenance release that provides minor stability and performance improvements, and resolves a dependency issue with the KMS Driver artifacts.

until 2025-07-23 (Exclusive)

• OTLP trace export configuration has been extended with several new parameters allowing connection to OTLP servers,
  which require more elaborate set-up:
  • trustCollectionPath should point to a valid CA certificate file. When selected a TLS connection
    is created instead of an open-text one.
  • additionalHeaders allows specifying key-value pairs that are added to the HTTP2 headers on all trace exporting
    calls to the OTLP server.
  • timeout sets the maximum time to wait for the collector to process an exported batch of spans.
    If unset, defaults to 10s.

What’s New

Improved Package Dependency Resolution

The package dependency resolver, which is used in various topology state checks and transaction processing is improved as follows:

• The underlying cache is now configurable via canton.parameters.general.caching.package-dependency-cache.
  By default, the cache is size-bounded at 10000 entries and a 15-minutes expiry-after-access eviction policy.
• The parallelism of the DB package fetch loader used in the package dependency cache
  is bounded by the canton.parameters.general.batching.parallelism config parameter, which defaults to 8.

Contract Prefetching

Contract prefetching is now also supported for createAndExercise command. On top of that, we now support recursive prefetching,
which allows to prefetch also referenced contract ids. The default max prefetching level is 3 and can be configured using
canton.participants.participant.ledger-api.command-service.contract-prefetching-depth = 3

Resolve KMS Driver Artifact Dependency Issues

The kms-driver-api and kms-driver-testing artifacts declared invalid dependencies in the Maven pom.xml files, which caused issues in fetching those artifacts. The declared invalid dependencies have been resolved.

Compatibility

The following Canton protocol versions are supported:

Dependency	Version
Canton protocol versions	5, 7

Canton has been tested against the following versions of its dependencies:

Dependency	Version
Java Runtime	OpenJDK 64-Bit Server VM Zulu11.72+19-CA (build 11.0.23+9-LTS, mixed mode)
Postgres	Recommended: PostgreSQL 12.22 (Debian 12.22-1.pgdg120+1) – Also tested: PostgreSQL 11.16 (Debian 11.16-1.pgdg90+1), PostgreSQL 11.16 (Debian 11.16-1.pgdg90+1), PostgreSQL 13.21 (Debian 13.21-1.pgdg120+1), PostgreSQL 13.21 (Debian 13.21-1.pgdg120+1), PostgreSQL 14.18 (Debian 14.18-1.pgdg120+1), PostgreSQL 14.18 (Debian 14.18-1.pgdg120+1), PostgreSQL 15.13 (Debian 15.13-1.pgdg120+1), PostgreSQL 15.13 (Debian 15.13-1.pgdg120+1)
Oracle	19.20.0

canton v2.10.1

Release of Canton 2.10.1

Canton 2.10.1 has been released on May 30, 2025. You can download the Daml Open Source edition from the Daml Connect Github Release Section. The Enterprise edition is available on Artifactory.
Please also consult the full documentation of this release.

Summary

This is a maintenance release that fixes one high, one medium, and two low severity issues.
Please update during the next maintenance window.

What’s New

Daml packages validation on Ledger API start-up

On Ledger-API start-up, the Daml package store of the participant node
is checked for upgrade compatibility for all persisted packages.
On compatibility check failure, the participant is shut down with an error message.
To disable the check (not recommended), set canton.participants.participant.parameters.unsafe-disable-upgrade-validation=true.

JWT Tokens in Admin API

Background

User authorization is extended to all service types for participant nodes in 2.10 for the Canton Admin API.

Specific Changes

The users is able to configure authorization on the Admin API of the participant node in a manner similar to what
is currently possible on the Ledger API. However, it is necessary to specify explicitly which users are
allowed in and which grpc services are accessible to them. An example configuration for both Ledger and Admin API
looks like this:

canton {
  participants {
    participant {
      ledger-api {
        port = 5001
        auth-services = [{
          type = jwt-rs-256-jwks
          url = "https://target.audience.url/jwks.json"
          target-audience = "https://rewrite.target.audience.url"
        }]
      }
      admin-api {
        port = 5002
        auth-services = [{
          type = jwt-rs-256-jwks
          url = "https://target.audience.url/jwks.json"
          target-audience = "https://rewrite.target.audience.url"
          users = [{
            user-id = alice
            allowed-services = [{
              "admin.v0.ParticipantRepairService",
              "connection.v30.ApiInfoService",
              "v1alpha.ServerReflection",
            }]
          }]
        }]
      }
    }
  }
}

While the users appearing in the sub claims of the JWT tokens on the Ledger API always have to be present in
the participant’s user database, no such requirement exists for the Admin API. The user in the authorization service
config can be an arbitrary choice of the participant’s operator. This user also needs to be configured in the associated
IDP system issuing the JWT tokens.

The configuration can contain a definition of either the target audience or the target scope depending on the specific
preference of the client organization. If none is given, the JWT tokens minted by the IDP must specify daml_ledger_api
as their scope claim.

Independent of the specific service that the operator wants to expose, it is a good practice to also give access rights
to the ServerReflection service. Some tools such as grpcurl or postman need to hit that service to construct their requests.

Impact and Migration

The changes are backwards compatible.

LF 1.17 templates cannot implement LF 1.15 interfaces.

Background

Bug 25-005, detailed below, prevents the execution of choices from LF
1.15 interfaces within LF 1.17 templates. To resolve this, we have
entirely restricted LF 1.17 templates from implementing LF 1.15
interfaces. However, this change is more than just a bug fix—it
reflects a deliberate alignment with upgradeability principles.
While mixing LF 1.15 interfaces with LF 1.17 templates may seem
advantageous, it is only useful if your model contains other LF 1.15
templates implementing those interfaces. Yet, this approach ultimately
disrupts the upgrade path. Maintaining two versions of a template
within the same model leads to inconsistency: LF 1.17 templates
support seamless upgrades, whereas LF 1.15 templates do not, requiring
an offline migration to fully upgrade the model.

Specific Changes

• The compiler now prevents Daml models from implementing an LF 1.15
  interface within an LF 1.17 template.

• For backward compatibility, participants can still load these models
  if they were compiled with SDK 2.10.0. However:

  • A warning is issued at load time, if those models contain an LF 1.17 template implementing an LF 1.15 interface.
  • Any attempt to execute a choice on an LF 1.15 interface within an
    LF 1.17 template (compiled with SDK 2.10.0) will trigger a runtime
    error during submission.

Impact and Migration

These changes preserve backward compatibility, while preventing
the participant from crashing.

Minor Improvements

• The daml values representing parties received over the Ledger API can be validated in a stricter manner. When the
  canton.participants.<participant>.http-ledger-api.daml-definitions-service-enabled parameter is turned on,
  the parties must adhere to a format containing the hint and the fingerprint separated by a double colon:
  <party-hint>::<fingerprint>. The change affects the values embedded in the commands supplied to the Submit* calls
  to the CommandSubmissionService and the CommandService.
• Added configuration for the size of the inbound metadata on the Ledger API. Changing this value allows
  the server to accept larger JWT tokens.
  canton.participants.participant.ledger-api.max-inbound-metadata-size=10240
• canton.participants.participant.parameters.disable-upgrade-validation is explicitly deemed a dangerous configuration by:
  • renaming it to unsafe-disable-upgrade-validation.
  • only allowing its setting in conjunction with canton.parameters.non-standard-config = yes

Bugfixes

(25-005, Low): Cannot exercise LF 1.15 interface choices on LF 1.17 contracts

Issue Description

Daml-LF 1.17 versions exercise-by-interface nodes according to the
interface's language version. This ensures that the choice argument
and result are not normalized if the interface is defined in LF 1.15,
which is important for Ledger API clients that have been compiled against
the interface and expect non-normalized values. Yet, the package name
is still set on the exercise node based on the contract's language
version, namely 1.17.

This leads to at least two problems:

• When Canton tries to serialize the transaction in Phase 7, the
  TransactionCoder attempts to serialize the node with version 1.15
  into the SingleDimensionEventLog, but cannot do so because package
  names cannot be serialized in 1.15. This serialization exception
  bubbles up into the application handler and causes the participant
  to disconnect from the domain. This problem is sticky in that crash
  recovery will run into the same problem again and disconnect
  again.

• When the template defines a key, Canton serializes the global key
  for the view participant according to the exercise node
  version. Accordingly, the hash of the key according to LF
  1.15. This trips up the consistency check in ViewParticipantData
  because the input contract's serialized key was hashed according to
  LF 1.17. This failure happens only Phase 3 during when decrypting
  and parsing the received views. Participants discard such views and
  reject the confirmation request. The failure does not happen in
  Phase 1 because the global key hashes are still correct in Phase 1.
  Serialization correctly sets the package name, but uses the wrong
  version (1.15) from the exercise node. Deserialization sees the
  wrong version and ignores the package name.
  Accordingly, the participant discards the views it cannot
  deserialize and rejects the confirmation request if it is a
  confirming node.

Affected Deployments

Participant nodes.

Affected Versions

• 2.10.0

Impact

• Participant node crashes and may need manual repair.
• Command submission fails with INVALID_ARGUMENT.

Symptom

If the template defines a contract key, the participant logs
LOCAL_VERDICT_MALFORMED_PAYLOAD with error message "Inconsistencies
for resolved keys: GlobalKey(...) -> Assigned(...)" and rejects the
confirmation request. The command submission fails with
INVALID_ARGUMENT

If the template does not define a contract key, the transaction gets
processed, but the participant fails to store the accepted transaction
in its database with the error message "Failed to serialize versioned
transaction: packageName is not supported by transaction version 15",
disconnects from the domain with an ApplicationHandlerFailure and
possible crashes (depending on configuration). Reconnection attempts
will run into the same problem over and over gain.

Workaround

Recompile the interfaces with LF 1.17. This may break ledger API
clients that expected trailing None record fields in exercise arguments
and results.

Likeliness

Deterministic.

Recommendation

Upgrade to 2.10.1. If your Daml models contain LF 1.17 templates
implementing LF 1.15 interfaces, and you face issues rewriting
everything in LF 1.17, please contact Digital Asset support.

(25-006, High): Confidential configuration fields are logged in plain text when using specific configuration syntax or CLI flags

Issue Description

If the logConfigWithDefaults config parameter is set to false (which is the default),
the config rendering logic fails to redact confidential information (e.g DB credentials) when config substitution is used in combination with a config element override.

Suppose we have the following configuration file:

canton.conf

_storage {
  password = confidential
}
canton {
  storage = ${_storage}
}

Now the confidential config element is changed via another config file:

override.conf

canton.storage.password = confidential2

and then:

canton v2.9.7

Release of Canton 2.9.7

Canton 2.9.7 has been released on April 14, 2025. You can download the Daml Open Source edition from the Daml Connect Github Release Section. The Enterprise edition is available on Artifactory.
Please also consult the full documentation of this release.

Summary

This is a maintenance release that fixes one medium severity issue which prevents migration of contracts with keys via ACS export / import. Please update if affected.

Bugfixes

(25-004, Medium): RepairService contract import discards re-computed contract keys in the repaired contract

Issue Description

The repair service re-computes contract metadata when adding new contracts.
However, instead of repairing the contract with the re-computed keys, it re-uses the keys from the input contract.
Combined with a gap in the console macros which do not propagate contract keys during ACS export,
migrating contracts with keys in that way can result in an inconsistency between the ACS and contract key store,
which crashes the participant when attempting to fetch a contract by key.

Affected Deployments

Participant nodes.

Affected Versions

• 2.10.0
• 2.9.0-2.9.6
• 2.8.x

Impact

Contracts with keys cannot be used after migration via ACS export / import.

Symptom

The participant crashes with
"java.lang.IllegalStateException: Unknown keys are to be reassigned. Either the persisted ledger state corrupted or this is a malformed transaction"
when attempting to lookup a contract by key that has been migrated via ACS export / import

Workaround

No workaround available. Update to 2.9.7 if affected.

Likeliness

Deterministic if migrating contracts with keys using ACS export to an unpatched version.

Recommendation

Upgrade to 2.9.7 if affected by this issue.

Compatibility

The following Canton protocol versions are supported:

Dependency	Version
Canton protocol versions	5

Canton has been tested against the following versions of its dependencies:

Dependency	Version
Java Runtime	OpenJDK 64-Bit Server VM Zulu11.72+19-CA (build 11.0.23+9-LTS, mixed mode)
Postgres	Recommended: PostgreSQL 12.22 (Debian 12.22-1.pgdg120+1) – Also tested: PostgreSQL 11.16 (Debian 11.16-1.pgdg90+1), PostgreSQL 13.20 (Debian 13.20-1.pgdg120+1), PostgreSQL 14.17 (Debian 14.17-1.pgdg120+1), PostgreSQL 15.12 (Debian 15.12-1.pgdg120+1)
Oracle	19.20.0

canton v2.10.0

Release of Canton 2.10.0

Canton 2.10.0 has been released on February 12, 2025. You can download the Daml Open Source edition from the Daml Connect Github Release Section. The Enterprise edition is available on Artifactory.
Please also consult the full documentation of this release.

Summary

Release 2.10.0 has three key enhancements.

First, the long awaited Smart Contract Upgrade (SCU) is now Generally Available. So, fixing application bugs or extending Daml models is possible without downtime or breaking Daml clients. This feature also eliminates the need to hardcode package IDs which increases developer efficiency. The steps to enable this feature are described below. It was introduced as Beta in v2.9.1 and has since undergone a lot of hardening based on customer feedback so it transitioned to GA status.

Secondly, the new “Tri-State Vetting” feature complements SCU by allowing a DAR to be unvetted in production. This is helpful to disable a DAR that has a bug in its business logic and then upgrade it without downtime.

Lastly, this is the first Daml Enterprise release to be designated a Long Term Support (LTS) release. An LTS release focuses on long term stability and may forgo feature enhancements. It is supported for multiple years and can be upgraded to with full data continuity, but it does have some caveats:
Limited cross-version compatibility, specifically no guaranteed support for old Canton Protocol versions.
No long-term support for deprecated features.
Focuses on supporting LTS versions of environment components (java, dbs, etc).
LTS releases are only guaranteed to have Critical or High issues fixed. Lower priority fixes are possible but not mandatory.

What’s New

Introduction of protocol version 7

Background

There is a new Canton protocol version (PV=7) in this release and it also supports PV=5.

Specific Changes

Protocol version 6 has been marked as deleted and should not be used.
Protocol version 7 has been introduced as its stable replacement. There is also a new Daml LF version (LF 1.17).
Some features have been deprecated in support of this being a LTS release and also to enable SCU.

Impact and Migration

Please remember that since version 2.9, you must set the protocol version explicitly. In prior releases, the domain protocol version was set to the latest protocol version by default. To specify the protocol version for a domain:

myDomain {
init.domain-parameters.protocol-version = 7
}

Specifying for a domain manager is:

domainManager {
init.domain-parameters.protocol-version = 7
}

You can read more about protocol versions in the public docs. If you are unsure which protocol version to pick, use the latest one supported by your binary (see docs).

Please ensure all your environments use the same protocol version: you should not use one protocol version in your test environment and another one in production.

If a protocol version is not provided, then an error message like this will be generated:

ERROR c.d.c.CantonEnterpriseApp$ - CONFIG_VALIDATION_ERROR(8,0): Failed to validate the configuration due to: Protocol version is not defined for domain `mydomain`. Define protocol version at key `init.domain-parameters.protocol-version` …

Daml-LF versions 1.14, 1.15, and 1.17 are available in this release. LF 1.15 is the default Daml compiler setting. LF 1.16 has been deleted and should not be used. Use LF 1.17 to enable the SCU feature.

The compatibility matrix is:

• PV5 is compatible with LF 1.14 and LF 1.15.
• PV7 is compatible with LF 1.14, LF 1.15, and LF 1.17.
• PV7 and LF 1.17 enable SCU and SCU is disabled with any other configuration.

Smart Contract Upgrading (SCU)

The SCU feature debuted as a Beta level feature in 2.9.1 and it is now GA. These release notes are similar to the 2.9.1 release notes with some updates.

Background

SCU allows Daml models (packages in DAR files) to be updated on Canton transparently, provided guidelines in making the changes are followed. For example, you can fix a Daml model bug by uploading the DAR that has the fixed package version. This feature requires LF 1.17 and Canton Protocol versions 7. The detailed documentation is available here with the reference documentation available here. Please note that enabling this feature may require code updates for rarely used language idioms. For example, it does require that the daml.yaml files set the package version and that the version is increasing as new versions are developed.

Details

This feature is well-suited for developing and rolling out incremental template updates. There are guidelines to ensure upgrade compatibility between DAR files. The compatibility is checked at compile time, DAR upload time, and runtime. This is to ensure data backwards compatibility and forward compatibility (subject to the guidelines being followed) so that DARs can be safely upgraded to new versions. It also prevents unexpected data loss if a runtime downgrade occurs (e.g., a ledger client is using template version 1.0.0 while the participant node has the newer version 1.1.0).

A general guideline is that additive model changes are allowed but items cannot be removed. A summary of the allowed changes in templates are:

• A template can add new optional fields at the end of the list of fields;
• A record datatype can add new optional fields at the end of the list of fields, and a variant/enum datatype can add new constructors at the end;
• The ensure predicate can be changed and it is reevaluated at interpretation;
• A choice signature can be changed by adding optional parameters at the end;
• The controller of a choice can be changed;
• The observer of a choice can be changed
• The body of a choice can be changed;
• A new choice can be added to a template;
• The implementation of an interface instance can be changed;

The Beta version of this feature allowed a new interface instance to be added to a template but this ability is not available in this GA release. Please consult the documentation for more information.

The package name associates a series of DAR versions where the newest version is the default version to use. The package name and version (e.g., “version: 1.1.0”) are specified in the daml.yaml file. Package name is now part of the Fully Qualified Name instead of the package ID. Internally, the package ID is still available and used at run time where the package name and version are resolved to a package ID. This allows backwards compatibility.There is flexibility where the package ID can still be specified (prior approach) or the package name can be used (new approach). A side effect is that the package name provides a namespace scope where modules, templates, and data belong to the namespace of a package.

To prevent unexpected behavior, this feature enforces that a DAR being uploaded to a participant node has a unique package name and version. This closes a loophole where the PN allowed uploading multiple DARs with the same package name and version. For backward compatibility, this restriction only applies for packages compiled with LF >= 1.17. If LF <= 1.15 is used, there can be several packages with the same name and version but this should be corrected as it will not be supported further.

Compilation support for smart contract upgrade is enabled by adding following fields to the daml.yaml:

• --target=1.17
• ‘upgrades: ’

For additional type checking, use the ‘dry-run’ option which simulates the checks a PN will run during the upload step. The format of the command is “daml ledger upload-dar --dry-run” which can be included as part of a CI/CD process.

The JSON API server is compatible with the smart contract upgrade feature by:

• Supporting package names for commands and queries;
• Allowing use of an optional packageIdSelectionPreference field to specify a preferred package ID to use. This allows the client to specify the package ID like in prior releases but it is not a best practice;
• Requiring either a package ID or package name to be present to disambiguate the partially-qualified form of template/interface ids.

Previously JSON API had supported partially qualified template IDs, (i.e. simply <module>:<entity>) as an interactive convenience which fails if there is more than one package with matching template names. Since this format was not supported for production use and will not work with smart contract upgrades, it is now unavailable.

The Java and TypeScript codegen allow the use of package name and package ID (if needed).

Impact and Migration

This feature is not enabled by default. There are four steps that are required to enable this feature:

• Compile the Daml model(s) into LF 1.17 (LF 1.15 is the default). When using the daml build command to compile a Daml project, make sure the LF-version is set to 1.17. To do this, set this field in the daml.yaml

  build-options:
  ---target=1.17
  

  Additionally, use the following field to enable compile time checking of LF 1.17 upgrade DARs:

  upgrades: <path to dar files of prior versions>
  

• The Canton protocol version needs to be set to 7. (This is the default version for daml sandbox and daml start.) See here (the parameter protocolVersion) for domain parameter configuration.

• Use the script library called daml-script-lts instead of the older daml-script.

• Domain migration. For existing systems, the protocol version change requires a domain migration that is discussed in “Change the Canton Protocol Version.”

This feature is not compatible with some deprecated coding patterns which may require some code changes.

1. Retroactive interface instances are not supported.
2. Usi...