Skip to content
Digital Asset Logo

Release of Daml SDK 1.6.0

| | |

Daml SDK 1.6.0 has been released on October 15th 2020. You can install it using:

daml install latest

Note: The 1.6.0 RCs had an issue when migrating from pre-1.0.0 ledgers. This is fixed in the stable release.

There are no changes requiring changes for existing applications. However we have fixed a bug in DA.Date.date which changes its behavior (see #7393) and are deprecating some functionality which may be removed from Daml after a minimum of 12 months so please read below.

Interested in what's happening in the Daml community and its ecosystem? If so we've got a jam packed summary for you in our latest community update.

Highlights

Impact and Migration

As part of the scope and status definition of core Daml technology as well as with the introduction of better stream queries in the JavaScript Client Libraries, there have been some deprecations. However, as per the guarantees given by semantic versioning and the feature and component status definitions, this merely means that these features may be removed with a major version release no earlier than 12 months from today.

If you are using any of the features listed below, you are advised to migrate to an alternative, detailed in the more detailed notes further down, within that time frame. Deprecations:

Ledger API Bindings

SDK

  • daml damlc package assistant command
  • daml 1.2 pragma
  • daml new with positional arguments

JavaScript Client Libraries

  • streamQuery and streamFetchByKey

Documentation on Versioning, Compatibility, and Support

Background

Since the release of Daml SDK 1.0, great care has been taken to ensure proper forwards and backwards compatibility, and ensure the stability users rightfully expect of mission-critical software like Daml. Until now, however, the specific compatibility and long-term support guarantees that were in place were not articulated, nor was there a clear, reliable definition of what constitutes Daml’s “public API.” 

The new documentation addresses this by adding a number of new pages covering Scope, Status, Compatibility, and Evolution of core Daml technology. As part of bringing clarity to the status and evolution of Daml, there has been a bit of housekeeping and some features that have been superseded, or have not seen much uptake have been deprecated. As per the guarantees given by semantic versioning and the feature and component status definitions, this merely means that these features may be removed with a major version release no earlier than 12 months from today. See “Impact and Migration” below for specifics and recommended alternatives.

Specific Changes

Impact and Migration

First and foremost, it is important to understand that there is no immediate need to act. Deprecation does not mean removal or end of support. Deprecation is an early warning that the feature may be removed, or at least lose support after an appropriate deprecation cycle. In the case of entire features like the Ledger API Bindings, these cycles are described on the feature and component status definitions page, and the current guarantee is that support will continue for at least 12 months, and can only end with a major version release.

Smaller interface changes like the daml damlc package command are simply covered by semantic versioning, which means they will stay supported at least until the next major release.

  • Users of the Scala and Node.js Ledger API bindings are advised to switch to a combination of the Java Ledger API Bindings and JSON API.
  • Users of the Java Reactive Components are advised to switch to the JSON API to replace LedgerView, and simply react to events from the Ledger API Transaction Service to build event based automation. We are also actively working on making Daml Triggers a stable component so for solutions not going into production before Q2 2021, those are another recommended option.
  • daml damlc package should be replaced by daml build.
  • daml 1.2 pragmas should simply be removed.
  • Use of daml new with positional arguments should be changed to the form with the --template argument.

Better Stream Query Features in Javascript Client Libs

Background

The existing streamQuery and streamFetchByKey functions accepted at most one query or key for which to stream data. Two new methods have been added to daml-ledger: streamQueries and streamFetchByKeys. They are similar to the existing singular versions, except they can take multiple queries and multiple keys, respectively, and return a union of the corresponding individual queries/keys. Because these new functions can do everything the existing ones can, we are deprecating the old forms, though in line with semantic versioning, they will not be removed until the next major version at the earliest.

Specific Changes

  • Addition of streamQueries function to daml-ledger
  • Addition of streamFetchByKeys function to daml-ledger
  • Deprecation of streamQuery in daml-ledger
  • Deprecation of streamFetchByKey  in daml-ledger

Impact and Migration

The upgrade path is straightforward:

  streamQuery(t); => streamQueries(t, []);

  streamQuery(t, undefined); => streamQueries(t, []);

  streamQuery(t, q); => streamQueries(t, [q]);

  streamFetchByKey(t, k); => streamFetchByKeys(t, [k]);

There is one caveat, though: streamFetchByKeys is a little bit less lenient in the format in which it expects the key. If your existing code conforms to the generated TypeScript code, everything should keep working, but if you were using plain JS or bypassing the TS type system, it is possible that you used to construct keys that will no longer be accepted. The new function requires all keys to be given in the output format of the JSON API,  which is a little bit more strict than the general JSON <-> LF conversion rules.

New Chapters in the Introduction to Daml

Background

An Introduction to Daml is intended to give new developers a crash course in Daml Contract development, getting them to the point of proficiency and effectiveness as quickly as possible. Several areas were identified as insufficiently covered either there or elsewhere in the documentation, so new sections are now available covering those gaps.

Specific Changes

Impact and Migration

None

Minor Improvements

  • Added undefined to Prelude, allowing the stubbing of functions, branches, or values during development.
  • daml start now has a --navigator-port option allowing you to specify the port for navigator's web server.
  • Daml Script has gained two new query functions: queryContractKey and queryFilter, allowing the querying of active contracts by key, or by type with a predicate.
  • The compiler will now emit a warning when you have a variant type constructor with a single argument of unit type (). For example, data Foo = Bar () | Baz will result in a warning on the constructor Bar.  This is because the unit type will not be preserved when importing the package via data-dependencies. The correct solution, usually, is to remove the argument from the constructor: data Foo = Bar | Baz. Note that this rule does not apply when the variant type has only one constructor, since no ambiguity arises.
  • DAR files are now already validated on the Ledger API server before uploading them to the ledger. This may increase upload time, but means the risk of invalid packages polluting the ledger is reduced.

Bugfixes

  • Newtype constructors must now have the same name as the newtype itself, since newtypes are record types. This restriction has been in place for Record Types for a long time, and it was an oversight that the compiler did not enforce this for newtype. This does not affect Daml compiled with older SDK versions in any way.
  • DA.Date.date now raises an error when the day argument is outside the valid range. It previously rolled over into the next month in an unsafe fashion. This does not affect Daml compiled with older SDK versions in any way.
  • Authorization checks are interleaved with execution. This resolves a number of minor privacy leaks. See #132 for details.
  • Fixed a bug in the JavaScript client libraries where, upon closing a stream, the underlying WebSocket connection may not be properly closed.

Integration Kit

  • In kvutils, the BatchedSubmissionValidator no longer has a parameter for commit parallelism. Commits are now always written serially to preserve order.
  • In kvutils, state is now sorted before committing. This allows us to provide stronger guarantees with regards to the serialized write sets. If you have implemented your own CommitStrategy, you should also ensure the output state is sorted before committing.
  • The StandaloneApiServer now takes a healthChecks parameter, which should identify the health checks to be exposed over the gRPC Health Checking Protocol. This will typically look something like:

      healthChecks = new HealthChecks("read" -> readService, "write" -> writeService)

    Integrators may also wish to expose the health of more components. All components wishing to report their health must implement the ReportsHealth trait.
  • Fixed a race condition in the Ledger API Test Tool in which multiple connections were created to a single participant, and only one was shut down properly. This error was likely benign but may cause spurious errors to show up when the test tool finishes and shuts down.
  • The hardcoded timeout for party allocation and package uploads in the Ledger API Server can be configured via ParticipantConfig and the default value is now set to 2 minutes (#7593 & #6880).

What’s Coming

We are continuing to work on performance of the Daml integration components and improving production readiness of Daml Ledgers, but there are exciting features and improvements in the pipeline for the next few releases as well.

  • The Trigger Service will reach feature completion and move into Beta
  • The authentication framework for Daml client applications (like the Trigger Service) is being revisited to make it more flexible (and secure!)
  • The build process for Daml client applications using the JavaScript/TypeScript tooling is being improved to remove the most common error scenarios
  • Daml’s error and execution semantics are being tidied up with a view towards improving exception handling in Daml
  • Daml will get a generic Map type as part of Daml-LF 1.9

Related Posts