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

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.
- Creation of an IOU with the same amount for the *Seller* happens atomically with a deduction of the same amount from the *Buyer'* IOU.
- *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 ``IOU`` contract with a trusted *Issuer* party as a signatory, 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.
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.

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.
- Creation of an IOU with the same amount for the *Seller* happens atomically with a deduction of the same amount from the *Buyer'* IOU.
- *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 trusted on-ledger ``IOU`` contract with a trusted *Issuer* party as a signatory, 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.