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 ().

Trigger

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 with createCmd 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 with createAndExerciseCmd 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 with exerciseCmd 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 with exerciseCmd 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

Data Types

data ACSBuilder

Used to construct an ‘ACS’ for ‘testRule’.

instance Monoid ACSBuilder

instance Semigroup ACSBuilder

Functions

toACS

: Template t => ContractId t -> ACSBuilder

Include the given contract in the ‘ACS’.

testRule

: Trigger s -> Party -> ACSBuilder -> Map CommandId [Command] -> s -> Script [Commands]

Execute a trigger’s rule once in a scenario.

flattenCommands

: [Commands] -> [Command]

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.

ACS

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 call emitCommands 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

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

TriggerState

Field Type Description
acs ACS  
party Party  
userState s  
commandsInFlight Map CommandId [Command]  
nextCommandId Int  

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

addCommands
: Map CommandId [Command] -> Commands -> Map CommandId [Command]
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

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.

Archived

Field Type Description
eventId EventId  
contractId AnyContractId  

instance Eq Archived

instance Show Archived

instance HasField “contractId” Archived AnyContractId

instance HasField “eventId” Archived EventId

data Command

A ledger API command. To construct a command use createCmd and exerciseCmd.

CreateCommand

Field Type Description
templateArg AnyTemplate  

ExerciseCommand

Field Type Description
contractId AnyContractId  
choiceArg AnyChoice  

CreateAndExerciseCommand

Field Type Description
templateArg AnyTemplate  
choiceArg AnyChoice  

ExerciseByKeyCommand

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.

Commands

Field Type Description
commandId CommandId  
commands [Command]  

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.

Completion

Field Type Description
commandId CommandId  
status CompletionStatus  

instance Show Completion

instance HasField “commandId” Completion CommandId

instance HasField “status” Completion CompletionStatus

data CompletionStatus

Failed

Field Type Description
status Int  
message Text  

Succeeded

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.

Created

Field Type Description
eventId EventId  
contractId AnyContractId  
argument AnyTemplate  

instance HasField “activeContracts” ActiveContracts [Created]

instance HasField “argument” Created AnyTemplate

instance HasField “contractId” Created AnyContractId

instance HasField “eventId” Created EventId

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.scala

CreatedEvent Created

ArchivedEvent Archived

instance HasField “events” Transaction [Event]

data EventId

EventId Text

instance Eq EventId

instance Show EventId

instance HasField “eventId” Archived EventId

instance HasField “eventId” Created 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.scala

MTransaction Transaction

MCompletion Completion

MHeartbeat

instance HasField “update” (Trigger s) (Time -> Message -> s -> (s, [Commands]))

instance HasField “updateState” (Trigger s) (ACS -> Message -> s -> s)

data RegisteredTemplates

AllInDar

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

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 type s.

Trigger

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 in AnyContractId.

fromAnyContractId

: Template t => AnyContractId -> Optional (ContractId t)

Check if a AnyContractId corresponds to the given template or return None 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
createCmd

: Template t => t -> Command

Create a contract of the given template.

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.