{"id":"sX9G4re8GaI","title":"Lesson 5: Upgrading Daml Applications","description":"At the end of this lesson the learner will be able to design a Daml app while taking into account the considerations for upgradability. This includes the ability to:\nevaluate the challenges of upgrading a Daml solution.\nevaluate the recommended approach for upgrading Daml apps.\nengineer backwards compatible and incompatible upgrades of Daml models.\ndesign a testing and rollback strategy for upgrades to Daml apps.\n\nFor a better learning experience, sign up and enroll in this free course at: https://daml.talentlms.com/plus/catalog/courses/161","channel_name":"Digital Asset Training","published_at":"2025-02-19T00:00:00.000Z","thumbnail_url":"https://i.ytimg.com/vi/sX9G4re8GaI/hqdefault.jpg","transcript_text":"upgrading a daml app means rolling out new versions of its components to change existing workflows or to add new workflows to the daml app upgrades must provide data continuity in the sense that the App State before the upgrade and the workflows that were in Flight remain available and continue advancing after the upgrade in this lesson we're going to learn the recommended approach to upgrading various components of a DL app we will look at the challenges of upgrading DL apps then we will explore the recommended approach to upgrading a DL app then we will learn how to implement backwards compatible upgrades to DL workflows and what to do when preserving backwards compatibility is not possible then we will examine recommendations for testing and upgrade and finally we'll learn how to perform a roll back when an upgrade goes wrong the challenge with upgrading DL apps stem from the distributed nature of the apps and the fact that they're deployed across organizational boundaries these challenges include asynchronous rollouts in most cases the app users and the app provider cannot upgrade at the same time upgrades must be rolled out in an asynchronous fashion and allow app users and the app provider to follow their own schedule for when to deploy an upgraded component zero downtime upgrades some of the apps workflows may need to be able to progress Around the Clock these workflows need to be upgraded with zero downtime that is in a way that does not interrupt ongoing workflows the approach we present provides zero downtime upgrades by default mixed version deployments because of asynchronous rollouts the app needs to support some level of mixed version deployments with the approach that we presented is sufficient to only provide backwards compatibility of backends and front ends with the DAR workflows from the previously deployed version in a real world DL app front ends backends and DL models are likely to evolve at different pace at any given moment in time a daml app is likely to utilize different version numbers for various components of the app like a server that implements an API typically evolving faster than the API itself it's likely that the front ends and back ends will evolve faster than the DL models and will have a different versioning strategy the front ends and backends will then specify the minimum version of the DAR files they require for Simplicity in this lesson we're going to refer to the version number of all components of a currently deployed and operational DL app as version one and all components of a new version of the app as version two the recommended high level approach for upgrading demo apps can be described as an asynchronous roll out with a synchronous switch over once the app provider has implemented and tested the app components version two the app provider makes the version two components available to app users the app provider and the app users asynchronously roll out upgraded backends and front ends and audit upgraded Dar packages then the app provider publishes a taret tget upgrade date when they expect app users to have deployed the upgrade and when they expect to decommission version one close to the Target upgrade date the app provider and the app users upload the DAR files in a coordinated fashion so that the new workflows become available on Ledger synchronously as of the target upgrade date the app front ends and backends should be implemented to support both version one and two of the workflows this allows the app provider and app users to deploy your updates independently on their own schedule multiple versions of the components are expected to be in production for a period of time until all app users have deployed version two of the components and are ready to switch to version two of the workflows the app provider and each app user first deploy version two of the front ends and backends and as the last step in the upgrade process they deploy version version two of the DAR files on their Canton participant nodes the version two Dar files should be deployed by the app provider and app users shortly before the target upgrade date this ensures a mostly synchronous switch over to version two workflows on The Ledger the uncoordinated switch over to using version two workflows can result in workflows getting stuck due two command submission failures when a command is submitted to The Ledger using version two work flows and the transaction cannot be processed by a participant node hosting a stakeholder in the transaction because it doesn't have version two DL models another example where the command submission will fail due to an uncoordinated switch to version 2 DL models is when a version two contract is used in explicit disclosure in this scenario all stakeholders of the disclosed contract will have uploaded version 2 DL models to their participant notes otherwise version 2 contract couldn't be created but if version two table models are not available on the participant node submitting a command that includes reference to this contract using explicit disclosure the command submission will fail starting with version 2.9 Dam will provide support for making backwards compatible changes to the workflows and their data to handle cross version interactions with zero doubt time the following backwards compatible changes to DL models are supported numer versions of a Dar package can add optional fields to contract and choice arguments as well as to Choice return types with the following default component behavior when a component reads daml values from older versions the newly added fields are defaulted To None when a component reads values from newer versions then the read succeeds if all unknown Fields have valued none otherwise the read fails as the component is missing an upgrade to deal with a newly set value this design Choice was made to safeguard apps from unexpected data loss an archive and recreate style code like this one assuming Fu CID points to a contract of type Fu with P equal to Alice party existing field equal to 10 newly added field equal to some 100 this code would result in a new contract Fu with newly added field equal none being created instead of the expected Fu and newly added field equal to some 100 as we already mentioned optional new Fields can be added to templates Choice arguments and choice result types for the latter the choice return type must be a damel record as opposed to scaler types or other assembly types like two pull list set or map if when creating a choice you envisage that sometime in the future you might need to add a piece of data to the return value of the choice use a d record for the return type it is a good practice to always favor Danel record over tpol as the return type of a choice the supported backwards compatible changes to DL models also include addition of new Constructors to enums and variant types newer versions of a Dar package can add new Constructors to enums and variant types downgrading a newly added Constructor will fail analogously to how downgrading a newly added optional field that is not none will fail newer versions of a Dar package can also add new choices new choices introduced in version two are available on an active contract created with version one as soon as the par participant nodes hosting the contract stakeholders have all uploaded Dar file version 2 for a choice existing in version one version two of a Dar package can change the choice controllers and observers the body of the choice can also be changed for example to fix bugs or to deal the newly added choice or contract argument choices cannot be removed but their body can be changed to always called the abort function the code for computing signatories observers and ensure Clauses can change with the following limitations the computed sets of signatories and observers must remain the same for existing contracts this is checked by recomputing signatories and observers using the code when accessing existing contracts as part of executing a fetch or an exercise transactions are aborted if this check fails the insure Clause is also Rec computed and rechecked when fetching or exercising choices on existing contracts if it evaluates to false then fetching the contract or exercising a choice on the contract fails templates cannot be removed but new templates can be added existing templates that should no longer be used can be rendered inoperable by using the insure false clause this will make it impossible to create new contracts using the template this will also make it impossible to exercise any choices including the implicit archive choice on existing contracts created using the template as insure Clauses are always evaluated using the newest version of the template when the choice is exercised this strong form of contract immobilization may not always be desired for example it may result in a large number of immobilized active contracts stored on The Ledger without a way to Archive them unless another update is deployed that makes their ensure Clause evaluate to True another way to deprecate a template is to remove all references to it from all other denal code new interface instances can be added to templates interface instances cannot be removed from a template however one can make all the interfaces Choice implementations fail with error no longer implemented interface definitions can not be changed for this reason we recommend always putting interface definitions into their own package that only defines the interfaces and contains no templates to implement Ledger reads in version two of the back end that are backwards compatible with version one of DL models transaction and contract filters with symbolic package references of the form of package name module name template ID can be used in Ledger reads to retrieve data from all contracts that are instances of the template module name template ID of any version of package name note that it is up to the backend code to handle missing or newly added optional Fields the cagin that are part of the DL SDK take care of this by implementing the conversion explained earlier where the value of a missing optional field is set to none for upgrades where version two front ends and back ends use new features such as new Fields variant Constructors choices or templates an additional consideration that's required the back ends and front ends need to be configurable so that they only start using these new features once the target upgrade date is in the past otherwise a command submission will fail if for example it tries to exercise a choice that's not available on all part participant nodes verifying the transaction not all changes to the workflows of a damel app fit within the support for backwards compatible daml upgrades the approach we've presented for managing the evolution of daml models follows the spirit of how API evolution is managed in a service-based architecture for existing apis that is the existing demo code only backwards compatible changes are allowed backwards incompatible changes can be introduced by implementing new apis that is new templates and choices for new workflows we recommend building backwards incompatible upgrades by introducing new templates and injecting a consuming upgrade Choice into the existing templates to Archive them and create an instance of the new template the consuming upgrade choice for the existing templates is added as a backwards compatible upgrade where required reference data for upgrade choices for example default values can be provided via additional Choice arguments backend automation can be used to actively migrate the old contracts to the new ones this will incur downtime on workflows until their contracts have been converted by the automation this approach to upgrading daml models was discussed in detail in the course three of daml contract developer certification whether an update to daml models is backwards compatible or not it is important to avoid package name conflicts in particular between packages published by different app providers we recommend adopting the convention from the Java ecosystem to prefix packages with the reverse DNS name of the app provider for example for the issuance workflows of the money market fund app provided by Acme corporate a we'd recommend using a D.L file containing the following configuration name com Acme money market fund issuance now that we've discussed the implementation of updates to daml workflows the next topic we're going to address is testing the upgrades testing the type level compatibility of packages with the same name is easiest done by uploading all release versions and the new versions of the packages to a fresh participant node as part of CI for this to work the release star versions used in production need to be available we recommend managing these in a dedicated artifact repository given their smallest size typically less than 1 Megabyte checking them in with the sources is also an option testing the workflow level compatibility is application specific we recommend writing at least one integration test the test the upgrade working for the core workflows along these lines start the app using version two but only upload Dar version one initialize the app and start one instance of every core workflow upload Dar version 2 switch the flag to tell the backends to start using version two validate that the core workflows are in the same state and Advance them to check that they are not stuck depending on the complexity of the upgrade additional more specific tests might be required note that it might sometimes be cheaper to avoid upgrading short-lived workflows and instead just let the inflight ones complete and ensure that all new instances are started with the new version the participant nodes have a feature whereby demo packages are marked as vetted after they're uploaded and before they're available in production a participant parp node publishes package vetting status on the synchronizer so that other participant nodes know in which workflows the parties on the participant can engage a package cannot be used until it's seted which allows to introduce an additional verification step in the process of deploying a daml package note that by default the packages are automatically vetted when they're uploaded the packages can also be unvetted for example sample un vetting package version one after uploading and vetting version two signals that the participant node can no longer engage in version one workflows which completes the upgrade process if an upgrade needs to be rolled back for upgrades that don't modify the types of existing templates and choices this can be done by unfed version two of the DAR package upgrades that add new fields to existing templates need to be rolled back in a roll pull forward fashion by publishing another upgrade as long as at least one contract has been created that makes use of a newly added field the reason is that such contracts cannot be read using the previous version of the D code just unet the new version of the DARS is this not possible unless it is okay for the contracts that use the new fields to no longer be referenced instead a new version of the DARS needs to be published which ignores the def faultily added new Fields the new version can also add an explicit downgrade choice that resets newly added fields to none so that the contracts can be downgraded to the original version backend automation can then go through the ACs and call the downgrade choice you can avoid the need for these kind of roll forward roll backs by breaking an upgrade that introduces new Fields into two first build an upgrade that only introduces the new Fields but does not use them since this upgrade does not do any code changes to choices it won't have to be rolled back to fix a bug second build an upgrade that changes the choice implementations to make use of the new fields in case of a problem this upgrade can be rolled back using unve to summarize in this lesson we have learned that the recommended approach to upgrading DL apps is used an asynchronous roll out with a synchronous switch over starting from daml 2.9 daml provides support for developing and rolling out zero downtime upgrades to workflows an upgrade can add new choices templates and interfaces change choice implementations and add new optional fields to templates interfaces and choices conversion rules are defined for DL values with newly added fields that make it easy for Ledger API clients to interact with multiple versions of the DAR files we recommend the app provider to publish a Target date for completing the upgrade uploading the DAR files close to that Target date and having components check that this date is passed before using features introduced in the new version to avoid workflows getting stuck","transcript_synced_at":"2026-10-26T04:04:18.621Z","segments":[{"start_seconds":4,"text":"upgrading a daml app means rolling out new versions of its components to change existing workflows or to add new","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=4s"},{"start_seconds":11,"text":"workflows to the daml app upgrades must provide data continuity in the sense that the App State before the upgrade","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=11s"},{"start_seconds":18,"text":"and the workflows that were in Flight remain available and continue advancing after the upgrade in this lesson we're","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=18s"},{"start_seconds":26,"text":"going to learn the recommended approach to upgrading various components of a DL app we will look at the challenges of","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=26s"},{"start_seconds":33,"text":"upgrading DL apps then we will explore the recommended approach to upgrading a DL app then we will learn how to","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=33s"},{"start_seconds":41,"text":"implement backwards compatible upgrades to DL workflows and what to do when preserving backwards compatibility is","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=41s"},{"start_seconds":48,"text":"not possible then we will examine recommendations for testing and upgrade and finally we'll learn how to perform a","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=48s"},{"start_seconds":55,"text":"roll back when an upgrade goes wrong the challenge with upgrading DL apps stem from the distributed nature of the apps","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=55s"},{"start_seconds":64,"text":"and the fact that they're deployed across organizational boundaries these challenges include asynchronous rollouts","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=64s"},{"start_seconds":72,"text":"in most cases the app users and the app provider cannot upgrade at the same time upgrades must be rolled out in an","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=72s"},{"start_seconds":80,"text":"asynchronous fashion and allow app users and the app provider to follow their own schedule for when to deploy an upgraded","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=80s"},{"start_seconds":88,"text":"component zero downtime upgrades some of the apps workflows may need to be able to progress Around the Clock these","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=88s"},{"start_seconds":96,"text":"workflows need to be upgraded with zero downtime that is in a way that does not interrupt ongoing workflows the approach","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=96s"},{"start_seconds":103,"text":"we present provides zero downtime upgrades by default mixed version deployments because of asynchronous rollouts the app","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=103s"},{"start_seconds":112,"text":"needs to support some level of mixed version deployments with the approach that we presented is sufficient to only provide backwards compatibility of","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=112s"},{"start_seconds":121,"text":"backends and front ends with the DAR workflows from the previously deployed version in a real world DL app front","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=121s"},{"start_seconds":129,"text":"ends backends and DL models are likely to evolve at different pace at any given moment in time a daml","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=129s"},{"start_seconds":137,"text":"app is likely to utilize different version numbers for various components of the app like a server that implements","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=137s"},{"start_seconds":144,"text":"an API typically evolving faster than the API itself it's likely that the front ends and back ends will evolve","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=144s"},{"start_seconds":152,"text":"faster than the DL models and will have a different versioning strategy the front ends and backends will then","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=152s"},{"start_seconds":159,"text":"specify the minimum version of the DAR files they require for Simplicity in this lesson we're going to refer to the version","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=159s"},{"start_seconds":167,"text":"number of all components of a currently deployed and operational DL app as version one and all components of a new","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=167s"},{"start_seconds":175,"text":"version of the app as version two the recommended high level approach for upgrading demo apps can be described","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=175s"},{"start_seconds":183,"text":"as an asynchronous roll out with a synchronous switch over once the app provider has implemented and tested the","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=183s"},{"start_seconds":190,"text":"app components version two the app provider makes the version two components available to app","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=190s"},{"start_seconds":197,"text":"users the app provider and the app users asynchronously roll out upgraded backends and front ends and audit","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=197s"},{"start_seconds":204,"text":"upgraded Dar packages then the app provider publishes a taret tget upgrade date when they expect app users to have deployed the","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=204s"},{"start_seconds":213,"text":"upgrade and when they expect to decommission version one close to the Target upgrade date the app provider and","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=213s"},{"start_seconds":221,"text":"the app users upload the DAR files in a coordinated fashion so that the new workflows become available on Ledger","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=221s"},{"start_seconds":228,"text":"synchronously as of the target upgrade date the app front ends and backends should be implemented to support both","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=228s"},{"start_seconds":236,"text":"version one and two of the workflows this allows the app provider and app users to deploy your updates independently on their own","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=236s"},{"start_seconds":245,"text":"schedule multiple versions of the components are expected to be in production for a period of time until all app users have deployed version two","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=245s"},{"start_seconds":254,"text":"of the components and are ready to switch to version two of the workflows the app provider and each app user first","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=254s"},{"start_seconds":262,"text":"deploy version two of the front ends and backends and as the last step in the upgrade process they deploy version","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=262s"},{"start_seconds":269,"text":"version two of the DAR files on their Canton participant nodes the version two Dar files should be deployed by the app","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=269s"},{"start_seconds":277,"text":"provider and app users shortly before the target upgrade date this ensures a mostly synchronous switch over to","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=277s"},{"start_seconds":284,"text":"version two workflows on The Ledger the uncoordinated switch over to using version two workflows can result","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=284s"},{"start_seconds":292,"text":"in workflows getting stuck due two command submission failures when a command is submitted to The Ledger using version two work flows and the","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=292s"},{"start_seconds":300,"text":"transaction cannot be processed by a participant node hosting a stakeholder in the transaction because it doesn't","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=300s"},{"start_seconds":307,"text":"have version two DL models another example where the command submission will fail due to an","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=307s"},{"start_seconds":314,"text":"uncoordinated switch to version 2 DL models is when a version two contract is used in explicit disclosure in this","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=314s"},{"start_seconds":322,"text":"scenario all stakeholders of the disclosed contract will have uploaded version 2 DL models to their participant notes","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=322s"},{"start_seconds":330,"text":"otherwise version 2 contract couldn't be created but if version two table models are not available on the participant","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=330s"},{"start_seconds":337,"text":"node submitting a command that includes reference to this contract using explicit disclosure the command submission will","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=337s"},{"start_seconds":346,"text":"fail starting with version 2.9 Dam will provide support for making backwards compatible changes to the workflows and","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=346s"},{"start_seconds":354,"text":"their data to handle cross version interactions with zero doubt time the following backwards compatible changes to DL models are","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=354s"},{"start_seconds":363,"text":"supported numer versions of a Dar package can add optional fields to contract and choice arguments as well as","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=363s"},{"start_seconds":370,"text":"to Choice return types with the following default component behavior when a component reads daml values from older","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=370s"},{"start_seconds":379,"text":"versions the newly added fields are defaulted To None when a component reads values from newer","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=379s"},{"start_seconds":387,"text":"versions then the read succeeds if all unknown Fields have valued none otherwise the read fails as the","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=387s"},{"start_seconds":394,"text":"component is missing an upgrade to deal with a newly set value this design Choice was made to safeguard apps from","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=394s"},{"start_seconds":402,"text":"unexpected data loss an archive and recreate style code like this one","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=402s"},{"start_seconds":409,"text":"assuming Fu CID points to a contract of type Fu with P equal to Alice party existing field equal to 10 newly added","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=409s"},{"start_seconds":418,"text":"field equal to some 100 this code would result in a new contract Fu with newly added field equal","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=418s"},{"start_seconds":427,"text":"none being created instead of the expected Fu and newly added field equal to some","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=427s"},{"start_seconds":434,"text":"100 as we already mentioned optional new Fields can be added to templates Choice arguments and choice result types for","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=434s"},{"start_seconds":442,"text":"the latter the choice return type must be a damel record as opposed to scaler types or other assembly types like two","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=442s"},{"start_seconds":450,"text":"pull list set or map if when creating a choice you envisage that sometime in the future you might need to add a piece of","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=450s"},{"start_seconds":458,"text":"data to the return value of the choice use a d record for the return type it is a good practice to always favor Danel","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=458s"},{"start_seconds":466,"text":"record over tpol as the return type of a choice the supported backwards compatible changes to DL models also","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=466s"},{"start_seconds":475,"text":"include addition of new Constructors to enums and variant types newer versions of a Dar package can add new","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=475s"},{"start_seconds":483,"text":"Constructors to enums and variant types downgrading a newly added Constructor will fail analogously to how","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=483s"},{"start_seconds":492,"text":"downgrading a newly added optional field that is not none will fail newer versions of a Dar package can also add","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=492s"},{"start_seconds":500,"text":"new choices new choices introduced in version two are available on an active contract created with version one as","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=500s"},{"start_seconds":508,"text":"soon as the par participant nodes hosting the contract stakeholders have all uploaded Dar file version 2 for a","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=508s"},{"start_seconds":516,"text":"choice existing in version one version two of a Dar package can change the choice controllers and observers the","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=516s"},{"start_seconds":523,"text":"body of the choice can also be changed for example to fix bugs or to deal the newly added choice or contract","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=523s"},{"start_seconds":531,"text":"argument choices cannot be removed but their body can be changed to always called the abort function","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=531s"},{"start_seconds":539,"text":"the code for computing signatories observers and ensure Clauses can change with the following limitations the computed sets of","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=539s"},{"start_seconds":548,"text":"signatories and observers must remain the same for existing contracts this is checked by recomputing signatories and","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=548s"},{"start_seconds":556,"text":"observers using the code when accessing existing contracts as part of executing a fetch or an exercise transactions are","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=556s"},{"start_seconds":564,"text":"aborted if this check fails the insure Clause is also Rec computed and rechecked when fetching or","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=564s"},{"start_seconds":571,"text":"exercising choices on existing contracts if it evaluates to false then fetching the contract or exercising a choice on","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=571s"},{"start_seconds":580,"text":"the contract fails templates cannot be removed but new templates can be added existing templates that should no","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=580s"},{"start_seconds":589,"text":"longer be used can be rendered inoperable by using the insure false clause this will make it impossible to","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=589s"},{"start_seconds":596,"text":"create new contracts using the template this will also make it impossible to exercise any choices including the","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=596s"},{"start_seconds":604,"text":"implicit archive choice on existing contracts created using the template as insure Clauses are always evaluated","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=604s"},{"start_seconds":611,"text":"using the newest version of the template when the choice is exercised this strong form of contract immobilization may not","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=611s"},{"start_seconds":619,"text":"always be desired for example it may result in a large number of immobilized active contracts stored on The Ledger","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=619s"},{"start_seconds":627,"text":"without a way to Archive them unless another update is deployed that makes their ensure Clause evaluate to True","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=627s"},{"start_seconds":635,"text":"another way to deprecate a template is to remove all references to it from all other denal code new interface instances","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=635s"},{"start_seconds":643,"text":"can be added to templates interface instances cannot be removed from a template however one can","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=643s"},{"start_seconds":651,"text":"make all the interfaces Choice implementations fail with error no longer implemented interface definitions can","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=651s"},{"start_seconds":659,"text":"not be changed for this reason we recommend always putting interface definitions into their own package that only defines","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=659s"},{"start_seconds":667,"text":"the interfaces and contains no templates to implement Ledger reads in version two of the back end that are","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=667s"},{"start_seconds":677,"text":"backwards compatible with version one of DL models transaction and contract filters with symbolic package references of the","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=677s"},{"start_seconds":685,"text":"form of package name module name template ID can be used in Ledger reads to retrieve data from all contracts that","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=685s"},{"start_seconds":694,"text":"are instances of the template module name template ID of any version of package","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=694s"},{"start_seconds":701,"text":"name note that it is up to the backend code to handle missing or newly added optional Fields the cagin that are part","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=701s"},{"start_seconds":709,"text":"of the DL SDK take care of this by implementing the conversion explained earlier where the value of a missing","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=709s"},{"start_seconds":716,"text":"optional field is set to none for upgrades where version two front ends and back ends use new features such as","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=716s"},{"start_seconds":724,"text":"new Fields variant Constructors choices or templates an additional consideration that's required the back ends and front","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=724s"},{"start_seconds":732,"text":"ends need to be configurable so that they only start using these new features once the target upgrade date is in the","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=732s"},{"start_seconds":740,"text":"past otherwise a command submission will fail if for example it tries to exercise a choice that's not available on all","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=740s"},{"start_seconds":748,"text":"part participant nodes verifying the transaction not all changes to the workflows of a damel app fit within the","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=748s"},{"start_seconds":756,"text":"support for backwards compatible daml upgrades the approach we've presented for managing the evolution of daml","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=756s"},{"start_seconds":764,"text":"models follows the spirit of how API evolution is managed in a service-based architecture for existing apis that is","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=764s"},{"start_seconds":773,"text":"the existing demo code only backwards compatible changes are allowed backwards incompatible changes can be","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=773s"},{"start_seconds":781,"text":"introduced by implementing new apis that is new templates and choices for new workflows we recommend building","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=781s"},{"start_seconds":790,"text":"backwards incompatible upgrades by introducing new templates and injecting a consuming upgrade Choice into the","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=790s"},{"start_seconds":797,"text":"existing templates to Archive them and create an instance of the new template the consuming upgrade choice","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=797s"},{"start_seconds":804,"text":"for the existing templates is added as a backwards compatible upgrade where required reference data for","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=804s"},{"start_seconds":812,"text":"upgrade choices for example default values can be provided via additional Choice","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=812s"},{"start_seconds":818,"text":"arguments backend automation can be used to actively migrate the old contracts to the new ones this will incur downtime on","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=818s"},{"start_seconds":828,"text":"workflows until their contracts have been converted by the automation this approach to upgrading daml models was","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=828s"},{"start_seconds":835,"text":"discussed in detail in the course three of daml contract developer certification whether an update to daml","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=835s"},{"start_seconds":843,"text":"models is backwards compatible or not it is important to avoid package name conflicts in particular between packages","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=843s"},{"start_seconds":851,"text":"published by different app providers we recommend adopting the convention from the Java ecosystem to","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=851s"},{"start_seconds":859,"text":"prefix packages with the reverse DNS name of the app provider for example for the issuance workflows of the money","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=859s"},{"start_seconds":866,"text":"market fund app provided by Acme corporate a we'd recommend using a D.L file containing the following","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=866s"},{"start_seconds":874,"text":"configuration name com Acme money market fund issuance now that we've discussed the implementation of updates to daml","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=874s"},{"start_seconds":883,"text":"workflows the next topic we're going to address is testing the upgrades testing the type level","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=883s"},{"start_seconds":890,"text":"compatibility of packages with the same name is easiest done by uploading all release versions and the new versions of","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=890s"},{"start_seconds":897,"text":"the packages to a fresh participant node as part of CI for this to work the release star","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=897s"},{"start_seconds":904,"text":"versions used in production need to be available we recommend managing these in a dedicated artifact repository given","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=904s"},{"start_seconds":912,"text":"their smallest size typically less than 1 Megabyte checking them in with the sources is also an","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=912s"},{"start_seconds":919,"text":"option testing the workflow level compatibility is application specific we recommend writing at least one","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=919s"},{"start_seconds":927,"text":"integration test the test the upgrade working for the core workflows along these lines start the app using version two","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=927s"},{"start_seconds":935,"text":"but only upload Dar version one initialize the app and start one instance of every core","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=935s"},{"start_seconds":943,"text":"workflow upload Dar version 2 switch the flag to tell the backends to start using version","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=943s"},{"start_seconds":951,"text":"two validate that the core workflows are in the same state and Advance them to check that they are not stuck depending","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=951s"},{"start_seconds":959,"text":"on the complexity of the upgrade additional more specific tests might be required note that it might sometimes be","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=959s"},{"start_seconds":967,"text":"cheaper to avoid upgrading short-lived workflows and instead just let the inflight ones complete and ensure that","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=967s"},{"start_seconds":974,"text":"all new instances are started with the new version the participant nodes have a feature whereby demo packages are marked","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=974s"},{"start_seconds":983,"text":"as vetted after they're uploaded and before they're available in production a participant parp node publishes package","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=983s"},{"start_seconds":990,"text":"vetting status on the synchronizer so that other participant nodes know in which workflows the parties on the participant can","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=990s"},{"start_seconds":998,"text":"engage a package cannot be used until it's seted which allows to introduce an additional verification step in the","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=998s"},{"start_seconds":1006,"text":"process of deploying a daml package note that by default the packages are automatically vetted when they're","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1006s"},{"start_seconds":1014,"text":"uploaded the packages can also be unvetted for example sample un vetting package version one after uploading and","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1014s"},{"start_seconds":1022,"text":"vetting version two signals that the participant node can no longer engage in version one workflows which completes the upgrade","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1022s"},{"start_seconds":1030,"text":"process if an upgrade needs to be rolled back for upgrades that don't modify the types of existing templates and choices","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1030s"},{"start_seconds":1038,"text":"this can be done by unfed version two of the DAR package upgrades that add new fields to","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1038s"},{"start_seconds":1045,"text":"existing templates need to be rolled back in a roll pull forward fashion by publishing another upgrade as long as at","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1045s"},{"start_seconds":1052,"text":"least one contract has been created that makes use of a newly added field the reason is that such contracts cannot be","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1052s"},{"start_seconds":1060,"text":"read using the previous version of the D code just unet the new version of the DARS is this not possible unless it is","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1060s"},{"start_seconds":1068,"text":"okay for the contracts that use the new fields to no longer be referenced instead a new version of the","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1068s"},{"start_seconds":1075,"text":"DARS needs to be published which ignores the def faultily added new Fields the new version can also add an","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1075s"},{"start_seconds":1083,"text":"explicit downgrade choice that resets newly added fields to none so that the contracts can be downgraded to the original","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1083s"},{"start_seconds":1091,"text":"version backend automation can then go through the ACs and call the downgrade choice you can avoid the need for these","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1091s"},{"start_seconds":1100,"text":"kind of roll forward roll backs by breaking an upgrade that introduces new Fields into two first build an upgrade that only","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1100s"},{"start_seconds":1109,"text":"introduces the new Fields but does not use them since this upgrade does not do any code changes to choices it won't","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1109s"},{"start_seconds":1117,"text":"have to be rolled back to fix a bug second build an upgrade that changes the choice implementations to make use","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1117s"},{"start_seconds":1125,"text":"of the new fields in case of a problem this upgrade can be rolled back using unve to summarize in this lesson we have","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1125s"},{"start_seconds":1134,"text":"learned that the recommended approach to upgrading DL apps is used an asynchronous roll out with a synchronous","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1134s"},{"start_seconds":1141,"text":"switch over starting from daml 2.9 daml provides support for developing and rolling out zero downtime upgrades to","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1141s"},{"start_seconds":1150,"text":"workflows an upgrade can add new choices templates and interfaces change choice","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1150s"},{"start_seconds":1157,"text":"implementations and add new optional fields to templates interfaces and choices conversion rules are defined for","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1157s"},{"start_seconds":1165,"text":"DL values with newly added fields that make it easy for Ledger API clients to interact with multiple versions of the","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1165s"},{"start_seconds":1173,"text":"DAR files we recommend the app provider to publish a Target date for completing the upgrade uploading the DAR files","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1173s"},{"start_seconds":1181,"text":"close to that Target date and having components check that this date is passed before using features introduced in the new version to avoid workflows","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1181s"},{"start_seconds":1190,"text":"getting stuck","url":"https://www.youtube.com/watch?v=sX9G4re8GaI&t=1190s"}],"youtube_url":"https://youtube.com/watch?v=sX9G4re8GaI","url":"https://ccpedia.xyz/videos/sX9G4re8GaI"}