From c63f265b5eed7e8d836087c1da403cd017b64a91 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastian=20M=C3=BCller?= Date: Tue, 26 Mar 2024 09:35:40 -0700 Subject: [PATCH 1/2] sync --- .../version-1.0/cadence_migration_guide/index.md | 2 +- .../cadence_migration_guide/staging-guide.mdx | 14 ++++++++++++-- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/versioned_docs/version-1.0/cadence_migration_guide/index.md b/versioned_docs/version-1.0/cadence_migration_guide/index.md index 89d620d..e66cf37 100644 --- a/versioned_docs/version-1.0/cadence_migration_guide/index.md +++ b/versioned_docs/version-1.0/cadence_migration_guide/index.md @@ -37,7 +37,7 @@ To ensure your contracts are fully operational with Cadence 1.0, follow these es flow-c1 version ``` -5. **Stage**: A new **_Staging process_** will be released in the coming weeks that checks if your updated code is compatible with Cadence 1.0. Complete this [form](https://docs.google.com/forms/d/e/1FAIpQLSfprZJLPSEAS6H7_oL0j6bzetDzkHPmDZHYAGgqAAOAdLDKqw/viewform) to stay informed about updates and receive recommendations tailored to your code. +5. **Stage**: The last step is to get your updated code ready to replace your live pre-cadence 1.0 code when the upgrade occurs, to do this you need to [stage](https://cadence-lang.org/docs/cadence_migration_guide/staging-guide) your contracts. Stage them on testnet and ensure that they are working as expected along with their staged dependencies. Staging for mainnet contracts is coming soon. ### Resources diff --git a/versioned_docs/version-1.0/cadence_migration_guide/staging-guide.mdx b/versioned_docs/version-1.0/cadence_migration_guide/staging-guide.mdx index 853cb96..ab58446 100644 --- a/versioned_docs/version-1.0/cadence_migration_guide/staging-guide.mdx +++ b/versioned_docs/version-1.0/cadence_migration_guide/staging-guide.mdx @@ -17,10 +17,20 @@ This guide aims to simplify the migration process to Cadence 1.0, making it acce ## Staging a contract + + In order to migrate your updated smart contract to Cadence 1.0, it's crucial to stage it on the Testnet network. This preliminary step not only verifies the contract's compatibility and syntactical correctness but also ensures a seamless transition to the new environment. ```bash -flow migrate stage-contract HelloWorld --network=testnet +flow-c1 migrate stage-contract HelloWorld --network=testnet ``` Ensure that HelloWorld accurately reflects the name of your contract as specified in your flow.json configuration file. @@ -30,7 +40,7 @@ Ensure that HelloWorld accurately reflects the name of your contract as specifie To confirm that your contract is ready for migration and has been successfully staged, execute the following command: ```bash -flow migrate is-staged HelloWorld --network=testnet +flow-c1 migrate is-staged HelloWorld --network=testnet ``` A response of true indicates that your contract has been approved by the Flow Blockchain Testnet network and is ready for the migration process. From 7b048ed68b3af83680f8e524fa7921c07c90942c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastian=20M=C3=BCller?= Date: Tue, 26 Mar 2024 09:38:34 -0700 Subject: [PATCH 2/2] document account type changes --- .../type-annotations-guide.mdx | 58 ++++++++++--------- .../type-annotations-guide.mdx | 58 ++++++++++--------- 2 files changed, 64 insertions(+), 52 deletions(-) diff --git a/docs/cadence_migration_guide/type-annotations-guide.mdx b/docs/cadence_migration_guide/type-annotations-guide.mdx index 488d259..ef1f5bc 100644 --- a/docs/cadence_migration_guide/type-annotations-guide.mdx +++ b/docs/cadence_migration_guide/type-annotations-guide.mdx @@ -6,44 +6,44 @@ sidebar_label: Cadence Type Annotations 1.0 Guide # Type Annotations in Cadence 1.0 -In addition to updating your contracts in reaction to the Core Contract changes in Cadence 1.0, -certain language changes in Cadence 1.0 will also require changes to type annotations in your contracts, -in particular type annotations on resource and struct fields. +In addition to updating your contracts in reaction to the Core Contract changes in Cadence 1.0, +certain language changes in Cadence 1.0 will also require changes to type annotations in your contracts, +in particular type annotations on resource and struct fields. These type updates are required to accurately reflect the way that the Cadence 1.0 data migrations will change -the types of these fields' values, and the Cadence 1.0 upgrade validator will enforce that these upgrades are accurate. +the types of these fields' values, and the Cadence 1.0 upgrade validator will enforce that these upgrades are accurate. ## Restricted Types -In Cadence 1.0, support for restricted types was dropped, and replaced with [intersection types](https://cadence-lang.org/docs/1.0/language/intersection-types). -As such, any existing restricted types must be replaced with a different type. -During the automated state migration for the Cadence 1.0 upgrade, restricted typed-values will be migrated according to a specific set of rules, and all developers must update the types in their contracts to mirror this. +In Cadence 1.0, support for restricted types was dropped, and replaced with [intersection types](https://cadence-lang.org/docs/1.0/language/intersection-types). +As such, any existing restricted types must be replaced with a different type. +During the automated state migration for the Cadence 1.0 upgrade, restricted typed-values will be migrated according to a specific set of rules, and all developers must update the types in their contracts to mirror this. * `AnyStruct{I}` and `AnyResource{I}` should be migrated to just `{I}`, as these types have identical behavior * For any other type `T`, `T{I}` should be migrated to `T`, as this is the most specific possible type that can go here * For any type `T`, `T{}` should be migrated to just `T`, as there is no support for empty intersection types -So, for example, a value of type `FlowToken.Vault{FungibleToken.Receiver}` should be migrated to just a `FlowToken.Vault` type, -while a value of type `AnyResource{Provider, Receiver}` should be migrated to a `{Provider, Receiver}` intersection. +So, for example, a value of type `FlowToken.Vault{FungibleToken.Receiver}` should be migrated to just a `FlowToken.Vault` type, +while a value of type `AnyResource{Provider, Receiver}` should be migrated to a `{Provider, Receiver}` intersection. ## Reference Types Reference types (whether on their own like `&FlowToken.Vault` or within a capability type like `Capability<&FlowToken.Vault{FungibleToken.Provider}>`) -from contracts written in Cadence v0.42 will need to be given -[entitlements](https://cadence-lang.org/docs/1.0/language/access-control#entitlements) in order to retain the same functionality -in Cadence 1.0. -The Cadence 1.0 automated data migration will automatically grant the appropriate entitlements to stored values, -but any reference types that appear in your contracts will need to be manually updated. - -The update you will need to perform involves changing each reference type to have the appropriate entitlements necessary to perform -the same operations in Cadence 1.0 that it previously could in Cadence v0.42. +from contracts written in Cadence v0.42 will need to be given +[entitlements](https://cadence-lang.org/docs/1.0/language/access-control#entitlements) in order to retain the same functionality +in Cadence 1.0. +The Cadence 1.0 automated data migration will automatically grant the appropriate entitlements to stored values, +but any reference types that appear in your contracts will need to be manually updated. + +The update you will need to perform involves changing each reference type to have the appropriate entitlements necessary to perform +the same operations in Cadence 1.0 that it previously could in Cadence v0.42. The Cadence 1.0 upgrade validator will enforce that these upgrades are accurate, and will suggest the correct type in case of an error. However, if you'd like to understand how the validator computes this type, the next section has a technical explanation of what the validator is computing. ### How the Validator Computes Entitlements -The first basic concept necessary to understand the upgrade is the "entitlements function"; -i.e. a hypothetical function that computes the set of entitlements that are valid for some composite or interface type `T`. -This is just the complete set of entitlements that appear in that type's definition. +The first basic concept necessary to understand the upgrade is the "entitlements function"; +i.e. a hypothetical function that computes the set of entitlements that are valid for some composite or interface type `T`. +This is just the complete set of entitlements that appear in that type's definition. E.g., for a resource type `R` defined as: @@ -54,15 +54,15 @@ access(all) resource R { } ``` -`Entitlements(I)` would be equal to `{E, G, H}`, i.e. all the entitlements that appear in `I`'s definition. -The idea here is that any reference that was previously typed as `&R` was originally able to call all -the `pub` functions in `R` (here both `foo` and `bar`), and after the Cadence 1.0 migration we want that to still be the case. +`Entitlements(I)` would be equal to `{E, G, H}`, i.e. all the entitlements that appear in `I`'s definition. +The idea here is that any reference that was previously typed as `&R` was originally able to call all +the `pub` functions in `R` (here both `foo` and `bar`), and after the Cadence 1.0 migration we want that to still be the case. In order to make that true, we need to give the `&R` all the entitlements it might need to do that, which is exactly `Entitlements(R)`. -All of which is to say, any `&R` reference types that appear in your contract must be updated to `auth(E1, E2, ...) &R`, where `E1, E2, ...` are all +All of which is to say, any `&R` reference types that appear in your contract must be updated to `auth(E1, E2, ...) &R`, where `E1, E2, ...` are all the entitlements in `Entitlements(R)`. -One important note is that reference to restricted types (`&T{I}`) behave slightly differently; instead of being given entitlements to `T`, they +One important note is that reference to restricted types (`&T{I}`) behave slightly differently; instead of being given entitlements to `T`, they are instead granted only entitlements based on the interfaces in the restriction set (here `{I}`). So for some interface and composite defined like so: ```cadence @@ -76,4 +76,10 @@ access(all) resource R: I { ``` A type `&R{I}` should be updated to `auth(E) &R`, since the entitlements it is given is only those in `I`. It does not receive an entitlement to `F`, since -the old `&R{I}` was not able to call `bar`. \ No newline at end of file +the old `&R{I}` was not able to call `bar`. + +## Account Types + +The replacement for `AuthAccount` is the fully-entitled type `auth(Storage, Contracts, Keys, Inbox, Capabilities) &Account`. + +The replacement for `PublicAccount` is the unentitled type `&Account`. diff --git a/versioned_docs/version-1.0/cadence_migration_guide/type-annotations-guide.mdx b/versioned_docs/version-1.0/cadence_migration_guide/type-annotations-guide.mdx index 488d259..ef1f5bc 100644 --- a/versioned_docs/version-1.0/cadence_migration_guide/type-annotations-guide.mdx +++ b/versioned_docs/version-1.0/cadence_migration_guide/type-annotations-guide.mdx @@ -6,44 +6,44 @@ sidebar_label: Cadence Type Annotations 1.0 Guide # Type Annotations in Cadence 1.0 -In addition to updating your contracts in reaction to the Core Contract changes in Cadence 1.0, -certain language changes in Cadence 1.0 will also require changes to type annotations in your contracts, -in particular type annotations on resource and struct fields. +In addition to updating your contracts in reaction to the Core Contract changes in Cadence 1.0, +certain language changes in Cadence 1.0 will also require changes to type annotations in your contracts, +in particular type annotations on resource and struct fields. These type updates are required to accurately reflect the way that the Cadence 1.0 data migrations will change -the types of these fields' values, and the Cadence 1.0 upgrade validator will enforce that these upgrades are accurate. +the types of these fields' values, and the Cadence 1.0 upgrade validator will enforce that these upgrades are accurate. ## Restricted Types -In Cadence 1.0, support for restricted types was dropped, and replaced with [intersection types](https://cadence-lang.org/docs/1.0/language/intersection-types). -As such, any existing restricted types must be replaced with a different type. -During the automated state migration for the Cadence 1.0 upgrade, restricted typed-values will be migrated according to a specific set of rules, and all developers must update the types in their contracts to mirror this. +In Cadence 1.0, support for restricted types was dropped, and replaced with [intersection types](https://cadence-lang.org/docs/1.0/language/intersection-types). +As such, any existing restricted types must be replaced with a different type. +During the automated state migration for the Cadence 1.0 upgrade, restricted typed-values will be migrated according to a specific set of rules, and all developers must update the types in their contracts to mirror this. * `AnyStruct{I}` and `AnyResource{I}` should be migrated to just `{I}`, as these types have identical behavior * For any other type `T`, `T{I}` should be migrated to `T`, as this is the most specific possible type that can go here * For any type `T`, `T{}` should be migrated to just `T`, as there is no support for empty intersection types -So, for example, a value of type `FlowToken.Vault{FungibleToken.Receiver}` should be migrated to just a `FlowToken.Vault` type, -while a value of type `AnyResource{Provider, Receiver}` should be migrated to a `{Provider, Receiver}` intersection. +So, for example, a value of type `FlowToken.Vault{FungibleToken.Receiver}` should be migrated to just a `FlowToken.Vault` type, +while a value of type `AnyResource{Provider, Receiver}` should be migrated to a `{Provider, Receiver}` intersection. ## Reference Types Reference types (whether on their own like `&FlowToken.Vault` or within a capability type like `Capability<&FlowToken.Vault{FungibleToken.Provider}>`) -from contracts written in Cadence v0.42 will need to be given -[entitlements](https://cadence-lang.org/docs/1.0/language/access-control#entitlements) in order to retain the same functionality -in Cadence 1.0. -The Cadence 1.0 automated data migration will automatically grant the appropriate entitlements to stored values, -but any reference types that appear in your contracts will need to be manually updated. - -The update you will need to perform involves changing each reference type to have the appropriate entitlements necessary to perform -the same operations in Cadence 1.0 that it previously could in Cadence v0.42. +from contracts written in Cadence v0.42 will need to be given +[entitlements](https://cadence-lang.org/docs/1.0/language/access-control#entitlements) in order to retain the same functionality +in Cadence 1.0. +The Cadence 1.0 automated data migration will automatically grant the appropriate entitlements to stored values, +but any reference types that appear in your contracts will need to be manually updated. + +The update you will need to perform involves changing each reference type to have the appropriate entitlements necessary to perform +the same operations in Cadence 1.0 that it previously could in Cadence v0.42. The Cadence 1.0 upgrade validator will enforce that these upgrades are accurate, and will suggest the correct type in case of an error. However, if you'd like to understand how the validator computes this type, the next section has a technical explanation of what the validator is computing. ### How the Validator Computes Entitlements -The first basic concept necessary to understand the upgrade is the "entitlements function"; -i.e. a hypothetical function that computes the set of entitlements that are valid for some composite or interface type `T`. -This is just the complete set of entitlements that appear in that type's definition. +The first basic concept necessary to understand the upgrade is the "entitlements function"; +i.e. a hypothetical function that computes the set of entitlements that are valid for some composite or interface type `T`. +This is just the complete set of entitlements that appear in that type's definition. E.g., for a resource type `R` defined as: @@ -54,15 +54,15 @@ access(all) resource R { } ``` -`Entitlements(I)` would be equal to `{E, G, H}`, i.e. all the entitlements that appear in `I`'s definition. -The idea here is that any reference that was previously typed as `&R` was originally able to call all -the `pub` functions in `R` (here both `foo` and `bar`), and after the Cadence 1.0 migration we want that to still be the case. +`Entitlements(I)` would be equal to `{E, G, H}`, i.e. all the entitlements that appear in `I`'s definition. +The idea here is that any reference that was previously typed as `&R` was originally able to call all +the `pub` functions in `R` (here both `foo` and `bar`), and after the Cadence 1.0 migration we want that to still be the case. In order to make that true, we need to give the `&R` all the entitlements it might need to do that, which is exactly `Entitlements(R)`. -All of which is to say, any `&R` reference types that appear in your contract must be updated to `auth(E1, E2, ...) &R`, where `E1, E2, ...` are all +All of which is to say, any `&R` reference types that appear in your contract must be updated to `auth(E1, E2, ...) &R`, where `E1, E2, ...` are all the entitlements in `Entitlements(R)`. -One important note is that reference to restricted types (`&T{I}`) behave slightly differently; instead of being given entitlements to `T`, they +One important note is that reference to restricted types (`&T{I}`) behave slightly differently; instead of being given entitlements to `T`, they are instead granted only entitlements based on the interfaces in the restriction set (here `{I}`). So for some interface and composite defined like so: ```cadence @@ -76,4 +76,10 @@ access(all) resource R: I { ``` A type `&R{I}` should be updated to `auth(E) &R`, since the entitlements it is given is only those in `I`. It does not receive an entitlement to `F`, since -the old `&R{I}` was not able to call `bar`. \ No newline at end of file +the old `&R{I}` was not able to call `bar`. + +## Account Types + +The replacement for `AuthAccount` is the fully-entitled type `auth(Storage, Contracts, Keys, Inbox, Capabilities) &Account`. + +The replacement for `PublicAccount` is the unentitled type `&Account`.