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
template
keyword- parameters
with
followed by the names of parameters and their types- template body
where
keywordCan include:
- template-local definitions (deprecated)
let
keywordLets you make definitions that have access to the contract arguments and are available in the rest of the template definition.
- signatories
signatory
keywordRequired. 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.
- observers
observer
keywordOptional. Parties that aren’t signatories but who you still want to be able to see this contract.
- an agreement
agreement
keywordOptional. Text that describes the agreement that this contract represents.
- a precondition
ensure
keywordOnly create the contract if the conditions after
ensure
evaluate to true.- a contract key
key
keywordOptional. Lets you specify a combination of a party and other data that uniquely identifies a contract of this template. See Reference: Contract Keys.
- maintainers
maintainer
keywordRequired if you have specified a
key
. Keys are only unique to amaintainer
. See Reference: Contract Keys.- choices
choice NameOfChoice : ReturnType controller nameOfParty do
Defines choices that can be exercised. See Choice structure for what can go in a choice.
Choice Structure¶
Here is the structure of a choice inside a template:
choice NameOfChoice
: () -- replace () with the actual return type
with
party : Party -- parameters here
controller party
do
return () -- replace this line with the choice body
- consumption annotation
- Optionally one of
preconsuming
,postconsuming
,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
with
keywordIf you include a
Party
as a choice argument, you can make thatParty
thecontroller
of the choice. This means that the controller can be specified when the choice is exercised, rather than when the contract is created. For the exercise to work, the party needs to be able to see the contract, i.e. it must be anobserver
or asignatory
.- a controller (or controllers)
controller
keywordWho can exercise the choice.
- choice observers
observer
keywordOptional. 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
choice
keyword.The optional
observer
keyword must precede the mandatorycontroller
keyword.- a choice body
After
do
keywordWhat 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
Create a new contract of this template.
create NameOfContract with contractArgument1 = value1; contractArgument2 = value2; ...
- exercise
Exercise a choice on a particular contract.
exercise idOfContract NameOfChoiceOnContract with choiceArgument1 = value1; choiceArgument2 = value 2; ...
- fetch
Fetch a contract using its ID. Often used with assert to check conditions on the contract’s content.
fetchedContract <- fetch IdOfContract
- fetchByKey
Like
fetch
, but uses a contract key rather than an ID.fetchedContract <- fetchByKey @ContractType contractKey
- lookupByKey
Confirm that a contract with the given contract key exists.
fetchedContractId <- lookupByKey @ContractType contractKey
- abort
Stop execution of the choice, fail the update.
if False then abort
- assert
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)
- getTime
Gets the ledger time. Usually used to restrict when a choice can be exercised.
currentTime <- getTime
- return
Explicitly return a value. By default, a choice returns the result of its last update expression. This means you only need to use
return
if 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