Release of Daml SDK 0.13.55

Daml SDK 0.13.55 has been released on the 18th of March 2020. You can install it using

daml install latest

If you're planning to upgrade your Daml SDK to take advantage of our newest features please note that some action may be required on your part. If you're not planning to upgrade then no change is necessary.

Summary

  • Daml Script is officially supported
    • Action required by April 2020 if you use scenarios for Sandbox initialization
  • Daml Repl is available as an experimental feature
  • Daml-LF 1.8 adds support for cross-SDK DAR Dependencies and Contract Upgrades
    • Minor action required to mitigate an upcoming restriction to Daml type naming
  • Improved daml.yaml features
  • More consistent APIs regarding contract visibility
    • Potentially breaking change that is unlikely to affect any existing Daml applications
  • New command deduplication feature
    • Action required by April 2020 if you rely on maximum record time for command deduplication
  • Security improvement
    • Immediate action required to make SDK components continue to listen on external network interfaces

Detailed Release Notes

Daml Script - A better way to initialize and test your ledger

Background

Being able to script the interaction with a Daml ledger is useful for testing, application initialization, and even one-off operations in production use. Daml scenarios cover a subset of those uses: Realtime testing and feedback in the IDE and ledger initialization in the Sandbox in static time mode. The main drawback of scenarios is that outside of the IDE, they only work with the Sandbox in static time mode and only during ledger initialisation. We have, therefore, built Daml Script, which generalizes the concepts behind Scenarios to work for any Daml Ledger, at any time. Going forward, we will deprecate ledger initialization based on Scenarios, and we recommend users to start using Daml Script now.

Specific Changes

  • Daml Script is no longer experimental
  • daml.yaml now supports the specification of an initialization script via the init-script field, which is analogous to the scenario field.
  • Daml Script now works against ledgers with authentication with tokens passed in via the --access-token-file flag
  • Daml Sandbox now shows a deprecation warning if a scenario is used for initialization

Impact and Migration

Scenarios for Sandbox initialization will no longer be supported with the next SDK release in April 2020, but will continue to be supported for Daml model testing in the IDE and command line. If you are using a scenario to initialize the Sandbox today, we recommend migrating that to a Daml script. Daml Script has similar syntax to Scenarios, and the migration from scenarios to Daml script is documented.

Experimental: Daml Repl - Interactive Daml Script

Background

We are introducing an interactive read-eval-print-loop (REPL) for interacting with a Daml ledger. This feature is analogous to using an interactive shell session to examine and change the data in a relational database. It is based on Daml Script and allows accessing all functions from your Daml code. We encourage you to test this feature and provide feedback. It is still marked as experimental, so we can incorporate your feedback effectively and efficiently.

Specific Changes

  • Introduction of the daml repl cli command

Impact and Migration

Daml Repl is an entirely new feature, and no changes to existing projects are needed. Please refer to the docs for more information on this new functionality.

Daml-LF 1.8 brings cross-SDK upgrades and data dependencies

Background

One of Daml’s unique features is that the clear data ownership based on signatories allows for clean contract upgrades directly from within Daml. So far, this required SDK versions of the original and the new Daml contracts to be equal, a limitation that we obviously wanted to lift. This release lifts this restriction and adds support for contract migrations across SDK versions thanks to adding support for data-dependencies in daml.yaml.

dependencies and data-dependencies are source and binary dependencies respectively. dependencies should be used to include any libraries (e.g. the Daml Standard Library) that are always deployed together with the project, whereas data-dependencies should be used for any dependencies that are independently deployable, for example the Daml Finance Library, or applications already running on the target ledger.

Specific Changes

  • daml.yaml now supports a section for data-dependencies in addition to dependencies
  • The already deprecated daml migrate command has been removed
  • Data constructors for record types have to be the same as the type name.

Impact and Migration

To make use of this feature, Daml projects have to be compiled to Daml-LF 1.8. The current default is still 1.7, and so this has to be done by passing in the flag --target=1.8. Detailed information on the upgrading and dependency functionality can be found in the docs.

Data constructors that don’t match record type names have to be renamed. For example, if you had a record type data Foo = Bar with .., you need to change it to data Foo = Foo with ..

More functionality in daml.yaml

Background

The project file daml.yaml should tell the Daml Assistant CLI everything it needs to know to set up a test environment using daml start. However, until this release, there were certain Sandbox, Navigator, and HTTP JSON API settings that needed to be set through additional command line flags. These can now be set using sandbox-options, navigator-options and json-api-options sections in daml.yaml.

Specific changes

  • Items under the sandbox-options, navigator-options and json-api-options sections in daml.yaml are picked up by daml start and passed to the respective components.

Impact and Migration

Command line arguments like daml start --sandbox-option="--wall-clock-time" will keep working as before, but you can now simplify your CLI usage moving them into daml.yaml.

Cleanup of some API services and components

Background

Privacy is one of Daml’s primary concerns, with visibility of data usually constrained to signatories and observers of contracts. However, there are two well-documented and controlled mechanisms through which non-observers can learn about contracts: Divulgence and Witnessing.

Whether events or contracts that are known due to those mechanisms are shown in APIs or tools used to be inconsistent and led to oddities such as the Navigator showing assets that had been transferred. This change addresses these inconsistencies and ensures divulged and witnessed contracts are only included in APIs returning transaction trees.

Specific Changes

  • The Flat Transaction Service and Active Contract Service no longer include divulged and witnessed contracts
  • The JSON API no longer includes divulged and witnessed contracts
  • The Extractor no longer stores divulged and witnessed contracts and the column contract.witness_parties has been renamed to contract.stakeholders

Impact and Migration

Applications are unlikely to be accidentally relying on the current behaviour so there is probably little to no impact on existing Daml applications.

In general, if you want to share data on a Daml ledger, we recommend using the observer mechanism or sharing it in dedicated sharing contracts as highlighted in the Broadcast Example.

New Command Deduplication Mechanism

Background

For certain applications, it is crucially important that commands will not be processed twice, even if application or ledger components crash or network links fail. The new command deduplication mechanism gives a way to achieve that.

The previous mechanism based on Maximum Record Time (MRT) and Checkpoints on the CompletionStream was difficult to use in practice and didn’t generalise to ledgers without a linearly ordered record time. The new mechanism is designed to replace the old one over the course of the next Daml SDK releases.

Specific Change

  • The Command and CommandSubmission services add a deduplication_time parameter to commands during which no second command with the commandId can be submitted.

Impact and Migration

The maximum record time based mechanism for command deduplication is now deprecated and will be removed with the next SDK release. We recommend switching from the MRT-based mechanism to deduplication_time based one. Detailed documentation here.

Minor Improvements

  • JSON API
    • The JSON API has a new /v1/create-and-exercise endpoint that allows the submission of commands creating a contract and then immediately exercising a choice on it.
    • The experimental websocket streaming version no longer sends a {"live": true} marker to indicate live data is starting. Instead, live data is indicated by the presence of an offset.
    • The /v1/parties endpoint now allows POST requests, which expect a JSON array of party identifiers as input, and returns the corresponding party details.
  • Language
    • The pragma daml 1.2 is now optional. This is in preparation for Daml SDK 1.0 from which time on the language won’t be versioned independently from the SDK.
  • Ledgers
    • Rejected submissions are now logged at a lower "INFO" level to remove a source of warnings/errors without relation to server health.
    • The Sandbox can now produce random ContractIds consistent with other ledger implementations. This can be activated using the flags --contract-id-seeding=weak or --contract-id-seeding=strong. The weak version uses a less safe, non-blocking random number source.
  • Security
    • All services now bind to localhost (127.0.0.1) instead to all interfaces (0.0.0.0). This default can be overridden using command line flags
      • daml sandbox --address 0.0.0.0
      • daml navigator 0.0.0.0 6865
      • daml json-api --address 0.0.0.0