Jan 19 2024: We have published an update to this post, please take a look here: Update on Cadence 1.0 Upgrade Plan
Flow is releasing the biggest upgrade of Cadence since it launched in 2020 and this post explains everything you need to know to get ready.
TLDR
The Cadence 1.0 upgrade will deliver over 20 features and improvements – a giant leap forward in how dapps on Flow are built and run. Cadence code execution will be more secure, development of dapps on Flow safer, and the language simpler to understand and more efficient to build in.
After Cadence 1.0 launches, future Cadence releases will be backwards-compatible, crucial for improving network availability, and finally deliver on composability promises (no contracts will be broken by new Cadence features, immutable contracts will become a realistic option on Flow).
To unlock all these benefits, the Cadence 1.0 release is a breaking change – dapp developers need to upgrade all Cadence code used by their dapp (including all existing smart contracts deployed on Flow) to Cadence 1.0, to ensure it continues to work after the network upgrade.
Developers will be able to start migrating and testing their contracts soon: We aim to release the Flow Emulator with Cadence 1.0 RC1 before the end of 2023.
Before the end of 2023 we will launch a new test network (named Crescendo) and early Feb 2024 we will upgrade it to Cadence 1.0. At that point developers will be able to test their dapps on a real network, interacting with other migrated contracts and tools.
In mid-April we plan to upgrade Testnet, followed by Mainnet two weeks later, completing the upgrade by the end of April 2024.
Please note that these times are estimates and we may delay the launch if necessary. We want to make sure the Flow community has enough time to prepare for the upgrade and for that reason we won’t bring it forward - the earliest upgrade date will be end of April 2024. We will keep you updated with the latest plans in our Discord and will also keep this forum post up to date.
The Flow team wants to make sure that every developer has support through this upgrade. In addition to the usual support provided through Discord channels, we are going to start hosting regular public meetings where anyone can join and get help with their contract upgrade and ask any questions related to Cadence 1.0 and the upgrade process in general. These sessions will be scheduled in Flow Webinars & Events calendar and announced on flow-events Discord channel.
What does it mean for me if I am a …
Cadence Developer with Flow dapp live on Mainnet
- Now: Learn about what is changing in Cadence 1.0: Update on Cadence 1.0 (you can subscribe to the forum post above to receive notifications about future updates).
- Now: Start working on upgrading your contracts, transactions and scripts, following the guidance in the post above. You can use the latest preview release of the Emulator now, and soon the Emulator with Cadence 1.0 Release Candidate 1.
3.2. - Mid Dec 2023: When Flow Emulator with Cadence 1.0 Release Candidate 1 is available (Milestone 1), start testing your dapp updated to Cadence 1.0.
At this point the Flow team will start series of events anyone can join to ask questions and get help with their dapp upgrade. These sessions will be scheduled in Flow Webinars & Events calendar and announced on flow-events Discord channel. - Early to mid Jan 2023: When Flow Emulator running Cadence 1.0 supports deployment of a smart contract which is based on Cadence version 0.42 (Milestone 3), test the update of your existing contract (based on Cadence v0.42) to Cadence 1.0 and report any issues to the Cadence team in the developer-questions Discord channel, using “C1.0 upgrade” at the beginning of the message, to help us categorize questions related to Cadence 1.0.
- End of Jan 2024: when the staged contract update mechanism is deployed on the new test network (called Crescendo network; Milestone 5), stage your updated contracts to be automatically upgraded when the network is upgraded to Cadence 1.0.
To avoid introducing security vulnerabilities during this step, please read the important note about business logic updates in the milestone 5 section of the detailed plan below. - Early to mid Feb 2024: After the Crescendo network is upgraded to Cadence 1.0 (Milestone 6), validate that your contract was upgraded correctly and start testing your dapp.
Please read this important note about implications of missing this step in the milestone 6 section of the detailed plan below. - Mid Apr 2024: Similar to step 5 above, before Testnet is upgraded to Cadence 1.0 (Milestone 7), stage your contracts to be upgraded using the staged contract update mechanism. After the testnet upgrade to Cadence 1.0, test your dapp.
- End of Apr 2024: Similar to step 6 above, before Mainnet is upgraded to Cadence 1.0 (Milestone 8), stage your contracts to be upgraded using the staged contract update mechanism.
- 1st May 2024: Mainnet is upgraded to Cadence 1.0 (Milestone 8). Validate your contracts were correctly upgraded and your dapp works as expected.
Cadence Developer with no live dapp yet on Mainnet
- Now: Learn about what is changing in Cadence 1.0: Update on Cadence 1.0.
- Upgrade your contracts, transactions and scripts to be compatible with Cadence 1.0. You can start testing with the Cadence 1.0 on Flow Emulator as soon as mid-Dec 2023. You can start testing on a real network when Crescendo network will be upgraded to Cadence 1.0 early-mid Feb 2024.
- If you plan to deploy your dapp to Mainnet before it is upgraded to Cadence 1.0, make sure you are prepared to upgrade it to Cadence 1.0 - see the steps in the section above.
Node Operator
The network upgrade to Cadence 1.0 will follow the usual process and will include a migration of execution state. For that reason it is likely to require a longer network outage than usual.
User of a dapp on Flow
We expect that in almost all cases, you won’t need to do anything! The dapp team should handle everything without a need for an end user to move their assets or sign transactions. But, if you’re not sure, you can reach out to the team behind the dapp and ask them about their plans to upgrade to Cadence 1.0.
Detailed Upgrade Plan Description
The diagram below illustrates the estimated timeline and milestones of the upgrade process.
The Flow team plans to release Cadence 1.0 in a series of milestones, to give all developers plenty of time to learn about the changes and to migrate and test their dapps.
Milestone 1 will release the Flow Emulator based on Cadence 1.0 Release Candidate 1. This will enable developers to play with Cadence 1.0 and to start updating contracts, transactions and scripts to Cadence 1.0. It enables testing in an “empty” environment, with no pre-existing on-chain data and other contracts deployed.
Milestone 2 marks the launch of Crescendo network, which will be later upgraded to Cadence 1.0 and used for testing multiple steps in the upgrade process. Dapp developers can prepare any data on Crescendo network they will need for migration testing.
Milestone 3 will extend the Flow Emulator with a feature which which enables the deployment of a smart contract which is based on Cadence version 0.42 (Cadence v0.42 is live on Mainnet since Nov 8 2023). This enables developers to test the upgrade of their existing contracts to Cadence 1.0. This step is important, because the Cadence runtime performs a number of checks when a contract is upgraded, to ensure that the upgrade does not break backwards compatibility of existing resources. If your contract upgrade to Cadence 1.0 fails, the Cadence team needs to hear from you! You can get in touch with the team on developer-questions Discord channel, please use “C1.0 upgrade” at the beginning of the message to help us categorize questions related to Cadence 1.0.
Milestone 4 is about the successful test of the migrations of on-chain data to Cadence 1.0. The Flow team has built a number of state migrations which convert the existing on-chain data to Cadence 1.0. Those migrations will be run during the network upgrade to Cadence 1.0 – first on Crescendo network, and later on Testnet and Mainnet. This step does not require any extra work from the dapp developers and will be completed by the Flow team using the Crescendo network state.
This step also includes the migration of on-chain data required by the optimized storage and EVM on Flow features.
Milestone 5 is the last step before Crescendo network will be ready for the upgrade to Cadence 1.0. The Flow team will deploy the staged contract upgrade mechanism, which will be used by dapp developers to stage their contract to be upgraded during the network upgrade to Cadence 1.0.
The on-chain data migration logic relies on assumption that the updated contracts uploaded by dapp developers limits updates to the minimum changes required by the Cadence 1.0 version - in other words, the updated contract should be behaviour-preserving.
If the contract upgrade to Cadence 1.0 also includes changes to business logic, the on-chain data migration won’t work as expected and might result in security vulnerabilities in the migrated on-chain data.
Milestone 6 is upgrade of Crescendo network to Cadence 1.0 and will likely also include first version of EVM on Flow and Optimized storage. The Flow team will stop Crescendo network, trigger upgrade of contracts that were staged for upgrade (milestone 4), run all Cadence 1.0 migrations (described in milestone 3) and restart the network. This completes the first full upgrade process to Cadence 1.0. The next milestones repeats this process on Testnet and later Mainnet. This step creates a fully working “real” environment, where developers can test their dapps interaction with other contracts and projects available on Crescendo network. The Flow team may repeat this step multiple times (resetting the Crescendo network to pre-upgrade state and performing the upgrade again) to fix issues found during the upgrade process.
Developers must stage their contracts to be upgraded in this step. The Entitlements migration requires the Cadence 1.0 version of a contract to be staged for upgrade in order to successfully complete the migration of the related on-chain data as described in the Entitlements Migration Proposal. If a contract is not staged for the upgrade at this point, the Entitlements migration for the related on-chain data will not be run, and it won’t be possible to test the contract on Crescendo network.
Please note that the same applies to upgrade of Testnet and Mainnet.
Milestone 7 is identical to M5 on Crescendo network, but this time on Testnet.
Milestone 8 launches Cadence 1.0 on Mainnet.
If any of this isn’t clear or you have further questions, please reply on this post, or contact us on developer-questions Discord channel, using “C1.0 upgrade” at the beginning of the message to help us categorize questions related to Cadence 1.0.
We are of course open to feedback and collaboration with you all!
Thank you, the Flow Foundation