digital-asset · moisesackerman-da · Sep 20, 2023 · Sep 4, 2023 · Sep 4, 2023 · Sep 4, 2023
@@ -56,7 +56,7 @@ Choice Name
 
 - 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.
+- Must be unique in the module. Different templates defined in the same module cannot share a choice name.
 - If you're using controller-first, you can have multiple choices after one ``can``, for tidiness. However, note that this syntax is deprecated and will be removed in a future version of Daml.
 
 .. _daml-ref-controllers:

@@ -56,7 +56,7 @@ Choice Name
 
 - 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.
+- Must be unique in the module. Different templates defined in the same module cannot share a choice name.
 - If you're using controller-first, you can have multiple choices after one ``can``, for tidiness. However, note that this syntax is deprecated and will be removed in a future version of Daml.
 
 .. _daml-ref-controllers:

@@ -60,10 +60,7 @@ is a triple of:
 #. the template arguments
 
 The signatories of a Daml contract are derived from the template arguments and the explicit signatory annotations on the contract template.
-The contract observers are also derived from the template arguments and include:
-
-1. the observers as explicitly annotated on the template
-2. all controllers `c` of every choice defined using the syntax :code:`controller c can...` (as opposed to the syntax :code:`choice ... controller c`)
+The contract observers are those explicitly defined in the template using the ``observer`` keyword.
 
 For example, the following template exactly describes the contract model
 of a simple IOU with a unit amount, shown earlier.

@@ -102,7 +102,7 @@ This motivates the following definition: a party `p` is an **informee** of an ac
   * `A` is a **Create** on a contract `c` and `p` is a stakeholder of `c`.
 
   * `A` is a consuming **Exercise** on a contract `c`, and `p` is a stakeholder of `c` or an actor on `A`.
-    Note that a Daml "flexible controller" :ref:`can be an exercise actor without being a contract stakeholder <da-model-daml>`.
+    Note that a Daml choice controller :ref:`can be an exercise actor without being a contract stakeholder <da-model-daml>`.
 
   * `A` is a non-consuming **Exercise** on a contract `c`, and `p` is a signatory of `c` or an actor on `A`.
 

@@ -263,7 +263,7 @@ Observers have guarantees in Daml. In particular, they are guaranteed to see act
 
 Since observers are calculated from the arguments of the contract, they always know about each other. That's why, rather than adding Bob as an observer on Alice's ``AssetHolder`` contract, and using that to authorize the transfer in ``Trade_Settle``, Alice creates a one-time authorization in the form of a ``TransferAuthorization``. If Alice had lots of counterparties, she would otherwise end up leaking them to each other.
 
-Controllers declared in the ``choice`` syntax are not automatically made observers, as they can only be calculated at the point in time when the choice arguments are known. On the contrary, controllers declared via the ``controller cs can`` syntax are automatically made observers, but this syntax is deprecated and will be removed in a future version of Daml.
+Choice controllers are not automatically made observers, as they can only be calculated at the point in time when the choice arguments are known.
 
 .. _privacy:
 

@@ -6,58 +6,19 @@ Reference: Choices
 
 This page gives reference information on choices. For information on the high-level structure of a choice, see :doc:`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
-
-.. warning::
-
-  ``controller`` first syntax is deprecated since Daml 2.0 and will be removed in a future version. For more information, see :ref:`daml-ref-controller-can-deprecation`.
-
-.. literalinclude:: ../code-snippets/Structure.daml
-   :language: daml
-   :start-after: -- start of choice snippet
-   :end-before: -- end of choice snippet
-
-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.
-
-.. _daml-ref-choice-observers:
-
-A secondary difference is that starting with ``choice`` allows *choice observers* to be attached to the choice using the ``observer`` keyword. The choice observers are a list of parties that, in addition to the stakeholders, will see all consequences of the action.
-
-.. literalinclude:: ../code-snippets/Structure.daml
-   :language: daml
-   :start-after: -- start of choice observer snippet
-   :end-before: -- end of choice observer snippet
-
 .. _daml-ref-choice-name:
 
 Choice Name
 ***********
 
 .. literalinclude:: ../code-snippets/Reference.daml
    :language: daml
-   :start-after: -- start choice-first choice name snippet
-   :end-before: -- end choice-first choice name snippet
-   :caption: Option 1 for specifying choices: choice name first
-
-.. literalinclude:: ../code-snippets/Reference.daml
-   :language: daml
-   :start-after: -- start controller-first choice name snippet
-   :end-before: -- end controller-first choice name snippet
-   :caption: Option 2 for specifying choices (deprecated syntax): controller first
-
+   :start-after: -- start choice name snippet
+   :end-before: -- end choice name snippet
 
+- ``choice`` keyword
 - 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. However, note that this syntax is deprecated and will be removed in a future version of Daml.
+- Must be unique in the module. Different templates defined in the same module cannot share a choice name.
 
 .. _daml-ref-controllers:
 
@@ -66,21 +27,30 @@ Controllers
 
 .. literalinclude:: ../code-snippets/Reference.daml
    :language: daml
-   :start-after: -- start choice-first controller snippet
-   :end-before: -- end choice-first controller snippet
-   :caption: Option 1 for specifying choices: choice name first
-
-.. literalinclude:: ../code-snippets/Reference.daml
-   :language: daml
-   :start-after: -- start controller-first controller snippet
-   :end-before: -- end controller-first controller snippet
-   :caption: Option 2 for specifying choices (deprecated syntax): controller first
+   :start-after: -- start controller snippet
+   :end-before: -- end controller snippet
 
 - ``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.
 
+.. warning::
+
+  You **must** make sure that the controller parties are observers (or signatories) of the contract, otherwise they cannot see the contract (and therefore cannot exercise the choice).
+
+.. _daml-ref-choice-observers:
+
+Choice Observers
+****************
+
+*Choice observers* can be attached to a choice using the ``observer`` keyword. The choice observers are a list of parties who are not stakeholders but who see all the consequences of the action.
+
+.. literalinclude:: ../code-snippets/Structure.daml
+   :language: daml
+   :start-after: -- start of choice observer snippet
+   :end-before: -- end of choice observer snippet
+
 .. _daml-ref-consumability:
 
 Contract Consumption
@@ -93,15 +63,8 @@ Preconsuming Choices
 
 .. literalinclude:: ../code-snippets/Reference.daml
    :language: daml
-   :start-after: -- start choice-first preconsuming snippet
-   :end-before: -- end choice-first preconsuming snippet
-   :caption: Option 1 for specifying choices: choice name first
-
-.. literalinclude:: ../code-snippets/Reference.daml
-   :language: daml
-   :start-after: -- start controller-first preconsuming snippet
-   :end-before: -- end controller-first preconsuming snippet
-   :caption: Option 2 for specifying choices (deprecated syntax): controller first
+   :start-after: -- start preconsuming snippet
+   :end-before: -- end preconsuming snippet
 
 - ``preconsuming`` keyword. Optional.
 - Makes a choice pre-consuming: the contract is archived before the body of the exercise is executed.
@@ -115,15 +78,8 @@ Postconsuming Choices
 
 .. literalinclude:: ../code-snippets/Reference.daml
    :language: daml
-   :start-after: -- start choice-first postconsuming snippet
-   :end-before: -- end choice-first postconsuming snippet
-   :caption: Option 1 for specifying choices: choice name first
-
-.. literalinclude:: ../code-snippets/Reference.daml
-   :language: daml
-   :start-after: -- start controller-first postconsuming snippet
-   :end-before: -- end controller-first postconsuming snippet
-   :caption: Option 2 for specifying choices (deprecated syntax): controller first
+   :start-after: -- start postconsuming snippet
+   :end-before: -- end postconsuming snippet
 
 - ``postconsuming`` keyword. Optional.
 - Makes a choice post-consuming: the contract is archived after the body of the exercise is executed.
@@ -136,15 +92,8 @@ Non-consuming Choices
 
 .. literalinclude:: ../code-snippets/Reference.daml
    :language: daml
-   :start-after: -- start choice-first nonconsuming snippet
-   :end-before: -- end choice-first nonconsuming snippet
-   :caption: Option 1 for specifying choices: choice name first
-
-.. literalinclude:: ../code-snippets/Reference.daml
-   :language: daml
-   :start-after: -- start controller-first nonconsuming snippet
-   :end-before: -- end controller-first nonconsuming snippet
-   :caption: Option 2 for specifying choices (deprecated syntax): controller first
+   :start-after: -- start nonconsuming snippet
+   :end-before: -- end nonconsuming snippet
 
 - ``nonconsuming`` keyword. Optional.
 - Makes a choice non-consuming: that is, exercising the choice does not archive the contract.
@@ -167,8 +116,8 @@ Choice Arguments
 
 .. literalinclude:: ../code-snippets/Reference.daml
    :language: daml
-   :start-after: -- start choice-first params snippet
-   :end-before: -- end choice-first params snippet
+   :start-after: -- start choice params snippet
+   :end-before: -- end choice params snippet
 
 - ``with`` keyword.
 - Choice arguments are similar in structure to :ref:`daml-ref-template-parameters`: a :ref:`record type <daml-ref-record-types>`.
@@ -184,70 +133,3 @@ Choice Body
 - 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 :doc:`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.
-
-.. _daml-ref-controller-can-deprecation:
-
-Deprecation of ``controller`` first syntax
-******************************************
-
-Since Daml 2.0, using ``controller`` first syntax to define a choice will
-result in the following warning:
-
-.. code-block:: text
-
-  The syntax 'controller ... can' is deprecated,
-  it will be removed in a future version of Daml.
-  Instead, use 'choice ... with ... controller' syntax.
-  Note that 'choice ... with ... controller' syntax does not
-  implicitly add the controller as an observer,
-  so it must be added explicitly as one (or as a signatory).
-
-Migrating
-=========
-
-Users are strongly encouraged to adapt their choices to use ``choice``
-first syntax. This is a schema to adapt affected code:
-
-#. For each ``controller ... can`` block,
-
-   #. Note the parties between the ``controller`` and ``can`` keywords; these are the block controllers.
-
-   #. Ensure that all the block controllers are signatories or observers of the template. If any controller is neither a signatory nor observer of the template, add it as an observer.
-
-   #. For each choice in the block,
-
-      #. Prefix the choice name with the ``choice`` keyword, but keep any consumption qualifiers before ``choice``.
-
-      #. Add a ``controller`` clause with the block controllers before the body of the choice (the ``do`` block) .
-
-   #. Remove the ``controller ... can`` block header and adjust indentation as necessary.
-
-Turning off the warning
-=======================
-
-This warning is controlled by the warning flag ``controller-can``, which means
-that it can be toggled independently of other warnings. This is especially
-useful for gradually migrating code that used this syntax.
-
-To turn off the warning within a Daml file, add the following line at the top of
-the file:
-
-.. code-block:: daml
-
-  {-# OPTIONS_GHC -Wno-controller-can #-}
-
-To turn it off for an entire Daml project, add the following entry to the
-``build-options`` field of the project's ``daml.yaml`` file
-
-.. code-block:: yaml
-
-  build-options:
-  - --ghc-option=-Wno-controller-can
-
-Within a project where the warning has been turned off via the ``daml.yaml``
-file, it can be turned back on for individual Daml files by adding the following
-line at the top of each file:
-
-.. code-block:: daml
-
-  {-# OPTIONS_GHC -Wcontroller-can #-}
@@ -68,42 +68,21 @@ template body
     :ref:`choices <daml-ref-choice-structure>`
         ``choice NameOfChoice : ReturnType controller nameOfParty do``
 
-        or
-
-    	``controller nameOfParty can NameOfChoice : ReturnType do``
-
-        Defines choices that can be exercised. See `Choice structure`_ for what can go in a choice. Note that ``controller``-first syntax is deprecated and will be removed in a future version of Daml.
+        Defines choices that can be exercised. See `Choice structure`_ for what can go in a choice.
 
 .. _daml-ref-choice-structure:
 
 Choice Structure
 ****************
 
-Here's the structure of a choice inside a template. There are two ways of specifying a choice:
-
-- start with the ``choice`` keyword
-- start with the ``controller`` keyword
+Here is the structure of a choice inside a template:
 
 .. literalinclude:: ../code-snippets/Structure.daml
    :language: daml
    :start-after: -- start of choice snippet
    :end-before: -- end of choice snippet
    :dedent: 4
 
-:ref:`a controller (or controllers) <daml-ref-controllers>`
-    ``controller`` keyword
-
-    Who can exercise the choice.
-
-:ref:`choice observers <daml-ref-choice-observers>`
-    ``observer`` keyword
-
-    Optional. Additional parties that are guaranteed to be informed of an exercise of the choice.
-
-    To specify choice observers, you must start you choice with the ``choice`` keyword.
-
-    The optional ``observer`` keyword must precede the mandatory ``controller`` keyword.
-
 :ref:`consumption annotation <daml-ref-consumability>`
     Optionally one of ``preconsuming``, ``postconsuming``, ``nonconsuming``, which changes the behavior of the choice with respect to privacy and if and when the contract is archived.
     See :ref:`contract consumption in choices <daml-ref-consumability>` for more details.
@@ -117,7 +96,21 @@ Here's the structure of a choice inside a template. There are two ways of specif
 :ref:`choice arguments <daml-ref-choice-arguments>`
     ``with`` keyword
 
-    If you start your choice with ``choice`` and include a ``Party`` as a parameter, you can make that ``Party`` the ``controller`` of the choice. This is a feature called "flexible controllers", and it means you don't have to specify the controller when you create the contract - you can specify it when you exercise the choice. To exercise a choice, the party needs to be a signatory or an observer of the contract and must be explicitly declared as such.
+    If you include a ``Party`` as a choice argument, you can make that ``Party`` the ``controller`` of the choice. This means that the controller can be specified when the choice is exercised, rather than when the contract is created. For the exercise to work, the party needs to be able to see the contract, i.e. it must be an ``observer`` or a ``signatory``.
+
+:ref:`a controller (or controllers) <daml-ref-controllers>`
+    ``controller`` keyword
+
+    Who can exercise the choice.
+
+:ref:`choice observers <daml-ref-choice-observers>`
+    ``observer`` keyword
+
+    Optional. Additional parties that are guaranteed to be informed of an exercise of the choice.
+
+    To specify choice observers, you must start you choice with the ``choice`` keyword.
+
+    The optional ``observer`` keyword must precede the mandatory ``controller`` keyword.
 
 :ref:`a choice body <daml-ref-choice-body>`
     After ``do`` keyword

@@ -231,9 +231,6 @@ Choices
 - 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.
-- There are two ways of specifying a choice: start with the ``choice`` keyword or start with the ``controller`` keyword.
-
-  Starting with ``choice`` lets you pass in a ``Party`` to use as a controller. But you must make sure to add that party as an ``observer``.
 - See :doc:`choices` for full reference information.
 
 .. _daml-ref-serializable-types:

@@ -1,5 +1,5 @@
 {
-  "daml": "2.7.0-snapshot.20230719.11983.0.vd999a21a",
+  "daml": "2.8.0-snapshot.20230913.12113.0.vf71b764f",
   "canton": "2.8.0-snapshot.20230828.11069.0.v0819eb02",
   "daml_finance": "1.3.2",
   "canton_drivers": "0.1.9"