| status | flip | authors | sponsor | updated |
|---|---|---|---|---|
Implemented |
56 |
Joshua Hannan (joshua.hannan@flowfoundation.org) |
Joshua Hannan (joshua.hannan@flowfoundation.org) |
2024-03-11 |
This FLIP proposes multiple updates to the Flow Non-Fungible Token
Standard contracts as part of the Cadence 1.0 upgrade,
primarily about adding support for defining multiple token types
in one contract, adding standard events, integrating ViewResolver,
adding support for updating NFTs, adding support for sub-NFTs, and adding entitlements
Some of these changes are dependent on other Cadence FLIPs that made fundamental changes to the language that have been approved and implemented, primarily interface inheritance, removal of nested type requirements, removal of custom destructors, and allowing interfaces to emit events.
The changes proposed here will be breaking for all non-fungible token implementations on the Flow blockchain, as well as contracts that utilize tokens based on the standard, third-party integrations such as event listeners, and apps that interface with the contracts.
The current non-fungible token standard for Flow was designed in mid 2019, at a time when Cadence itself was still being designed. The current standard, though functional, leaves much to be desired.
The current token standard uses contract interfaces and nested type requirements.
They are designed in a way that requires each concrete contract
to provide exactly one NFT and one Collection type.
This means that any project that needs multiple tokens must deploy multiple contracts.
In the case of very simple tokens, this is a lot of complexity for very little value.
Related to this problem, functionality and metadata associated with some tokens, such as paths and empty vault creation methods is only accessible directly through the contract itself, when it should also be accessible directly through an instance of a token resource and/or interface.
Many contracts also do not implement MetadataViews properly because there is no requirement for it in the standard.
In the case of events, currently there is no way for the standard to ensure that implementations are emitting standardized and correct events, which this upgrade will address.
With these upgrades, users will now be able to:
- Define multiple tokens in a single contract.
- Query all the data about a token directly through the contract as well as the
Vaultresource and core interfaces. - Have standard events emitted correctly for important operations (
Withdrawn,Deposited,Updated, andNonFungibleToken.NFT.ResourceDestroyed). - Support querying information about NFTs that an NFT directly owns.
- Check if a
Receiveraccepts a given token type.
The original proposal is on the Flow Forum. A pull request with the suggested code changes is in the flow fungible token github repository.
The main code changes and their implications are described here. The linked proposals provide more context, though the proposal in the forum post is quite out of date.
Now that nested type requirements have been removed, contracts can define
multiple token types. The type information can be accessed by using the built-in
contract.publicTypes(): [Type] method. A return value of this is now required
in the NonFungibleToken.createEmptyCollection(nftType: Type) method because
the caller needs to specify which type they are looking for.
ViewResolver has also been updated to require type information
when querying views from a contract:
access(all) contract interface ViewResolver {
/// Function that returns all the Metadata Views implemented by the resolving contract.
/// Some contracts may have multiple resource types that support metadata views
/// so there is an optional parameter for specify which resource type the caller
/// is looking for views for.
/// Some contract-level views may be type-agnostic. In that case, the contract
/// should return the same views regardless of what type is passed in.
///
/// @param resourceType: An optional resource type to return views for
/// @return An array of Types defining the implemented views. This value will be used by
/// developers to know which parameter to pass to the resolveView() method.
///
access(all) view fun getContractViews(resourceType: Type?): [Type]
/// Function that resolves a metadata view for this token.
/// Some contracts may have multiple resource types that support metadata views
/// so there there is an optional parameter to specify which resource type the caller
/// is requesting views for.
/// Some contract-level views may be type-agnostic. In that case, the contract
/// should return the same views regardless of what type is passed in.
///
/// @param resourceType: An optional resource type to return views for
/// @param view: The Type of the desired view.
/// @return A structure representing the requested view.
///
access(all) fun resolveContractView(resourceType: Type?, viewType: Type): AnyStruct?
}While all contracts that implement the NonFungibleToken standard
will need to implement these functions, many of them will still
only have a single token type in their contract.
Therefore, they can ignore the resourceType parameter.
In addition to these changes to ViewResolver, the MetadataViews.Resolver
resource interface has been moved to the ViewResolver contract because
this is the logical place for it to live and it also avoids a circular dependency.
Instead of requiring events to be defined in the token implementations contracts, they will only be defined in the non-fungible token standard smart contract and will be emitted in post-conditions from the correct methods in the resource interfaces defined in the standard.
Standard events contain more information about the NFT that is being transferred, such as the type of the NFT and important metadata about the transfer. This includes UUIDs of the collections involved in the token movements in case this information is useful.
Here is an example of the proposal:
/// The event that is emitted when tokens are withdrawn from a Vault
access(all) event Withdrawn(type: String, amount: UFix64, from: Address?, fromUUID: UInt64, withdrawnUUID: UInt64)It is useful to be able to query a non-fungible token receiver to see what types of tokens it can accept.
access(all) resource interface Receiver {
/// getSupportedNFTTypes returns a list of NFT types that this receiver accepts
/// @return A dictionary of types mapped to booleans indicating if this
/// reciever supports it
access(all) view fun getSupportedNFTTypes(): {Type: Bool}
/// Returns whether or not the given type is accepted by the collection
/// A collection that can accept any type should just return true by default
/// @param type: An NFT type
/// @return A boolean indicating if this receiver can recieve the desired NFT type
access(all) view fun isSupportedNFTType(type: Type): Bool
}In the current standard, borrowNFT() is meant to panic if the NFT to borrow
is not found in the collection. This is clearly the wrong choice, because
it is a best practice to have getter functions return nil if something goes wrong
instead of panicking and reverting the transaction.
access(all) view fun borrowNFT(_ id: UInt64): &{NFT}?The requirement to include an ownedNFTs: {UInt64: @NFT} field
in Collection implementations is restrictive because developers may want
to store tokens in a unique way that is different what what could be specified.
This proposal removes ownedNFTs and only requires a getIDs() method
for the collection to indicate which IDs it contains.
Move createEmptyCollection() to inside the NFT and Collection definitions in addition to the contract
It is useful to be able to create a new empty collection
directly from an NFT or a Collection object instead of having to import
the contract and call the method from the contract.
access(all) resource interface Collection {
/// createEmptyCollection creates an empty Collection
/// and returns it to the caller so that they can own NFTs
access(all) fun createEmptyCollection(): @{Collection} {
post {
result.getType() == self.getType(): "The created collection does not have the same type as this collection"
result.getLength() == 0: "The created collection must be empty!"
}
}
}Metadata Views for non-fungible tokens should be easily accessible
from interfaces defined by the standard.
This proposal enforces that implementations implement the ViewResolver contract interface,
NFT implementations implement the ViewResolver.Resolver interface,
and Collection implementations implement the ViewResolver.ResolverCollection interface.
A powerful feature of Cadence is that resources can own other resources.
Many NonFungibleToken implementations make it possible for their NFTs to own other
NFTs. The standard is being updated to support
querying information about these sub-NFTs.
It is not required though, so default implementations that return empty values are provided.
access(all) resource interface NFT {
/// Gets all the NFTs that this NFT directly owns
/// @return A dictionary of all subNFTS keyed by type
access(all) view fun getAvailableSubNFTS(): {Type: UInt64} {
return {}
}
/// Get a reference to an NFT that this NFT owns
/// Both arguments are optional to allow the NFT to choose
/// how it returns sub NFTs depending on what arguments are provided
/// For example, if `type` has a value, but `id` doesn't, the NFT
/// can choose which NFT of that type to return if there is a "default"
/// If both are `nil`, then NFTs that only store a single NFT can just return
/// that. This helps callers who aren't sure what they are looking for
///
/// @param type: The Type of the desired NFT
/// @param id: The id of the NFT to borrow
///
/// @return A structure representing the requested view.
access(all) fun getSubNFT(type: Type, id: UInt64) : &{NonFungibleToken.NFT}? {
return nil
}
}Many projects support updating metadata or stored fields for their NFTs.
It is important that these projects have a standard way to indicate
that an NFT has been updated. The standard defines an
Update event
that any project can access to say that an NFT is updated:
access(all) event Updated(type: String, id: UInt64, uuid: UInt64, owner: Address?)
access(contract) view fun emitNFTUpdated(_ nftRef: auth(Update | Owner) &{NonFungibleToken.NFT})
{
emit Updated(type: nftRef.getType().identifier, id: nftRef.id, uuid: nftRef.uuid, owner: nftRef.owner?.address)
}The emitNFTUpdated event is used to emit the event and can only be called
with an Update or Owner-entitled reference to the NFT that has been updated.
Projects should NOT override the default implementation of emitNFTUpdated()
or they will lose access to the standard event.
They still will call it using the name of their contract though. So if Top Shot were to want to emit the event, the syntax would look like this:
TopShot.emitNFTUpdated(nftReference)The main drawback of this upgrade is the breaking changes. It could cause downtime for some projects who aren't prepared to perform the upgrade right after stable cadence is enabled, but that applies to any breaking change in stable cadence. The updates that developers will have to do are fairly straightforward and will not require much work.
Please share any other drawbacks that you may discover with these changes.
- Keep the standard the same:
- If nested type requirements are removed, this may not be possible
- This would avoid the breaking changes, which would be nice in the short term, but would not be setting up cadence developers for success in the long term.
- Make
NonFungibleTokena contract instead of an interface:- This would allow the contract to have utility methods to have more fine-grained control
over how standard events are emitted, but would not allow the standard
to enforce that implementations use the
ViewResolverinterface and have thecreateEmptyCollection(vaultType: Type)function.
- This would allow the contract to have utility methods to have more fine-grained control
over how standard events are emitted, but would not allow the standard
to enforce that implementations use the
Most of the methods in the non-fungible token interface are expected to be O(1), so there is no performance requirements to enforce with the methods. That is mostly up to the developers who are implementing the tokens to ensure.
The getIDs() method can sometimes return a list that is too large for
the transaction or script to handle. We'd like to have some sort of method
that returns a paginated list of IDs instead of the whole list.
Any proposals for that would be appreciated,
but it will likely require a Cadence language update.
- Adds no new dependencies
- Dependent projects
- All non-fungible tokens on Flow and some projects that utilize them.
- Build and test time will stay the same. they are relatively small changes.
- The Flow smart contract engineering team will maintain the code
- The code can be tested on its own once a compatible version of cadence is released.
- Some of the changes illustrate Cadence best practices, such as encapsulating functionality within resources, avoiding public fields, and giving developers flexibility to write composable code.
- Check out the Cadence 1.0 migration guide for instructions on how to update contracts to the new standards:
- FCL, emulator, and other such tools should not be affected besides potentially having to update standard transactions if they aren't compatible.
- The upgrade will go out at the same time as stable cadence if approved
A critical piece of tooling for non-fungible tokens would be a struct that contains a provider capability but restricts the capability to only be able to withdraw specified IDs or number of tokens from the underlying collection. Currently, providers have no limit, but all tokens should be able to create scoped providers.
This feature is out of the scope of this proposal, but should definitely be a standard that lives alongside the main fungible token standard. We hope to shepherd a proposal for these soon.
Each NFT implementor also needs to implement their own Collection resource. The Collection implementation of the Example NFT contract is 5x as long as the NFT implementation itself. Almost all collection code is copied, so it could be very nice to have a universal collection that can hold any type of NFT.
There is a universal collection implementation in the branch where the new standard is, but that will be discussed an another place.
In combination with the upgrades to the FT standard, we'd like for users to be able to utilize more sophisticated functionality in their tokens, such as what was enabled with an upgrade like ERC-1155 and other such upgrades in Ethereum. We would greatly appreciate if any developers with ethereum experience could think about these upgrades from the perspective of being able to create the same kinds of projects that are possible with other token standards in other languages.