This is a description of the work-in-progress standard for non-fungible token contracts on the Flow Blockchain. It is meant to contain the minimum functionality to implement a safe, secure, easy to understand, and easy to use non-fungible token contract in Cadence.
Flow is a new blockchain for open worlds. Read more about it here.
Cadence is a new Resource-oriented programming language for developing smart contracts for the Flow Blockchain. Read more about it here
We recommend that anyone who is reading this should have already completed the Cadence Tutorials so they can build a basic understanding of the programming language.
Resource-oriented programming, and by extension Cadence, is the perfect programming environment for Non-Fungible Tokens (NFTs), because users are able to store their NFT objects directly in their accounts and transact peer-to-peer. Please see the blog post about resources to understand why they are perfect for digital assets.
Flow and Cadence are both still in development, so this standard will still be going through a lot of changes as the protocol and language evolves, and as we receive feedback from the community about the standard.
We'd love to hear from anyone who has feedback. Main feedback we are looking for is:
- Are there any features that are missing from the standard?
- Are the features that we have included defined in the best way possible?
- Are there any pre and post conditions that are missing?
- Are the pre and post conditions defined well enough? Error messages?
- Are there any other actions that need an event defined for them?
- Are the current event definitions clear enough and do they provide enough information?
- Are the variable, function, and parameter names descriptive enough?
- Are there any openings for bugs or vulnerabilities that we are not noticing?
Please create an issue in this repo if there is a feature that you believe needs discussing or changing.
These features are the ones that are specified in the interface for NFTs. Please be aware, that a NFT contract that implements the interface can include other features in addition to these if they so wish. Also be aware that with the way that Cadence smart contracts define objects and with how objects can be integrated easily into other contracts, many more actions and features are possible even with a contract that only defines the bare minimim functionality.
The main interface requires that implementing types define a NFT
resource
and a Collection
resource that contains and manages these NFTs.
- Get the total number of tokens that have been created by the contract
pub var totalSupply: UInt64
- Event that gets emitted when the contract is initialized
event ContractInitialized()
- unique identifier
pub let id: UInt64
- function to borrow a reference to a specific NFT in the collection
pub fun borrowNFT(id: UInt64): &NonFungibleToken.NFT
- the caller can read fields and call functions on the NFT with the reference
- withdraw event
event Withdraw(id: UInt64, from: Address?)
- Provider interface
pub fun withdraw(withdrawID: UInt64): @NonFungibleToken.NFT
- deposit event
event Deposit(id: UInt64, to: Address?)
- Receiver interface
pub fun deposit(token: @NonFungibleToken.NFT)
- IMPORTANT: In order to comply with the deposit function in the interface, an implementation MUST take a
@NonFungibleToken.NFT
resource as an argument. This means that anyone can send a resource object that conforms to@NonFungibleToken.NFT
to a deposit function. In an implementation, you MUST cast thetoken
as your specific token type before depositing it or you will deposit another token type into your collection:let token <- token as! @MugenNFT.NFT
getIDs(): [UInt64]
returns an array of all the tokens in the collection
pub fun createEmptyCollection(): @NonFungibleToken.NFTCollection
- no event
- defined in the contract
- the returned collection must not contain any NFTs
- no event
This covers much of the same ground that a spec like ERC-721 or ERC-1155 covers, but without most of the downsides.
- Tokens cannot be sent to contracts that don't understand how to use them, because an account has to have a
Receiver
orCollection
in its storage to receive tokens. - If the recipient is a contract that has a stored
Collection
, the tokens can just be deposited to that Collection without having to do a clunkyapprove
,transferFrom
- Events are defined in the contract for withdrawing and depositing, so a recipient will always be notified that someone has sent them tokens with their own deposit event.
- This version can support batch transfers of NFTs. Even though it isn't explicitly defined in the contract, a batch transfer can be done within a transaction by just withdrawing all the tokens to transfer, then depositing them wherever they need to be, all atomically.
- Transfers can trigger actions because users can define custom
Receivers
to execute certain code when a token is sent. - Easy ownership indexing: Instead of having to iterate through all tokens to find which ones you own, you have them all stored in your account's collection and can get the list of the ones you own instantly
We are still trying to think about how to do token metadata, which is very important. We want to be able to have all metadata on-chain, but we haven't made much progress discussing or designing it.
If you want to test out these contracts, we recommend either testing them with the Flow Playground or with the Visual Studio Code Extension.
The steps to follow are:
- Deploy
NonFungibleToken.cdc
- Deploy
MugenNFT.cdc
, importingNonFungibleToken
from the address you deployed it to.
Then you can experiment with some of the other transactions and scripts in transactions/
or even write your own. You'll need to replace some of the import address placeholders with addresses that you deploy to, as well as some of the transaction arguments.
You can find automated tests in the lib/go/test/nft_test.go
file. It uses the transaction templates that are contained in the lib/go/templates/templates.go
file. Currently, these rely on a dependency from a private dapper labs repository to run, so external users will not be able to run them. We are working on making all of this public so anyone can run tests, but haven't completed this work yet.
(These could each be defined as a separate interface and standard and are probably not part of the main standard) They are not implemented in this repository yet
10- Withdrawing tokens from someone else's Collection by using their Provider
reference.
- approved withdraw event
- Providing a resource that only approves an account to withdraw a specific amount per transaction or per day/month/etc.
- Returning the list of tokens that an account can withdraw for another account.
- Reading the balance of the account that you have permission to send tokens for
- Owner is able to increase and decrease the approval at will, or revoke it completely
- This is much harder than anticipated
11 - Standard for Composability/Extensibility
12 - Minting a specific amount of tokens using a specific minter resource that an owner can control
- tokens minted event
- Setting a cap on the total number of tokens that can be minted at a time or overall
- Setting a time frame where this is allowed
13 - Burning a specific amount of tokens using a specific burner resource that an owner controls
- tokens burnt event
- Setting a cap on the number of tokens that can be burned at a time or overall
- Setting a time frame where this is allowed
14 - Pausing Token transfers (maybe a way to prevent the contract from being imported? probably not a good idea)
15 - Cloning the token to create a new token with the same distribution
flow project deploy
flow transactions send transactions/setup_account.cdc --signer emulator-account
flow transactions send transactions/setup_account.cdc --signer emulator-account2
flow transactions send transactions/mint_nft.cdc f8d6e0586b0a20c7 111
flow transactions send transactions/mint_nft.cdc 01cf0e2f2f715450 111
flow scripts execute scripts/get_total_supply.cdc
flow scripts execute scripts/get_collection_item.cdc f8d6e0586b0a20c7 0
flow scripts execute scripts/get_collection_item.cdc 01cf0e2f2f715450 1
The works in these folders /onflow/flow-NFT/blob/master/contracts/MugenNFT.cdc /onflow/flow-NFT/blob/master/contracts/NonFungibleToken.cdc
are under the Unlicense https://github.com/onflow/flow-NFT/blob/master/LICENSE