Overview: template structure¶
This page covers what a template looks like: what parts of a template there are, and where they go.
For the structure of a Daml file outside a template, see Reference: Daml file structure.
Template outline structure¶
Here’s the structure of a Daml template:
template NameOfTemplate with exampleParty : Party exampleParty2 : Party exampleParty3 : Party exampleParameter : Text -- more parameters here where signatory exampleParty observer exampleParty2 agreement -- some text "" ensure -- boolean condition True key (exampleParty, exampleParameter) : (Party, Text) maintainer (exampleFunction key) -- a choice goes here; see next section
- template name
withfollowed by the names of parameters and their types
- template body
- template-local definitions
Lets you make definitions that have access to the contract arguments and are available in the rest of the template definition.
Required. The parties (see the Party type) who must consent to the creation of this contract. You won’t be able to create this contract until all of these parties have authorized it.
Optional. Parties that aren’t signatories but who you still want to be able to see this contract.
- an agreement
Optional. Text that describes the agreement that this contract represents.
- a precondition
Only create the contract if the conditions after
ensureevaluate to true.
- a contract key
Optional. Lets you specify a combination of a party and other data that uniquely identifies a contract of this template. See Reference: Contract keys.
Required if you have specified a
key. Keys are only unique to a
maintainer. See Reference: Contract keys.
choice NameOfChoice : ReturnType controller nameOfParty do
controller nameOfParty can NameOfChoice : ReturnType do
Defines choices that can be exercised. See Choice structure for what can go in a choice. Note that
controller-first syntax is deprecated and will be removed in a future version of Daml.
Here’s the structure of a choice inside a template. There are two ways of specifying a choice:
- start with the
- start with the
-- option 1 for specifying choices: choice name first choice NameOfChoice : () -- replace () with the actual return type with party : Party -- parameters here controller party do return () -- replace this line with the choice body -- option 2 for specifying choices (deprecated syntax): controller first controller exampleParty can NameOfAnotherChoice : () -- replace () with the actual return type with party : Party -- parameters here do return () -- replace the line with the choice body
- a controller (or controllers)
Who can exercise the choice.
- choice observers
Optional. Additional parties that are guaranteed to be informed of an exercise of the choice.
To specify choice observers, you must start you choice with the
observerkeyword must precede the mandatory
- consumption annotation
- Optionally one of
nonconsuming, which changes the behavior of the choice with respect to privacy and if and when the contract is archived. See contract consumption in choices for more details.
- a name
- Must begin with a capital letter. Must be unique - choices in different templates can’t have the same name.
- a return type
- after a
:, the return type of the choice
- choice arguments
If you start your choice with
choiceand include a
Partyas a parameter, you can make that
controllerof the choice. This is a feature called “flexible controllers”, and it means you don’t have to specify the controller when you create the contract - you can specify it when you exercise the choice. To exercise a choice, the party needs to be a signatory or an observer of the contract and must be explicitly declared as such.
- a choice body
What happens when someone exercises the choice. A choice body can contain update statements: see Choice body structure below.
Choice body structure¶
A choice body contains
Update expressions, wrapped in a do block.
The update expressions are:
Create a new contract of this template.
create NameOfContract with contractArgument1 = value1; contractArgument2 = value2; ...
Exercise a choice on a particular contract.
exercise idOfContract NameOfChoiceOnContract with choiceArgument1 = value1; choiceArgument2 = value 2; ...
Fetch a contract using its ID. Often used with assert to check conditions on the contract’s content.
fetchedContract <- fetch IdOfContract
fetch, but uses a contract key rather than an ID.
fetchedContract <- fetchByKey @ContractType contractKey
Confirm that a contract with the given contract key exists.
fetchedContractId <- lookupByKey @ContractType contractKey
Stop execution of the choice, fail the update.
if False then abort
Fail the update unless the condition is true. Usually used to limit the arguments that can be supplied to a contract choice.
assert (amount > 0)
Gets the ledger time. Usually used to restrict when a choice can be exercised.
currentTime <- getTime
Explicitly return a value. By default, a choice returns the result of its last update expression. This means you only need to use
returnif you want to return something else.
return ContractID ExampleTemplate
The choice body can also contain:
- let keyword
- Used to assign values or functions.
- assign a value to the result of an update statement
- For example:
contractFetched <- fetch someContractId