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 4 commits
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. This ensures that workflows executed based on the disclosed contract's contents conform to on-ledger agreements between the stakeholders (or trusted parties) involved.
Copy link
Contributor

Choose a reason for hiding this comment

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

@juliuswilliam-da We might need to adapt the wording here. Usage of contracts noun here is slightly confusing. Are you referring to the actual Daml contracts that are instances of Daml templates that are stored on ledger? Or to preconditions for executing choices?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Good point, I am referring to the contracts noun here.
What would be the correct terminology for contracts in public-facing content?


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 prevent unexpected outcomes.
Copy link
Contributor

Choose a reason for hiding this comment

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

I think there is some confusion wrt disclosed contracts and its contents. They cannot contain malicious data, or not malicious in the tampered-with sense. If a created_event_blob (in essence, the disclosed contract payload) has been tampered with after being shared off-ledger, the Canton participant node will reject it. It does so by using a special mechanism, called contract authentication and is specifically designed to disallow malicious modification.

Having said so, probably this is something worth clarifying in this document then. I can try to add a section on the security of a contract's contents.

Note: An explicitly disclosed contract is nothing more than an authenticated off-ledger representation of a contract ALREADY stored on the ledger. The necessity of such an off-ledger representation is probably more a technicality made to ensure that non-stakeholders can use in their command submissions contracts that they did not see ON-LEDGER before (and that neither their participants saw). If you are curious about more details of this, we can arrange a call so we could clarify how this documentation can be improved.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Thanks for the clarification Tudor.
I'm aware of the fact that disclosed contracts still provide sufficient security which includes tamper protection.

The scenario i'm thinking of is when a malicious user legitimately creates a contract and provides it to another user to exercise on with malicious intention.

e.g a PaymentRequest contract is created legitimately by a malicious party Alice. It is then provided off-ledger to party Bob under the guise of payment for a service which was provided.
Because Bob cannot see the contents of the disclosed contract, he may unintentionally execute a payment which results in more funds than previously agreed upon for the service.

On-ledger business validation via other contracts such as a service agreement which Bob is a stakeholder on which defines the amount eligible to be paid for such a service would prevent such scenarios from occurring.

I can see this being more relevant to Daml development rather than ECD specifically, though I think it's more important with ECD due to the fact that controllers are unable to view the contents of the disclosed contract they are working with.
If there is already a section on business logic validation via other contracts, placing a link here with a reminder that the safeguards are important when working with ECD would be sufficient as well.

What do you think?


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. This ensures that workflows executed based on the disclosed contract's contents conform to on-ledger agreements between the stakeholders (or trusted parties) involved.

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 prevent unexpected outcomes.

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