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.
- 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=nomode. 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
mainto be more inclusive. If you had a source code dependency on the repository you need to switch to the new branch.
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.
- The Ledger API version is now at 1.8.
- The gRPC Ledger API has new optional fields
Commandsobject, 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
The meaning of these fields is that the parties in
act_asare 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
read_asmay 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
Commandsis now optional and implicitly added to the
act_aslist if set, meaning the effective
act_asis the union of the
act_asfield and the
- Daml Script exposes the new functionality through a function
submitMulti [alice, bob] [carol] do ...sets Alice and Bob in
act_asand Carol in
submitMultiMustFailfunction is provided as a counterpart to
- The Java Ledger API Bindings and Codegen have been expanded with the new fields.
- The JSON API infers the
read_asfields 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_asto set the
partyfield on the
Commandsobject. 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 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
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
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:
- The Daml compiler can now target Daml-LF 1.11 by setting
- The Sandbox and Sandbox Classic have new command line flags
--early-access-unsafewhich 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
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 : ()
Here the parties in
receivers will all see an exercise node of type
MyEvent with a payload containing
- Generic maps add a type
GenMapand standard library module
DA.Mapallowing maps with arbitrary serializable types as keys. This supersedes the
TextMaptype and standard library module
DA.Next.Map, which required conversion functions between the key type and
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
TextMapmay therefore be attractive as this is represented as a JSON object.
- All inbuilt and derived instances of
Shownow 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:
- 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
2. If you would like Sandbox Classic to resemble production ledgers more closely, switch contract id seeding mode by adding:
Removal of Navigator Console
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.
daml navigator consolecommand has been removed.
Impact and Migration
We recommend Daml REPL for shell-based interaction with Daml ledgers.
- Daml Connect development is now conducted from the
mainbranch, rather than the
masterone. 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);
- Fixed a rarely occurring issue that caused transactions to be sent out of order from the Ledger API. See #7521
createAndExercisefailed to typecheck with a mismatch in the key type.
- Fix a bug in Daml Script where
Nonedespite 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
- 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.
- 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.