Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add safeguards section to explicit contract disclosure docs for 2.9.1 and 3.1 #774

Closed
wants to merge 5 commits into from
Closed

Add safeguards section to explicit contract disclosure docs for 2.9.1 and 3.1 #774

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
659208f
Add safeguards section to explicit contract disclosure docs for 2.9.1…
juliuswilliam-da Aug 6, 2024
683f0ad
Update docs/2.9.1/docs/app-dev/explicit-contract-disclosure.rst
juliuswilliam-da Aug 7, 2024
f1748f4
Update docs/3.1/docs/app-dev/explicit-contract-disclosure.rst
juliuswilliam-da Aug 7, 2024
221b505
Updated wording
juliuswilliam-da Aug 7, 2024
b3fd4f3
Rephrasing
juliuswilliam-da Aug 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions docs/2.9.1/docs/app-dev/explicit-contract-disclosure.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,3 +264,23 @@ These last two steps are executed using the new Daml Script functions supporting

.. note:: For an example using Java bindings for client applications, see the
`Java Bindings StockExchange example project <https://github.com/digital-asset/ex-java-bindings/blob/f474ae83976b0ad197e2fabfce9842fb9b3de907/StockExchange/README.rst>`_.

Safeguards
------------------------------------------
Explicit Contract Disclosure usage should always be accompanied by on-ledger contracts to ensure workflows executed based on the disclosed contract's contents conform to on-ledger agreements between the stakeholders (or trusted parties) involved.
juliuswilliam-da marked this conversation as resolved.
Show resolved Hide resolved

In the above example, ``IOU`` contracts between **Buyer** and **Issuer** (a trusted party on the ledger) ensure that the exercising of the ``Offer_Accept`` choice using disclosed contract results in a contractually agreed-upon outcome.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In the above example, ``IOU`` contracts between **Buyer** and **Issuer** (a trusted party on the ledger) ensure that the exercising of the ``Offer_Accept`` choice using disclosed contract results in a contractually agreed-upon outcome.
In the above example, ``IOU`` contracts between _Buyer_ and _Issuer_ (a trusted party on the ledger) ensure that exercising the ``Offer_Accept`` choice using the disclosed contract results in a contractually agreed-upon outcome.

According to our style guide, italics are used to draw attention to non-UI words.

Copy link
Contributor Author

@juliuswilliam-da juliuswilliam-da Aug 7, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@cathyjung-da Underscores don't seem to be resolving to italics on my local preview, can I confirm that it resolves correctly on your end?
I also see that Buyer and Seller parties are emphasized with asterisks in the rest of the docs. Should those be changed as well?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @juliuswilliam-da, thank you for raising this! I used Github's default comment feature to italicize the text, which used underscores, but according to this doc we're supposed to use single asterisk, like Buyer *Buyer*, to italicize text in rst. I began to support the doc team relatively recently, and just learned about this also.

I see that Buyer and Seller are bolded in the rest of the doc. I'm not sure how they didn't get noticed and revised sooner, but yes, according to our style guide, we're supposed italicize all the Buyer and Seller with italics and bold them only if they are UI elements.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would try to avoid overuse of variations of contract/contractually as it's not clear (at least to me) what type of restrictions are you referring to. Are they business logic restrictions (e.g. enforced through asserts) or Daml model restrictions (e.g. based on authorization/visibility).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see how it can be confusing.
I am referring to business logic restrictions here.

Would replacement of ''contractually'' with ''mutually'' be more accurate?


This works by performing several safety checks in the ``IOU_Transfer`` choice within the ``IOU`` contract, which is called from the ``Offer_Accept`` choice.
juliuswilliam-da marked this conversation as resolved.
Show resolved Hide resolved

The ``IOU`` contract provides several safeguards in the ``Offer_Accept`` workflow:

- **Buyer** exercising the ``Offer_Accept`` choice is defined on the ``IOU`` agreement.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **Buyer** exercising the ``Offer_Accept`` choice is defined on the ``IOU`` agreement.
- _Buyer_ exercising the ``Offer_Accept`` choice is defined on the ``IOU`` agreement.

- Creation of an IOU with an same amount for the **Seller** happens atomically with a deduction of the same amount from the **Buyer'** IOU.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Creation of an IOU with an same amount for the **Seller** happens atomically with a deduction of the same amount from the **Buyer'** IOU.
- Creation of an IOU with the same amount for the _Seller_ happens atomically with a deduction of the same amount from the _Buyer_'s IOU.

- **Buyer** cannot be deducted and **Seller** cannot receive more than the stipulated value on the ``IOU`` contract.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **Buyer** cannot be deducted and **Seller** cannot receive more than the stipulated value on the ``IOU`` contract.
- _Buyer_ cannot be deducted and _Seller_ cannot receive more than the stipulated value on the ``IOU`` contract.


By ensuring the **Buyer** party expected to execute the ``Offer_Accept`` choice, a trusted **Issuer** party and required terms of execution are clearly defined on an on-ledger multi-signatory ``IOU`` contract, the **Seller** can disclose the ``Offer`` contract and the **Buyer** can execute the ``Offer_Accept`` choice on the disclosed ``Offer`` contract knowing workflow safety is ensured.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
By ensuring the **Buyer** party expected to execute the ``Offer_Accept`` choice, a trusted **Issuer** party and required terms of execution are clearly defined on an on-ledger multi-signatory ``IOU`` contract, the **Seller** can disclose the ``Offer`` contract and the **Buyer** can execute the ``Offer_Accept`` choice on the disclosed ``Offer`` contract knowing workflow safety is ensured.
As the _Buyer_ party exercises the ``Offer_Accept`` choice, a trusted _Issuer_ party and required terms of execution are clearly defined on an on-ledger multi-signatory ``IOU`` contract. The _Seller_ can disclose the ``Offer`` contract and the _Buyer_ can exercise the ``Offer_Accept`` choice on the disclosed ``Offer`` contract, knowing that workflow safety is ensured.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IOU is not multi-signatory, is it?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What I think you are referring here is suggesting as a good practice to use preconditions (e.g. assert) on contracts creation and choice execution. If this is the case, I don't see how this applies specifically to explicit disclosure as it is a general good practice in designing Daml models. Please correct me if you had a different interpretation

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes indeed, I forgot to correct that statement, thank you.
IOU is a single signatory contract created by Issuer (a party trusted by both the seller and buyer)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree preconditions are a recommended best practice for Daml code in general.
I feel the "preconditions" section do not provide enough emphasis on business logic assertion, and may be skipped over a developer when starting to develop with Daml. (Maybe a section on business logic assertion via on-ledger contracts when developing workflows in the this section could be helpful?)

I wanted to call it out here as

  1. ECD involves execution on contracts which controllers do not have visibility of in the ledger. Because the controller cannot see what is included in the contract, it is important to ensure that sufficient business logic assertions via on-ledger contracts which the controller can see (such as IOU) is implemented in the disclosed contract's workflow to ensure workflow safety.
  2. Emphasizing on the importance of business logic assertions in the ECD feature section would be more likely to bring the concept to a developer's attention. Having said that, if we already have a section on business logic assertion within Daml workflows which can be linked here, that would be better than rewriting the entire concept here.


If disclosed contracts contain malicious data or are maliciously executed on, the safeguards will prevent unexpected outcomes outside the bounds of the agreement stated on the ``IOU`` contract from resolving.
juliuswilliam-da marked this conversation as resolved.
Show resolved Hide resolved

Generic variants of the discussed safeguards should be implemented when utilizing explicitly disclosed contracts to ensure workflow safety.
20 changes: 20 additions & 0 deletions docs/3.1/docs/app-dev/explicit-contract-disclosure.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,3 +264,23 @@ These last two steps are executed using the new Daml Script functions supporting

.. note:: For an example using Java bindings for client applications, see the
`Java Bindings StockExchange example project <https://github.com/digital-asset/ex-java-bindings/blob/f474ae83976b0ad197e2fabfce9842fb9b3de907/StockExchange/README.rst>`_.

Safeguards
------------------------------------------
Explicit Contract Disclosure usage should always be accompanied by on-ledger contracts to ensure workflows executed based on the disclosed contract's contents conform to on-ledger agreements between the stakeholders (or trusted parties) involved.
juliuswilliam-da marked this conversation as resolved.
Show resolved Hide resolved

In the above example, ``IOU`` contracts between **Buyer** and **Issuer** (a trusted party on the ledger) ensure that the exercising of the ``Offer_Accept`` choice using disclosed contract results in a contractually agreed-upon outcome.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In the above example, ``IOU`` contracts between **Buyer** and **Issuer** (a trusted party on the ledger) ensure that the exercising of the ``Offer_Accept`` choice using disclosed contract results in a contractually agreed-upon outcome.
In the above example, ``IOU`` contracts between _Buyer_ and _Issuer_ (a trusted party on the ledger) ensure that the exercising of the ``Offer_Accept`` choice using the disclosed contract results in a contractually agreed-upon outcome.


This works by performing several safety checks in the ``IOU_Transfer`` choice within the ``IOU`` contract, which is called from the ``Offer_Accept`` choice.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This works by performing several safety checks in the ``IOU_Transfer`` choice within the ``IOU`` contract, which is called from the ``Offer_Accept`` choice.
This works by having the ``Offer_Accept`` choice invoke the ``IOU_Transfer`` choice, which performs several safety checks within itself, as part of the ``IOU`` contract.


The ``IOU`` contract provides several safeguards in the ``Offer_Accept`` workflow:

- **Buyer** exercising the ``Offer_Accept`` choice is defined on the ``IOU`` agreement.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **Buyer** exercising the ``Offer_Accept`` choice is defined on the ``IOU`` agreement.
- _Buyer_ exercising the ``Offer_Accept`` choice is defined on the ``IOU`` agreement.

- Creation of an IOU with an same amount for the **Seller** happens atomically with a deduction of the same amount from the **Buyer'** IOU.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Creation of an IOU with an same amount for the **Seller** happens atomically with a deduction of the same amount from the **Buyer'** IOU.
- Creation of an IOU with an same amount for the _Seller_ happens atomically with a deduction of the same amount from the _Buyer_'s IOU.

- **Buyer** cannot be deducted and **Seller** cannot receive more than the stipulated value on the ``IOU`` contract.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **Buyer** cannot be deducted and **Seller** cannot receive more than the stipulated value on the ``IOU`` contract.
- _Buyer_ cannot be deducted and _Seller_ cannot receive more than the stipulated value on the ``IOU`` contract.


By ensuring the **Buyer** party expected to execute the ``Offer_Accept`` choice, a trusted **Issuer** party and required terms of execution are clearly defined on an on-ledger multi-signatory ``IOU`` contract, the **Seller** can disclose the ``Offer`` contract and the **Buyer** can execute the ``Offer_Accept`` choice on the disclosed ``Offer`` contract knowing workflow safety is ensured.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
By ensuring the **Buyer** party expected to execute the ``Offer_Accept`` choice, a trusted **Issuer** party and required terms of execution are clearly defined on an on-ledger multi-signatory ``IOU`` contract, the **Seller** can disclose the ``Offer`` contract and the **Buyer** can execute the ``Offer_Accept`` choice on the disclosed ``Offer`` contract knowing workflow safety is ensured.
By ensuring the _Buyer_ party expected to execute the ``Offer_Accept`` choice, a trusted _Issuer_ party and required terms of execution are clearly defined on an on-ledger multi-signatory ``IOU`` contract, the _Seller_ can disclose the ``Offer`` contract and the _Buyer_ can execute the ``Offer_Accept`` choice on the disclosed ``Offer`` contract knowing workflow safety is ensured.


If disclosed contracts contain malicious data or are maliciously executed on, the safeguards will prevent unexpected outcomes outside the bounds of the agreement stated on the ``IOU`` contract from resolving.
juliuswilliam-da marked this conversation as resolved.
Show resolved Hide resolved

Generic variants of the discussed safeguards should be implemented when utilizing explicitly disclosed contracts to ensure workflow safety.