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.
--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.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.
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
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.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.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
.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.submitMulti
. submitMulti [alice, bob] [carol] do ...
sets Alice and Bob in act_as
and Carol in read_as
.submitMultiMustFail
function is provided as a counterpart to submitMustFail
.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:
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.UnimplementedException
) for immediate migration.
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
--target=1.11
.--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.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
.
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
.TextMap
may therefore be attractive as this is represented as a JSON object.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:
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
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
daml navigator console
command has been removed.
Impact and Migration
We recommend Daml REPL for shell-based interaction with Daml ledgers.
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.
const allUser: QueryResult<User.User, User.User.Key, typeof User.User.templateId> = useStreamQueries(User.User);
const allUser: User.User.QueryResult = useStreamQueries(User.User);
exercise
and createAndExercise
failed to typecheck with a mismatch in the key type.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.