This repo is outdated. It is kept online to avoid broken links, but it will no longer be updated. Please refer to the [current documentation](https://docs.daml.com) for instructions on how to upgrade DAML models post-1.0.
Copyright (c) 2019, Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
SPDX-License-Identifier: Apache-2.0When you create DAML contracts and templates for a business process or workflow, you may need to upgrade them when the process or workflow itself changes.
To help you understand how you might change a workflow, this page goes through an example of how to upgrade two templates (and the contracts on the ledger based on them).
In an upgrade like this, contracts on the ledger stay as they are, but are no longer active. New contract templates are used going forward, but only once accepted by the appropriate participants: where participants were signatories to the original contracts, they must approve changes before their contract can be upgraded.
In the example on this page, the Operator is an Derivatives Exchange operator. They want to change two aspects of their current model: their equity symbol contracts and their option type contracts.
For explanations of the terms used in the example, see In The Money.
Note: This example focuses on upgrading DAML templates and contracts, not on the processes that govern the derivatives market. The templates here are just small fragments of the actual DAML models used by the derivatives exchange and its clearing house participants.
- At the moment (V1)
The Operator maintains a list of equity symbols, which are the underlying instruments of the Stock Option it lists. They use exactly three characters for each equity symbol: for example, "XYZ" for The XYZ Company.
- What they want to change (V2)
Relax the three character constraint, and allow names that will range from three to five characters long.
- The DAML contracts
There is one equity symbol contract instance for each underlying symbol. The Operator is the only signatory to the contracts. The Operator discloses the contracts to all Participants: they are observers to all instances.
V1 equity symbol contracts enforce three characters for the symbol. V2 enforce between three and five characters.
- At the moment (V1)
The Operator lists the equity options (Puts and Calls) that trade on its exchange.
When an option contract reaches its expiration date, if it is in the money by more than 1.5% of the option's strike price, it is automatically exercised. 1.5% is a limit set by the exchange for all contracts and cannot be changed.
- What they want to change (V2)
Allow Participants to set their own exercise limit for each option type.
- The DAML contracts
Both the the Operator and the Participant are signatories on option type contracts. There is one contract instance per Participant, symbol and option type (put or call).
V2 option type templates have the option exercise limit as an extra field (not present in V1). They give a choice to the Participant to change the default value of 1.5% to a limit they choose.
To upgrade all the V1 contracts to V2 contracts, the Operator needs to create an upgrade process using DAML templates. The upgrade process introduces the new DAML templates and migrates the existing active contract set to the new one.
The process must:
- upgrade the Operator itself
- upgrade each Participant independently
- be able to roll back in case it is deemed necessary by the Operator
- maintain a continuous service
- achieve consistency across the distributed network
Note: As the ledger construct is immutable and append-only, the ledger is not actually "rolled back" or "unwound". Instead, the contracts are just "downgraded" to their previous version, by creating new instances that preserve the initial data.
The Operator needs three sets of templates for the upgrade:
- The V1 Templates
The DAML templates currently being used by the Operator and the Participants. In subfolder V1.
- The V2 Templates
The DAML templates to use after the upgrade process completes. In subfolder V2.
- The Upgrade Templates
In subfolder Upgrade. These are:
- A Master Upgrade template
This is owned by the Operator. It's used to orchestrate the upgrade (or rollback).
- A Participant Upgrade template
For contracts where the Participant is a signatory, this allows Participates to delegate the right to the Operator to upgrade (or rollback) contracts.
- Upgrade and Rollback templates
These describe the transition of each V1 template to V2, and V2 back to V1.
The V1 and V2 Templates are independent of each other. The Upgrade Templates reference both V1 and V2.
This page only covers the design and implementation of the Upgrade Templates, and the process which upgrades the existing contracts.
It does not cover the process of rolling templates out to ledgers, but here is a brief discussion of this process.
Most of the upgrade process does not need to happen simultaneously for all Participants. Only one process does: upgrading active contract instances of affected workflows to the new template version.
This means V1 and V2 contract instances will co-exist on the ledger, until everything has been upgraded to V2 and all V1 instances have been archived. The templates carrying out the upgrade will also be active on the ledger; they can be created and archived on an ad-hoc basis.
Upgrading business logic on distributed systems is a non-trivial task. When a distributed DAML-based system is upgraded, the changes that affect the communication protocol between the nodes (the GSL) and the content of that communication (Core Transactions and DAML) require coordination between participants.
This section explains the DAML templates in the code for this example. Each template to be upgraded has two versions: V1 and V2
The EquitySymbol (V1) and EquitySymbol (V2) templates contains the upgrade for information about the underlying symbol. They are issued by the Operator and disclosed to Participants using the observer mechanism. They use the ensure precondition to enforce the character limit.
The OptionType (V1) and OptionType (V2) templates contains the upgrade for information about options. It is an agreement between the Operator and a Participant. V2 has a new Decimal field exerciseLimit : Decimal and a new choice ChangeExerciseLimit with newExerciseLimit : Decimal given to the Participant.
These upgrade templates contain the rules of how to upgrade EquitySymbol and OptionType contract instances from V1 to V2. Each of these is done by a separate template instance: UpgradeSymbol, and UpgradeOptionType
The signatories of these contracts match the signatories of the contracts that they are upgrading. They are created by the Operator, and have an choice. The non-consuming Upgrade choice acts as a converter, taking a V1 contract instance and returns a V2 instance. Specifically, it:
- Fetches the data from V1.
- Archives V1.
- Creates a V2 instance with that same data.
Once all contracts of V1 are passed through the Upgrade choice, the Operator can then archive the Upgrade contract.
OptionType 's new exerciseLimit field is initialized with the presetExerciseLimit of 1.5% by this choice.
The process described above also applies for rolling back. Just like UpgradeSymbol and UpgradeOptionType, the corresponding RollbackSymbol and RollbackOptionType have a Rollback non-consuming choice, that accepts an instance of V2, fetches its data, archives it and yields a V1 version.
The Master upgrade contract is created and owned by the Operator. It is responsible for orchestrating the upgrade process, and executing batch upgrades to operator-only owned contracts (such as EquitySymbol instances).
The master upgrade contract cannot be used to batch upgrade contracts where the Participant is a signatory. The Operator cannot force Participants into contracts or change the templates that parties have agreed to.
Instead, it must obtain their prior consent. In this case, it uses the RequestParticipantUpgrade choice to invite Participants to delegate their right to an upgrade. This leads to the creation of a ParticipantUpgradeRequest contract instance which allows the Participant to authorizes the Operator to update by an Accept choice on that contract.
Choices to the MasterUpgrade contract are non-consuming: they can be executed multiple times. The Operator can choose the "batch size" - how many instances of EquitySymbol contracts are added to a list - depending on the number of the contract instances to be converted. This is passed as an argument to the choice that upgrades them (or rolls them back).
The ParticipantUpgrade contract instance authorizes the Operator to perform an upgrade (or rollback) to the OptionType contract instances where the Participant is a signatory. The equivalent batching paradigm applies here as well.
When rolling back, there may be instances of the EquitySymbol and OptionType templates which reference symbols of more than three characters. These symbols are not valid in V1.
If you try to roll back a EquitySymbol contract which is not compatible with V1, a SymbolRollbackConflict is created. This contract preserves the original data and allows the Operator to resolve the conflict. It can either ResolveConflict with symbol : Text (specifying a valid symbol name) or Archive the data. The OptionTypeRollbackConflict takes a similar approach.
These DAML templates are not instrumental to the upgrade process: they are here to make this example work. They create the contract instances that will be converted during the upgrade workflow, and demonstrate that the upgrade has taken place.
The Operator template contract is used by the Operator to create new EquitySymbol instances using the RegisterSymbol choice. The Operator may also exercise the OnboardClearingParticipant choice to yield a ClearingParticipantInvitation instance.
Since the Operator template references the EquitySymbol template (which gets upgraded to V2), the Operator template also needs upgrading. That way, after the upgrade completes, the Operator will be able to register symbols of the V2 EquitySymbol template.
When a Participant accepts a CleringParticipantInvitation, it generates the set of OptionType contracts for that Participant. Although you could, there is no need to provision for upgrading instances of the ClearingParticipantInvitation templates:
Contracts of this template are likely to be short lived, because they are used for the sole purpose of onboarding a Participant to the exchange. Before an upgrade takes place, the Operator can simply archive any outstanding instances of ClearingParticipantInvitation that have not been Accepted.
UpgradeExample.daml includes a scenario for an end-to-end upgrade and rollback workflow between the Operator and two Participants.
- Set Up Parties: The DAML Parties that will be involved in the workflow are given names and created
- Set Up Demo Data: DemoData.daml includes the sample data used in the workflow:
- Onboard Participants: The Operator creates a role contract and registers symbols. Then they onboard the two Participants.
- Upgrade to V2: The setup is now operating in version V1. To transition to V2, the Operator commences the upgrade workflow
- Verify the Upgrade: All contracts are now upgraded to V2. This step checks:
- if the Operator can register a symbol that is four characters long
- if a Participant can change the exercise limit
- Roll Back: The previous step verified that the setup is now on V2. The Operator now tries rolling back the system to V1.
- The Operator doesn't need a confirmation from each Participant in order to roll back: they already gave this authorization to the Operator by accepting the
ParticipantUpgradeRequest. - Since the Operator has registered the "ACME" symbol (which cannot exist in V1 because it contains four characters), there will be a conflict. This step resolves the conflict by providing a three character version of the symbol ("ACM").
- Verify the Rollback: All contracts are now rolled back. This step checks:
- the Operator can no longer register a symbol that does not contain three characters
- the new "ACM"
EquitySymbolcontains all information from its V2 counterpart other than the symbol name
This example takes place in the derivatives trading realm.
The parties in the example are:
- The Operator
One equity derivatives exchange operator.
- The Participants
Multiple options clearing houses that are participants to the exchange.
A derivatives exchange is an organization that provides a central marketplace where derivative contracts, such as stock options, trade.
An options clearing house is an organization that acts as an intermediary between buyers and sellers of options contracts on a derivatives exchange.
The clearing house will take the opposite position of each side of a trade. The purpose of this is to improve the efficiency of the markets and add stability to the financial system.
An equity derivative is a financial instrument. Its value is derived from the price movements of an underlying equity.
For example, a stock option contract (see below) is an equity derivative because its value is determined by the price movements of the underlying stock.
A stock option is an equity derivative that gives the buyer the right, but not the obligation, to buy or sell the underlying stock at an agreed upon price (the strike price). The buyer can exercise this right at most once within a certain period of time (until the expiration date).
This example has two types of stock options:
- A call option
This gives the buyer the right to buy a stock at the strike price (before the expiration).
- A put option
This gives the buyer the right to sell a stock at the strike price (before the expiration).
Being in the money means that it may worthwhile for the buyer to exercise (make use of their right) the option.
- For a call option
Being in the money means that the price of the option's underlying asset is above the call option's strike price.
- For a put option
Being in the money means that the price of the option's underlying asset is below the put option's strike price.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent