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 ACS
Active contract set, you can use
getContracts
to access the templates of a given type.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 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. Given the party your trigger is running as, the ACS, the commands in flight and the user-defined state, you can send commands to the ledger using emitCommands
to change the ACS.registeredTemplates RegisteredTemplates The templates the trigger will receive events for. 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)
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.instance Action TriggerA
instance Applicative TriggerA
instance HasField “rule” (Trigger s) (Party -> ACS -> Time -> Map CommandId [Command] -> s -> TriggerA ())
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.
- 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.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
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 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
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 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.
instance HasField “events” Transaction [Event]
data EventId
data Message
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
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 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.
- 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.
- 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.