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]))