Lesson 5: Upgrade Contract Pattern

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

1. 0:00

   when making changes to a demo application you should first try to make the change by adding new templates instead of modifying the old ones however there are situations where you cannot avoid making changes to an old template this lesson covers how to make changes to existing templates in a way that preserves all authorization guarantees and gives a systematic way to perform the upgrade to do this you will learn about the upgrade contract pattern here is a scenario where there is a package

2. 0:32

   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 choice proposed transfer 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 proposal is the same as that of the position the

3. 1:04

   new owner is one of The Observers added to the list of observers of the position it has two choices except in cancel if accepted the position will be transferred to the new owner here is the workflow in this scenario the owner of a position 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 transferred to the new owner

4. 1:37

   here is the code the position template has a proposed transfer choice the transfer Proposal with two choices except by the new owner and cancel by the owner using these two templates you can use a script to simulate an initial state of The Ledger here are two data records to create test parties and test users test parties has P bank P Alice and p-bob test users has their corresponding user IDs Eubank

5. 2:09

   ulice and ubob the script init parties allocates test parties and initucers Maps test users to their respective parties finally in the init cash script you create a position payload with p-bank as the issuer as well as the owner and quantity as one with this payload the bank creates a transfer proposal to transfer five positions to Alice and three positions to Bob once Alice and Bob accept these proposals they have the positions in

6. 2:42

   their accounts when you run this script you get a starting state of The Ledger with all transfer proposals archived and an active contract set of five positions for Alice and three for Bob now assume that the bank wants to add a field called currency to the position template you know that you cannot just go ahead and change the position template code without obtaining approval from all the parties involved in the contract to make sure that you take appropriate

7. 3:13

   approvals in a systematic manner from the parties involved in a template you can express the upgrade itself as a contract to which all parties must agree this provides a mechanism to let the parties know that this is an upgrade and gives them an opportunity to accept or reject it this approach is called the upgrade contract pattern this is based on the proposed accept pattern that you may be familiar with the key idea is that the issuer proposes

8. 3:44

   the upgrade to the position owners through an upgrade proposal this template has an accept a grade choice that must be accepted by the counterparty when the counterparty accepts this Choice an upgrader is created that has the Run upgrade Choice which the issuer can now exercise the Run upgrade choice will then archive the old positions and create new positions according to the new position

9. 4:10

   template in the upgrade 3 package the workflow in a script would go something like this for each of the owners say Alice and Bob the bank creates upgrade proposals Alice and Bob then exercised the accept upgrade Choice which creates their upgrader contracts in the example you have just two owners with a handful of positions in a real world application there may be thousands of owners with millions of positions so these upgrader contracts need to be

10. 4:43

    batched together to optimize upgrade performance at a conceptual level the bank will submit these upgraders which will fetch the old positions to extract the payload archive the old positions and then create new positions let us look at the code first create a separate package where you write the new template code here you have the upgrade 3 package inside that is the currency module with the new position template which has a currency field

11. 5:14

    this template replaces the old position template in the initial State package shown earlier next there is the upgrade module in upgrade package where the old cache positions are imported also you need the new currency module that will have the new positions the upgrade proposal has just one choice accept upgrade which creates the upgrader in the upgrader template there is a non-consuming choice called run upgrade which takes a list of position C IDs as

12. 5:47

    an input parameter for each of these positions it extracts the payload by using the fetch function then archives the old position it then uses the payload to create a new position record with currency as US dollar with the rest of the fields remaining the same as in the old position let us test these in a script in this test upgrade script start by running the in a cache script to bring

13. 6:14

    the ledger to a certain state then the bank proposes the upgrade to Alice and Bob one by one Alice and Bob accept the proposal which creates their upgrades then the bank queries for all the upgrades for each upgrader it fetches all the positions of the counterparty in that upgrader and extracts the old position C IDs finally the bake exercises the Run upgrade Choice passing the position C IDs when you run this script all the

14. 6:46

    positions in initial State package are archived and new positions in upgrade 3 package are created that have currency as their new field this example demonstrates how to change a template using the upgrade contract pattern let us summarize the upgrade contract pattern provides a way to change existing templates without breaking the authorization guarantees instead of treating a change to a template as just a software update it

15. 7:15

    treats upgrade itself as a contract to which all concerned parties must agree in this pattern there is an upgrade Proposal with a choice to accept proposal for the concerned parties when a party accepts The Proposal an operator contract is created that has a run-up rate choice that is then exercised by the party making the changes