Reference: templates

This page gives reference information on templates:

For the structure of a template, see Overview: template structure.

Template name

template NameOfTemplate
  • This is the name of the template. It’s preceded by template keyword. 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).

Template parameters

template NameOfTemplate
  with
    exampleParty : Party
    exampleParty2 : Party
    exampleParty3 : Party
    -- more parameters here
  • with keyword. 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.

  • You must pass in the parties as parameters to the contract.

    This means isn’t valid to replace the giver variable in the Payout template above directly with 'Elizabeth'.

    Parties can only be named explicitly in scenarios.

Signatory parties

where
  signatory exampleParty
  • signatory keyword. After where. Followed by at least one Party.

  • Signatories are the parties (see the Party type) 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.

  • 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).

  • You must have least one signatory per template. You can have many, either as a comma-separated list or reusing the keyword.

Observers

where
  observer exampleParty2
  • observer keyword. After where. Followed by at least one Party.
  • Observers are additional stakeholders, so the contract instance is visible to these parties (see the Party type).
  • Optional. You can have many, either as a comma-separated list or reusing the keyword.
  • Use when a party needs visibility on a contract, or be informed or contract events, but is not a signatory or controller.

Choices

where
  controller exampleParty can
    -- a choice goes here; see next page
  • 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 nonconsuming keyword.
  • See Reference: choices for full reference information.

Agreements

where
  agreement
    -- text representing the contract
  • agreement keyword, 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 tx is of type Text.

    You can use the built-in operator show to convert party names to a string, and concatenate with <> .

Preconditions

where
  ensure
    -- boolean condition
  • ensure keyword, followed by a boolean condition.
  • Used on contract creation. ensure limits the values on parameters that can be passed to the contract: the contract can only be created if the boolean condition is true.