ERC-998 Composable NFTs (composable tokens) (Composable Non-Fungible Token)

Draft · NFTs & multi-token · created 2018-07-07

An extension standard that lets an NFT (ERC-721 token) directly own other NFTs or ERC-20 tokens. It groups tokens into a tree structure via ownership relationships, so that changing only the root owner transfers the entire structure at once.

Why it is needed

Under existing standards, the owner of a token is always a wallet address or contract address. The standard alone cannot let an NFT own another NFT, or let an NFT hold an ERC-20 token inside it. So to manage or trade several related tokens as a single unit, there is no choice but to move each token separately. This standard extends ERC-721 to define a way to record in the contract the relationship of a token owning another token. When tokens form a list or tree connected by ownership relationships, there is a single address at the top of that structure that owns the whole thing (the root owner). Changing only the root owner transfers the entire bundle together in a single transaction.

What to implement

In depth

Four kinds of composables

This standard defines four kinds. ERC998ERC721 top-down is an ERC-721 token that receives and holds other ERC-721 tokens, and ERC998ERC20 top-down is an ERC-721 token that holds ERC-20 tokens. ERC998ERC721 bottom-up is an ERC-721 token that attaches itself to another ERC-721 token, and ERC998ERC20 bottom-up is an ERC-20 token that can be attached to an ERC-721 token. Top-down contracts store each token's list of child tokens, and bottom-up contracts store each token's parent token. A single token can serve multiple roles at once, and implementing one or more of the four interfaces makes it compliant with this standard. ERC-165 must be applied to each interface used. Use bottom-up if you want to attach another NFT to a regular ERC-721 token, and top-down if you want an NFT to hold a regular ERC-721 token.

Root-owner-based authentication

All permission checks are based on the rootOwner at the top of the tree. After finding the root owner via rootOwnerOf(_tokenId), it is compared against msg.sender, the return value of getApproved(tokenId), and the return value of isApprovedForAll(rootOwner, msg.sender); if any one matches, the check passes, otherwise it throws. approve and getApproved are also implemented based on rootOwner. Because approval records are stored as a pair of rootOwner and tokenId, when the tree passes to a new root owner, approvals made by the previous owner remain solely tied to the previous owner, so there is no need to worry about the approval status of child composables.

Traversal and the magic value 0xcd740db5

rootOwnerOf and rootOwnerOfChild walk back up the tree following ownership relationships. If a bottom-up token has a parent, rootOwnerOf is called on the parent; if that fails, rootOwnerOfChild is called; and if that also fails, the token's owner address is treated as the root. Since it cannot be known in advance whether the counterpart contract has the relevant function, the actual call must be made via staticcall in assembly to check for failure and prevent state changes. In the returned bytes32 value, the first 4 bytes hold the magic value 0xcd740db5, and the last 20 bytes hold the address. This value is the XOR of the four selectors rootOwnerOf, rootOwnerOfChild, tokenOwnerOf, and ownerOfChild. In calls where the existence of the function is uncertain, the first 4 bytes must always be compared against this value to confirm it is a valid return. Top-down and bottom-up are mutually compatible, so rootOwnerOf returns the topmost address regardless of the configuration.

Two paths for placing a token into a top-down composable

There are two ways to place an ERC-721 token. First, calling safeTransferFrom on the original contract while carrying the recipient parent tokenId as an integer in data lets the composable's onERC721Received read and record it. The return value is the magic value 0x150b7a02. Second, for older contracts without safeTransferFrom (the original text cites CryptoKitties as an example), approve the composable contract via approve or setApprovalForAll, then call getChild. getChild must authenticate that msg.sender is the owner of or approved for that ERC-721 token. ERC-20 follows the same structure: if ERC-223's transfer(address,uint256,bytes) is supported, send with the tokenId carried in data and get notified via tokenFallback. Otherwise, use approve followed by getERC20.

The transferFrom prohibition rule and the from:to:what format

Whether top-down or bottom-up, attempting to move a token owned by another token directly via transferFrom or safeTransferFrom must always throw, because these functions do not specify which token is the owner. The transferFrom family should only be used for tokens owned by an address. Instead, all transfer functions specify the sender, recipient, and target in a from:to:what format. The original text gives as an example the problem of not specifying from: when an exchange contract is the operator for multiple users, if user A sends token 1 to B, and right after, the exchange, intending to receive the same token from A, sends it to C, then without specifying from, the token B just received would be wrongly transferred to C. Specifying from causes the second transfer to fail.

Required validation for bottom-up composables

ERC-721 bottom-up stores an owner address and parent tokenId for each token, queried via tokenOwnerOf. If isParent is true, tokenOwner is the owning contract's address and parentTokenId is valid; if false, it is a user address and parentTokenId should be ignored. transferToParent and transferAsChild must check that the receiving token exists on the receiving contract, and throw otherwise. transferFromParent and transferAsChild must check that the sending contract and tokenId actually own that token. ERC-20 bottom-up can be implemented by adding a contractAddress->tokenId->balance mapping in addition to the address balance mapping. transferToParent must check via ERC-165's supportsInterface that the receiving contract implements ERC-721, and it is advisable to confirm the existence of the receiving token with an ownerOf call. The standard ERC-20 Transfer event should be emitted alongside every transfer. When a token is a party to the transfer, it is advisable to put that token's contract address in the corresponding parameter.

Optional enumeration interfaces

Querying the list of child tokens is separated out into optional interfaces. ERC998ERC721TopDownEnumerable (identifier 0xa344afe4) provides totalChildContracts, childContractByIndex, totalChildTokens, and childTokenByIndex to query by index the child contracts and child tokens a parent token has. ERC998ERC20TopDownEnumerable (0xc5fd96cd) provides totalERC20Contracts and erc20ContractByIndex. ERC998ERC721BottomUpEnumerable (0x8318b539) queries the number of child tokens a parent token has and each child by index. The ERC-165 identifiers for the core interfaces are 0xcde244d9 for ERC998ERC721TopDown, 0x7294ffed for ERC998ERC20TopDown, 0xa1b23002 for ERC998ERC721BottomUp, and 0xffafa991 for ERC998ERC20BottomUp.

Draft status

This proposal was created in July 2018 and is in Draft status. Its contents may change and it is not a finalized standard. The Security Considerations section also only notes that further discussion is needed, meaning the security analysis has not been settled. The reference implementation is in the composables-998 repository linked in the original text.

Original ERC · ← ERCs