Merge pull request #42 from onflow/josh/add-migration-guides

Adds placeholders for guides with important info about token standard upgrades.

docs/anti-patterns.md

@@ -1,6 +1,6 @@
 ---
 title: Cadence Anti-Patterns
-sidebar_position: 6
+sidebar_position: 7
 sidebar_label: Anti-Patterns
 ---
 

docs/cadence_migration_guide/_category_.json

@@ -0,0 +1,3 @@
+{
+    "position": 5
+}

docs/cadence_migration_guide/core-contracts-guide.mdx

@@ -0,0 +1,56 @@
+---
+title: Protocol Smart Contracts 1.0 Changes Guide
+sidebar_position: 4
+sidebar_label: Core Contracts Guide
+---
+
+# Protocol Smart Contracts in Cadence 1.0
+
+In 2024, the network will be upgrading to Cadence 1.0. 
+In addition to many changes to the Cadence programming language and
+the Cadence token standards, the flow protocol smart contracts
+are also being updated to be compatible with the changes.
+
+All applications and smart contracts that interact with these contracts
+will need to update their transactions and scripts in order to be compatible with the changes.
+
+# Important Info
+
+We are assuming that you are somewhat familiar with
+[the Cadence 1.0 changes](https://forum.flow.com/t/update-on-cadence-1-0/5197)
+and the changes to the fungible token standard for this document. Please
+read those guides if you are curious about those changes.
+
+The updated code for the Cadence 1.0 versions of the protocol smart contracts
+is locaed in the [`stable-cadence` branch of the flow-core-contracts repo](https://github.com/onflow/flow-core-contracts/pull/319).
+Please look at the changes there to understand how the contracts have changed.
+Every contract in the repo is changing.
+
+In the latest version of the emulator, here are the import addresses
+for all of the important contracts related to the protocol:
+
+| Contract                    | Emulator Import Address |
+| --------------------------- | ----------------------- |
+| `FungibleToken`             | `0xee82856bf20e2aa6`    |
+| `ViewResolver`              | `0xf8d6e0586b0a20c7`    |
+| `Burner`                    | `0xf8d6e0586b0a20c7`    |
+| `MetadataViews`             | `0xf8d6e0586b0a20c7`    |
+| `FungibleTokenMetadataViews`| `0xee82856bf20e2aa6`    |
+| `FlowToken`                 | `0x0ae53cb6e3f42a79`    |
+| `FlowFees`                  | `0xe5a8b7f23e8b548f`    |
+| `FlowStorageFees`           | `0xf8d6e0586b0a20c7`    |
+| `FlowServiceAccount`        | `0xf8d6e0586b0a20c7`    |
+| `NodeVersionBeacon`         | `0xf8d6e0586b0a20c7`    |
+| `RandomBeaconHistory`       | `0xf8d6e0586b0a20c7`    |
+| `LockedTokens`              | `0xf8d6e0586b0a20c7`    |
+| `StakingProxy`              | `0xf8d6e0586b0a20c7`    |
+| `FlowIDTableStaking`        | `0xf8d6e0586b0a20c7`    |
+| `FlowClusterQC`             | `0xf8d6e0586b0a20c7`    |
+| `FlowDKG`                   | `0xf8d6e0586b0a20c7`    |
+| `FlowEpoch`                 | `0xf8d6e0586b0a20c7`    |
+| `FlowStakingCollection`     | `0xf8d6e0586b0a20c7`    |
+
+
+# Upgrade Guide
+
+Coming soon!

docs/cadence_migration_guide/ft-guide.mdx

@@ -0,0 +1,59 @@
+---
+title: Fungible Token Cadence 1.0 Migration Guide
+sidebar_position: 3
+sidebar_label: FT Cadence 1.0 Guide
+---
+
+# Fungible Tokens in Cadence 1.0
+
+In 2024, the network will be upgrading to Cadence 1.0. 
+In addition to many changes to the Cadence programming language,
+the Cadence token standards are also being streamlined and improved.
+All applications will need to prepare and migrate their existing
+Cadence smart contracts, scripts, and transactions for the update.
+If you do not update your code, your applications will become non-functional
+after the network upgrade.
+
+This document describes the changes to the Cadence Fungible Token (FT) standard and
+gives a step-by-step guide for how to upgrade your FT contract from Cadence 0.42
+to Cadence 1.0.
+
+We'll be using the [`ExampleToken` contract](https://github.com/onflow/flow-ft/blob/v2-standard/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
+[`v2-standard` branch of the flow-ft repo](https://github.com/onflow/flow-ft/pull/131).
+Please look at the changes there to understand how the standard and examples have changed.
+This branch also includes the updated versions of `FungibleTokenMetadataViews`,
+`Burner`, `FungibleTokenSwitchboard`, and `TokenForwarding`.
+
+In the latest version of the emulator, here are the import addresses
+for all of the important contracts related to fungible tokens:
+
+| Contract                    | Emulator Import Address |
+| --------------------------- | ----------------------- |
+| `FungibleToken`             | `0xee82856bf20e2aa6`    |
+| `ViewResolver`              | `0xf8d6e0586b0a20c7`    |
+| `Burner`                    | `0xf8d6e0586b0a20c7`    |
+| `MetadataViews`             | `0xf8d6e0586b0a20c7`    |
+| `FungibleTokenMetadataViews`| `0xee82856bf20e2aa6`    |
+| `FungibleTokenSwitchboard`  | `0xee82856bf20e2aa6`    |
+
+# Upgrade Guide
+
+Coming soon!

docs/cadence-migration-guide.md → docs/cadence_migration_guide/index.md

@@ -1,22 +1,24 @@
 ---
 title: Cadence 1.0 Migration Guide
+sidebar_position: 1
 sidebar_label: Cadence 1.0 Migration Guide
-sidebar_position: 3
 ---
 
 # Cadence 1.0 Migration Guide
 
-Coming in 2024, the network will be upgrading to the Cadence 1.0. This means that all applications will need to prepare and migrate their existing Cadence smart contracts, scripts, and transactions for the update. If you do not update your contracts, your applications will become non-functional after the network upgrade. The specific upgrade date will be announced later.
+Coming in 2024, the network will be upgrading to the Cadence 1.0. This means that all applications will need to prepare and migrate their existing Cadence smart contracts, scripts, and transactions for the update. If you do not update your code, your applications will become non-functional after the network upgrade. The specific upgrade date will be announced later.
 
 We have created several resources to help developers update their applications. Use the following links to start upgrading your contracts and to understand how the network upgrade will affect your application:
 
 - [Understand the upgrade, the timeline, and how it affects you](https://forum.flow.com/t/cadence-1-0-upgrade-plan/5477)
 - [Learn how Cadence will be changing for 1.0](https://forum.flow.com/t/update-on-cadence-1-0/5197)
 - [Learn how to update your Flow CLI to test against Cadence 1.0](https://forum.flow.com/t/update-on-cadence-1-0/5197/7)
+- [Learn how to update your Non-Fungible Token contracts for Cadence 1.0](./nft-guide.mdx)
+- [Learn how to update your Fungible Token contracts for Cadence 1.0](./ft-guide.mdx)
 - [Check out the Cadence language 1.0 docs](https://cadencelang.dev/docs/1.0/)
 
 ## Get Help With Migrating Your Dapp to Cadence 1.0
 
 If you have any questions related to Cadence 1.0 migration, or if you need help, please contact the Flow development community on [developer-questions Discord channel](https://discord.com/channels/613813861610684416/621847426201944074). Please use “C1.0 upgrade” at the beginning of the message to help us categorize questions related to Cadence 1.0.
 
-We will soon start hosting regular "Cadence 1.0 upgrade office hours" events anyone can join to ask questions and get help with their dapp upgrade. These sessions will be scheduled in [Flow Webinars & Events calendar](https://calendar.google.com/calendar/u/0?cid=Y180Nzk3OGY1Y2Q5ZGE2MzZjYWRjNmI4NDczMTAyYjUwOTJjMWE4NjVkZDAxMDU1ODM5M2VjYjdmOWZkMGM5YWQwQGdyb3VwLmNhbGVuZGFyLmdvb2dsZS5jb20) and announced on [flow-events Discord channel](https://discord.com/channels/613813861610684416/1050190147100102787).
+The Flow team has started hosting regular "Cadence 1.0 upgrade office hours" events anyone can join to ask questions and get help with their dapp upgrade. These sessions are scheduled in [Flow Webinars & Events calendar](https://calendar.google.com/calendar/u/0?cid=Y180Nzk3OGY1Y2Q5ZGE2MzZjYWRjNmI4NDczMTAyYjUwOTJjMWE4NjVkZDAxMDU1ODM5M2VjYjdmOWZkMGM5YWQwQGdyb3VwLmNhbGVuZGFyLmdvb2dsZS5jb20) and announced on [flow-events Discord channel](https://discord.com/channels/613813861610684416/1050190147100102787).

docs/cadence_migration_guide/nft-guide.mdx

@@ -0,0 +1,59 @@
+---
+title: Non-Fungible Token Cadence 1.0 Migration Guide
+sidebar_position: 2
+sidebar_label: NFT Cadence 1.0 Guide
+---
+
+# Non-Fungible Tokens in Cadence 1.0
+
+In 2024, the network will be upgrading to Cadence 1.0. 
+In addition to many changes to the Cadence programming language,
+the Cadence token standards are also being streamlined and improved.
+All applications will need to prepare and migrate their existing
+Cadence smart contracts, scripts, and transactions for the update.
+If you do not update your code, your applications will become non-functional
+after the network upgrade.
+
+This document describes the changes to the Cadence Non-Fungible Token (NFT) standard and
+gives a step-by-step guide for how to upgrade your NFT contract from Cadence 0.42
+to Cadence 1.0.
+
+We'll be using the [`ExampleNFT` contract](https://github.com/onflow/flow-nft/blob/standard-v2/contracts/ExampleNFT.cdc)
+as an example. Many projects have used `ExampleNFT` as a starting point for their projects,
+so it is widely applicable to most NFT developers on Flow.
+The upgrades required for `ExampleNFT` 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 `ExampleNFT`,
+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/56)
+that describes the changes to the `NonFungibleToken` standard first.
+
+The updated code for the V2 Fungible Token standard is locaed in the
+[`standard-v2` branch of the flow-nft repo](https://github.com/onflow/flow-nft/pull/126).
+Please look at the changes there to understand how the standard and examples have changed.
+This branch also includes the updated versions of `MetadataViews`, `ViewResolver`,
+and `NFTForwarding`.
+
+In the latest version of the emulator, here are the import addresses
+for all of the important contracts related to non-fungible tokens:
+
+| Contract                    | Emulator Import Address |
+| --------------------------- | ----------------------- |
+| `NonFungibleToken`          | `0xf8d6e0586b0a20c7`    |
+| `FungibleToken`             | `0xee82856bf20e2aa6`    |
+| `ViewResolver`              | `0xf8d6e0586b0a20c7`    |
+| `Burner`                    | `0xf8d6e0586b0a20c7`    |
+| `MetadataViews`             | `0xf8d6e0586b0a20c7`    |
+
+# Upgrade Guide
+
+Coming soon!
+

docs/design-patterns.md

@@ -1,6 +1,6 @@
 ---
 title: Cadence Design Patterns
-sidebar_position: 5
+sidebar_position: 6
 sidebar_label: Design Patterns
 ---
 

docs/project-development-tips.md

@@ -1,7 +1,7 @@
 ---
 title: Flow Smart Contract Project Development Standards
 sidebar_label: Development Standards
-sidebar_position: 7
+sidebar_position: 8
 description: "Learn how to effectively organize and manage a Cadence project"
 ---
 

docs/security-best-practices.md

@@ -1,7 +1,7 @@
 ---
 title: Cadence Security Best Practices
 sidebar_label: Security Best Practices
-sidebar_position: 7
+sidebar_position: 8
 ---
 
 This is an opinionated list of best practices Cadence developers should follow to write more secure Cadence code.

docs/solidity-to-cadence.md

@@ -1,6 +1,6 @@
 ---
 title: Guide for Solidity developers
-sidebar_position: 8
+sidebar_position: 9
 ---
 Cadence introduces a different way to approach smart contract development which may feel unfamiliar to
 Solidity developers. There are fundamental mindset and platform differences, and also several new language