Skip to content

Commit

Permalink
Merge branch 'main' of https://github.com/onflow/cadence-lang.org int…
Browse files Browse the repository at this point in the history 
…o supun/contract-updatability
  • Loading branch information
@SupunS
SupunS committed Oct 22, 2024
2 parents ffe5729 + 7079a21 commit 950efd9
Show file tree
Hide file tree
Showing 69 changed files with 2,829 additions and 3,995 deletions.
32 changes: 13 additions & 19 deletions docs/cadence-migration-guide/core-contracts-guide.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,30 +6,24 @@ sidebar_label: Core Contracts Guide

## Protocol Smart Contracts in Cadence 1.0

In 2024, the network will be upgrading to 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
are also being updated to be compatible with the changes.
also 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.
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 updates](https://forum.flow.com/t/update-on-cadence-1-0/5197) and modifications to the Fungible Token Standard. We encourage you to consult those guides for more details on these changes if you are interested.
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 [`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.

Please see the latest post in [this forum thread](https://forum.flow.com/t/update-on-cadence-1-0/5197/8)
to find the latest version of the CLI and emulator that you should be testing with.

It is also important to remember that after you've made your changes to your contracts,
you will have to stage the upgrades on testnet and mainnet in order for them
to be upgraded and migrated properly. You can find informaion about how to do that
here: https://github.com/onflow/contract-updater
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:
Expand Down Expand Up @@ -66,5 +60,5 @@ 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.
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.
105 changes: 0 additions & 105 deletions docs/cadence-migration-guide/emulator-state-migration-guide.mdx
View file

This file was deleted.

169 changes: 25 additions & 144 deletions docs/cadence-migration-guide/ft-guide.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,28 +6,24 @@ sidebar_label: FT Cadence 1.0 Guide

# Fungible Tokens in Cadence 1.0

In 2024, the network will be upgrading to 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 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.
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 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)
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
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
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.

Expand All @@ -37,18 +33,11 @@ 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`.

Please see the latest post in [this forum thread](https://forum.flow.com/t/update-on-cadence-1-0/5197/8)
to find the latest version of the CLI and emulator that you should be testing with.

It is also important to remember that after you've made your changes to your contracts,
you will have to stage the upgrades on testnet and mainnet in order for them
to be upgraded and migrated properly. You can find informaion about how to do that
here: https://github.com/onflow/contract-updater
[`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.
Expand All @@ -68,26 +57,23 @@ 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:
here is information about where to find the Cadence 1.0 versions of each:

**USDC:** See [this PR in the USDC repo](https://github.com/flow-usdc/flow-usdc/pull/82)
for updated USDC contracts.
**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)
**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)
[This Discord announcement](https://discord.com/channels/613813861610684416/811693600403357706/1225909248429527140)
also contains versions of a lot of important contracts.

For any other contracts, search for their github repo and there will likely be
a PR or feature branch with the Cadence 1.0 changes. If there isn't, please
create an issue in the repo or reach out to that team directly via their support
or Discord channel to ask them about their plans to update their 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). While
the contracts aren't exactly the same, they share a huge amount of functionality,
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.
Expand All @@ -100,119 +86,14 @@ Here, we will only describe the changes that are specific to the fungible token
It is now an interface that inherits from `Provider`, `Receiver`, `Balance`,
`ViewResolver.Resolver`, and `Burner.Burnable`.

To ensure compatibility, [update your `Vault` interface conformance list to only
implement `FungibleToken.Vault`](https://github.com/onflow/flow-ft/pull/131/files#diff-dcb2cd49f7f399806400b83a9695278b867b9937d195d6f45063bc000d146223R82):
```cadence
access(all) resource Vault: FungibleToken.Vault {
```
In addition, since `Vault` is an interface, you will need to update every instance in your code
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()`:
Example in `deposit()`:
```cadence
/// deposit now accepts a resource that implements the `FungibleToken.Vault` interface type
access(all) fun deposit(from: @{FungibleToken.Vault})
```

**Note for Custom Migrations:** All stored objects that currently use the concrete type
`FungibleToken.Vault` will be automatically migrated to use the interface type `{NonFungibleToken.Vault}`
as part of the Flow team's custom state migrations.
Your code still needs to be updated to reflect this though.

## Add `Withdraw` entitlements to `withdraw()`

Now that unrestricted casting is possible in Cadence, it is necessary to use
[entitlements](https://cadence-lang.org/docs/1.0/language/access-control#entitlements)
to restrict access to privledged functions in any composite type.

The only default method that needs to be restricted is the `withdraw` method:
```cadence
access(FungibleToken.Withdraw) fun withdraw(amount: UFix64): @ExampleToken.Vault {
```
This means that you can only call the `withdraw` method if you control the actual object
or if you have an `auth(FungibleToken.Withdraw)` entitled reference to it.

So in a typical transfer transaction when you need to withdraw from a vault,
you would get the reference like this:
```cadence
// Get a reference to the signer's stored vault
let vaultRef = signer.storage.borrow<auth(FungibleToken.Withdraw) &ExampleToken.Vault>(from: self.vaultData.storagePath)
?? panic("Could not borrow reference to the owner's Vault!")
```
From the [flow-ft `transfer_tokens.cdc` transaction](https://github.com/onflow/flow-ft/blob/v2-standard/transactions/transfer_tokens.cdc).

## Use the new `Burner` contract if desired

Custom destructors were removed as part of Cadence 1.0, so `destroy` blocks
in resource definitions are no longer allowed. If you were using the `destroy`
block to emit a custom event or subtract the destroyed tokens' supply from your
token's total supply and still want that functionality, you'll need to
[use the `burnCallback()` method from the `Burner` smart contract](https://github.com/onflow/flow-ft/pull/131/files#diff-dcb2cd49f7f399806400b83a9695278b867b9937d195d6f45063bc000d146223R100-R106):

```
/// Called when a fungible token is burned via the `Burner.burn()` method
access(contract) fun burnCallback() {
if self.balance > 0.0 {
ExampleToken.totalSupply = ExampleToken.totalSupply - self.balance
}
self.balance = 0.0
}
```

This will automatically be executed if a Vault is destroyed
via the `Burner.burn()` method. It will emit a standard event to indicate the destruction,
so no need to include one yourself unless you need
to emit other information besides the balance and type.

As shown above, this is also where you can subtract the destroyed tokens from the
total supply. This function requires you to set the balance of the vault to zero
before the function execution completes though. This is to prevent spam.

## Add `isAvailableToWithdraw` method

Some more complex types that implement `Provider` may want a more efficient way
to describe if a desired amount of tokens can be withdrawn.
`isAvailableToWithdraw` allows that.

[The `Vault` implementation is simple though](https://github.com/onflow/flow-ft/pull/131/files#diff-dcb2cd49f7f399806400b83a9695278b867b9937d195d6f45063bc000d146223R127-R130):
```cadence
/// In `ExampleToken.Vault`
/// Asks if the amount can be withdrawn from this vault
access(all) view fun isAvailableToWithdraw(amount: UFix64): Bool {
return amount <= self.balance
}
```

## Remove Private Path and Type fields

Since private paths were removed in Cadence 1.0, these fields are no longer needed,
so remove the code that returns them in your `resolveView` method for `FTVaultData`:
```cadence
/// In `ExampleToken.resolveContractView()`
///
case Type<FungibleTokenMetadataViews.FTVaultData>():
return FungibleTokenMetadataViews.FTVaultData(
storagePath: /storage/exampleTokenVault,
receiverPath: /public/exampleTokenReceiver,
metadataPath: /public/exampleTokenVault,
/// REMOVED: providerPath
receiverLinkedType: Type<&ExampleToken.Vault>(),
metadataLinkedType: Type<&ExampleToken.Vault>(),
/// REMOVED: providerLinkedType
createEmptyVaultFunction: (fun(): @{FungibleToken.Vault} {
return <-ExampleToken.createEmptyVault(vaultType: Type<@ExampleToken.Vault>())
})
)
```

Private paths are no longer able to be used in Cadence across the board,
so you'll need to find other ways to do what you were doing with them before.
This will likely involve [Capability Controllers](https://github.com/onflow/flips/blob/main/cadence/20220203-capability-controllers.md).

## Conclusion

This guide briefly covered the Cadence 1.0 changes that are specific to Fungible Tokens.
If you have any more questions or would like additional sections to be added to the guide,
please create an issue in [the cadence-lang.org repo](https://github.com/onflow/cadence-lang.org)
or ask in discord and the flow team will be happy to assist!
If you have any more questions, please ask in discord and the Flow team will be happy to assist!
4 changes: 2 additions & 2 deletions docs/cadence-migration-guide/improvements.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1688,7 +1688,7 @@ resource SubResource {
resource R {
let subR: @SubResource
init(id: Int) {
self.subR <- create SubResource(id: id)
}
Expand All @@ -1713,7 +1713,7 @@ resource SubResource {
resource R {
let subR: @SubResource
init(id: Int) {
self.subR <- create SubResource(id: id)
}
Expand Down
Loading

0 comments on commit 950efd9

Please sign in to comment.