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 keyword

Can include:

template-local definitions

let keyword

Lets you make definitions that have access to the contract arguments and are available in the rest of the template definition.

signatories

signatory keyword

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.

observers

observer keyword

Optional. Parties that aren’t signatories but who you still want to be able to see this contract.

an agreement

agreement keyword

Optional. Text that describes the agreement that this contract represents.

a precondition

ensure keyword

Only create the contract if the conditions after ensure evaluate to true.

a contract key

key keyword

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

Required if you have specified a key. Keys are only unique to a maintainer. 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 keyword

If you include a Party as a choice argument, you can make that Party the controller 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 an observer or a signatory.

a controller (or controllers)

controller keyword

Who can exercise the choice.

choice observers

observer keyword

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

The optional observer keyword must precede the mandatory controller keyword.

a choice body

After do keyword

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

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