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.
- Scope, Status, Compatibility, and Evolution of core DAML technology are now comprehensively documented.
- The Introduction to DAML documentation has gained new chapters on Dependencies, Functional Programming, The DAML Standard Library, and Testing and Debugging.
Impact and Migration
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
- Scala Ledger API Bindings and Codegen
- Node.js Ledger API Bindings
- Reactive Components of Java Ledger API Bindings (package
daml damlc packageassistant command
daml newwith positional arguments
Documentation on Versioning, Compatibility, and Support
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.
- A new section “DAML Ecosystem” has been added to the documentation.
- Several components and features have been deprecated
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 packageshould be replaced by
daml 1.2pragmas should simply be removed.
- Use of
daml newwith positional arguments should be changed to the form with the
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
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.
- Addition of
- Addition of
- Deprecation of
- Deprecation of
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
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.
- New sections on
Impact and Migration
Prelude, allowing the stubbing of functions, branches, or values during development.
daml startnow has a
--navigator-portoption allowing you to specify the port for navigator’s web server.
- DAML Script has gained two new query functions:
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 () | Bazwill 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.
- 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.datenow 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.
BatchedSubmissionValidatorno longer has a parameter for commit parallelism. Commits are now always written serially to preserve order.
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.
StandaloneApiServernow takes a
healthChecksparameter, 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
- 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).
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!)
- 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