DIP721 - Introduction
DIP721 is an ERC-721 style non-fungible token standard built mirroring its Ethereum counterpart and adapting it to the Internet Computer, maintaining the same interface.
This standard aims to adopt the EIP-721 to the Internet Computer; providing a simple, non-ambiguous, extendable API for the transfer and tracking ownership of NFTs and expanding/building upon the EXT standard with partial compatibility.
- Candid and interface.
- Description.
Important: This is an an in-development standard, consider it a work in progress as we finalize details in its design and gather feedback from the community.
Contributing
We'd like to collaborate with the community to provide better token standard implementation for the developers on the IC, if you have some ideas you'd like to discuss, submit an issue, if you want to improve the code or you made a different implementation, make a pull request!
Motivation
DIP-721 tries to improve on existing Internet Computer standards in the following ways:
- Most NFT projects don't require a multi-token standard, and a simple NFT standard like DIP-721 would suffice. Users of NFTs based on multi-token standards (such as EXT) will be required to pay extra cycle cost compared to DIP-721.
- Most NFT projects don't require the generalization of IC Principals into Ledger Accounts, and avoiding that direction can help reduce the complexity of the API.
- Most current NFT standards on the IC don't yet have proper metadata support for NFTs.
- The ability to track the history of NFT transfers is an important requirement of almost every NFT projects, and it should be a core part of the standard.
- Most NFT projects don't require arbitrarily large token balances, and that can lead to more cycle inefficient implementations.
- DIP-721 closely follows the original EIP-721, and that will make porting existing Ethereum contracts onto the IC more straightforward.
- NFTs projects that choose to implement DIP-721, will be able to implement other NFT token standards without worrying about interface function name collision. This is achieved by DIP-721 postfixing all its interface methods with DIP721.
Interface specification
Basic interface
Every DIP-721 compatible smart contract must implement this interface. All other interfaces are optional. For all interface methods trapping (instead of returning an error) is allowed, but not encouraged.
balanceOfDip721
Count of all NFTs assigned to user.
balanceOfDip721: (user: principal) -> (nat64) query;
ownerOfDip721
Returns the owner of the NFT associated with token_id. Returns ApiError.InvalidTokenId, if the token id is invalid.
ownerOfDip721: (token_id: nat64) -> (OwnerResult) query;
safeTransferFromDip721
Safely transfers token_id token from user from to user to. If to is zero, then ApiError.ZeroAddress should be returned. If the caller is neither the owner, nor an approved operator, nor someone approved with the approveDip721 function, then ApiError.Unauthorized should be returned. If token_id is not valid, then ApiError.InvalidTokenId is returned.
safeTransferFromDip721: (from: principal, to: principal, token_id: nat64) -> (TxReceipt);
transferFromDip721
Identical to safeTransferFromDip721 except that this function doesn't check whether the to is a zero address or not.
transferFromDip721: (from: principal, to: principal, token_id: nat64) -> (TxReceipt);
supportedInterfacesDip721
Returns the interfaces supported by this smart contract.
supportedInterfacesDip721: () -> (vec InterfaceId) query;
logoDip721
Returns the logo of the NFT contract.
logoDip721: () -> (LogoResult) query;
nameDip721
Returns the name of the NFT contract.
nameDip721: () -> (text) query;
symbolDip721
Returns the symbol of the NFT contract.
symbolDip721: () -> (text) query;
totalSupplyDip721
Returns the total current supply of NFT tokens. NFTs that are minted and later burned explictely or sent to the zero address should also count towards totalSupply.
totalSupplyDip721: () -> (nat64) query;
getMetadataDip721
Returns the metadata for token_id. Returns ApiError.InvalidTokenId, if the token_id is invalid.
getMetadataDip721: (token_id: nat64) -> MetadataResult query;
getMetadataForUserDip721
Returns all the metadata for the coins user owns.
getMetadataForUserDip721: (user: principal) -> (vec ExtendedMetadataResult);
Transfer notification interface
This interface add notification feature for NFT transfers. Implementing this interface might open up other smart contracts to re-entrancy attacks.
safeTransferFromNotifyDip721
Same as safeTransferFromDip721, but to is treated as a smart contract that implements the Notification interface. Upon successful transfer onDIP721Received is called with data.
safeTransferFromNotifyDip721: (from: principal, to: principal, token_id: nat64, data: vec nat8) -> (TxReceipt);
transferFromNotifyDip721
Same as transferFromDip721, but to is treated as a smart contract that implements the Notification interface. Upon successful transfer onDIP721Received is called with data.
transferFromNotifyDip721: (from: principal, to: principal, token_id: nat64, data: vec nat8) -> (TxReceipt);
Approval interface
This interface adds approve functionality to DIP-721 tokens.
approveDip721
Change or reaffirm the approved address for an NFT. The zero address indicates there is no approved address. Only one user can be approved at a time to manage token_id. Approvals given by the approveDip721 function are independent from approvals given by the setApprovalForAllDip721. Returns ApiError.InvalidTokenId, if the token_id is not valid. Returns ApiError.Unauthorized in case the caller neither owns token_id nor he is an operator approved by a call to the setApprovalForAll function.
approveDip721: (user: principal, nat64: token_id) -> (TxReceipt) query;
setApprovalForAllDip721
Enable or disable an operator to manage all of the tokens for the caller of this function. Multiple operators can be given permission at the same time. Approvals granted by the approveDip721 function are independent from the approvals granted by setApprovalForAll function. The zero address indicates there are no approved operators.
setApprovalForAllDip721: (operator: principal, isApproved: bool) -> (TxReceipt);
getApprovedDip721
Returns the approved user for token_id. Returns ApiError.InvalidTokenId if the token_id is invalid.
getApprovedDip721: (token_id: nat64) -> (TxReceipt) query;
isApprovedForAllDip721
Returns true if the given operator is an approved operator for all the tokens owned by the caller, returns false otherwise.
isApprovedForAllDip721: (operator: principal) -> (bool) query;
Mint interface
This interface adds mint functionality to DIP-721 tokens.
mintDip721
Mint an NFT for principal to. The parameter blobContent is non zero, if the NFT contract embeds the NFTs in the smart contract. Implementations are encouraged to only allow minting by the owner of the smart contract. Returns ApiError.Unauthorized, if the caller doesn't have the permission to mint the NFT.
mintDip721: (to: principal, metadata: Metadata, blobContent: blob) -> (MintReceipt);
Burn interface
This interface adds burn functionality to DIP-721 tokens.
burnDip721
Burn an NFT identified by token_id. Implementations are encouraged to only allow burning by the owner of the token_id. Returns ApiError.Unauthorized, if the caller doesn't have the permission to burn the NFT. Returns ApiError.InvalidTokenId, if the provided token_id doesn't exist.
burnDip721: (token_id: nat64) -> (TxReceipt);
Notification interface
transferFromNotifyDip721 and safeTransferFromNotifyDip721 functions can - upon successfull NFT transfer - notify other smart contracts that adhere to the following interface.
caller is the entity that called the transferFromNotifyDip721 or safeTransferFromNotifyDip721 function, and from is the previous owner of the NFT.
onDIP721Received: (address caller, address from, uint256 token_id, bytes data) -> ();
Datastructure specification
OwnerResult
type ApiError =
variant {
Unauthorized;
InvalidTokenId;
ZeroAddress;
Other;
};
type OwnerResult =
variant {
Err: ApiError;
Ok: Principal;
};
TxReceipt
type TxReceipt =
variant {
Err: ApiError;
Ok: nat;
};
InterfaceId
type InterfaceId =
variant {
Approval;
TransactionHistory;
Mint;
Burn;
TransferNotification;
};
LogoResult
type LogoResult =
record {
logo_type: text // MIME type of the logo
data: text // Base64 encoded logo
};
type ExtendedMetadataResult =
record {
metadata_desc: MetadataDesc;
token_id: nat64;
};
MetadataResult
type MetadataResult =
variant {
Err: ApiError;
Ok: MetadataDesc;
};
type MetadataDesc = vec MetadataPart;
type MetadataPart =
record {
purpose: MetadataPurpose;
key_val_data: vec MetadataKeyVal;
data: blob;
};
type MetadataPurpose =
variant {
Preview; // used as a preview, can be used as preivew in a wallet
Rendered; // used as a detailed version of the NFT
};
type MetadataKeyVal =
record {
text;
MetadataVal;
};
type MetadataVal =
variant {
TextContent : Text;
BlobContent : blob;
NatContent : Nat;
Nat8Content: Nat8;
Nat16Content: Nat16;
Nat32Content: Nat32;
Nat64Content: Nat64;
};
Predefined key value pairs
content hash
Uniquely identifies the content of the NFT by its hash fingerprint. This field might be missing unless the NFT is stored on the Web, in which case the content hash is mandatory.
{"contentHash", BlobContent(<hash of the content>)}
contentType
{"contentType", TextContent(<MIME type of the NFT>)}
locationType
{"locationType", Nat8Content(<type of the location>)}
1 - IPFS storage
2 - Asset canister storage
3 - URI(Web) storage
4 - Embedded in the token contract
location
{"location", any(<location>)}
// where any(<location>) is one of the followings based on the "locationType"
BlobContent(<IPFS location hash>) - IPFS
TextContent(<PrincipalId of the asset canister>) - Asset canister
TextContent(<URI of the NFT location on the Web>) - URI
location field is missing - Embedded in the token contract
TxResult
type TxResult =
record {
fee: Nat;
transaction_type: TransactionType;
};
type TransactionType =
variant {
Transfer:
record {
token_id: nat64;
from: principal;
to: principal;
};
TransferFrom:
record {
token_id: nat64;
from: principal;
to: principal;
};
Approve:
record {
token_id: nat64;
from: principal;
to: principal;
};
SetApprovalForAll:
record {
from: principal;
to: principal;
};
Mint:
record {
token_id: nat64;
};
Burn:
record {
token_id: nat64;
};
};
MintReceipt
type MintReceipt =
variant {
Err: variant {
Unauthorized;
};
Ok: record {
token_id: nat64; // minted token id
id: nat // transaction id
};
};
BurnRequest
type BurnRequest =
record {
token_id: nat64;
}
Fees
Implementations are encouraged not to charge any fees when an approved entity transfers NFTs on the user's behalf, as that entity might have no means for payment. If any fees needs to be taken for such a transferFromDip721, safeTransferFromDip721, transferFromNotifyDip721, safeTransferFromNotifyDip721 call, then it is encouraged to be taken during the call to approveDip721, setApprovalForAllDip721 from the caller's balance.
56 Nov 12, 2022
5 Jan 9, 2022
6 Dec 20, 2022
156 Apr 28, 2022
9 Apr 1, 2023
3.2k Jan 4, 2023
1.2k Jan 1, 2023
6 May 31, 2022
8 Jul 2, 2022
7 Oct 13, 2022
12 Apr 7, 2022
15 Dec 16, 2022
4.7k Jan 4, 2023
4 Oct 6, 2022
3 May 10, 2022
6 Nov 22, 2022