Merge pull request #150 from onflow/bastian/migration-guide

Bring back subset of migration guide
onflow · Sep 23, 2024 · c6f1558 · c6f1558
2 parents 9bde7ff + d4510ee
commit c6f1558
Show file tree

Hide file tree

Showing 12 changed files with 2,217 additions and 49 deletions.
diff --git a/docs/cadence-migration-guide/_category_.json b/docs/cadence-migration-guide/_category_.json
@@ -0,0 +1,3 @@
+{
+    "position": 5
+}
diff --git a/docs/cadence-migration-guide/core-contracts-guide.mdx b/docs/cadence-migration-guide/core-contracts-guide.mdx
@@ -0,0 +1,64 @@
+---
+title: Protocol Smart Contracts 1.0 Changes Guide
+sidebar_position: 4
+sidebar_label: Core Contracts Guide
+---
+
+## Protocol Smart Contracts in Cadence 1.0
+
+On September 4th, 2024 the Flow Mainnet upgraded to Cadence 1.0.
+In addition to many changes to the Cadence programming language and
+the Cadence token standards, the Flow Protocol smart contracts
+also updated to be compatible with the changes.
+
+All applications that interact with these contracts need to update their transactions and scripts
+in order to be compatible with the changes.
+
+## Important Info
+
+This document assumes you have a basic understanding of the
+[Cadence 1.0 improvements](./improvements.md) and modifications to the Fungible Token Standard.
+We encourage you to consult those guides for more details on these changes if you are interested.
+
+The updated code for the Cadence 1.0 versions of the protocol smart contracts is located in the
+[`master` branch of the flow-core-contracts repo](https://github.com/onflow/flow-core-contracts).
+Please look at the [PR that made the changes](https://github.com/onflow/flow-core-contracts/pull/319)
+to understand how the contracts have changed. Every contract in the repo changed.
+
+Additionally, here are the import addresses
+for all of the important contracts related to the protocol:
+
+| Contract                    | Emulator Import Address | Testing Framework    |
+| --------------------------- | ----------------------- | -------------------- |
+| `FungibleToken`             | `0xee82856bf20e2aa6`    | `0x0000000000000002` |
+| `ViewResolver`              | `0xf8d6e0586b0a20c7`    | `0x0000000000000001` |
+| `Burner`                    | `0xf8d6e0586b0a20c7`    | `0x0000000000000001` |
+| `MetadataViews`             | `0xf8d6e0586b0a20c7`    | `0x0000000000000001` |
+| `FungibleTokenMetadataViews`| `0xee82856bf20e2aa6`    | `0x0000000000000002` |
+| `FlowToken`                 | `0x0ae53cb6e3f42a79`    | `0x0000000000000003` |
+| `FlowFees`                  | `0xe5a8b7f23e8b548f`    | `0x0000000000000004` |
+| `FlowStorageFees`           | `0xf8d6e0586b0a20c7`    | `0x0000000000000001` |
+| `FlowServiceAccount`        | `0xf8d6e0586b0a20c7`    | `0x0000000000000001` |
+| `NodeVersionBeacon`         | `0xf8d6e0586b0a20c7`    | `0x0000000000000001` |
+| `RandomBeaconHistory`       | `0xf8d6e0586b0a20c7`    | `0x0000000000000001` |
+| `LockedTokens`              | `0xf8d6e0586b0a20c7`    | `0x0000000000000001` |
+| `StakingProxy`              | `0xf8d6e0586b0a20c7`    | `0x0000000000000001` |
+| `FlowIDTableStaking`        | `0xf8d6e0586b0a20c7`    | `0x0000000000000001` |
+| `FlowClusterQC`             | `0xf8d6e0586b0a20c7`    | `0x0000000000000001` |
+| `FlowDKG`                   | `0xf8d6e0586b0a20c7`    | `0x0000000000000001` |
+| `FlowEpoch`                 | `0xf8d6e0586b0a20c7`    | `0x0000000000000001` |
+| `FlowStakingCollection`     | `0xf8d6e0586b0a20c7`    | `0x0000000000000001` |
+
+See the other guides in this section of the docs for the import
+addresses of other important contracts in the emulator.
+
+## Upgrade Guide
+
+The NFT guide covers a lot of common changes that are required for NFT contracts,
+but many of these changes will also apply to any contract on Flow, so it is still
+useful to read even if you don't have an NFT contract.
+
+The core contracts do not have any meaningful changes outside of what is required
+to be compatible with Cadence 1.0 and the token standard changes.
+If you have questions about the core contracts changes for Cadence 1.0,
+please reach out to the Flow team in Discord and we will be happy to help.
diff --git a/docs/cadence-migration-guide/ft-guide.mdx b/docs/cadence-migration-guide/ft-guide.mdx
@@ -0,0 +1,99 @@
+---
+title: Fungible Token Cadence 1.0 Migration Guide
+sidebar_position: 3
+sidebar_label: FT Cadence 1.0 Guide
+---
+
+# Fungible Tokens in Cadence 1.0
+
+On September 4th, 2024 the Flow Mainnet upgraded to Cadence 1.0.
+In addition to many changes to the Cadence programming language,
+the Cadence token standards also got streamlined and improved.
+All applications need to migrate their existing Cadence scripts and transactions for the update.
+If you do not update your code, your application will not function.
+
+This document describes the changes to the Cadence Fungible Token (FT) standard.
+We'll be using the
+[`ExampleToken` contract](https://github.com/onflow/flow-ft/blob/master/contracts/ExampleToken.cdc)
+as an example. Many projects have used `ExampleToken` as a starting point for their projects,
+so it is widely applicable to most NFT developers on Flow.
+The upgrades required for `ExampleToken` will cover 90%+ of what you'll
+need to do to update your contract. Each project most likely has
+additional logic or features that aren't included in `ExampleToken`,
+but hopefully after reading this guide, you'll understand Cadence 1.0
+well enough that you can easily make any other changes that are necessary.
+
+As always, there are plenty of people on the Flow team and in the community
+who are happy to help answer any questions you may have, so please reach out
+in Discord if you need any help.
+
+# Important Info
+
+Please read [the FLIP](https://github.com/onflow/flips/pull/55)
+that describes the changes to the `FungibleToken` standard first.
+
+The updated code for the V2 Fungible Token standard is located in the
+[`master` branch of the flow-ft repo](https://github.com/onflow/flow-ft).
+Please look at the [PR that made the changes](https://github.com/onflow/flow-ft/pull/131)
+to understand how the standard and examples have changed.
+Note the changes to the `FungibleTokenMetadataViews`,
+`Burner`, `FungibleTokenSwitchboard`, and `TokenForwarding` contracts.
+
+Additionally, here are the import addresses
+for all of the important contracts related to fungible tokens.
+The second column is the import address if you are testing with a basic version of the emulator.
+The third column contains the import addresses if you are using the Cadence testing framework.
+
+| Contract                    | Emulator Import Address | Testing Framework    |
+| --------------------------- | ----------------------- | -------------------- |
+| `FungibleToken`             | `0xee82856bf20e2aa6`    | `0x0000000000000002` |
+| `ViewResolver`              | `0xf8d6e0586b0a20c7`    | `0x0000000000000001` |
+| `Burner`                    | `0xf8d6e0586b0a20c7`    | `0x0000000000000001` |
+| `MetadataViews`             | `0xf8d6e0586b0a20c7`    | `0x0000000000000001` |
+| `FungibleTokenMetadataViews`| `0xee82856bf20e2aa6`    | `0x0000000000000002` |
+| `FungibleTokenSwitchboard`  | `0xee82856bf20e2aa6`    | `0x0000000000000002` |
+
+See the other guides in this section of the docs for the import
+addresses of other important contracts in the emulator.
+
+As for contracts that are important for NFT developers but aren't "core contracts",
+here is information about where to find the Cadence 1.0 versions of each:
+
+**USDC:** USDC was migrated to standard bridged USDC on Flow. See the [repo](https://github.com/onflow/bridged-usdc) for the latest version of the USDC contract.
+
+**Account Linking and Hybrid Custody:**
+See [this PR in the hybrid custody repo](https://github.com/onflow/hybrid-custody/pull/164)
+for updated hybrid custody contracts.
+
+[This Discord announcement](https://discord.com/channels/613813861610684416/811693600403357706/1225909248429527140)
+also contains versions of a lot of important contracts.
+
+Use the [Flow Contract Browser](https://contractbrowser.com/) to find the 1.0 code of other contracts.
+
+# Migration Guide
+
+Please see the [NFT Cadence 1.0 migration guide](./nft-guide.mdx).
+While the contracts aren't exactly the same, they share a huge amount of functionality,
+and the changes described in that guide will cover 90% of the changes
+that are needed for fungible tokens, so if you just follow those instructions
+for your fungible token contract, you'll be most of the way there.
+
+Here, we will only describe the changes that are specific to the fungible token standard.
+
+## `Vault` implements `FungibleToken.Vault`
+
+`FungibleToken.Vault` is no longer a resource type specification.
+It is now an interface that inherits from `Provider`, `Receiver`, `Balance`,
+`ViewResolver.Resolver`, and `Burner.Burnable`.
+
+Since `Vault` is an interface, you will need to update every instance in your code
+that refers to `@FungibleToken.Vault` or `&FungibleToken.Vault` to
+`@{FungibleToken.Vault}` or `&{FungibleToken.Vault}` respectively to show
+that it is now an interface specification instead of a concrete type specification.
+Example in `deposit()`:
+```cadence
+/// deposit now accepts a resource that implements the `FungibleToken.Vault` interface type
+access(all) fun deposit(from: @{FungibleToken.Vault})
+```
+
+If you have any more questions, please ask in discord and the Flow team will be happy to assist!