From c1c45b5ac7233232baee2d0d12f4685b36919b25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mois=C3=A9s=20Ackerman?= <6054733+akrmn@users.noreply.github.com> Date: Mon, 4 Sep 2023 15:14:28 +0200 Subject: [PATCH 01/11] Update '../code-snippets/Structure.daml' choice snippets in 2.8.0 --- docs/2.8.0/docs/daml/reference/choices.rst | 49 +++++++------------- docs/2.8.0/docs/daml/reference/structure.rst | 45 ++++++++---------- 2 files changed, 37 insertions(+), 57 deletions(-) diff --git a/docs/2.8.0/docs/daml/reference/choices.rst b/docs/2.8.0/docs/daml/reference/choices.rst index cc4f2a73c..5559c6c02 100644 --- a/docs/2.8.0/docs/daml/reference/choices.rst +++ b/docs/2.8.0/docs/daml/reference/choices.rst @@ -6,36 +6,6 @@ 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 @@ -57,7 +27,6 @@ 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. -- 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: @@ -76,11 +45,29 @@ Controllers :end-before: -- end controller-first controller snippet :caption: Option 2 for specifying choices (deprecated syntax): controller first + + - ``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 won't be able to see the contract (and therefore won't be able to exercise the choice). + +.. _daml-ref-choice-observers: + +Choice Observers +**************** + +It is possible for *choice observers* to be attached to a 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 new choice observer snippet + :end-before: -- end of new choice observer snippet + .. _daml-ref-consumability: Contract Consumption diff --git a/docs/2.8.0/docs/daml/reference/structure.rst b/docs/2.8.0/docs/daml/reference/structure.rst index 8a2ff2b68..1e6e9689c 100644 --- a/docs/2.8.0/docs/daml/reference/structure.rst +++ b/docs/2.8.0/docs/daml/reference/structure.rst @@ -68,42 +68,21 @@ template body :ref:`choices ` ``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's 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 + :start-after: -- start of new choice snippet + :end-before: -- end of new choice snippet :dedent: 4 -:ref:`a controller (or controllers) ` - ``controller`` keyword - - Who can exercise the choice. - -: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 ` 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 ` 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 ` ``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) ` + ``controller`` keyword + + Who can exercise the choice. + +: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 ` After ``do`` keyword From d1dd9d6efc7f5d1f0d83eb467d04f7eeed9810c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mois=C3=A9s=20Ackerman?= <6054733+akrmn@users.noreply.github.com> Date: Mon, 4 Sep 2023 15:24:10 +0200 Subject: [PATCH 02/11] Remove mention of controller-can syntax in 'Intro to Daml: Composing --- docs/2.8.0/docs/daml/intro/7_Composing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/2.8.0/docs/daml/intro/7_Composing.rst b/docs/2.8.0/docs/daml/intro/7_Composing.rst index 768f2f116..15aef3573 100644 --- a/docs/2.8.0/docs/daml/intro/7_Composing.rst +++ b/docs/2.8.0/docs/daml/intro/7_Composing.rst @@ -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: From a7dd1f3f6f7bcf1bf6a06c1e1d222040a2a1ae45 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mois=C3=A9s=20Ackerman?= <6054733+akrmn@users.noreply.github.com> Date: Mon, 4 Sep 2023 15:33:56 +0200 Subject: [PATCH 03/11] Update '../code-snippets/Reference.daml' choice snippet in 2.8.0 Ref Templates --- docs/2.8.0/docs/daml/reference/templates.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/2.8.0/docs/daml/reference/templates.rst b/docs/2.8.0/docs/daml/reference/templates.rst index d5ea70127..3bcf09df5 100644 --- a/docs/2.8.0/docs/daml/reference/templates.rst +++ b/docs/2.8.0/docs/daml/reference/templates.rst @@ -225,15 +225,12 @@ Choices .. literalinclude:: ../code-snippets/Reference.daml :language: daml - :start-after: -- start template choice snippet - :end-before: -- end template choice snippet + :start-after: -- start new template choice snippet + :end-before: -- end new template choice snippet - 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: From fe58481114c109101fd3f1e4ee2d02d343b1327d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mois=C3=A9s=20Ackerman?= <6054733+akrmn@users.noreply.github.com> Date: Mon, 4 Sep 2023 15:43:59 +0200 Subject: [PATCH 04/11] Update '../code-snippets/Reference.daml' choice snippets in 2.8.0 Ref Choices --- docs/2.8.0/docs/daml/reference/choices.rst | 64 +++++----------------- 1 file changed, 13 insertions(+), 51 deletions(-) diff --git a/docs/2.8.0/docs/daml/reference/choices.rst b/docs/2.8.0/docs/daml/reference/choices.rst index 5559c6c02..cf96b43c6 100644 --- a/docs/2.8.0/docs/daml/reference/choices.rst +++ b/docs/2.8.0/docs/daml/reference/choices.rst @@ -13,19 +13,11 @@ 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 new choice name snippet + :end-before: -- end new 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. .. _daml-ref-controllers: @@ -35,17 +27,8 @@ 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 new controller snippet + :end-before: -- end new 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. @@ -80,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 new preconsuming snippet + :end-before: -- end new preconsuming snippet - ``preconsuming`` keyword. Optional. - Makes a choice pre-consuming: the contract is archived before the body of the exercise is executed. @@ -102,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 new postconsuming snippet + :end-before: -- end new postconsuming snippet - ``postconsuming`` keyword. Optional. - Makes a choice post-consuming: the contract is archived after the body of the exercise is executed. @@ -123,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 new nonconsuming snippet + :end-before: -- end new nonconsuming snippet - ``nonconsuming`` keyword. Optional. - Makes a choice non-consuming: that is, exercising the choice does not archive the contract. @@ -154,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 new choice params snippet + :end-before: -- end new choice params snippet - ``with`` keyword. - Choice arguments are similar in structure to :ref:`daml-ref-template-parameters`: a :ref:`record type `. From 9d894fb5a282c31d567fd61c812da7bf2605e296 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mois=C3=A9s=20Ackerman?= <6054733+akrmn@users.noreply.github.com> Date: Mon, 4 Sep 2023 15:44:44 +0200 Subject: [PATCH 05/11] Remove 2.8.0 Ref Choices section on 'controller..can' deprecation --- docs/2.8.0/docs/daml/reference/choices.rst | 67 ---------------------- 1 file changed, 67 deletions(-) diff --git a/docs/2.8.0/docs/daml/reference/choices.rst b/docs/2.8.0/docs/daml/reference/choices.rst index cf96b43c6..4acf66e54 100644 --- a/docs/2.8.0/docs/daml/reference/choices.rst +++ b/docs/2.8.0/docs/daml/reference/choices.rst @@ -133,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 #-} From d616911bcf61646e59e10328ca4e28f0fe9ef8ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mois=C3=A9s=20Ackerman?= <6054733+akrmn@users.noreply.github.com> Date: Mon, 4 Sep 2023 15:47:52 +0200 Subject: [PATCH 06/11] Remove mention of flexible controller in ledger model --- docs/2.8.0/docs/concepts/ledger-model/ledger-daml.rst | 5 +---- docs/2.8.0/docs/concepts/ledger-model/ledger-privacy.rst | 2 +- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/2.8.0/docs/concepts/ledger-model/ledger-daml.rst b/docs/2.8.0/docs/concepts/ledger-model/ledger-daml.rst index 134b943fb..8b85eac38 100644 --- a/docs/2.8.0/docs/concepts/ledger-model/ledger-daml.rst +++ b/docs/2.8.0/docs/concepts/ledger-model/ledger-daml.rst @@ -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. diff --git a/docs/2.8.0/docs/concepts/ledger-model/ledger-privacy.rst b/docs/2.8.0/docs/concepts/ledger-model/ledger-privacy.rst index 5e43c6af3..0e7cb3ed3 100644 --- a/docs/2.8.0/docs/concepts/ledger-model/ledger-privacy.rst +++ b/docs/2.8.0/docs/concepts/ledger-model/ledger-privacy.rst @@ -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 `. + Note that a Daml choice controller :ref:`can be an exercise actor without being a contract stakeholder `. * `A` is a non-consuming **Exercise** on a contract `c`, and `p` is a signatory of `c` or an actor on `A`. From 2d4c99e191a5974c2412af5d1aadc0c64cedddd4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mois=C3=A9s=20Ackerman?= <6054733+akrmn@users.noreply.github.com> Date: Tue, 5 Sep 2023 11:01:13 +0200 Subject: [PATCH 07/11] Correct claim that choice names must be unique in {project=>module} --- docs/2.6.5/docs/daml/reference/choices.rst | 2 +- docs/2.7.1/docs/daml/reference/choices.rst | 2 +- docs/2.8.0/docs/daml/reference/choices.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/2.6.5/docs/daml/reference/choices.rst b/docs/2.6.5/docs/daml/reference/choices.rst index cc4f2a73c..f8cb83c15 100644 --- a/docs/2.6.5/docs/daml/reference/choices.rst +++ b/docs/2.6.5/docs/daml/reference/choices.rst @@ -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: diff --git a/docs/2.7.1/docs/daml/reference/choices.rst b/docs/2.7.1/docs/daml/reference/choices.rst index cc4f2a73c..f8cb83c15 100644 --- a/docs/2.7.1/docs/daml/reference/choices.rst +++ b/docs/2.7.1/docs/daml/reference/choices.rst @@ -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: diff --git a/docs/2.8.0/docs/daml/reference/choices.rst b/docs/2.8.0/docs/daml/reference/choices.rst index 4acf66e54..91f6012cc 100644 --- a/docs/2.8.0/docs/daml/reference/choices.rst +++ b/docs/2.8.0/docs/daml/reference/choices.rst @@ -18,7 +18,7 @@ Choice Name - ``choice`` keyword - 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. +- Must be unique in the module. Different templates defined in the same module cannot share a choice name. .. _daml-ref-controllers: From ce5a17b81526fecfaf2f7f9c9146955ef715abbc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mois=C3=A9s=20Ackerman?= <6054733+akrmn@users.noreply.github.com> Date: Tue, 5 Sep 2023 16:45:01 +0200 Subject: [PATCH 08/11] Apply suggestions from code review Co-authored-by: carrielaben-da <91496516+carrielaben-da@users.noreply.github.com> --- docs/2.8.0/docs/daml/reference/choices.rst | 4 ++-- docs/2.8.0/docs/daml/reference/structure.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/2.8.0/docs/daml/reference/choices.rst b/docs/2.8.0/docs/daml/reference/choices.rst index 91f6012cc..f04c44194 100644 --- a/docs/2.8.0/docs/daml/reference/choices.rst +++ b/docs/2.8.0/docs/daml/reference/choices.rst @@ -37,14 +37,14 @@ Controllers .. warning:: - You **must** make sure that the controller parties are observers (or signatories) of the contract, otherwise they won't be able to see the contract (and therefore won't be able to exercise the choice). + 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 **************** -It is possible for *choice observers* to be attached to a 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. +*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 diff --git a/docs/2.8.0/docs/daml/reference/structure.rst b/docs/2.8.0/docs/daml/reference/structure.rst index 1e6e9689c..74b640f44 100644 --- a/docs/2.8.0/docs/daml/reference/structure.rst +++ b/docs/2.8.0/docs/daml/reference/structure.rst @@ -75,7 +75,7 @@ template body Choice Structure **************** -Here's the structure of a choice inside a template: +Here is the structure of a choice inside a template: .. literalinclude:: ../code-snippets/Structure.daml :language: daml From 08a6febf0f76862039237e613255219369fe82da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mois=C3=A9s=20Ackerman?= <6054733+akrmn@users.noreply.github.com> Date: Tue, 12 Sep 2023 10:37:32 +0200 Subject: [PATCH 09/11] Drop 'new' from 'code-snippets/{Structure,Reference}.daml' tags --- docs/2.8.0/docs/daml/reference/choices.rst | 28 ++++++++++---------- docs/2.8.0/docs/daml/reference/structure.rst | 4 +-- docs/2.8.0/docs/daml/reference/templates.rst | 4 +-- 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/2.8.0/docs/daml/reference/choices.rst b/docs/2.8.0/docs/daml/reference/choices.rst index f04c44194..d0f5b1ed3 100644 --- a/docs/2.8.0/docs/daml/reference/choices.rst +++ b/docs/2.8.0/docs/daml/reference/choices.rst @@ -13,8 +13,8 @@ Choice Name .. literalinclude:: ../code-snippets/Reference.daml :language: daml - :start-after: -- start new choice name snippet - :end-before: -- end new choice name snippet + :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. @@ -27,8 +27,8 @@ Controllers .. literalinclude:: ../code-snippets/Reference.daml :language: daml - :start-after: -- start new controller snippet - :end-before: -- end new controller snippet + :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. @@ -48,8 +48,8 @@ Choice Observers .. literalinclude:: ../code-snippets/Structure.daml :language: daml - :start-after: -- start of new choice observer snippet - :end-before: -- end of new choice observer snippet + :start-after: -- start of choice observer snippet + :end-before: -- end of choice observer snippet .. _daml-ref-consumability: @@ -63,8 +63,8 @@ Preconsuming Choices .. literalinclude:: ../code-snippets/Reference.daml :language: daml - :start-after: -- start new preconsuming snippet - :end-before: -- end new preconsuming snippet + :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. @@ -78,8 +78,8 @@ Postconsuming Choices .. literalinclude:: ../code-snippets/Reference.daml :language: daml - :start-after: -- start new postconsuming snippet - :end-before: -- end new postconsuming snippet + :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. @@ -92,8 +92,8 @@ Non-consuming Choices .. literalinclude:: ../code-snippets/Reference.daml :language: daml - :start-after: -- start new nonconsuming snippet - :end-before: -- end new nonconsuming snippet + :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. @@ -116,8 +116,8 @@ Choice Arguments .. literalinclude:: ../code-snippets/Reference.daml :language: daml - :start-after: -- start new choice params snippet - :end-before: -- end new choice 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 `. diff --git a/docs/2.8.0/docs/daml/reference/structure.rst b/docs/2.8.0/docs/daml/reference/structure.rst index 74b640f44..74529af9f 100644 --- a/docs/2.8.0/docs/daml/reference/structure.rst +++ b/docs/2.8.0/docs/daml/reference/structure.rst @@ -79,8 +79,8 @@ Here is the structure of a choice inside a template: .. literalinclude:: ../code-snippets/Structure.daml :language: daml - :start-after: -- start of new choice snippet - :end-before: -- end of new choice snippet + :start-after: -- start of choice snippet + :end-before: -- end of choice snippet :dedent: 4 :ref:`consumption annotation ` diff --git a/docs/2.8.0/docs/daml/reference/templates.rst b/docs/2.8.0/docs/daml/reference/templates.rst index 3bcf09df5..3178d1115 100644 --- a/docs/2.8.0/docs/daml/reference/templates.rst +++ b/docs/2.8.0/docs/daml/reference/templates.rst @@ -225,8 +225,8 @@ Choices .. literalinclude:: ../code-snippets/Reference.daml :language: daml - :start-after: -- start new template choice snippet - :end-before: -- end new template choice snippet + :start-after: -- start template choice snippet + :end-before: -- end template choice snippet - A right that the contract gives the controlling party. Can be *exercised*. - This is essentially where all the logic of the template goes. From 4376e6698fce42c15ba035ff801cf9a15b77e668 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mois=C3=A9s=20Ackerman?= <6054733+akrmn@users.noreply.github.com> Date: Wed, 13 Sep 2023 19:03:52 +0200 Subject: [PATCH 10/11] Update daml snapshot version for 2.8.0 docs --- docs/2.8.0/versions.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/2.8.0/versions.json b/docs/2.8.0/versions.json index f9ed6761c..9c69ea371 100644 --- a/docs/2.8.0/versions.json +++ b/docs/2.8.0/versions.json @@ -1,5 +1,5 @@ { - "daml": "2.7.0-snapshot.20230719.11983.0.vd999a21a", + "daml": "2.8.0-snapshot.20230908.12101.0.v1bee52e4", "canton": "2.8.0-snapshot.20230828.11069.0.v0819eb02", "daml_finance": "1.3.2", "canton_drivers": "0.1.9" From 938f592dcfefb6e2b7abac2145edb1c09920d338 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mois=C3=A9s=20Ackerman?= <6054733+akrmn@users.noreply.github.com> Date: Wed, 13 Sep 2023 19:59:30 +0200 Subject: [PATCH 11/11] Update daml snapshot version for 2.8.0 docs [bis] --- docs/2.8.0/versions.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/2.8.0/versions.json b/docs/2.8.0/versions.json index 9c69ea371..bc864c197 100644 --- a/docs/2.8.0/versions.json +++ b/docs/2.8.0/versions.json @@ -1,5 +1,5 @@ { - "daml": "2.8.0-snapshot.20230908.12101.0.v1bee52e4", + "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"