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 getTemplates to access the templates of a given type.

instance HasField “acs” (TriggerState s) ACS

instance HasField “initialize” (Trigger s) (ACS -> s)

instance HasField “rule” (Trigger s) (Party -> ACS -> 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 ().

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

instance HasField “initialize” (Trigger s) (ACS -> s)

instance HasField “rule” (Trigger s) (Party -> ACS -> 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.

instance Functor TriggerA

instance Action TriggerA

instance Applicative TriggerA

instance HasField “rule” (Trigger s) (Party -> ACS -> Map CommandId [Command] -> s -> TriggerA ())

Functions

getTemplates

: Template a => ACS -> [(ContractId a, a)]

Extract the templates of a given type from the ACS.

emitCommands

: [Command] -> TriggerA CommandId

Send a transaction consisting of the given commands to the ledger.

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.

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.

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

ActiveContracts

Field Type Description
activeContracts [Created]  

instance HasField “activeContracts” ActiveContracts [Created]

instance HasField “initialState” (Trigger s) (Party -> 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 “contractId” AnyContractId (ContractId ())

instance HasField “contractId” Archived AnyContractId

instance HasField “contractId” Command AnyContractId

instance HasField “contractId” Created 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  

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 “rule” (Trigger s) (Party -> ACS -> Map CommandId [Command] -> s -> TriggerA ())

instance HasField “templateArg” Command AnyTemplate

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 “rule” (Trigger s) (Party -> ACS -> 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 -> ActiveContracts -> (s, [Commands]))

instance HasField “update” (Trigger s) (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.

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.

MTransaction Transaction

MCompletion Completion

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

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

data TemplateId

We implicitly assume that the package id corresponds to the package the trigger is part of. This type is temporary until we have a builtin in LF for identifiers.

TemplateId

Field Type Description
moduleName Text  
entityName Text  

instance HasField “entityName” TemplateId Text

instance HasField “moduleName” TemplateId Text

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 -> ActiveContracts -> (s, [Commands])  
update Message -> s -> (s, [Commands])  

instance HasField “initialState” (Trigger s) (Party -> ActiveContracts -> (s, [Commands]))

instance HasField “update” (Trigger s) (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.

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.

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.