ERC-998 Composable Non-Fungible Token Standard

[mattlockyer]

title: ERC-998 Composable Non-Fungible Token Standard
authors: Matt Lockyer mattdlockyer@gmail.com; Nick Mudge nick@perfectabstractions.com; Jordan Schalm jordan.schalm@gmail.com
status: Draft
type: Standards Track
category: ERC
created: 2018-04-15
requires: 721, 20

Update

The latest code is in the EIP and reference implementation

EIP
eip-998.md

Reference Implementation
https://github.com/mattlockyer/composables-998

Reading
Original Medium post:
Introducing Crypto Composables

Crypto Composables - Use Cases and Applications

Abstract

A standard extension for any non-fungible token to own another non-fungible ERC-721 or fungible ERC-20 tokens. Transferring the token composition means transferring the entire hierarchy of items. For example, a cryptokitty may own a scratching post and a feeding dish; the dish may contain some amount of fungible “chow” tokens. If I sell the cryptokitty, I sell all of the belongings of the cryptokitty.

Specification
After several discussions with the community we settled on providing these 4 extensions to a standard ERC-721 NFT in order to support composable functionality:

ERC998ERC721 top-down composable tokens that receive, hold and transfer ERC721 tokens
ERC998ERC20 top-down composable tokens that receive, hold and transfer ERC20 tokens
ERC998ERC721 bottom-up composable tokens that attach themselves to other ERC721 tokens.
ERC998ERC20 bottom-up composable tokens that attach themselves to ERC721 tokens.

For more details on the reference implementation, visit the EIP.

Summary

I’ve presented a new standard for composable non-fungible tokens, ERC-998, that allows for the ownership of ERC-998, ERC-721 and ERC-20 tokens. This allows standard assets to be composed into complex compositions and traded using a single transfer. The additional functionality that can be added to a non-fungible token based on the presence of specific child tokens is open for exploration. I believe that standard interfaces for non-fungible and fungible assets to be composed and act upon one another is an exciting new area for the Ethereum community to explore and I look forward to seeing the work.

LATEST: EIP with reference implementation code

eip-998.md

[mattlockyer]

It was pointed out to me by @jeffwalsh that adding an ERC-20 token required it's own method for incrementing the balance rather than replacing it.

He's also implemented an example using a basic ERC-721 in this fiddle. Many thanks Jeff.

[Physes]

You might want to check out Delegated Non-Fungible Tokens: #994 which already sets out the architecture of parent/child NFTs. Whereas a single NFT is considered a "deed", a tree of NFTs could be considered a "zone".

[mryellow]

sets out the architecture of parent/child NFTs

// maps child delegate token to parent ID
mapping(uint256 => uint256) private sub;

sub[_delegate] == _tokenId, sub[newTokenId] = _tokenId

Not too different from the proposed mapping:

// which asset owns which other assets at which address
mapping(uint256 => mapping(address => uint256)) children;

However not dealing with the same contract with parents and children being simply related key to key as is the case with #994.

sub[newTokenId] = _tokenId as described works as it's always the child having a single parent. Where children[_tokenID][_childContract] = _index looks to fail as it will over-write the previous child token entry when a new child is added.

Could it be isChild[_tokenId][_childContract][_childId] = true is appropriate mapping instead?

mapping(uint256 => mapping(address => mapping(uint256 => bool))

[mryellow]

This was an edit, but then grew so I'll post again:

I guess for fungible you want it to be an integer.

mapping(uint256 => mapping(address => mapping(uint256 => uint256))

Where > 0 == true for NFTs. i.e. setting it to 1 is sufficient to be recognised as a child.

Alternatively the whole thing on it's head so that one child has one parent as is the case with #994.

parents[_childContract][_childId] = _tokentId with fungibles using index 0 for _childId

edit: Although that then breaks when you're trying to figure out where a fungible is held.

[mattlockyer]

I see your point about the child tokenId being overwritten, that's a pain.

I had several approaches to this and I knew this wasn't perfect. You are right that a child contract will only be able to have one ERC-721 child. Darn.

A strict requirement of this proposal will be NOT requiring any changes to children that are already ERC-721 or ERC-20, meaning they won't have to upgrade to be a child of a composite.

Another approach was to keep the mapping:

mapping(uint256 => mapping(address => uint256));

And upgrade to a pseudo unique address for ERC-721 children:

// generate a unique address for ERC-721 child tokens
// from _childContract and _childTokenId
address childToken = address(keccak256(_childContract, _childTokenId));
// everything successful and you want to add the child token
// use the unique address
children[_tokenId][childToken] = _childTokenId;

Note: this is actually how the EVM generates smart contract addresses, using the hash of address + nonce as a bytes20 address type.

In this way we have a pseudo unique address for every child token.

We will have to adopt your bookkeeping method 0 means no child and 1 means child exists.

I really wanted to reduce the need for a deep mapping as in your proposed solution, although my unique address generation pushes a bit more computation and gas fees onto the miners and users.

This would have to be calculated to transfer a child token as well, like so:

address childToken = address(keccak256(_childContract, _childTokenId));
// other conditions
require(children[_tokenId][childToken] == 1); //0 is false and 1 is true for non-fungible tokens
// transfer child here if other conditions check out
children[_tokenId][childToken] = 0;

Thoughts on this @mryellow?

[mryellow]

address childToken = address(keccak256(_childContract, _childTokenId));

Interesting, so it's keccak256(_childContract) or just straight _childContract address in the case of a fungible?

I was thinking a lot of the issues go away when dealing with non-fungible or fungibles independently. It's always this bit where you have to start thinking about using "tokenId" index 0 or returning "tokenId" 1 as "true", which all ends up feeling more untidy then was the intention.

Perhaps the neatest solution is to not attempt to deal with them in the same variable, but storing differently once you know what type you're dealing with. Not sure how best to represent anything like that semantically though. Could add a boolean for fungible to any methods where tokenId/value appears to select between them, though that's not exactly neat either.

[mattlockyer]

I think you avoid it when dealing with fungibles. So in the fungible functions, simply use the fungible contract address. There's no need for extra computation in the fungibles functions.

Could be possible to go with a completely new mapping for non-fungibles and deal with them seperately.

mapping(uint256 => mapping(address => bool)) childTokens; // NFTs
mapping(uint256 => mapping(address => uint256)) childBalance; // FTs

And still use the pseudo address construction for dealing with NFTs to ensure a unique address per NFT.

[mryellow]

pseudo address construction

Another thought on this concept, ERC: Ethereum Claims Registry #780 features some prior work which might be informative:

The key parameter is intentionally very generic. The ERC does not impose any restrictions saying that certain values for key should only be used for certain things. Rather this is something that the community is free to experiment with. If there is some emerging standard a new EIP can be created for that. There are also a lot of already existing naming conventions for claims that are in use today and coming up with our own standard might limit the ability for these to be used.

Having a key with a construction recipe for fungibles and non-fungibles which is consistent might be something worth looking at. Perhaps stepping away from address type here is nice or opens up more possibilities.

bytes32 key = bytes32(keccak256(_childContract, _childTokenId));

However would this add anything or is the key always built the same way?

Would anyone ever want to use the key for anything else other than an "address" for a token?

[mattlockyer]

My feeling on this, and why I refer to is at "pseudo address creation" is because it is analogous to how smart contract addresses are generated given the nonce of the smart contract.

So here we are creating an address for every NFT based on the contract address and tokenId of the NFT. This is exactly the same as if every NFT were deployed as a new contract from the main contract.

[vernon99]

This is a great start, thanks. Like the idea of pseudo-addresses for child tokens. Have a bunch of thoughts. Here're three major points.

1. Mixed token types in one mapping.

Could be possible to go with a completely new mapping for non-fungibles and deal with them seperately.

As you said, I think this is a preferred solution. I don't think it's a good idea to have one mapping for two different standards. It adds complexity (and fragility), adds unexpected behaviors, makes it harder for the wallets to process two different types. Wallets actually don't know the type beforehand - how would they know what token is that without guessing that through presence of the methods, etc? To me that's the biggest problem that I don't see how to resolve without splitting. Token type needs to be defined very explicitly.

So fungiblePossessions and nonfungiblePossessions may be more appropriate, with comments explicitly saying what standards to they support (ERC20+ERC677 and ERC721 respectively).

2. Currently it requires two transactions to pass ownership. This is very old-school :) ERC721 supports safeTransferFrom with onERC721Received callback (that needs to be implemented by this standard). ERC20 unfortunately doesn't and ERC223 is not backwards compatible with ERC20. But there's a nice ERC677 addition to ERC20 that keeps it backward compatible while adding transferAndCall and tokenFallback pair similarly to described for 721 above. All the key exchanges already support that and this token should also support the callbacks. This is very critical to avoid two transactions per transfer, a bane of many early tokens.

3. There has to be a way to enumerate all the children. Otherwise you have the wallets problem again, now for list of possessions. ERC721 actually implementa it, see ERC721Enumerable (which should really not be optional). The way it works is we maintain both the hashing for retrieval/checks (to see if it holds this particular token) but also an array to be able to get a token by index. Then you just iterate till you hit 0. That also gives you numberOfChildren that is missing right now completely from the spec. To avoid loops in the smart contract we will need to smartly update the array and keep indices. See how Decentraland did it in the storage and then in enumerable interface.

Also, more like a suggestion. "children" naming sounds a bit off for ERC20. It's more like stuff that belongs to this token. Maybe possessions would be better, or something like that. Nit.

[mg6maciej]

Hello everybody and thanks @mattlockyer for creating this ERC. I was thinking about something like this for over a month, happy to see it brought to attention of a broader community.

My initial idea was very similar to this, that you embed such functionality as an extension to ERC721, and your ERC998 contract would be an owner of some ERC721 tokens (from the perspective of owned token) while keeping information that the true owner is a token this contract itself keeps track of.

I see some problems with such approach. The most important one being that if you have a chain of tokens from different ERC998 contracts, as a user you will have hard time understanding what contract you need to call to transfer a CryptoKitty that is owned by a DogERC998 token that is owned by PersonERC998 token that you own. I might be wrong here, but my intuition tells me you would have to call PersonERC998 and pass it 2 arrays of all contracts and tokens that are owners (parent, grandparent, ...) of the token to be able to retrieve that poor little Kitty.

Currently I'm thinking this is a perfect example where global / master registry could be used. I started drafting it (code is here) and would like to ask all of you if you also think this might be a good idea. I also agree with all the points @vernon99 mentioned and already partially incorporated them into the codebase.
The biggest advantage of using registry is that it will support CryptoKitty being owned by another CryptoKitty.

[mattlockyer]

Thank you everyone for the comments. I have been grinding through an implementation with tests so we have a basis from which to work on finding the most optimal solutions together.

@vernon99 I have address the first 2 concerns for nonfungible "possessions". I like this name.

mapping(uint256 => mapping(address => bool)) nonfungiblePossessions;
  mapping(uint256 => mapping(address => uint256)) fungiblePossessions;
  
  function bytesToUint(bytes b) internal pure returns (uint256 result) {
    result = 0;
    for (uint256 i = 0; i < b.length; i++) {
      uint256 c = uint256(b[i]);
      if (c >= 48 && c <= 57) {
        result = result * 10 + (c - 48);
      }
    }
  }
  
  function _nonfungibleAddress(
    address _childContract, uint256 _childTokenId
  ) internal pure returns (address) {
    return address(keccak256(_childContract, _childTokenId));
  }
  
  /**************************************
  * ERC-721 Non-Fungible Possessions
  **************************************/
  
  //adding nonfungible possessions
  //receives _data which determines which NFT composable of this contract the possession will belong to
  function onERC721Received(address _from, uint256 _tokenId, bytes _data) public returns(bytes4) {
    //convert _data bytes to uint256, assuming tokens were passed in as string data
    // i.e. tokenId = 5 would be "5" coming from web3 or another contract
    uint256 id = bytesToUint(_data);
    nonfungiblePossessions[id][_nonfungibleAddress(msg.sender, _tokenId)] = true;
    return ERC721_RECEIVED;
  }
  
  //transfer the ERC-721
  function transferChild(
    address _to,
    uint256 _tokenId,
    address _childContract,
    uint256 _childTokenId
  ) public {
    // require ownership of parent token &&
    // check parent token owns the child token
    // use the 'pseudo address' for the specific child tokenId
    address childToken = _nonfungibleAddress(_childContract, _childTokenId);
    require(_owns(msg.sender, _tokenId));
    require(nonfungiblePossessions[_tokenId][childToken] == true);
    require(
      _childContract.call(
        // if true, transfer the child token
        // not a delegate call, the child token is owned by this contract
        bytes4(keccak256("safeTransferFrom(address,address,uint256)")),
        this, _to, _childTokenId
      )
    );
    // remove the parent token's ownership of the child token
    nonfungiblePossessions[_tokenId][childToken] = false;
  }

This code is working now, it's here if you want to run it yourself.

I have put ERC-20 on hold for a bit, seems relatively trivial once ERC-721 is working. @vernon99 thanks again for the comments on where to look for that implementation.

@mg6maciej thanks for dropping in here. I think the global registry is a fantastic solution to a lot of the needs of developers out there.

I do foresee some issues with functionality, specific implementations that restrict the composability of assets for example. For all basic compositions though, I think it's quite a good approach!

[mattlockyer]

I've made some updates to the comment at the top to reflect the dramatic changes to the originally proposed code.

Thank you @vernon99 @mg6maciej for the feedback. It motivated me to push forward and get a more comprehensive and elegant solution up.