This page gives reference information on choices:
For information on the high-level structure of a choice, see Overview: template structure.
There are two ways you can start a choice:
- start with the
- start with the
-- 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 is automatically added as an observer when you compile your DAML files.
choice ExampleChoice1 : () -- replace () with the actual return type
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.
controller exampleParty can
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.
nonconsuming choice ExampleChoice3 : () -- replace () with the actual return type
nonconsuming ExampleChoice4 : () -- replace () with the actual return type
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 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.
with exampleParameter : Text
- Introduced with
- The logic in this section is what is executed when the choice gets exercised.
- The choice body contains
Updateexpressions. 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