Skip to content
Digital Asset Logo

Release of Daml SDK 1.3.0

| | |

Daml SDK 1.3.0 has been released 16th July 2020. You can install it using

daml install latest

This is a purely additive upgrade which comes with new features, functionality, and bug fixes. Upgrading should not require any intervention.

Summary

  • The Websocket query and fetch APIs are now stable.
  • The JSON API Server is now released as a standalone JAR file to GitHub Releases.
  • Daml Script and REPL now work in Static Time mode and can query parties.
  • Daml Studio exposes more details on how contracts were disclosed.
  • Trigger Service, a solution to host and manage Daml Triggers is now available in Early Access.

Known Issues

The Daml Studio VSCode extension is affected by a known and recently fixed bug in recent VSCode versions: https://github.com/microsoft/vscode/issues/89038

For some users this may lead to the Scenario View in VSCode not rendering correctly. If you are affected by this issue upgrading to VSCode 1.47 should resolve it.

What’s New

Websocket API is stable

Background

The JSON API Server exposes several Websocket endpoints which allow clients to maintain a live view of contract data without polling. These endpoints have been available since before SDK 1.0 in early access, and are now considered stable.

Specific Changes

  • The API specification for the /v1/stream/query and /v1/stream/fetch endpoints are finalized and fully implemented. 

Impact and Migration

The final version of these endpoints is backwards compatible with SDK 1.0 in the sense that clients of these endpoints from SDK 1.0 work with SDK 1.3. Thus no action needs to be taken.

Standalone JSON API Server

Background

The JSON API Server is a component intended to be run in production environments to supplement the lower level Ledger API with an easy-to-use queryable ledger state consumable by any HTTP 1.1 client, including web browsers. Despite this intended use case, the JSON API Server was only distributed as part of the SDK, which meant that the Daml SDK had to be installed on production servers in order to run the JSON API Server. Providing a stand-alone JAR distribution gives application operators a much leaner deployment option.

Specific Changes

Impact and Migration

This is purely additive to the distribution via the SDK so no action is needed. However, if you do run the JSON API Server in a test or production environment, this gives you a leaner and more portable way of doing so.

More functionality in Daml Script and REPL

Background

Daml Script and REPL had some limitations in key test and production use cases. Firstly, neither exposed the Time Service, which made them hard to use in static time mode. Secondly, they only exposed functions to allocate parties, not to query existing parties, which required existing parties to be passed in via a file, or to be obtained using unsafe functions like partyFromText. By exposing the relevant functions of the Ledger API in Daml Script and REPL, Ledger Time can now be queried and set in Static Time mode, and existing parties can be queried.

In addition, it is now possible to use Daml Script and REPL with multiple JWTs, which in particular, means they can be used with multiple parties on DABL.

Specific Changes

  • Daml Script and REPL’s getTime now correctly handles time changes in static time mode and returns the current time by querying the time service rather than defaulting to the Unix epoch.
    This only works in static time mode and via gRPC. In wallclock mode, getTime continues to return the system time in UTC. When run against the JSON API in static time mode, it continues returning Unix epoch.
  • Add setTime to Daml Script and REPL which sets the ledger time via the Ledger API time service.
    This only works in static time mode and via gRPC.
  • Add listKnownParties and listKnownPartiesOn to query the corresponding ListKnownParties endpoint in the Party Management service.
  • The time mode for Daml REPL can now be specified using the--static-time and --wall-clock-time flags.
  • You can now use Daml Script with multiple auth tokens. This is particularly useful if you are working with the JSON API where you can only have one party per token or with an IAM that only provides single-party tokens. The tokens are specified in the participant configuration passed via --participant-config in a new access_token field. The existing --access-token-file flag is still supported if you want to use the same token for all connections. See https://docs.daml.com/daml-script/index.html#running-daml-script-against-authenticated-ledgers for more details.

Impact and Migration

This functionality is purely additive so no action needs to be taken.

More Privacy information in Daml Studio

Background

Daml Studio’s Scenario view allows developers to explore the transactions resulting from their Daml models in real time. One of the main uses of doing so is to verify that privacy is preserved as expected. Until now, the available views only gave information on who got to see a contract and through which transaction. SDK 1.3 adds information on the mechanism through which a party learned about a contract. This saves the developer the work of inferring this from the detailed transaction view.

Specific Changes

  • When displaying scenario results in table view in Daml Studio, there’s now a new checkbox “Show Detailed Disclosure” which shows indications _why_ a party knows about the existence of a contract:
    • S means the party is a signatory.
    • O means the party is an observer.
    • W means the party has witnessed the creation of the contract.
    • D means the party has learned about the contract via divulgence.

Impact and Migration

This functionality is purely additive so no action needs to be taken.

Early Access Trigger Service

Background

Daml Triggers give developers the ability to write automation of Daml applications in the style of database triggers using the Daml language itself, aiding code reuse and allowing contract definitions and basic automation to be packaged and shipped together. These triggers need to be managed at runtime, which until now required developers to manage individual JVM processes, raising the bar to actually deploying Daml Triggers in production. The Trigger Service provides a way to manage Daml Triggers via a simple REST API.

The Trigger Service is currently in Alpha, meaning API changes are still likely, and it notably doesn’t support authentication yet.

Specific Changes

  • Added the daml trigger-service command to the SDK to start the Trigger Service. More information in the documentation.

Impact and Migration

This functionality is purely additive so no action needs to be taken. If you are already evaluating Triggers for your application, we highly recommend trying out the Trigger Service as it should ease their use considerably. We welcome your feedback.

Minor Improvements

  • The Java Binding’s Bot.wire and Bot.wireSimple now return a Disposable, which can be used to shut down the flows. You are encouraged to call .dispose() before terminating the client.
  • Added a CLI option for specifying the initial skew parameter for the time model. You can control the allowed difference between the Ledger Effective Time and the Record time using the --max-ledger-time-skew flag.
  • When run with persistence, the Sandbox used to crash if the database wasn’t running during startup. It now instead waits for the database to start up.
  • Additional CLI options to configure the write pipeline in Sandbox, allowing operators to determine at what point back pressure is applied. See daml sandbox --help for details.
  • Initialize the loading indicators in @daml/react of useQuery, useFetchByKey and their streaming variants with true. This removes a glitch where the loading indicator was false for a very brief moment when components using these hooks were mounted although no data had been loaded yet. Code using these hooks does not need to be adapted in response to this change.
  • The create-daml-app example can now be run against a HTTP JSON API port specified in the environment variable REACT_APP_HTTP_JSON_PORT
  • Improved error messages on unsuccessful key lookups.

Bug and Security fixes

  • damlc test --project-root now works with relative paths as well.
  • The Package Management Service's ListKnownParties response's PartyDetails now properly reflects where a party is non-local on distributed, multi-participant ledgers that expose parties to remote participants.
  • The application identifier in a command submission request is now checked against the authorization token. See https://github.com/digital-asset/daml/issues/4409.
  • In scenarios, fetches and exercises of contract keys associated with contracts not visible to the submitter are now handled properly instead of showing a low-level error.
  • Some libraries in the Daml Studio VS Code Extension were updated to fix security issues. Daml Studio now requires VSCode 1.39 or newer.
  • Fix an issue in Daml Script where the port was ignored for non-empty paths in the url when running Daml Script over the JSON API.
  • Fix an issue in the Ledger API indexer that could have caused a crash in the presence of divulged contracts. Exclusively affects Daml ledger implementations where distributed participants each only see a portion of the ledger. The sandbox is not affected. See https://github.com/digital-asset/daml/pull/6607.

Ledger Integration Kit

  • The Ledger API Test Tool --exclude and --include flags now match the full test name as a prefix, rather than just suite names. Test name is built by combining the suite name with a test identifier, so this change should be fully backwards compatible. Run with --list-all to list all tests (as opposed to just the test suites with --list).
  • LfValueTranslation.Cache now requires separate configuration of lfValueTranslationEventCache and lfValueTranslationContractCache
  • Upgrade auth0 jwks-rsa version to 0.11.0
  • KVUtils does not commit output keys whose value is identical to input anymore
  • The Ledger API Server + Sandbox now accepts a new time model if none is set. Previously, it would erroneously be rejected because the generation number submitted to was incorrectly set to 2 rather than 1. This would not affect most users of Sandbox or other kvutils-based ledgers, as if a configuration is set automatically on startup when creating a new ledger. This affects users who explicitly override the initial ledger configuration submit delay to something longer than a few milliseconds.
  • Add 8 new  timer metrics to track database performance when storing transactions. The overall time is measured by daml.index.db.store_ledger_entry.
    • Timer daml.index.db.store_ledger_entry.prepare_batches: measures the time for preparing batch insert/delete statements
    • Timer daml.index.db.store_ledger_entry.events_batch: measures the time for inserting events
    • Timer daml.index.db.store_ledger_entry.delete_contract_witnesses_batch:  measures the time for deleting contract witnesses
    • Timer daml.index.db.store_ledger_entry.delete_contracts_batch: measures the time for deleting contracts
    • Timer daml.index.db.store_ledger_entry.insert_contracts_batch: measures the time for inserting contracts
    • Timer daml.index.db.store_ledger_entry.insert_contract_witnesses_batch: measures the time for inserting contract witnesses
    • Timer daml.index.db.store_ledger_entry.insert_completion: measures the time for inserting the completion
    • Timer daml.index.db.store_ledger_entry.update_ledger_end: measures the time for updating the ledger end
  • Added 4 new timer metrics to track Daml execution performance The overall time is measured by daml.execution.total
    • Timer daml.execution.lookup_active_contract_per_execution: measures the accumulated time spent for looking up active contracts per execution
    • Histogram daml.execution.lookup_active_contract_count_per_execution: measures the number of active contract lookups per execution
    • Timer daml.execution.lookup_contract_key_per_execution: measures the accumulated time spent for looking up contract keys per execution
    • Histogram daml.execution.lookup_contract_key_count_per_execution: measures the number of contract key lookups per execution

What’s Coming

Most of our current work is going into performance of the Daml integration components and improving production readiness of Daml Ledgers. In parallel, we are putting finishing touches on the feature work we’ve started on:

  • The Trigger Service is expected to reach feature completion and move into Beta stage in one of the next releases
  • Daml REPL is expected to become stable in one of the next releases
  • Daml will get a generic Map type as part of Daml-LF 1.9.

Related Posts