Daml 2.0 has been released. You can install it using:

daml install 2.0.0

Highlights

• Integrating Canton into Daml - introducing Canton-enabled drivers
• Improvements in the developer experience to build and test distributed applications
• Addition of the User Management Service
• Supporting newer versions of dependencies

Impact and Migration

Daml always aims to maintain stability and ensure backwards compatibility, even between major versions. To keep to this mantra the migration impact has been kept to a minimum:

• For Canton-enabled drivers, backwards compatibility will be broken only in ways we expect to have zero or minimal impact on production customers (except in corner cases):
• A Daml 1.X project should compile unchanged in Daml 2.X.
• A Daml 1.X project should run unchanged on a Daml 2.X ledger.
• For changes that may have a minimal impact see title Impact and Migration in the Integrating Canton into Daml - introducing Canton-enabled drivers section further down in these release notes.
• Daml will continue supporting superseded Daml 1.X and associated Drivers for a minimum of 12 months.
• The Daml Driver for VMBC is a special case where there is no breaking change as it will not yet become a Canton-enabled driver. It will be fully compatible with Daml 2.0.

What’s new

Integrating Canton into Daml - introducing Canton-enabled drivers 

Background

Three years ago Daml started a project called Canton, a distributed ledger that can be enhanced when deployed with complementary blockchains, to help achieve its goal of building a global economic network of seamlessly interconnected businesses. With the release of version 2.0, Daml is integrating Canton into its product. Canton-enabled drivers deliver enhanced security and privacy, allow more flexible network topologies, and introduce network composability as an early access / alpha feature:

• Security confidence regardless of the underlying infrastructure: Messages are encrypted at the participant level regardless of the underlying infrastructure - a relational database or a blockchain layer - requiring less trust in anyone who has access to information on the domain.
• Increased privacy: Encrypting messages at the participant level means that the content of the transaction is hidden from anyone who has access to information on the domain.
• Flexible topologies: Both centralized and decentralized architectural models are supported by all Canton-enabled drivers making it easier to move between topologies, enable a hybrid model and give the flexibility for parties to move from sharing a participant to hosting their own.
• GDPR compliance: Canton-enabled drivers and 1.x VMBC drivers also provide history pruning and redaction capabilities for its log, meaning that it’s easy to comply with GDPR’s right to be forgotten .
• Network composability (alpha): Daml participants can transact across multiple domains on underlying blockchains and relational database infrastructures, giving seamless application composability across the whole network of networks and making a single Global Economic Network.

Specific Changes

• Click here to read more about Canton and the benefits that it brings to Daml.
• Daml now ships in three versions: Daml Enterprise, Daml Hub and Daml Open Source.
• The Software Development Kit (SDK) now ships with a fully integrated Canton Ledger and integrated Daml tooling.
• Canton-enabled drivers for underlying synchronization technologies will now be distributed as plugins to the Canton participant.

Impact and Migration

• For Canton-enabled drivers, we expect that in the majority of cases backwards compatibility will not be broken:
• A Daml 1.X project should compile unchanged in Daml 2.X
• A Daml 1.X project should run unchanged on a Daml 2.X ledger
• Changes which we expect to have zero or minimal impact on production customers, except in corner cases, are as follows:
• The DA.Next.Map and DA.Next.Set modules have been deprecated since v1.10 and are now removed from the Daml standard library. The DA.Map and DA.Set libraries should be used instead.
• The functions in DA.List.Total now return Optional instead of ActionFail.
• The DA.Maybe.Total and DA.Optional.Total modules have been removed. Use the functions from DA.Optional or pattern match directly.
• The deprecated DA.Generics module has been removed.
• Digital Asset has data migration tooling available to migrate from 1.x to Daml 2.0. Please see the documentation section Importing Existing Contracts. Contact your sales representative for access to the tooling.
• The daml compiler can only produce packages in LF 1.14 (the default since SDK 1.15). DARs referenced in the data-dependencies field of your daml.yaml must be in LF 1.8 (default since SDK 1.0) or newer.
• Support for depending on DARs with LF versions < 1.8 has been removed from the compiler and daml2js.
• Java 11 is now the minimum supported version of Java.
• The syntax controller … can will be deprecated in favor of the choice X controller … syntax. If the deprecated syntax is used then the following warning will be shown in the IDE:
  The syntax 'controller ... can' is deprecated, it will be removed in a future version of Daml. Instead, use 'choice ... with ... controller' syntax. Note that 'choice ... with ... controller' syntax does not implicitly add the controller as an observer, so it must be added explicitly as one (or as a signatory).
• Daml will continue supporting superseded Daml 1.X and associated drivers for a minimum of 12 months.
• Party IDs are no longer user defined strings but are randomly and dynamically generated hashes, therefore party IDs should no longer be hardcoded into code. To help manage dynamic party IDs the Participant User Management feature has been added, details of this change are outlined below.

Improvements in the developer experience to build and test distributed applications

Background

Along with the addition of Canton, the existing Sandbox in the SDK will be replaced with the Canton Sandbox. This improvement will better align the development tooling and developer experience with distributed production use-cases when deploying applications into production and in the ongoing development. Overall this change will add to an even smoother development lifecycle.

The integration of Canton also means that all Daml customers will get the Participant node as part of the Daml application stack promoting applications to be run in more distributed deployments. This change will encourage customers joining a new network to run their own participant, including networks running a PostgreSQL driver, increasing parties' security and privacy on the network.

Specific Changes

• daml start and daml sandbox now launch a Canton test ledger.

Impact and Migration

• Implicit party allocation has been removed.
• Party IDs are no longer user defined strings but are randomly and dynamically generated hashes. To help manage this the User Management Service feature has been added, details of this change are outlined below. Party IDs are unchanged on Daml for VMware Blockchain and Daml for VMware Blockchain will not support the User Management Service in this release.

Addition of the User Management Service

Background

In previous versions managing the mapping between users and Daml parties has not been well supported in many Integration and Access Management (IAM) systems. There is also a limit to the number of parties which can be included in one JWT token header limiting the number parties that a user can act, or read as and revoking access with JWT tokens in most cases is not immediate.

To solve these challenges we are delivering the User Management Service in Daml 2.0 where we introduce the concept of a (participant) user. Each user is typically associated with a primary party and is given the rights to act as or read as other parties. Every participant node will maintain its own mapping from its user ids to the parties that they can act, or read as. Also, when used, user's ids will serve as application ids. Thus, participant users can be used to manage the permissions of Daml applications (i.e. to authorize applications to read-as or act-as certain parties).

The User Management Service means that parties become more like roles and Daml moves to be in line with more familiar concepts like users, roles & groups in databases. This means that dynamic group management becomes easier because participant administrators can effortlessly add and remove the ability for users to act and read as specific parties.

The addition of this feature also prepares the way for other features to be more easily added to Daml in the future such as assigning read as delegation for users on other participants in a distributed environment and resource isolation which will enable participant administrators to assign resource quotas to users' in the participant node’s user management system, and the participant node will then track and limits a user's resource usage accordingly.

Specific Changes

This is a new feature in the Daml Ledger API and users can be assigned in development, in test, and in Daml script. The Ledger API features can be queried to determine whether a participant node supports user management or not. 

For more information see the documentation. The Daml script user management functions start here in the documentation. VMBC drivers will not support the User Management Service in this release. 

Impact and Migration

This is a purely additive feature and the Participant User Access will need to be set up with users and associated parties if this feature is used. To learn how to do so see the documentation. All previously created party authorisation tokens will still work with version 2.0.

Supporting newer versions of dependencies

Background

To keep our dependencies secure and up to date we are updating some of the supported levels to match those supported by the software providers.

Specific Changes

• The minimum supported versions are listed below:
• Java 11
• PostgreSQL 10
• Oracle 19.11
• VSCode 1.52

Impact and Migration

If a lower version of the software listed above is used it will need to be updated to a supported version before upgrading to Daml 2.0.

Additional Changes

• The restrictions on the name and version field in daml.yaml that produced warnings in previous SDK versions when violated now produce an error instead.
• The Reset Service has been removed from the Ledger API Test services.
• Further Ledger API changes
• Application-ID defaulting: as a convenience when using JWT authentication, a request's application_id field can be left empty to ask the server to set the field to the id of the authenticated user or the application-id in the custom token. There are three services that currently specify application_id's in the request: CommandService, CommandSubmissionService, and CommandCompletionService.
• Ledger Identity Service is deprecated, and the ledger_id field is now optional in all requests. The reason for making it optional is that for Canton there is only one global virtual ledger, so there's no need to identify that one ledger. Restrictions to specific participant nodes still work, and are recommended to be used where previously a ledgerId was used on purpose.
• Daml SDK 1.18 marked the last release of the Daml Driver for PostgreSQL 1.0 release line. While still supported, any new functionality going forward will only be available on Daml Driver for PostgreSQL 2.0.
• Scenarios have been removed from the SDK, applications being tested with scenarios should migrate to using Daml Script.
• The following, previously deprecated and labs features have been removed from the SDK:
• The Scala bindings library
• The Node.js bindings library
• The Extractor
• The Daml Assistant command to start the Daml Navigator daml ledger navigator has been dropped in favor of the shorter daml navigator command.
• The platform-version field in daml.yaml is no longer supported. You can still change the SDK version of individual components via the DAML_SDK_VERSION environment variable, e.g., DAML_SDK_VERSION=1.18 daml sandbox or by editing your daml.yaml.
• The warnings for invalid package names and versions in `daml.yaml` have been turned into errors. Valid package names must match the regex ^[A-Za-z][A-Za-z0-9]*(-[A-Za-z][A-Za-z0-9]*)*$ while valid package versions must match the regex ^(0|[1-9][0-9]*)(.(0|[1-9][0-9]*))*$.
• Contract and party identifiers have been shortened in the Navigator UI so that not all of the identifier is shown.  Clicking on a shortened contract or party identifier will copy the full identifier to the system clipboard. Also, input fields which require contract or party identifiers will suggest possible contract and party identifiers based on the user's input to make it easier to select the right contract or party.
• JSON API metrics have been added to keep track separately of the time taken to update the query store and serve the queries (see the documentation).
• Java bindings: the submissionId field previously introduced in the Ledger API is now exposed through the Java bindings as well.
• The option to have Daml spin up a ledger automatically with the command daml test-script has been removed.  To run all test scripts the command `daml script --all` should be used and a ledger must be specified.
• daml trigger now accepts a --ledger-user option which can be used instead of specifying the primary party and all other parties the user has claims to as -ledger-party and -ledger-readas.
• The primary method of configuring Daml components has changed to use HOCON configuration files.  CLI parameters are still supported for backward compatibility; however, HOCON files are suggested to use for configuration going forward.  The following components are affected: Oauth2-middleware, Trigger-Service, JSON-API.

Bug Fixes

• Under rare conditions in the JSON API, a POST-style multi-template query backed by a database could have different template IDs appear to be queried at different ledger times, if updated concurrently. This condition is now checked and accounted for.

• A bug where the HTTP JSON API could issue duplicate ledger calls and experience internal server errors when run with debug logging level has been fixed.  Also, internal server errors were only reported to the user but not logged and this has also been fixed.
• An issue with the typescript bindings has been fixed which caused nested maps not to get encoded properly before they were sent to the JSON API causing requests to fail with a decoding error on the JSON API.
• The argument order in the default implementation of Foldable.foldl1 has been changed to match the argument order of DA.List.foldl1 in the Daml standard library. To recover the previous behavior, swap the arguments.
• The grpc-max-message-size field in daml.yaml now also applies to the message that contains the result of a script.
• A bug has been fixed in Daml Studio which means that contracts that have been rolled back will no longer show up as active in the display table view and in the list of active contracts at the end of the transaction view.