Skip to content
Digital Asset Logo

Release of Daml Connect 1.9.0

|

Daml Connect 1.9.0 has been released on January 21st. You can install it using:

daml install 1.9.0

Want to know what's happening in our developer community? Check out the latest update for this month.

Note: This release fixes 2 bugs in the 1.9.0 RCs. One where the default contract id seeding mode in sandbox classic was erroneously set to testing-weak this was corrected to the previous default value of no. The other is the same as the recent 1.8.1 release to fix a bug in shared Daml Driver components ("The Integration Kit") where contract keys were not correctly updated which could cause incorrect contract key lookups. No ledgers were affected by this bug.

Highlights

  • Multi-party submissions which allow new forms of data sharing and use-cases including public reference data and better role-based access controls. 
  • Daml-LF 1.11 is now in Beta, bringing Choice Observers and Generic Maps.
  • Introduction of Ledger API version 1.8.

Impact and Migration

  • Multi-party submissions add new optional fields to the Ledger API and some interface definitions in Java. If you compile your own gRPC service stubs, or maintain your own implementation of some of the provided Java interfaces, you may need to add the new fields or methods. Details under Multi-Party Submissions.
  • Daml-LF 1.11 will not be compatible with the deprecated Sandbox Classic’s default --contract-id-seeding=no mode. If you use Sandbox Classic, you will need to either switch to a different contract seeding mode, or pin Daml-LF to 1.8. Details under Daml-LF 1.11.
  • Daml’s main development branch has been renamed from master to main to be more inclusive. If you had a source code dependency on the repository you need to switch to the new branch.

What’s New

Multi-Party Submissions

Background

Privacy and identity are core concerns of Daml. Users always act and read as parties, and events and contracts are authorized by and shared with those parties on a strict need-to-know basis. This uniquely strong privacy and authorization model is crucial for many of the core use cases for which it was designed. Multi-party submissions now extend this model to allow users to act and read on behalf of more than a single party at a time, adding support for important new use patterns without compromising Daml’s inherent privacy or security.

One pattern is the distribution of reference data such as pricing information coming from a trusted party (sometimes called an oracle). The oracle can now share reference data with a single dedicated broadcasting party PriceObserver and give all users that should be able to use the pricing information read access to that party. This drastically reduces the storage and management overhead of having to maintain lists of observers on the price contracts.

Another pattern that is enabled by multi-party submissions is bulk delegation and role-based access controls. It is easy to write a contract that allows an organisation ACME to delegate the right to ship widgets to an employee Alice, but without Alice being able to see the inventory of widgets, she can not make use of that right. As with the oracle pattern above, the need for Alice to be added as an observer to all inventory contracts as an individual can now be replaced by giving Alice read access to a dedicated `InventoryManager` party that is an observer on the inventory.

A blog post will follow these release notes to explore these and other use cases in more detail, and provides an example of how this can be used for role-based access control.

Specific Changes

  • The Ledger API version is now at 1.8.
  • The gRPC Ledger API has new optional fields act_as and read_as on the Commands object, which each take a list of parties. The parties need to be hosted on the participant the submission is sent to, and if authentication is enabled, the authentication token must include the parties in the corresponding actAs and readAs fields.

    The meaning of these fields is that the parties in act_as are the requesters as defined in the Daml Ledger Model. Top level actions are authorized by all parties in this list. For example, if act_as = [Alice, Bob, Carol], an action creating a contract with signatories Alice and Carol would be well-authorized.

    In addition any contracts visible to any party in act_as or read_as may be accessed during interpretation. For example, if act_as = [Alice], readAs = [PricingObserver], Alice can submit a transaction with a Fetch on a price contract only visible to PricingObserver.

    The party field on Commands is now optional and implicitly added to the act_as list if set, meaning the effective act_as is the union of the act_as field and the party field.
  • Daml Script exposes the new functionality through a function submitMulti. submitMulti [alice, bob] [carol] do ... sets Alice and Bob in act_as and Carol in read_as.
    A submitMultiMustFail function is provided as a counterpart to submitMustFail.
  • The Java Ledger API Bindings and Codegen have been expanded with the new fields.
  • The JSON API infers the act_as and read_as fields from the supplied JWT token.

Impact and Migration

This is an additive change, but the following should be noted:

  • JSON API and Daml Script always use the first party from act_as to set the party field on the Commands object. That means new versions of the API server and Script still work against old Ledger API versions. However, any attempt to use multi-party submissions against Ledger API version <= 1.7 will result in any additional parties being silently ignored by the Ledger API, most likely resulting in authorization or visibility errors.
  • Since the Javascript client libraries treat JWT tokens as opaque and connect to the JSON API, they fully support the new feature without change.
  • Since this feature adds new fields to the Ledger API and some interfaces in the Java rxbindings, setups with custom compiled client stubs, or custom implementations of the Java interfaces LedgerClient, CommandClient, or CommandSubmissionClient may experience compile time errors. Since the new fields are optional, implementations can be stubbed (e.g., by throwing an UnimplementedException) for immediate migration.

Daml-LF 1.11 in Beta

Background

Daml-LF is Daml’s intermediary language, analogous to Java bytecode. Daml Connect 1.9 introduces Daml-LF 1.11 in Beta. That means Daml-LF 1.11 will only change if bugs are discovered. Daml-LF 1.11 introduces two new language features (also in Beta): Choice Observers and Generic Maps. In addition, Daml Script, REPL and Triggers now properly convert from ContractId a value to Text using the show function.

To use the new features, your project has to explicitly target Daml-LF 1.11. You can enable this in your daml.yaml file by adding stanzas:

build-options:

  - --target=1.11

sandbox-options:

  - --early-access-unsafe

Specific Changes

  • The Daml compiler can now target Daml-LF 1.11 by setting --target=1.11.
  • The Sandbox and Sandbox Classic have new command line flags --early-access-unsafe which enables Daml-LF 1.11. This is deemed unsafe, because if Daml-LF is used with PostgreSQL backing, and Daml-LF 1.11 were to change, this may leave the database in an unusable state.
  • Choice observers, documented on the reference page for choices, add an additional keyword observer to the choice … syntax. Parties designated choice observers using that keyword are guaranteed to see the exercise of the choice. This can be useful for defining custom events, for example:

nonconsuming choice MyEvent : ()

  with

    message: Text

    sender: Party

    receivers: [Party]

  observer receivers

  controller sender

  do

    return ()

Here the parties in receivers will all see an exercise node of type MyEvent with a payload containing message.

  • Generic maps add a type GenMap and standard library module DA.Map allowing maps with arbitrary serializable types as keys. This supersedes the TextMap type and standard library module DA.Next.Map, which required conversion functions between the key type and Text.
    Note that the representation on the APIs is different. Generic maps are represented as lists of tuples on the API. For users of the JSON API in particular, the continued use of TextMap may therefore be attractive as this is represented as a JSON object.
  • All inbuilt and derived instances of Show now return the actual contract id in Daml Script, REPL, and Triggers, rather than the opaque ”<contract-id>” that’s returned in Daml contracts.

Impact and Migration

Note: Neither the regular Sandbox you use through daml sandbox or daml start, nor any production ledgers are affected by this change and require no action.

Sandbox Classic’s default contract seeding mode no is not compatible with Daml-LF 1.11. Once Daml-LF 1.11 becomes stable, it will become the default, so if you use Sandbox Classic, you need to either pin the Daml-LF version to <=1.8 or switch contract seeding mode. If you do neither, Sandbox Classic will present you with an error informing you that you need to do one or the other. 

We recommend doing one of the following in preparation for the rollout of Daml-LF 1.11:

  1. If you are relying on the human-readable, stable contract-ids for demo purposes, pin the Daml-LF version by adding this stanza to your daml.yaml:

build-options:

  - --target=1.8

2. If you would like Sandbox Classic to resemble production ledgers more closely, switch contract id seeding mode by adding:

sandbox-options:

  - --contract-id-seeding=strong

Removal of Navigator Console

Background

The “Labs” Early Access feature Navigator Console has been superseded by the stable Daml REPL. It has therefore been removed from Daml Connect 1.9.

Specific Changes

  • The daml navigator console command has been removed.

Impact and Migration

We recommend Daml REPL for shell-based interaction with Daml ledgers.

Minor Improvements

  • Daml Connect development is now conducted from the main branch, rather than the master one. If you had any dependency on the digital-asset/daml repository, you will need to update this parameter. See the forum thread for background and migration steps. 
  • The Daml Assistant’s update-check is disabled by default for new installations. In addition, auto-install is disabled by default on Windows. See here for instructions on how to configure these settings manually: https://docs.daml.com/tools/assistant.html#global-config-file-daml-config-yaml

    This measure prevents issues in locked-down environments where the assistant cannot contact remote servers to check for updates.
  • TypeScript code-generated code has gained convenient aliases for the full types of query results that are sometimes needed to inform the TypeScript compiler. In places where you previously had to write:
    const allUser: QueryResult<User.User, User.User.Key, typeof User.User.templateId> = useStreamQueries(User.User);

    you can now write:
    const allUser: User.User.QueryResult = useStreamQueries(User.User);

Bugfixes

  • Fixed a rarely occurring issue that caused transactions to be sent out of order from the Ledger API. See #7521
  • Fix a bug in the JavaScript client libraries where in some cases calls to exercise and createAndExercise failed to typecheck with a mismatch in the key type.
  • Fix a bug in Daml Script where queryContractKey incorrectly returned None despite there being an active contract with the given key. This affected Daml Script over gRPC, and keys with record types.
  • Fix a bug in Daml REPL where bindings with very long types sometimes resulted in parse errors on following lines. See #8213

Integration Kit

  • kvutils no longer supports fingerprints directly. Instead, if the ledger fingerprints the code, you can use the newer, more generic APIs to transform the state values to include those fingerprints, if necessary.
  • Emit OpenTelemetry spans and events for index DB reads.
  • Emit OpenTelemetry events for transactions streamed to the client from the Ledger API.
  • Enabled asynchronous commits in JdbcIndexer for improved performance when consuming state updates from the ledger.

What’s Next

  • The Trigger Service is getting ever more robust and is likely the next big feature to come to Daml Connect.
  • Improved exception handling in Daml didn’t make the cut for Daml-LF 1.11, but remains a high priority.
  • We have started work on a new features targeted at the Enterprise Edition of Daml Connect:
    • A profiler for Daml, helping developers write highly performant Daml code.
    • A mechanism to verify cryptographic signatures on commands submitted to the Ledger API, improving security in deployment topologies where the Ledger API is provided as a service.
    • Oracle DB support throughout the Daml Connect stack in addition to the current PostgreSQL support.

Related Posts