Reference: choices

This page gives reference information on choices:

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

Controllers

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.

Choice name

controller exampleParty can
  NameOfChoice
  • The name of the choice. Must begin with a capital letter.
  • Must be unique in your project. Choices in different templates can’t have the same name.
  • You can have multiple choices after one can, for tidiness.

Non-consuming choices

controller exampleParty can
  nonconsuming NameOfChoice2
  • 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

controller exampleParty can
  NameOfChoice4 : ContractId NameOfTemplate
  • 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

controller exampleParty can
  NameOfChoice3 : ExampleReturnType
    with
      exampleParameter : Text

Choice body

    controller exampleParty can
      NameOfChoice4 : ContractId NameOfTemplate
        do
          create NameOfTemplate with exampleParty; exampleParty2; exampleParty3
  • 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.