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¶
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.
Controllers¶
controller exampleParty
controller exampleParty can
controller
keywordThe 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.
Contract consumption¶
If no qualifier is present, choices are consuming: the contract is archived before the evaluation of the choice body and both the controllers and all contract stakeholders see all consequences of the action.
Preconsuming choices¶
preconsuming choice ExampleChoice5
: () -- replace () with the actual return type
preconsuming ExampleChoice7
: () -- replace () with the actual return type
preconsuming
keyword. Optional.- Makes a choice pre-consuming: the contract is archived before the body of the exercise is executed.
- The archival behavior is analogous to the consuming default behavior.
- Unlike what happens the in consuming behavior, though, only the controllers and signatories of the contract see all consequences of the action. If the choice archives the contract, other stakeholders merely see an archive action.
- Can be thought as a non-consuming choice that implicitly archives the contract before anything else happens
Postconsuming choices¶
postconsuming choice ExampleChoice6
: () -- replace () with the actual return type
postconsuming ExampleChoice8
: () -- replace () with the actual return type
postconsuming
keyword. Optional.- Makes a choice post-consuming: the contract is archived after the body of the exercise is executed.
- The contract can still be used in the body of the exercise.
- Only the controllers and signatories of the contract see all consequences of the action. If the choice archives the contract, other stakeholders merely see an archive action.
- Can be thought as a non-consuming choice that implicitly archives the contract after the choice has been exercised
Non-consuming choices¶
nonconsuming choice ExampleChoice3
: () -- replace () with the actual return type
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.
- Only the controllers and signatories of the contract see all consequences of the action. If the choice archives the contract, other stakeholders merely see an archive action.
- 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
with
keyword.- Choice arguments are similar in structure to Template parameters: a record type.
- A choice argument can’t have the same name as any parameter to the template the choice is in.
- Optional - only if you need extra information passed in to exercise the choice.
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 thereturn
keyword.