DAML Trigger Library¶
The DAML Trigger library defines the API used to declare a DAML trigger. See DAML Triggers - Off-Ledger Automation in DAML:: for more information on DAML triggers.
Module Daml.Trigger¶
Data Types¶
data Trigger s
This is the type of your trigger.
s
is the user-defined state type which you can often leave at()
.
Field Type Description initialize ACS -> s Initialize the user-defined state based on the ACS. updateState ACS -> Message -> s -> s Update the user-defined state based on the ACS and a transaction or completion message. rule Party -> ACS -> Time -> Map CommandId [Command] -> s -> TriggerA () The rule defines the main logic of your trigger. It can send commands to the ledger using emitCommands
to change the ACS. The rule depends on the following arguments: * The party your trigger is running as. * The current state of the ACS. * The current time (UTC in wallclock mode, Unix epoch in static mode) * The commands in flight. * The user-defined state.registeredTemplates RegisteredTemplates The templates the trigger will receive events for. heartbeat Optional RelTime Send a heartbeat message at the given interval. instance HasField “heartbeat” (Trigger s) (Optional RelTime)
instance HasField “initialize” (Trigger s) (ACS -> s)
instance HasField “registeredTemplates” (Trigger s) RegisteredTemplates
instance HasField “rule” (Trigger s) (Party -> ACS -> Time -> Map CommandId [Command] -> s -> TriggerA ())
instance HasField “updateState” (Trigger s) (ACS -> Message -> s -> s)
Functions¶
- getTemplates
- : Template a => ACS -> [(ContractId a, a)]
- getContracts
: Template a => ACS -> [(ContractId a, a)]
Extract the contracts of a given template from the ACS.
- emitCommands
: [Command] -> [AnyContractId] -> TriggerA CommandId
Send a transaction consisting of the given commands to the ledger. The second argument can be used to mark a list of contract ids as pending. These contracts will automatically be filtered from getContracts until we either get the corresponding transaction event for this command or a failing completion.
- dedupCreate
: (Eq t, Template t) => t -> TriggerA ()
Create the template if it’s not already in the list of commands in flight (it will still be created if it is in the ACS).
Note that this will send the create as a single-command transaction. If you need to send multiple commands in one transaction, use
emitCommands
withcreateCmd
and handle filtering yourself.
- dedupCreateAndExercise
: (Eq t, Eq c, Template t, Choice t c r) => t -> c -> TriggerA ()
Create the template and exercise a choice on it it’s not already in the list of commands in flight (it will still be created if it is in the ACS).
Note that this will send the create and exercise as a single-command transaction. If you need to send multiple commands in one transaction, use
emitCommands
withcreateAndExerciseCmd
and handle filtering yourself.
- dedupExercise
: (Eq c, Choice t c r) => ContractId t -> c -> TriggerA ()
Exercise the choice on the given contract if it is not already in flight.
Note that this will send the exercise as a single-command transaction. If you need to send multiple commands in one transaction, use
emitCommands
withexerciseCmd
and handle filtering yourself.If you are calling a consuming choice, you might be better off by using
emitCommands
and adding the contract id to the pending set.
- dedupExerciseByKey
: (Eq c, Eq k, Choice t c r, TemplateKey t k) => k -> c -> TriggerA ()
Exercise the choice on the given contract if it is not already in flight.
Note that this will send the exercise as a single-command transaction. If you need to send multiple commands in one transaction, use
emitCommands
withexerciseCmd
and handle filtering yourself.
- runTrigger
: Trigger s -> Trigger (TriggerState s)
Transform the high-level trigger type into the one from
Daml.Trigger.LowLevel
.
Module Daml.Trigger.Assert¶
Functions¶
- toACS
: Template t => ContractId t -> ACSBuilder
Include the given contract in the ‘ACS’.
- testRule
: Trigger s -> Party -> ACSBuilder -> Map CommandId [Command] -> s -> Scenario [Commands]
Execute a trigger’s rule once in a scenario.
- flattenCommands
-
Drop ‘CommandId’s and extract all ‘Command’s.
- assertCreateCmd
: (Template t, CanAbort m) => [Command] -> (t -> Either Text ()) -> m ()
Check that at least one command is a create command whose payload fulfills the given assertions.
- assertExerciseCmd
: (Template t, Choice t c r, CanAbort m) => [Command] -> ((ContractId t, c) -> Either Text ()) -> m ()
Check that at least one command is an exercise command whose contract id and choice argument fulfill the given assertions.
- assertExerciseByKeyCmd
: (TemplateKey t k, Choice t c r, CanAbort m) => [Command] -> ((k, c) -> Either Text ()) -> m ()
Check that at least one command is an exercise by key command whose key and choice argument fulfill the given assertions.
Module Daml.Trigger.Internal¶
Data Types¶
data ACS
Active contract set, you can use
getContracts
to access the templates of a given type.
Field Type Description activeContracts [(AnyContractId, AnyTemplate)] pendingContracts Map CommandId [AnyContractId] instance HasField “acs” (TriggerState s) ACS
instance HasField “activeContracts” ACS [(AnyContractId, AnyTemplate)]
instance HasField “initialize” (Trigger s) (ACS -> s)
instance HasField “pendingContracts” ACS (Map CommandId [AnyContractId])
instance HasField “rule” (Trigger s) (Party -> ACS -> Time -> Map CommandId [Command] -> s -> TriggerA ())
instance HasField “updateState” (Trigger s) (ACS -> Message -> s -> s)
data TriggerA a
TriggerA is the type used in the
rule
of a DAML trigger. Its main feature is that you can callemitCommands
to send commands to the ledger.TriggerA (State TriggerAState a)
instance Functor TriggerA
instance Action TriggerA
instance Applicative TriggerA
instance HasField “rule” (Trigger s) (Party -> ACS -> Time -> Map CommandId [Command] -> s -> TriggerA ())
data TriggerAState
Field Type Description commandsInFlight Map CommandId [Command] emittedCommands [Commands] Emitted commands in reverse because I can’t be bothered to implement a dlist. pendingContracts Map CommandId [AnyContractId] Map from command ids to the contract ids marked pending by that command. nextCommandId Int Command id used for the next submit instance HasField “commandsInFlight” TriggerAState (Map CommandId [Command])
instance HasField “emittedCommands” TriggerAState [Commands]
instance HasField “nextCommandId” TriggerAState Int
instance HasField “pendingContracts” TriggerAState (Map CommandId [AnyContractId])
data TriggerState s
instance HasField “acs” (TriggerState s) ACS
instance HasField “commandsInFlight” (TriggerState s) (Map CommandId [Command])
instance HasField “nextCommandId” (TriggerState s) Int
instance HasField “party” (TriggerState s) Party
instance HasField “userState” (TriggerState s) s
Functions¶
- insertTpl
- : AnyContractId -> AnyTemplate -> ACS -> ACS
- deleteTpl
- : AnyContractId -> ACS -> ACS
- lookupTpl
- : Template a => AnyContractId -> ACS -> Optional a
- applyEvent
- : Event -> ACS -> ACS
- applyTransaction
- : Transaction -> ACS -> ACS
- runRule
- : (Party -> ACS -> Time -> Map CommandId [Command] -> s -> TriggerA ()) -> Time -> TriggerState s -> (TriggerState s, [Commands])
- runTriggerA
- : TriggerA a -> TriggerAState -> (a, TriggerAState)
Module Daml.Trigger.LowLevel¶
Data Types¶
data ActiveContracts
Field Type Description activeContracts [Created] instance HasField “activeContracts” ActiveContracts [Created]
instance HasField “initialState” (Trigger s) (Party -> Time -> ActiveContracts -> (s, [Commands]))
data AnyContractId
This type represents the contract id of an unknown template. You can use
fromAnyContractId
to check which template it corresponds to.instance Eq AnyContractId
instance Show AnyContractId
instance HasField “activeContracts” ACS [(AnyContractId, AnyTemplate)]
instance HasField “contractId” AnyContractId (ContractId ())
instance HasField “contractId” Archived AnyContractId
instance HasField “contractId” Command AnyContractId
instance HasField “contractId” Created AnyContractId
instance HasField “pendingContracts” ACS (Map CommandId [AnyContractId])
instance HasField “pendingContracts” TriggerAState (Map CommandId [AnyContractId])
instance HasField “templateId” AnyContractId TemplateTypeRep
data Archived
The data in an
Archived
event.
Field Type Description eventId EventId contractId AnyContractId instance Eq Archived
instance Show Archived
instance HasField “contractId” Archived AnyContractId
data Command
A ledger API command. To construct a command use
createCmd
andexerciseCmd
.
Field Type Description templateArg AnyTemplate
Field Type Description contractId AnyContractId choiceArg AnyChoice
Field Type Description templateArg AnyTemplate choiceArg AnyChoice
Field Type Description tplTypeRep TemplateTypeRep contractKey AnyContractKey choiceArg AnyChoice instance HasField “choiceArg” Command AnyChoice
instance HasField “commands” Commands [Command]
instance HasField “commandsInFlight” TriggerAState (Map CommandId [Command])
instance HasField “commandsInFlight” (TriggerState s) (Map CommandId [Command])
instance HasField “contractId” Command AnyContractId
instance HasField “contractKey” Command AnyContractKey
instance HasField “rule” (Trigger s) (Party -> ACS -> Time -> Map CommandId [Command] -> s -> TriggerA ())
instance HasField “templateArg” Command AnyTemplate
instance HasField “tplTypeRep” Command TemplateTypeRep
data CommandId
CommandId Text
instance Eq CommandId
instance Show CommandId
instance HasField “commandId” Commands CommandId
instance HasField “commandId” Completion CommandId
instance HasField “commandId” Transaction (Optional CommandId)
instance HasField “commandsInFlight” TriggerAState (Map CommandId [Command])
instance HasField “commandsInFlight” (TriggerState s) (Map CommandId [Command])
instance HasField “pendingContracts” ACS (Map CommandId [AnyContractId])
instance HasField “pendingContracts” TriggerAState (Map CommandId [AnyContractId])
instance HasField “rule” (Trigger s) (Party -> ACS -> Time -> Map CommandId [Command] -> s -> TriggerA ())
instance MapKey CommandId
data Commands
A set of commands that are submitted as a single transaction.
instance HasField “commandId” Commands CommandId
instance HasField “commands” Commands [Command]
instance HasField “emittedCommands” TriggerAState [Commands]
instance HasField “initialState” (Trigger s) (Party -> Time -> ActiveContracts -> (s, [Commands]))
instance HasField “update” (Trigger s) (Time -> Message -> s -> (s, [Commands]))
data Completion
A completion message. Note that you will only get completions for commands emitted from the trigger. Contrary to the ledger API completion stream, this also includes synchronous failures.
Field Type Description commandId CommandId status CompletionStatus instance Show Completion
instance HasField “commandId” Completion CommandId
instance HasField “status” Completion CompletionStatus
data CompletionStatus
Field Type Description status Int message Text
Field Type Description transactionId TransactionId instance Show CompletionStatus
instance HasField “message” CompletionStatus Text
instance HasField “status” Completion CompletionStatus
instance HasField “status” CompletionStatus Int
instance HasField “transactionId” CompletionStatus TransactionId
data Created
The data in a
Created
event.
Field Type Description eventId EventId contractId AnyContractId argument AnyTemplate instance HasField “activeContracts” ActiveContracts [Created]
instance HasField “argument” Created AnyTemplate
instance HasField “contractId” Created AnyContractId
data Event
An event in a transaction. This definition should be kept consistent with the object
EventVariant
defined in triggers/runner/src/main/scala/com/digitalasset/daml/lf/engine/trigger/Converter.scalainstance HasField “events” Transaction [Event]
data EventId
data Message
Either a transaction or a completion. This definition should be kept consistent with the object
MessageVariant
defined in triggers/runner/src/main/scala/com/digitalasset/daml/lf/engine/trigger/Converter.scalainstance HasField “update” (Trigger s) (Time -> Message -> s -> (s, [Commands]))
instance HasField “updateState” (Trigger s) (ACS -> Message -> s -> s)
data RegisteredTemplates
Listen to events for all templates in the given DAR.RegisteredTemplates [RegisteredTemplate]
instance HasField “registeredTemplates” (Trigger s) RegisteredTemplates
instance HasField “registeredTemplates” (Trigger s) RegisteredTemplates
data Transaction
Field Type Description transactionId TransactionId commandId Optional CommandId events [Event] instance HasField “commandId” Transaction (Optional CommandId)
instance HasField “events” Transaction [Event]
instance HasField “transactionId” Transaction TransactionId
data TransactionId
TransactionId Text
instance Eq TransactionId
instance Show TransactionId
instance HasField “transactionId” CompletionStatus TransactionId
instance HasField “transactionId” Transaction TransactionId
data Trigger s
Trigger is (approximately) a left-fold over
Message
with an accumulator of types
.
Field Type Description initialState Party -> Time -> ActiveContracts -> (s, [Commands]) update Time -> Message -> s -> (s, [Commands]) registeredTemplates RegisteredTemplates heartbeat Optional RelTime instance HasField “heartbeat” (Trigger s) (Optional RelTime)
instance HasField “initialState” (Trigger s) (Party -> Time -> ActiveContracts -> (s, [Commands]))
instance HasField “registeredTemplates” (Trigger s) RegisteredTemplates
instance HasField “update” (Trigger s) (Time -> Message -> s -> (s, [Commands]))
Functions¶
- toAnyContractId
: Template t => ContractId t -> AnyContractId
Wrap a
ContractId t
inAnyContractId
.
- fromAnyContractId
: Template t => AnyContractId -> Optional (ContractId t)
Check if a
AnyContractId
corresponds to the given template or returnNone
otherwise.
- fromCreated
: Template t => Created -> Optional (EventId, ContractId t, t)
Check if a
Created
event corresponds to the given template.
- fromArchived
: Template t => Archived -> Optional (EventId, ContractId t)
Check if an
Archived
event corresponds to the given template.
- registeredTemplate
- : Template t => RegisteredTemplate
- exerciseCmd
: Choice t c r => ContractId t -> c -> Command
Exercise the given choice.
- createAndExerciseCmd
: (Template t, Choice t c r) => t -> c -> Command
Create a contract of the given template and immediately exercise the given choice on it.
- exerciseByKeyCmd
- : (Choice t c r, TemplateKey t k) => k -> c -> Command
- fromCreate
: Template t => Command -> Optional t
Check if the command corresponds to a create command for the given template.
- fromCreateAndExercise
: (Template t, Choice t c r) => Command -> Optional (t, c)
Check if the command corresponds to a create and exercise command for the given template.
- fromExercise
: Choice t c r => Command -> Optional (ContractId t, c)
Check if the command corresponds to an exercise command for the given template.
- fromExerciseByKey
: (Choice t c r, TemplateKey t k) => Command -> Optional (k, c)
Check if the command corresponds to an exercise by key command for the given template.