This page gives reference information on templates:
For the structure of a template, see Overview: template structure.
- This is the name of the template. It’s preceded by
templatekeyword. Must begin with a capital letter.
- This is the highest level of nesting.
- The name is used when creating a contract instance of this template (usually, from within a choice).
with exampleParty : Party exampleParty2 : Party exampleParty3 : Party exampleParam : Text -- more parameters here
withkeyword. The parameters are in the form of a record type.
- Passed in when creating a contract instance from this template. These are then in scope inside the template body.
- A template parameter can’t have the same name as any choice arguments inside the template.
- For all parties involved in the contract (whether they’re a
controller) you must pass them in as parameters to the contract, whether individually or as a list (
where signatory exampleParty
where. Followed by at least one
Signatories are the parties (see the
Partytype) who must consent to the creation of an instance of this contract. They are the parties who would be put into an obligable position when this contract is created.
DAML won’t let you put someone into an obligable position without their consent. So if the contract will cause obligations for a party, they must be a signatory. If they haven’t authorized it, you won’t be able to create the contract. In this situation, you may see errors like:
NameOfTemplate requires authorizers Party1,Party2,Party, but only Party1 were given.
When a signatory consents to the contract creation, this means they also authorize the consequences of choices that can be exercised on this contract.
The contract instance is visible to all signatories (as well as the other stakeholders of the contract). That is, the compiler automatically adds signatories as observers.
You must have least one signatory per template. You can have many, either as a comma-separated list or reusing the keyword. You could pass in a list (of type
where. Followed by at least one
- Observers are additional stakeholders, so the contract instance is visible to these parties (see the
- Optional. You can have many, either as a comma-separated list or reusing the keyword. You could pass in a list (of type
- Use when a party needs visibility on a contract, or be informed or contract events, but is not a signatory or controller.
- If you start your choice with
controller(see Choices below), you must make sure to add any potential controller as an observer. Otherwise, they will not be able to exercise the choice, because they won’t be able to see the contract.
-- option 1 for specifying choices: choice name first choice NameOfChoice1 : () -- replace () with the actual return type with exampleParameter : Text -- parameters here controller exampleParty do return () -- replace this line with the choice body -- option 2 for specifying choices: controller first controller exampleParty can NameOfChoice2 : () -- replace () with the actual return type with exampleParameter : Text -- parameters here do return () -- replace this line with the choice body nonconsuming NameOfChoice3 : () -- replace () with the actual return type with exampleParameter : Text -- parameters here do return () -- replace this line with the choice body
A right that the contract gives the controlling party. Can be exercised.
This is essentially where all the logic of the template goes.
By default, choices are consuming: that is, exercising the choice archives the contract, so no further choices can be exercised on it. You can make a choice non-consuming using the
There are two ways of specifying a choice: start with the
choicekeyword or start with the
choicelets you pass in a
Partyto use as a controller. But you must make sure to add that party as an
See Reference: choices for full reference information.
agreement -- text representing the contract ""
agreementkeyword, followed by text.
Represents what the contract means in text. They’re usually the boundary between on-ledger and off-ledger rights and obligations.
Usually, they look like
agreement tx, where
txis of type
You can use the built-in operator
showto convert party names to a string, and concatenate with
ensure True -- a boolean condition goes here
ensurekeyword, followed by a boolean condition.
- Used on contract creation.
ensurelimits the values on parameters that can be passed to the contract: the contract can only be created if the boolean condition is true.
Contract keys and maintainers¶
key (exampleParty, exampleParam) : (Party, Text) maintainer (exampleFunction key)
This feature lets you specify a “key” that you can use to uniquely identify an instance of this contract template.
If you specify a
key, you must also specify a
maintainer. This is a
Partythat will ensure the uniqueness of all the keys it is aware of.
Because of this, the
keymust include the
Partyor parties (for example, as part of a tuple or record), and the
maintainermust be a signatory or observer of the contract instance.
For a full explanation, see Contract keys.