Reference: choices

This page gives reference information on choices:

For information on the high-level structure of a choice, see Overview: template structure.

choice first or controller first

There are two ways you can start a choice:

  • start with the choice keyword
  • start with the controller keyword
    -- option 1 for specifying choices: choice name first
    choice NameOfChoice :
          () -- replace () with the actual return type
        with
        party : Party -- parameters here
      controller party
        do
          return () -- replace this line with the choice body

    -- option 2 for specifying choices: controller first
    controller exampleParty can
      NameOfAnotherChoice :
          () -- replace () with the actual return type
        with
          party : Party -- parameters here
        do
          return () -- replace the line with the choice body

The main difference is that starting with choice means that you can pass in a Party to use as a controller. If you do this, you must make sure that you add that party as an observer, otherwise they won’t be able to see the contract (and therefore won’t be able to exercise the choice).

In contrast, if you start with controller, the controller is automatically added as an observer when you compile your DAML files.

Choice name

Option 1 for specifying choices: choice name first
    choice ExampleChoice1
          : () -- replace () with the actual return type
Option 2 for specifying choices: controller first
      ExampleChoice2
          : () -- replace () with the actual return type
  • The name of the choice. Must begin with a capital letter.
  • If you’re using choice-first, preface with choice. Otherwise, this isn’t needed.
  • Must be unique in your project. Choices in different templates can’t have the same name.
  • If you’re using controller-first, you can have multiple choices after one can, for tidiness.

Controllers

Option 1 for specifying choices: choice name first
      controller exampleParty
Option 2 for specifying choices: controller first
    controller exampleParty can

  • controller keyword

  • The controller is a comma-separated list of values, where each value is either a party or a collection of parties.

    The conjunction of all the parties are required to authorize when this choice is exercised.

Non-consuming choices

Option 1 for specifying choices: choice name first
    nonconsuming choice ExampleChoice3
          : () -- replace () with the actual return type
Option 2 for specifying choices: controller first
      nonconsuming ExampleChoice4
          : () -- replace () with the actual return type

  • nonconsuming keyword. Optional.

  • Makes a choice non-consuming: that is, exercising the choice does not archive the contract.

    By default, choices are consuming: when a choice on a contract is exercised, that contract instance is archived. Archived means that it’s permanently marked as being inactive, and no more choices can be exercised on it, though it still exists on the ledger.

  • This is useful in the many situations when you want to be able to exercise a choice more than once.

Return type

  • Return type is written immediately after choice name.
  • All choices have a return type. A contract returning nothing should be marked as returning a “unit”, ie ().
  • If a contract is/contracts are created in the choice body, usually you would return the contract ID(s) (which have the type ContractId <name of template>). This is returned when the choice is exercised, and can be used in a variety of ways.

Choice arguments

        with
          exampleParameter : Text

Choice body

  • Introduced with do
  • The logic in this section is what is executed when the choice gets exercised.
  • The choice body contains Update expressions. For detail on this, see Reference: updates.
  • By default, the last expression in the choice is returned. You can return multiple updates in tuple form or in a custom data type. To return something that isn’t of type Update, use the return keyword.