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

[juliuswilliam-da]

This proposed section aims to convey the importance of workflow safeguards when working with ECD and reminds the user to include variants of these safeguards when working with ECD.

It specifically calls out the inclusion of workflow safeguards included in the ECD example code and why they are important.

[cathyjung-da]

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.

[juliuswilliam-da]

@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?

[cathyjung-da]

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.

[cathyjung-da]

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.

[cathyjung-da]

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.

[cathyjung-da]

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.

[cathyjung-da]

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.

[tudor-da]

@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?

[juliuswilliam-da]

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

[tudor-da]

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).

[juliuswilliam-da]

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

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

[tudor-da]

IOU is not multi-signatory, is it?

[tudor-da]

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

[juliuswilliam-da]

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)

[juliuswilliam-da]

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.

[tudor-da]

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.

[juliuswilliam-da]

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?

[dylant-da]

All of my issues are covered by prior reviews

[juliuswilliam-da]

Closed and replaced with #787, which has been merged.