DAML Triggers - Off-Ledger Automation in DAML¶
WARNING: DAML Triggers are an experimental feature that is actively being designed and is subject to breaking changes. We welcome feedback about DAML triggers on our issue tracker or on Slack.
In addition to the actual DAML logic which is uploaded to the Ledger and the UI, DAML applications often need to automate certain interactions with the ledger. This is commonly done in the form of a ledger client that listens to the transaction stream of the ledger and when certain conditions are met, e.g., when a template of a given type has been created, the client sends commands to the ledger, e.g., it creates a template of another type.
It is possible to write these clients in a language of your choice, e.g., JavaScript, using the HTTP JSON API. However, that introduces an additional layer of friction: You now need to translate between the template and choice types in DAML and a representation of those DAML types in the language you are using for your client. DAML triggers address this problem by allowing you to write certain kinds of automation directly in DAML reusing all the DAML types and logic that you have already defined. Note that while the logic for DAML triggers is written in DAML, they act like any other ledger client: They are executed separately from the ledger, they do not need to be uploaded to the ledger and they do not allow you to do anything that any other ledger client could not do.
Usage¶
Our example for this tutorial consists of 3 templates.
First, we have a template called Original
:
template Original
with
owner : Party
name : Text
textdata : Text
where
signatory owner
key (owner, name) : (Party, Text)
maintainer key._1
This template has an owner
, a name
that identifies it and some
textdata
that we just represent as Text
to keep things simple. We
have also added a contract key to ensure that each owner can only have
one Original
with a given name
.
Second, we have a template called Subscriber
:
template Subscriber
with
subscriber : Party
subscribedTo : Party
where
signatory subscriber
observer subscribedTo
key (subscriber, subscribedTo) : (Party, Party)
maintainer key._1
This template allows the subscriber
to subscribe to Original
s where subscribedTo
is the owner
.
For each of these Original
s, our DAML trigger should then automatically create an instance of
third template called Copy
:
template Copy
with
original : Original
subscriber : Party
where
signatory (signatory original)
observer subscriber
Our trigger should also ensure that the Copy
contracts stay in sync with changes on the ledger. That means
that we need to archive Copy
contracts if there is more than one for the same Original
, we need to archive
Copy
contracts if the corresponding Original
has been archived and we need to archive
all Copy
s for a given subscriber if the corresponding Subscriber
contract has been archived.
Implementing a DAML Trigger¶
Having defined what our DAML trigger is supposed to do, we can now
move on to its implementation. A DAML trigger is a regular DAML
project that you can build using daml build
. To get access to the
API used to build a trigger, you need to add the daml-triggers
library to the dependencies
field in daml.yaml
.
dependencies:
- daml-prim
- daml-stdlib
- daml-trigger
In addition to that you also need to import the Daml.Trigger
module.
DAML triggers automatically track the active contract set and the
commands in flight for you. In addition to that, they allow you to
have user-defined state that is updated based on new transactions and
command completions. For our copy trigger, the ACS is sufficient, so
we will simply use ()
as the type of the user defined state.
To create a trigger you need to define a value of type Trigger s
where s
is the type of your user-defined state:
data Trigger s = Trigger
{ initialize : ACS -> s
, updateState : ACS -> Message -> s -> s
, rule : Party -> ACS -> Time -> Map CommandId [Command] -> s -> TriggerA ()
, registeredTemplates : RegisteredTemplates
}
The initialize
function is called on startup and allows you to
initialize your user-defined state based on the active contract set.
The updateState
function is called on new transactions and command
completions and can be used to update your user-defined state based on
the ACS and the transaction or completion. Since our DAML trigger does
not have any interesting user-defined state, we will not go into
details here.
The rule
function is the core of a DAML trigger. It
defines which commands need to be sent to the ledger based on the
party the trigger is executed at, the current state of the ACS, the
current time, the commands in flight and the user defined state.
The type TriggerA
allows you to emit commands that are then sent
to the ledger. Like Scenario
or Update
, you can use do
notation with TriggerA
.
Finally, we can specify the templates that our trigger will operate
on. In our case, we will simply specify AllInDar
which means that
the trigger will receive events for all template types defined in the
DAR. It is also possible to specify an explicit list of templates,
e.g., RegisteredTemplates [registeredTemplate @Original, registeredTemplate @Subscriber, registeredTemplate @Copy]
.
This is mainly useful for performance reasons if your DAR contains many templates that are not relevant for your trigger.
For our DAML trigger, the definition looks as follows:
copyTrigger : Trigger ()
copyTrigger = Trigger
{ initialize = \_acs -> ()
, updateState = \_acs _message () -> ()
, rule = copyRule
, registeredTemplates = AllInDar
}
Now we can move on to the most complex part of our DAML trigger, the implementation of copyRule
.
First let’s take a look at the signature:
copyRule : Party -> ACS -> Time -> Map CommandId [Command] -> () -> TriggerA ()
copyRule party acs _time commandsInFlight () = do
We will need the party and the ACS to get the Original
contracts
where we are the owner, the Subscriber
contracts where we are in
the subscribedTo
field and the Copy
contracts where we are the
owner
of the corresponding Original
.
The commands in flight will be useful to avoid sending the same
command multiple times if copyRule
is run multiple times before we
get the corresponding transaction. Note that DAML triggers are
expected to be designed such that they can cope with this, e.g., after
a restart or a crash where the commands in flight do not contain
commands in flight from before the restart, so this is an optimization
rather than something required for them to function correctly.
First, we get all Subscriber
, Original
and Copy
contracts
from the ACS. For that, the DAML trigger API provides a
getContracts
function that given the ACS will return a list of all
contracts of a given template.
let subscribers : [(ContractId Subscriber, Subscriber)] = getContracts @Subscriber acs
let originals : [(ContractId Original, Original)] = getContracts @Original acs
let copies : [(ContractId Copy, Copy)] = getContracts @Copy acs
Now, we can filter those contracts to the ones where we are the
owner
as described before.
let ownedSubscribers = filter (\(_, s) -> s.subscribedTo == party) subscribers
let ownedOriginals = filter (\(_, o) -> o.owner == party) originals
let ownedCopies = filter (\(_, c) -> c.original.owner == party) copies
We also need a list of all parties that have subscribed to us.
let subscribingParties = map (\(_, s) -> s.subscriber) ownedSubscribers
As we have mentioned before, we only want to keep one Copy
per
Original
and Subscriber
and archive all others. Therefore, we
group identical Copy
contracts and keep the first of each group
while archiving the others.
let groupedCopies : [[(ContractId Copy, Copy)]]
groupedCopies = groupOn snd $ sortOn snd $ ownedCopies
let copiesToKeep = map head groupedCopies
let archiveDuplicateCopies = concatMap tail groupedCopies
In addition to duplicate copies, we also need to archive copies where
the corresponding Original
or Subscriber
no longer exists.
let archiveMissingOriginal = filter (\(_, c) -> c.original `notElem` map snd ownedOriginals) copiesToKeep
let archiveMissingSubscriber = filter (\(_, c) -> c.subscriber `notElem` subscribingParties) copiesToKeep
let archiveCopies = dedup $ map fst $ archiveDuplicateCopies <> archiveMissingOriginal <> archiveMissingSubscriber
To send the corresponding archve commands to the ledger, we iterate
over archiveCopies
using forA
and call the emitCommands
function. Each call to emitCommands
takes a list of commands which
will be submitted as a single transaction. The actual commands can be
created using exerciseCmd
and createCmd
.
forA archiveCopies $ \cid -> dedupExercise cid Archive
Finally, we also need to create copies that do not already exists. We
want to avoid creating copies for which there is already a command in
flight. The DAML Trigger API provides a dedupCreate
helper for this
which only sends the commands if it is not already in flight.
let neededCopies = [Copy m o | (_, m) <- ownedOriginals, o <- subscribingParties]
let createCopies = filter (\c -> c `notElem` map snd copiesToKeep) neededCopies
mapA dedupCreate createCopies
Running a DAML Trigger¶
To try this example out, you can replicate it using daml new
copy-trigger copy-trigger
. You first have to build the trigger like
you would build a regular DAML project using daml build
.
Then start the sandbox and navigator using daml start
.
Now we are ready to run the trigger using daml trigger
:
daml trigger --dar .daml/dist/copy-trigger-0.0.1.dar --trigger-name CopyTrigger:copyTrigger --ledger-host localhost --ledger-port 6865 --ledger-party Alice
The first argument specifies the .dar
file that we have just
built. The second argument specifies the identifier of the trigger
using the syntax ModuleName:identifier
. Finally, we need to
specify the ledger host, port and the party that our trigger is executed
as.
Now open Navigator at http://localhost:7500/.
First, login as Alice
and create an Original
contract with
party
set to Alice
. Now, logout and login as Bob
and
create a Subscriber
contract with subscriber
set to Bob
and subscribedTo
set to Alice
. After a short delay you should
now see a Copy
contract corresponding to the Original
that you
have created as Alice
. Once you archive the Subscriber
contract, you can see that the Copy
contract will also be
archived.
When using DAML triggers against a Ledger with authentication, you can
pass --access-token-file token.jwt
to daml trigger
which will
read the token from the file token.jwt
.
When not to use DAML triggers¶
DAML triggers deliberately only allow you to express automation that listens for ledger events and reacts to them by sending commands to the ledger. If your automation needs to interact with data outside of the ledger then DAML triggers are not the right tool. For this case, you can use the HTTP JSON API.