Lesson 4: Daml Application Upgrades

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

1. 0:00

   since a daml application runs on a distributed Ledger and each template represents a contractual multi-party agreement upgrading daml apps is different from how other software applications are upgraded this lesson will cover two simple types of upgrades in a daml application along with some techniques and best practices to perform those upgrades this lesson is a precursor to more advanced forms of upgrades that will be discussed in

2. 0:29

   lessons that follow follow let us take a scenario where there is a package named initial state that has a module named cache it has two templates the position template has issuer and owner as two signatories and observers as a list of parties it has a proposed transfer Choice which Returns the contract ID of a transfer proposal the transfer proposal template has a copy of the position for which the transfer has been proposed the signatory of the transfer

3. 1:01

   proposal is the same as that of the position the new owner is one of The Observers added to the list of observers of the position it has two choices accept and cancel if accepted the position will be transferred to the new owner the workflow is fairly simple the owner exercises the proposed transfer Choice which creates a transfer proposal at this point the owner can cancel the proposal or the new owner can accept the proposal in which case the position is

4. 1:34

   transferred to the new owner here is the code it has a package named initial state that has a module cache the cach module has two templates position and transfer proposal position has a proposed transfer Choice transfer proposal has two choices accept and cancel using these templates let us write a script that will play out a scenario where a bank proposes a transfer of cash positions to Alice and Bob and they accept the proposal to get

5. 2:08

   those positions write your script in the initial State package set up test parties and test users where pbank P Alice and P Bob are the parties and Ubank U Alice and ubob are the users the init party script allocates parties and init users script creates users and Maps them to their parties in this code you have a helper function called make user that takes an ID a party and user rights as input it then creates a user with

6. 2:41

   that ID and Returns the validated user ID then it Maps each of the users to the parties so Ubank is mapped to pbank U Alis is mapped to Pal Alis and ubob is mapped to peob once you have these users set up you can now create an initial set of positions for Alice and Bob for that run the in aach script where you initialize the parties and the users then create a position record with pbank as the owner as well as the issuer then have the bank create five

7. 3:17

   transfer proposals for Alice and three positions for Bob note the use of the replicate function which performs the subuser action five times for Alice and three times for Bob in a real world application these numbers will run into thousands or more but here they are small to demonstrate the concepts in The Next Step Alice and Bob accept their transfer proposals and get their positions the script Returns the parties and the users when you run

8. 3:49

   this script the transfer proposals created for Alice and Bob are archived and their positions are created as shown here this provides the initial state date of The Ledger now imagine that a new business requirement asks you to add know your customer or kyc information to the position template this means adding the owner's information such as owner's name address phone number and so on if you decide to add that information in the position template it would lead to

9. 4:21

   several problems first since a template represents a legal agreement any change to it must be approved by all its stakeholders to preserve its authorization guarantees second the new agreement overrides the old agreement this means you need to archive all the old positions and recreate them according to the new template if the issuer is a bank its owners and their positions may run into millions so that does not sound like a practical approach instead you

10. 4:54

    could add a new template called kyc in a separate package called upgrade one this template has the issuer and the counterparty whose kyc information is required this way while you do need agreement from the position owners you do not have to change the old positions which minimizes disruption here is a kyc script in the upgrade one package in this script you first run the in aache script to bring the ledger to the initial state which is

11. 5:25

    the starting point then the bank submits the creation of a kyc contract for each of the parties one by one this script only shows the creation of a kyc contract for Alice as an example this is a good technique to add a new type of data about a party without having to change any existing templates let us now think of another type of change required in this scenario say that you want position owners to be able to add observers to their positions this means

12. 5:59

    you must create a choice such as set observers and then have the owners add new observers to their positions an inefficient approach would be to get agreement from all the stakeholders to change the position template archive the old positions and recreate them using the new template a better solution is to create a new template such as additional rules in which you can add a non-consuming choice set ofs servers a position owner can exercise the choice

13. 6:30

    to add new observers as shown here the choice checks if the owner and the issuer for the position being updated match as that of the position passed to the choice if yes then the old position is archived and a new position is created with a new Observer list now let us play out the scenario using a script assume that Alice wants to make Bob an observer in all her positions in this ad Observer script the test said Observer script calls the in aach script to bring the

14. 7:03

    ledger to a certain starting State then you allocate a new party called P Bank Creer and Grant user rights for the users uis and ubob who can redas the P Bank Creer then the bank creates the new rules contract using the additional rules template now Alice and Bob can exercise the set Observer choice to add observers to their positions as shown here you first query for all Alice's positions then for each of those positions make peob an observer party

15. 7:38

    once again you did not have to make changes to any old templates so far this lesson covered how to add a new template called kyc and how to add new rules in terms of choices without modifying existing templates let us summarize the key ideas in this lesson upgrading a daml application is different from upgrading other types of applications because the authorization guarantees of a smart contract need to be maintained all concerned parties must

16. 8:11

    agree to the change contracts based on Old template need to be archived and new ones need to be created with the new template this requires that you should design your upgrades in such a way that you cause minimal changes to what already exists for example in the case of adding kyc data or a new choice for adding observers you added a new template with new data and choices instead of modifying the old

17. 8:58

    templates