Lesson 2: Design, Consequences, and Visibility

Captions as YouTube publishes them, usually machine-generated, so names such as Daml and Canton can be misheard.

1. 0:06

   in this lesson we will continue to examine key questions when representing a business workflow in daml in particular we will be looking at how daml represents the consequences of decisions as well as how it manages visibility and privacy of both decisions and their consequences when we reconsider business workflows from first principles we see that consists of a number of events that are the result of people making

2. 0:35

   decisions that have consequences that are observed by people authorizing them to make more decisions resulting in more events events people's decisions consequences observation authorization these are the fundamental building blocks of a distributed workflow and at the center of them is making decisions so at the center of each workflow is a loop Loop of people decisions and consequences hopefully continuing until it reaches a desired

3. 1:06

   goal a distributed workflow is one where the decisions being made and their consequences are no longer neatly confined to a single person team or organization instead they require coordination verification and rules so as we design a daml workflow we focus on understanding the decisions that make up the workf flow analyzing each decision we will keep coming back to the same set

4. 1:34

   of key questions to characterize and understand them what was the decision who made the decision what was their role in making this decision who authorize them to make the decision what are the consequences of the decision who has a right to be notified of the decision and who needs to be notified of the consequences of the decision it can be tempt in to immediately jump to questions about static data fields records and in a non-distributed system these can be

5. 2:08

   useful ways to structure our analysis however with distributed workflows this is a trap workflows are fundamentally Dynamic it is important to start by understanding the dynamic activities first it is the structure of these actions what they are and who is performing them that needs to structure your analysis in design only once you understand that structure can you consider the static targets of those activities the things being acted upon part of the power of daml is that it

6. 2:40

   provides first class representation for each of these Concepts what we have so far is a wave answer the questions what was the decision who made the decision and who authorized the decision in daml potential decisions become choices on active contracts and making a decision is represented by exercising one of those choices similarly that exercise is the result of a command submitted by a user acting as a party so the answer to who made the decision is represented by

7. 3:14

   that controller party finally the authorization to make the decision is associated with the active contract itself a contract can only exist if it has been signed by a set of parties who become the signatories of that contract contract the choices enabled by a contract are authorized by those signatories so the question who authorized the decision is represented in daml by the signatories on the contract the choice was exercised on we

8. 3:45

   see that several Core Concepts in daml are directly associated with representing decisions the exercise of a choice the controller party and the signatory parties we have answers for the first four questions so now we will look at the last three we should expect that in a business workflow the goal may include physical consequences one example might be there is now 80 tons of grade A tops soil at the Baker Street construction site of course as a digital information system

9. 4:19

   we don't deal with physical items directly we act a step removed from such things dealing only with claims and assertions with the information about the physical item so in daml our focus is reaching and recording consensus on facts specifically agreement on the current state of the business or on future obligations so our example becomes everyone agrees there is now 80 tons of grade A tops oil at the Baker Street construction site so we can go ahead and

10. 4:52

    pay for it now so in a daml system the consequences of a decision or Choice are one or more of the the following the authorizers and the decision maker in daml terms that means the signatories and controller jointly authorize someone to make a future decision jointly agree between them that a new fact is true and jointly agree between them that a previously agreed fact is no longer true now if we consider our Landscaping example we have Alice acting for acne

11. 5:27

    construction accepts an offer by Bob Bob is acting for Lando's landscaping supplies to sell 80 tons of grade a top soil for $22,000 the top soil is to be delivered to the Baker Street construction site when we break this down we have the decision maker which is the user Alice when Alice accepted the offer the role in making the decision Alice was acting as which is the party Acme Construction in the role of purchaser authorization

12. 5:59

    to make decision Alice was authorized to accept or reject the offer when it was made by the user of Bob and the role that authorized this decision Bob was acting as the party Lando landscaping supplies in the role of supplier of course we have to consider the consequences which include Acme construction and Lando's landscaping supplies agree to the sale of 80 tons of grade A tops oil for $2,000 they also agree that Lando's Landscaping

13. 6:32

    will deliver 80 tons of grade a top oil to Baker Street and AC construction agrees to transfer $2,000 to Lando's landscaping supplies if we were focused on the static data associated with the workflow the Temptation would be to stop here we might think we have our record surely we can just store it in a database somewhere and we are done but but stop and consider this in terms of decisions and it becomes clear we haven't yet identified any new decisions

14. 7:07

    authorized by this decision and without new decisions the workflow stalls here when we reconsider the consequences in terms of decisions we can flesh out the workflow there is still the base agreement the contract of sale AC construction and Lando's landscaping supplies agree to the sale of 80 tons of GR top soil for $2,000 but from the perspective of a damel workflow this isn't the really interesting bit what is interesting is

15. 7:39

    who is authorized to attest to the delivery of the top soil when it eventually happens and who is authorized to accept and acknowledge delivery of the tops soil when it is received these are questions about trust authorization and the critical decisions people need to make decisions that when represented explicitly like this could automatically authorize the transfer of $2,000 to

16. 8:05

    settle the account now we have an interesting distributed workflow by thinking in terms of decisions and actions we keep front of mind that someone has to be authorized to attest to what has happened in the external World moreover that the act of attestation is itself a decision as a multi-party business workflow we are no longer in a single day a silo with shared trust where the two parties can rely on shared policies or appeal to a

17. 8:35

    common manager to resolve disagreements if we need to know about the state of the world we need to identify who each relevant party trusts and authorize them explicitly to attest to this amme and Lando have a business relationship but to automate the workflow they need more than a handshake to validate and guarantee the rules of their agreement men are followed correctly this is where daml comes in in daml exercising the choice on an active contract results in a transaction on the

18. 9:09

    distributed Ledger the process of successfully writing the transaction to The Ledger involves providing a guarantee that every stakeholder to the transaction has complied with the rules has had a chance to verify this for themselves and has agreed that the rules were followed without going into too much detail a deml transaction contains the exercise Which choice was exercised

19. 9:35

    on which contract by which party new active contracts that were created as a result of the choice previously active contracts now inactive as a result of the choice we call this archiving the contract so returning to the question what are the consequences in daml all of the consequences we discussed end up being represented by the contents of the transaction so by the creation of a new contract or the archiving of an old one fortunately because contracts come

20. 10:08

    bundled with choices this is enough to represent everything we need we mentioned there were three consequences to consider in damel first the authorizers and the decision maker conjointly authorize someone to make a future decision in daml this is represented by some subset of the signatories and the controller becoming signatories on a newly created contract where the authorized party is a controller on a choice also the

21. 10:38

    authorizers and the decision maker can agree between them to attest that a new fact is true in daml this is represented by some subset of the signatories and the controller becoming signatories on a newly created contract that represents a statement of fact also the authorizers and the decision makers can agree between them that a previously attested fact is no longer true in daml this is represented by some subset of the signatories and the controller jointly

22. 11:09

    archiving The active contract that represented the old statement of fact and so we find two more Core Concepts in daml directly associated with representing decisions creating contracts And archiving contracts ultimately even when dealing with facts it is rarely the fact itself that is important at the very least when recording a fact we have to consider who has the authority to retract or alter that record this is an example of

23. 11:40

    something that is often ignored or handwaved away in centralized applications in a distributed multi-party workflow it is of vital importance to consider who has to agree about a fact and under what circumstances can someone change that record ultimately all consequences end up being about enabling future decisions even in the case of recording a simple fact we are still faced with defining how that record can be legitimately changed or retracted the consequences of

24. 12:12

    a decision in daml are the creation of a contract that now authorizes a choice be made in the future or the archive of a contract that retracts a previously authorized choice in a traditional business system built on a traditional database creating or archiving a contract would instead be inserting or deleting a record our Focus would then be on the data being updated or deleted in a daml system the insertion or deletion of data on The Ledger is a

25. 12:45

    secondary concern what really matters is who authorized the update and what future decisions have been authorized or deauthorized as a result so we can now answer how to represent SE several daml constructs an available decision this is a choice on an active contract a decision being made this is an exercise on an active contract the authorization required to make a decision these are the signatories on a contract and the consequences of the decision contracts

26. 13:20

    are created and archived we are now left with the final question who needs to be informed in a traditional system we would probably talk about read permissions or access controls but these presume a mutually trusted mediator who can enforce these policies however these are distributed workflows and a critical distinction that characterizes them is that there is no one who can provide this so instead of permissions or controls we have to

27. 13:51

    think in terms of privacy rather than who has permission to access instead pose the question who gets to be informed at all authorization and privacy are two of the most difficult problems to solve in any distributed system fortunately distributed workflows are Dam's reason to exist and we have just seen how it handles authorization it should come as no surprise then that D is also a powerful tool for handling the Privacy aspects of

28. 14:22

    a workflow daml specifies a strict need to no approach to privacy privacy is a complicated and subtle problem to solve and the precise specifics of what the DL Ledger provides and how it operates are commensurately complex we recommend that your senior technical staff review the detailed Ledger model documentation available online for the purposes of analyzing and describing workflows though the general

29. 14:53

    privacy principles suffice the fundamental requirements and resulting principes principles follow four intuitive rules this is a multi-party system and so a delegation of authority maybe between organizations in other words it may cross a trust boundary when this happens it is not good enough to deploy rules in someone else's Software System and trust their system to enforce them as we have seen one of daml strengths is its flexibility in modeling delegated authority so the

30. 15:27

    use of an authorization will often be by a delegated agent in another organization furthermore that delegated decision May mean authorizing a third party to contribute to the workflow in some way and with everyone involved belonging to different organizations therefore it is necessary for a party that grants an authority to be able to observe the use of that Authority and verify that its subsequent use or further delegation is correct and within any limits and conditions set

31. 15:59

    upon the initial Grant to achieve this a party needs to know how its Authority is used and to verify it is used within the parameters they specified a complement to this is when some decision revokes an authorization this can be as simple as revoking a permission previously granted or more complicated such as making a mutually exclusive offer to multiple parties that is only valid for the first to act in this latter case case I might make the offer but I am not the one who

32. 16:31

    revokes it instead it will be implicitly revoked for all Parties by the first party to take up the offer who will often be in a different organization from me it is clear that regardless of how it was ultimately granted and revoked I have a need to know that these authorization changes were valid and correct therefore a party granting an authority to act must have the right to verify that the grant was revoked vly there are often parties who have an

33. 17:01

    explicit need to know about an authorization an obvious example is the recipient of the authorization however this could also be a notary a regulator a market operator or just another party with an acknowledged interest in knowing what has happened of course this may cross a trust boundary in some cases it is required that they be in a different organization so they also require not only a right to be informed but a right to verify what happens therefore along

34. 17:34

    with the previously discussed parties who have an implicit need to know a party may be granted an explicit right to be informed and verify a grant of authority to act and any eventual revocation of that right finally there can be an explicit right to observe the specific use of an authorization for example if a client has been granted the right to conduct trades via a master Services agreement an auditor or regulator probably needs

35. 18:04

    the right to observe not only the authorizing MSA but also each individual use of this right and so this will need to be included in the model explicitly therefore a party may be granted an explicit right to be informed of a specific decision should it be made daml supports these four need to know principles using the concepts we have already already looked at signatories contracts choices and one New Concept observers let's look at how each of

36. 18:36

    these principles is modeled in daml you have a need to know how any Grant is used a party needs to know how its Authority is used and to verify it is used within the parameters they specified in daml this means that all signatories are always informed of the full details of any contract they are a sign signatory to and the full details of any choice exercised on that contract you have a need to know about any revocation a party granting an

37. 19:09

    authority to act must have the right to verify that the grant was revoked validly in daml this means that all signatories are always informed of the full details of any Archive of a contract explicit stakeholders have a need to know about the authorization a party May may be granted an explicit right to be informed and verify a grant of authority to act and any eventual revocation of that right in daml this means a party may be

38. 19:40

    designated a contract Observer granting an explicit right to be informed and verify the creation and archival of the contract explicit informes have a need to know about a decision a party may be granted an explicit right to be informed of a specific decision should it be made in daml this means a party may be designated a choice Observer granting an explicit right to be informed of any exercise of the choice the specifics of how to specify these in a daml model are

39. 20:15

    covered in the contract developer course when analyzing a workflow we just need to keep three things in mind signatories see everything that happens with a contract as they have a need to know of their authorization Grant every use of that authorization and the details of its eventual revocation Choice observers see everything about a specific Choice when it is exercised as this makes them an explicit inform me of any exercise of the choice contract observers see the

40. 20:49

    creation and everything about the archival of a contract as they have been made an explicit stakeholder in the authorization Grant represented by the contract now we have all the pieces to represent decisions and the workflows they drive in daml an available decision through a choice on an active contract a decision being made by an exercise on an active contract the authorization required to make a decision which are the signatories on a contract the

41. 21:21

    consequences of the decision represented by the creation and archival of contracts where contracts are created that authorize new choices by new controllers or assert an authorized consensus on the state of the business and contracts are archived that revoke authorization for choices by their controllers or reflect a change in that consensus finally we can recognize who will be informed specifically signatories on the contract

42. 21:52

    on which the choice was exercised parties explicitly nominated to be informed of the exercise of a choice and parties explicitly nominated to be informed of creation or archiving of the contracts affected by the choice returning to our original objective to design a workflow we now have the foundations for doing so in daml we start by identifying a key decision in the workflow this decision becomes a choice then we determine who made the

43. 22:25

    decision and what role were they fulfilling these become a user and the controller party respectively this choice will exist on a contract so once we determine who authorized the decision we know who signed the contract within the contract and the choice the controller and the signatories will be parties representing the role they fulfill in the workflow next we look at consequences making sure we identify what decisions are enabled

44. 22:54

    or become authorized by this decision each of these will become their own choices with their own authorization and their own consequences we also identify what has changed about the party's understanding of the state of the business as a result of the decision this will eventually need to be reflected as contracts to be archived and created finally we make a note of any additional parties that have a need or right to be informed of either the decision or any of its

45. 23:25

    consequences answering these questions provides us with a comprehensive understanding of this key decision which leaves only one final question to answer what was the previous decision that enabled or authorized this one this decision becomes a preceding choice in the workflow and so we will repeat our analysis for this new choice and every other choice we discover through the process if we continue repeating this process of the workflow until we can

46. 23:55

    find no more decisions left to analyze then we will be left with a comprehensive understanding of the entire workflow importantly this analysis will include the extra detail required to capture the distributed requirements of a multi-party business workflow and does so in a way that will allow you to take full advantage of the daml platform