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
    controller exampleParty3 can
      -- 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:

signatories

signatory keyword

The parties (see the Party type) who must consent to the creation of an instance of this contract.

observers

observer keyword

Parties that aren’t signatories but can still see this contract.

an agreement

agreement keyword

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.

choices

controller nameOfParty can nameOfChoice

Defines choices that can be exercised. See Choice structure for what can go in a choice.

Choice structure

Here’s the structure of a choice inside a template:

controller exampleParty3 can
  NameOfChoice : -- return type here
      ()
    with
      -- parameters here
      party : Party
    do
      -- choice body; see next section
      return ()
a controller (or controllers)

controller keyword

Who can exercise the choice.

consumability

nonconsuming keyword

By default, contracts are archived when a choice on them is exercised. If you include nonconsuming, this choice can be exercised over and over.

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
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 instance 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 instance using its ID. Often used with assert to check conditions on the contract’s content.

fetchedContract <- fetch IdOfContract

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 effective 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 amount

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