From 5ca0e7d86d22d2b3e9a535bfa9ed68555f484e52 Mon Sep 17 00:00:00 2001 From: Nick Mudge Date: Tue, 24 Jul 2018 08:26:06 -0700 Subject: [PATCH] Adds EIP 998 (#1252) * Create eip-173.md * Removed "review-period-end" * Update eip-173.md Fixed the notice for the transferOwnership function. Stated that emitting the OwnershipTransferred event on contract creation is unspecified. * Update eip-173.md Updated info about the OwnershipTransferred event. "The OwnershipTransferred event does not have to be emitted when a contract is created." * Update eip-173.md Set the discussions-to data. * Create eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md * Update eip-998.md --- EIPS/eip-998.md | 780 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 780 insertions(+) create mode 100644 EIPS/eip-998.md diff --git a/EIPS/eip-998.md b/EIPS/eip-998.md new file mode 100644 index 00000000000000..dc99ebc32ff2cf --- /dev/null +++ b/EIPS/eip-998.md @@ -0,0 +1,780 @@ +--- +eip: 998 +title: ERC-998 Composable Non-Fungible Token Standard +author: Matt Lockyer , Nick Mudge +discussions-to: https://github.com/ethereum/EIPs/issues/998 +type: Standards Track +category: ERC +status: Draft +created: 2018-07-07 +requires: 721, 165 +--- + +## Simple Summary + +An extension of the [ERC721 standard](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-721.md) to enable ERC721 tokens to own other ERC721 tokens and ERC20 tokens. + +## Abstract + +An ERC988 composable is an ERC721 token with additional functionality for owning or being owned by other ERC721 tokens. An ERC998 composable can also own ERC20 tokens. + +An ERC721 token owns another token if the the ownership of the token has been transferred to it. + +A top-down composable contract stores and keeps track of child tokens for each of its tokens. + +A bottom-up composable contract stores and keeps track of a parent token for each its tokens. + +With either kind of composable it is possible to compose lists or trees of ERC721 tokens connected by ownership. Any such structure will have a single owner address at the root of the structure that is the owner of the entire composition. The entire composition can be transferred with one transaction by changing the root owner. + +Both kinds of composable, top-down and bottom-up, have their advantages and disadvantages which are explained in the Rational section. It is possible for a composable token to be one or both kinds of composable. + +## Specification + +This specification specifies: + +1. [ERC721 top-down composable tokens that receive, hold and transfer ERC721 tokens](#erc721-top-down-composable) +2. [ERC20 top-down composable tokens that receive, hold and transfer ERC20 tokens](#erc20-top-down-composable) +3. [ERC721 bottom-up composable tokens that attach themselves to other ERC721 tokens.](#erc721-bottom-up-composable) + +### ERC721 + +Both ERC721 top-down and ERC721 bottom-up composable contracts must implement the [ERC721 interface](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-721.md). + +### ERC165 + +The [ERC165 standard](https://eips.ethereum.org/EIPS/eip-165) must be applied to each ERC998 interface that is used. + +### Authentication + +Authenticating whether a user or contract can execute some action works the same for both top-down and bottom-up composables. + +A `rootOwner` refers to the owner address at the top of a tree of composables and ERC721 tokens. An `immediateOwner` refers to an address that directly owns a composable or ERC721 token with no composables between it and the token it owns. + +Authentication within any composable is done by finding the rootOwner and comparing it to `msg.sender`, the return result of `getApproved(tokenId)` and the return result of `isApprovedForAll(rootOwner, msg.sender)`. If no match is found then the immediateOwner of the composable is found and compared to `msg.sender` and the return result of `isApprovedForAll(immediateOwner, msg.sender)`. If a match is found then authentication passes, otherwise authentication fails and the contract throws. + +Here is an example of authentication code: +```solidity +require(rootOwner == msg.sender || isApprovedForAll(rootOwner,msg.sender) || + getApproved(tokenId) == msg.sender || immediateOwner == msg.sender || + isApprovedForAll(immediateOwner,msg.sender); +``` + +The `approve(address _approved, uint256 _tokenId)` and `getApproved(uint256 _tokenId)` ERC721 functions are implemented specifically for the rootOwner, not the immediateOwner. This enables a tree of composables to be transferred to a new rootOwner without worrying about which addresses have been approved in child composables, because any prior approves can only be used by the prior rootOwner. + +Here are example implementations: +```solidity +function approve(address _approved, uint256 _tokenId) external { + address immediateOwner = tokenIdToTokenOwner[_tokenId]; + require(immediateOwner != address(0)); + address rootOwner = address(rootOwnerOf(_tokenId)); + require(rootOwner == msg.sender || isApprovedForAll(rootOwner,msg.sender) || + immediateOwner == msg.sender || isApprovedForAll(immediateOwner,msg.sender)); + + rootOwnerAndTokenIdToApprovedAddress[rootOwner][_tokenId] = _approved; + emit Approval(rootOwner, _approved, _tokenId); +} + +function getApproved(uint256 _tokenId) public view returns (address) { + address rootOwner = address(rootOwnerOf(_tokenId)); + return rootOwnerAndTokenIdToApprovedAddress[rootOwner][_tokenId]; +} +``` +### Traversal + +The rootOwner of a composable is gotten by calling `rootOwnerOf(uint256 _tokenId)` or `rootOwnerOfChild(address _childContract, uint256 _childTokenId)`. These functions are used by top-down and bottom-up composables to traverse up the tree of composables and ERC721 tokens to find the rootOwner. + +Top-down and bottom-up composables are interoperable with each other. It is possible for a top-down composable to own a bottom-up composable or for a top-down composable to own an ERC721 token that owns a bottom-up token. In any configuration calling `rootOwnerOf(uint256 _tokenID)` on the bottom composable will return the owner address at the top of the ownership tree. + +Tokens/contracts that implement the above authentication and traversal functionality are "composable aware". + +Composables and "composable aware" contracts/tokens must call the `onERC998Removed` function in all their transferFrom/safeTransferFrom functions to notify owning/_from contracts that ERC721 tokens are removed. + +### Composable Transfer Function Parameter Format + +Composable functions that make transfers follow the same parameter format: **from:to:what**. + +For example the ` getChild(address _from, uint256 _tokenId, address _childContract, uint256 _childTokenId)` composable function transfers an ERC721 token from an address to a top-down composable. The `_from` parameter is the **from**, the `_tokenId` parameter is the **to** and the `address _childContract, uint256 _childTokenId` parameters are the **what**. + +The `transferChild/safeTransferChild` transfer functions do not have a **from** because it is already known that the **from** is `this`, the current contract. + +### ERC721 Top-Down Composable + +ERC721 top-down composables act as containers for ERC721 tokens. + +ERC721 top-down composables are ERC721 tokens that can receive, hold and transfer ERC721 tokens. + +There are two ways to transfer a ERC721 token to a top-down composable: +1. Use the `function safeTransferFrom(address _from, address _to, uint256 _tokenId, bytes data)` function. The `_to` argument is the top-down composable contract address. The `bytes data` argument holds the integer value of the top-down composable tokenId that the ERC721 token is transferred to. +2. Call `approve` in the ERC721 token contract for the top-down composable contract. Then call `getChild` in the composable contract. + +The first ways is for ERC721 contracts that have a `safeTransferFrom` function. The second way is for contracts that do not have this function such as cryptokitties. + +Every ERC721 top-down composable compliant contract must implement the ERC998ERC721TopDown interface. + +The ERC998ERC721TopDownEnumerable and ERC998ERC20TopDownEnumerable interfaces are optional. + +```solidity +pragma solidity ^0.4.24; + +/// @title ERC998ERC721 Top-Down Composable Non-Fungible Token +/// @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-998.md +/// Note: the ERC-165 identifier for this interface is 0x1bc995e4 +interface ERC998ERC721TopDown { + + /// @dev This emits when a token receives a child token. + /// @param _from The prior owner of the token. + /// @param _tokenId The token that receives the child token. + event ReceivedChild( + address indexed _from, + uint256 indexed _tokenId, + address indexed _childContract, + uint256 _childTokenId + ); + + /// @dev This emits when a child token is transferred from a token to an address. + /// @param _tokenId The parent token that the child token is being transferred from. + /// @param _to The new owner address of the child token. + event TransferChild( + uint256 indexed tokenId, + address indexed _to, + address indexed _childContract, + uint256 _childTokenId + ); + + /// @notice Get the root owner of tokenId. + /// @param _tokenId The token to query for a root owner address + /// @return rootOwner The root owner at the top of tree of tokens. + function rootOwnerOf(uint256 _tokenId) public view returns (bytes32 rootOwner); + + /// @notice Get the root owner of a child token. + /// @param _childContract The contract address of the child token. + /// @param _childTokenId The tokenId of the child. + /// @return rootOwner The root owner at the top of tree of tokens. + function rootOwnerOfChild(address _childContract, uint256 _childTokenId) public view returns (bytes32 rootOwner); + + /// @notice Get the parent tokenId of a child token. + /// @param _childContract The contract address of the child token. + /// @param _childTokenId The tokenId of the child. + /// @return parentTokenOwner The parent address of the parent token + /// @return parentTokenId The parent tokenId of _tokenId + function ownerOfChild(address _childContract, uint256 _childTokenId) + external + view + returns (address parentTokenOwner, uint256 parentTokenId); + + /// @notice A token receives a child token + /// @param _operator The address that caused the transfer. + /// @param _from The owner of the child token. + /// @param _childTokenId The token that is being transferred to the parent. + /// @param _data Up to the first 32 bytes contains an integer which is the receiving parent tokenId. + function onERC721Received(address _operator, address _from, uint256 _childTokenId, bytes _data) + external + returns(bytes4); + + /// @notice Let's an owning contract know that a specified token is transferred out + /// @param The address that caused the transfer. + /// @param _toContract The contract that receives the child token + /// @param _childTokenId The child tokenId that is being removed. + /// @param _data Additional data with no specified format + function onERC998Removed(address _operator, address _toContract, uint256 _childTokenId, bytes _data) external; + + /// @notice Transfer child token from top-down composable to address. + /// @param _to The address that receives the child token + /// @param _childContract The ERC721 contract of the child token. + /// @param _childTokenId The tokenId of the token that is being transferred. + function transferChild(address _to, address _childContract, uint256 _childTokenId) external; + + /// @notice Transfer child token from top-down composable to address. + /// @param _to The address that receives the child token + /// @param _childContract The ERC721 contract of the child token. + /// @param _childTokenId The tokenId of the token that is being transferred. + function safeTransferChild(address _to, address _childContract, uint256 _childTokenId) external; + + /// @notice Transfer child token from top-down composable to address. + /// @param _to The address that receives the child token + /// @param _childContract The ERC721 contract of the child token. + /// @param _childTokenId The tokenId of the token that is being transferred. + /// @param _data Additional data with no specified format + function safeTransferChild(address _to, address _childContract, uint256 _childTokenId, bytes _data) external; + + /// @notice Get a child token from an ERC721 contract. + /// @param _from The address that owns the child token. + /// @param _tokenId The token that becomes the parent owner + /// @param _childContract The ERC721 contract of the child token + /// @param _childTokenId The tokenId of the child token + function getChild(address _from, uint256 _tokenId, address _childContract, uint256 _childTokenId) external; +} +``` + +#### rootOwnerOf +```solidity +/// @notice Get the root owner of tokenId. +/// @param _tokenId The token to query for a root owner address +/// @return rootOwner The root owner at the top of tree of tokens. +function rootOwnerOf(uint256 _tokenId) public view returns (bytes32 rootOwner); +``` + +This function traverses token owners until the the root owner address of `_tokenId` is found. + +The first 4 bytes of rootOwner contain the ERC998 magic value `0x62ff4869`. The last 20 bytes contain the root owner address. + +The magic value is returned because this function may be called on contracts when it is unknown if the contracts have a `rootOwnerOf` function. The magic value is used in such calls to ensure a valid return value is received. + +If it is unknown whether a contract has the `rootOwnerOf` function then the magic value must be compared to `0x62ff4869`. + +`0x62ff4869` is equal to: `this.rootOwnerOf.selector ^ this.rootOwnerOfChild.selector;` + +Here is an example of a value returned by `rootOwnerOf`. +`0x62ff48690000000000000000e5240103e1ff986a2c8ae6b6728ffe0d9a395c59` + +#### rootOwnerOfChild +```solidity +/// @notice Get the root owner of a child token. +/// @param _childContract The contract address of the child token. +/// @param _childTokenId The tokenId of the child. +/// @return rootOwner The root owner at the top of tree of tokens. +function rootOwnerOfChild(address _childContract, uint256 _childTokenId) public view returns (bytes32 rootOwner); +``` + +This function traverses token owners until the the root owner address of the supplied child token is found. + +The first 4 bytes of rootOwner contain the ERC998 magic value `0x62ff4869`. The last 20 bytes contain the root owner address. + +The magic value is returned because this function may be called on contracts when it is unknown if the contracts have a `rootOwnerOf` function. The magic value is used in such calls to ensure a valid return value is received. + +If it is unknown whether a contract has the `rootOwnerOf` function then the magic value must be compared to `0x62ff4869`. + +#### ownerOfChild + +```solidity +/// @notice Get the parent tokenId of a child token. +/// @param _childContract The contract address of the child token. +/// @param _childTokenId The tokenId of the child. +/// @return parentTokenOwner The parent address of the parent token +/// @return parentTokenId The parent tokenId of _tokenId +function ownerOfChild(address _childContract, uint256 _childTokenId) + external + view + returns (address parentTokenOwner, uint256 parentTokenId); +``` + +This function is used to get the parent tokenId of a child token and get the owner address of the parent token. + + +#### onERC721Received +```solidity +/// @notice A token receives a child token +/// @param _operator The address that caused the transfer. +/// @param _from The prior owner of the child token. +/// @param _childTokenId The token that is being transferred to the parent. +/// @param _data Up to the first 32 bytes contains an integer which is the receiving parent tokenId. +function onERC721Received(address _operator, address _from, uint256 _childTokenId, bytes _data) + external + returns(bytes4); +``` + +This is a function defined in the ERC721 standard. This function is called in an ERC721 contract when `safeTransferFrom` is called. The `bytes _data` argument contains an integer value from 1 to 32 bytes long that is the parent tokenId that an ERC721 token is transferred to. + +The `onERC721Received` function is how a top-down composable contract is notified that an ERC721 token has been transferred to it and what tokenId in the top-down composable is the parent tokenId. + +The return value for `onERC721Received` is the magic value `0x150b7a02` which is equal to `bytes4(keccak256(abi.encodePacked("onERC721Received(address,address,uint256,bytes)")))`. + +#### onERC998Removed +```solidity +/// @notice Let's an owning contract know that a specified token is transferred out +/// @param The address that caused the transfer. +/// @param _toContract The contract that receives the child token +/// @param _childTokenId The child tokenId that is being removed. +/// @param _data Additional data with no specified format +function onERC998Removed(address _operator, address _toContract, uint256 _childTokenId, bytes _data) external; +``` + +Any composable or "composable aware" contract must call the `onERC998Removed` function within all `transferFrom/safeTransferFrom` functions on the contract that is losing ownership of an ERC721 token. It is used to notify top-down composables that they no longer have a child token and to remove it from any internal bookkeeping/tracking. + +Contracts that call `onERC998Removed` must not throw if the call fails because it is possible that a contract does not have the `onERC998Removed` function. + +#### transferChild +```solidity +/// @notice Transfer child token from top-down composable to address. +/// @param _to The address that receives the child token +/// @param _childContract The ERC721 contract of the child token. +/// @param _childTokenId The tokenId of the token that is being transferred. +function transferChild(address _to, address _childContract, uint256 _childTokenId) external; +``` + +This function authenticates `msg.sender` and transfers a child token from a top-down composable to a different address. + +This function makes this call within it: `ERC721(_childContract).transferFrom(this, _to, _childTokenId);` + +#### safeTransferChild +```solidity +/// @notice Transfer child token from top-down composable to address. +/// @param _to The address that receives the child token +/// @param _childContract The ERC721 contract of the child token. +/// @param _childTokenId The tokenId of the token that is being transferred. +function safeTransferChild(address _to, address _childContract, uint256 _childTokenId) external; +``` + +This function authenticates `msg.sender` and transfers a child token from a top-down composable to a different address. + +This function makes this call within it: `ERC721(_childContract).safeTransferFrom(this, _to, _childTokenId);` + +#### safeTransferChild +```solidity +/// @notice Transfer child token from top-down composable to address or other top-down composable. +/// @param _to The address that receives the child token +/// @param _childContract The ERC721 contract of the child token. +/// @param _childTokenId The tokenId of the token that is being transferred. +/// @param _data Additional data with no specified format, can be used to specify tokenId to transfer to +function safeTransferChild(address _to, address _childContract, uint256 _childTokenId, bytes _data) external; +``` + +This function authenticates `msg.sender` and transfers a child token from a top-down composable to a different address or to a different top-down composable. + +A child token is transferred to a different top-down composable if the `_to` address is a top-down composable contract and `bytes _data` is supplied an integer representing the parent tokenId. + +This function makes this call within it: `ERC721(_childContract).safeTransferFrom(this, _to, _childTokenId, _data);` + +#### getChild +```solidity +/// @notice Get a child token from an ERC721 contract. +/// @param _from The address that owns the child token. +/// @param _tokenId The token that becomes the parent owner +/// @param _childContract The ERC721 contract of the child token +/// @param _childTokenId The tokenId of the child token +function getChild(address _from, uint256 _tokenId, address _childContract, uint256 _childTokenId) external; +``` + +This function is used to transfer an ERC721 token when its contract does not have a `safeTransferChild(address _to, address _childContract, uint256 _childTokenId, bytes _data)` function. + +A transfer with this function is done in two steps: +1. The owner of the ERC721 token calls `approve` or `setApprovalForAll` in the ERC721 contract for the top-down composable contract. +2. The owner of the ERC721 token calls `getChild` in the top-down composable contract for the ERC721 token. + +The `getChild` function must authenticate that `msg.sender` is the owner of the ERC721 token in the ERC721 contract or is approved or an operator of the ERC721 token in the ERC721 contract. + +#### ERC721 Top-Down Composable Enumeration +Optional interface for top-down composable enumeration: + +```solidity +/// @dev The ERC-165 identifier for this interface is 0xa344afe4 +interface ERC998ERC721TopDownEnumerable { + + /// @notice Get the total number of child contracts with tokens that are owned by tokenId. + /// @param _tokenId The parent token of child tokens in child contracts + /// @return uint256 The total number of child contracts with tokens owned by tokenId. + function totalChildContracts(uint256 _tokenId) external view returns(uint256); + + /// @notice Get child contract by tokenId and index + /// @param _tokenId The parent token of child tokens in child contract + /// @param _index The index position of the child contract + /// @return childContract The contract found at the tokenId and index. + function childContractByIndex(uint256 _tokenId, uint256 _index) external view returns (address childContract); + + /// @notice Get the total number of child tokens owned by tokenId that exist in a child contract. + /// @param _tokenId The parent token of child tokens + /// @param _childContract The child contract containing the child tokens + /// @return uint256 The total number of child tokens found in child contract that are owned by tokenId. + function totalChildTokens(uint256 _tokenId, address _childContract) external view returns(uint256); + + /// @notice Get child token owned by tokenId, in child contract, at index position + /// @param _tokenId The parent token of the child token + /// @param _childContract The child contract of the child token + /// @param _index The index position of the child token. + /// @return childTokenId The child tokenId for the parent token, child token and index + function childTokenByIndex(uint256 _tokenId, address _childContract, uint256 _index) + external + view + returns (uint256 childTokenId); +} +``` + +### ERC20 Top-Down Composable + +ERC20 top-down composables act as containers for ERC20 tokens. + +ERC20 top-down composables are ERC721 tokens that can receive, hold and transfer ERC20 tokens. + +There are two ways to transfer ERC20 tokens to an ERC20 Top-Down Composable: + +1. Use the `transfer(address _to, uint256 _value, bytes _data);` function from the ERC223 contract. The `_to` argument is the ERC20 top-down composable contract address. The `_value` argument is how many ERC20 tokens to transfer. The `bytes` argument holds the integer value of the top-down composable tokenId that receives the ERC20 tokens. +2. Call `approve` in the ERC20 contract for the ERC20 top-down composable contract. Then call `getERC20(address _from, uint256 _tokenId, address _erc20Contract, uint256 _value)` from the ERC20 top-down composable contract. + +The first way is for ERC20 contracts that support the ERC223 standard. The second way is for contracts that do not. + +ERC20 top-down composables implement the following interface: + +```solidity +/// @title ERC998ERC20 Top-Down Composable Non-Fungible Token +/// @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-998.md +/// Note: the ERC-165 identifier for this interface is 0x7294ffed +interface ERC998ERC20TopDown { + + /// @dev This emits when a token receives ERC20 tokens. + /// @param _from The prior owner of the token. + /// @param _tokenId The token that receives the ERC20 tokens. + /// @param _erc20Contract The ERC20 contract. + /// @param _value The number of ERC20 tokens received. + event ReceivedERC20( + address indexed _from, + uint256 indexed _tokenId, + address indexed _erc20Contract, + uint256 _value + ); + + /// @dev This emits when a token transfers ERC20 tokens. + /// @param _tokenId The token that owned the ERC20 tokens. + /// @param _to The address that receives the ERC20 tokens. + /// @param _erc20Contract The ERC20 contract. + /// @param _value The number of ERC20 tokens transferred. + event TransferERC20( + uint256 indexed _tokenId, + address indexed _to, + address indexed _erc20Contract, + uint256 _value + ); + + /// @notice A token receives ERC20 tokens + /// @param _from The prior owner of the ERC20 tokens + /// @param _value The number of ERC20 tokens received + /// @param _data Up to the first 32 bytes contains an integer which is the receiving tokenId. + function tokenFallback(address _from, uint256 _value, bytes _data) external; + + /// @notice Look up the balance of ERC20 tokens for a specific token and ERC20 contract + /// @param _tokenId The token that owns the ERC20 tokens + /// @param _erc20Contract The ERC20 contract + /// @return The number of ERC20 tokens owned by a token from an ERC20 contract + function balanceOfERC20(uint256 _tokenId, address _erc20Contract) external view returns(uint256); + + /// @notice Transfer ERC20 tokens to address + /// @param _tokenId The token to transfer from + /// @param _value The address to send the ERC20 tokens to + /// @param _erc20Contract The ERC20 contract + /// @param _value The number of ERC20 tokens to transfer + function transferERC20(uint256 _tokenId, address _to, address _erc20Contract, uint256 _value) external; + + /// @notice Transfer ERC20 tokens to address or ERC20 top-down composable + /// @param _tokenId The token to transfer from + /// @param _value The address to send the ERC20 tokens to + /// @param _erc223Contract The ERC223 token contract + /// @param _value The number of ERC20 tokens to transfer + /// @param _data Additional data with no specified format, can be used to specify tokenId to transfer to + function transferERC223(uint256 _tokenId, address _to, address _erc223Contract, uint256 _value, bytes _data) + external; + + /// @notice Get ERC20 tokens from ERC20 contract. + /// @param _from The current owner address of the ERC20 tokens that are being transferred. + /// @param _tokenId The token to transfer the ERC20 tokens to. + /// @param _erc20Contract The ERC20 token contract + /// @param _value The number of ERC20 tokens to transfer + function getERC20(address _from, uint256 _tokenId, address _erc20Contract, uint256 _value) external; +} +``` +#### tokenFallback +```solidity +/// @notice A token receives ERC20 tokens +/// @param _from The prior owner of the ERC20 tokens +/// @param _value The number of ERC20 tokens received +/// @param _data Up to the first 32 bytes contains an integer which is the receiving tokenId. +function tokenFallback(address _from, uint256 _value, bytes _data) external; +``` + +This function comes from the [ERC223 standard](https://github.com/ethereum/EIPs/issues/223) which is an extension of the ERC20 standard. This function is called on the receiving contract from the sending contract when ERC20 tokens are transferred. This function is how the ERC20 top-down composable contract gets notified that one of its tokens received ERC20 tokens. Which token received ERC20 tokens is specified in the `_data` parameter. + +#### balanceOfERC20 +```solidity +/// @notice Look up the balance of ERC20 tokens for a specific token and ERC20 contract +/// @param _tokenId The token that owns the ERC20 tokens +/// @param _erc20Contract The ERC20 contract +/// @return The number of ERC20 tokens owned by a token from an ERC20 contract +function balanceOfERC20(uint256 _tokenId, address _erc20Contract) external view returns(uint256); +``` + +Gets the balance of ERC20 tokens owned by a token from a specific ERC20 contract. + +#### transferERC20 +```solidity +/// @notice Transfer ERC20 tokens to address +/// @param _tokenId The token to transfer from +/// @param _value The address to send the ERC20 tokens to +/// @param _erc20Contract The ERC20 contract +/// @param _value The number of ERC20 tokens to transfer +function transferERC20(uint256 _tokenId, address _to, address _erc20Contract, uint256 _value) external; +``` + +This is used to transfer ERC20 tokens from a token to an address. This function calls `ERC20(_erc20Contract).transfer(_to, _value)`; + +This function must authenticate `msg.sender`. + +#### transferERC223 +```solidity + /// @notice Transfer ERC20 tokens to address or ERC20 top-down composable + /// @param _tokenId The token to transfer from + /// @param _value The address to send the ERC20 tokens to + /// @param _erc223Contract The ERC223 token contract + /// @param _value The number of ERC20 tokens to transfer + /// @param _data Additional data with no specified format, can be used to specify tokenId to transfer to + function transferERC223(uint256 _tokenId, address _to, address _erc223Contract, uint256 _value, bytes _data) + external; +``` + +This function is from the [ERC223 standard](https://github.com/ethereum/EIPs/issues/223). It is used to transfer ERC20 tokens from a token to an address or to another token by putting an integer token value in the `_data` argument. + +This function must authenticate `msg.sender`. + +#### getERC20 +```solidity +/// @notice Get ERC20 tokens from ERC20 contract. +/// @param _from The current owner address of the ERC20 tokens that are being transferred. +/// @param _tokenId The token to transfer the ERC20 tokens to. +/// @param _erc20Contract The ERC20 token contract +/// @param _value The number of ERC20 tokens to transfer +function getERC20(address _from, uint256 _tokenId, address _erc20Contract, uint256 _value) external; +``` + +This function is used to transfer ERC20 tokens to an ERC20 top-down composable when an ERC20 contract does not have a `transferERC223(uint256 _tokenId, address _to, address _erc223Contract, uint256 _value, bytes _data)` function. + +Before this function can be used the ERC20 top-down composable contract address must be approved in the ERC20 contract to transfer the ERC20 tokens. + +This function must authenticate that `msg.sender` equals `_from` or has been approved in the ERC20 contract. + +#### ERC20 Top-Down Composable Enumeration +Optional interface for top-down composable enumeration: + +```solidity +/// @dev The ERC-165 identifier for this interface is 0xc5fd96cd +interface ERC998ERC20TopDownEnumerable { + + /// @notice Get the number of ERC20 contracts that token owns ERC20 tokens from + /// @param _tokenId The token that owns ERC20 tokens. + /// @return uint256 The number of ERC20 contracts + function totalERC20Contracts(uint256 _tokenId) external view returns(uint256); + + /// @notice Get an ERC20 contract that token owns ERC20 tokens from by index + /// @param _tokenId The token that owns ERC20 tokens. + /// @param _index The index position of the ERC20 contract. + /// @return address The ERC20 contract + function erc20ContractByIndex(uint256 _tokenId, uint256 _index) external view returns(address); +} +``` + +### ERC721 Bottom-Up Composable + +ERC721 bottom-up composables are ERC721 tokens that attach themselves to other ERC721 tokens. + +ERC721 bottom-up composable contracts store the owning address of a token and the parent tokenId if any. + +```solidity +/// @title ERC998ERC721 Bottom-Up Composable Non-Fungible Token +/// @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-998.md +/// Note: the ERC-165 identifier for this interface is 0xa1b23002 +interface ERC998ERC721BottomUp { + + /// @dev This emits when a token is transferred to an ERC721 token + /// @param _toContract The contract the token is transferred to + /// @param _toTokenId The token the token is transferred to + /// @param _tokenId The token that is transferred + event TransferToParent( + address indexed _toContract, + uint256 indexed _toTokenId, + uint256 _tokenId + ); + + /// @dev This emits when a token is transferred from an ERC721 token + /// @param _fromContract The contract the token is transferred from + /// @param _fromTokenId The token the token is transferred from + /// @param _tokenId The token that is transferred + event TransferFromParent( + address indexed _fromContract, + uint256 indexed _fromTokenId, + uint256 _tokenId + ); + + /// @notice Get the root owner of tokenId. + /// @param _tokenId The token to query for a root owner address + /// @return rootOwner The root owner at the top of tree of tokens. + function rootOwnerOf(uint256 _tokenId) external view returns (bytes rootOwner); + + /// @notice Get the owner addess and parent token (if there is one) of a token + /// @param _tokenId The tokenId to query. + /// @return tokenOwner The owner address of the token + /// @return parentTokenId The parent owner of the token + /// @return isParent True if parentTokenId is a valid parent tokenId and false if there is no parent tokenId + function tokenOwnerOf(uint256 _tokenId) + external + view + returns (address tokenOwner, uint256 parentTokenId, bool isParent); + + /// @notice Transfer token from owner address to a token + /// @param _from The owner address + /// @param _toContract The ERC721 contract of the receiving token + /// @param _toToken The receiving token + /// @param _data Additional data with no specified format + function transferToParent(address _from, address _toContract, uint256 _toTokenId, uint256 _tokenId, bytes _data) + external; + + /// @notice Transfer token from a token to an address + /// @param _fromContract The address of the owning contract + /// @param _fromTokenId The owning token + /// @param _to The address the token is transferred to. + /// @param _tokenId The token that is transferred + /// @param _data Additional data with no specified format + function transferFromParent(address _fromContract, uint256 _fromTokenId, address _to, uint256 _tokenId, bytes _data) + external; + + /// @notice Transfer a token from a token to another token + /// @param _fromContract The address of the owning contract + /// @param _fromTokenId The owning token + /// @param _toContract The ERC721 contract of the receiving token + /// @param _toToken The receiving token + /// @param _tokenId The token that is transferred + /// @param _data Additional data with no specified format + function transferAsChild(address _fromContract, uint256 _fromTokenId, address _toContract, uint256 _toTokenId, uint256 _tokenId, bytes _data) + external; +} +``` + +#### rootOwnerOf +```solidity +/// @notice Get the root owner of tokenId. +/// @param _tokenId The token to query for a root owner address +/// @return rootOwner The root owner at the top of tree of tokens. +function rootOwnerOf(uint256 _tokenId) public view returns (bytes32 rootOwner); +``` + +This function traverses token owners until the the root owner address of `_tokenId` is found. + +The first 4 bytes of rootOwner contain the ERC998 magic value `0x62ff4869`. The last 20 bytes contain the root owner address. + +The magic value is returned because this function may be called on contracts when it is unknown if the contracts have a `rootOwnerOf` function. The magic value is used in such calls to ensure a valid return value is received. + +If it is unknown whether a contract has the `rootOwnerOf` function then the magic value must be compared to `0x62ff4869`. + +`0x62ff4869` is equal to: `this.rootOwnerOf.selector ^ this.rootOwnerOfChild.selector;` + +Here is an example of a value returned by `rootOwnerOf`. +`0x62ff48690000000000000000e5240103e1ff986a2c8ae6b6728ffe0d9a395c59` + +#### tokenOwnerOf +```solidity +/// @notice Get the owner addess and parent token (if there is one) of a token +/// @param _tokenId The tokenId to query. +/// @return tokenOwner The owner address of the token +/// @return parentTokenId The parent owner of the token +/// @return isParent True if parentTokenId is a valid parent tokenId and false if there is no parent tokenId +function tokenOwnerOf(uint256 _tokenId) + external + view + returns (address tokenOwner, uint256 parentTokenId, bool isParent); +``` + +This function is used to get the owning address and parent tokenId of a token if there is one stored in the contract. + +If `isParent` is true then `tokenOwner` is the owning ERC721 contract address and `parentTokenId` is a valid parent tokenId. If `isParent` is false then `tokenOwner` is a user address and `parentTokenId` does not contain a valid parent tokenId and must be ignored. + +#### transferToParent +```solidity +/// @notice Transfer token from owner address to a token +/// @param _from The owner address +/// @param _toContract The ERC721 contract of the receiving token +/// @param _toToken The receiving token +/// @param _data Additional data with no specified format +function transferToParent(address _from, address _toContract, uint256 _toTokenId, uint256 _tokenId, bytes _data) + external; +``` + +This function is used to transfer a token from an address to a token. `msg.sender` must be authenticated. + +This function must check that `_toToken` exists in `_toContract` and throw if not. + + +#### transferFromParent +```solidity +/// @notice Transfer token from a token to an address +/// @param _fromContract The address of the owning contract +/// @param _fromTokenId The owning token +/// @param _to The address the token is transferred to. +/// @param _tokenId The token that is transferred +/// @param _data Additional data with no specified format +function transferFromParent(address _fromContract, uint256 _fromTokenId, address _to, uint256 _tokenId, bytes _data) + external; +``` +This function is used to transfer a token from a token to an address. `msg.sender` must be authenticated. + +This function must check that `_fromContract` and `_fromTokenId` own `_tokenId` and throw not. + +#### transferAsChild +```solidity +/// @notice Transfer a token from a token to another token +/// @param _fromContract The address of the owning contract +/// @param _fromTokenId The owning token +/// @param _toContract The ERC721 contract of the receiving token +/// @param _toToken The receiving token +/// @param _tokenId The token that is transferred +/// @param _data Additional data with no specified format +function transferAsChild(address _fromContract, uint256 _fromTokenId, address _toContract, uint256 _toTokenId, uint256 _tokenId, bytes _data) + external; +``` + +This function is used to transfer a token from a token to another token. `msg.sender` must be authenticated. + +This function must check that `_toToken` exists in `_toContract` and throw if not. + +This function must check that `_fromContract` and `_fromTokenId` own `_tokenId` and throw if not. + +#### ERC721 Bottom-Up Composable Enumeration +Optional interface for bottom-up composable enumeration: + +```solidity +/// @dev The ERC-165 identifier for this interface is 0x8318b539 +interface ERC998ERC721BottomUpEnumerable { + + /// @notice Get the number of ERC721 tokens owned by parent token. + /// @param _parentContract The contract the parent ERC721 token is from. + /// @param _parentTokenId The parent tokenId that owns tokens + // @return uint256 The number of ERC721 tokens owned by parent token. + function totalChildTokens(address _parentContract, uint256 _parentTokenId) external view returns (uint256); + + /// @notice Get a child token by index + /// @param _parentContract The contract the parent ERC721 token is from. + /// @param _parentTokenId The parent tokenId that owns the token + /// @param _index The index position of the child token + /// @return uint256 The child tokenId owned by the parent token + function childTokenByIndex(address _parentContract, uint256 _parentTokenId, uint256 _index) + external + view + returns (uint256); +} +``` + +## Rationale +Two different kinds of composable (top-down and bottom-up) exist to handle different use cases. A regular ERC721 token cannot own a top-down composable, but it can own a bottom-up composable. A bottom-up composable cannot own a regular ERC721 but a top-down composable can own a regular ERC721 token. Having multiple kinds of composables enable different token ownership possibilities. + +#### Which Kind of Composable To Use? + +If you want to transfer regular ERC721 tokens to non-fungible tokens, then use top-down composables. + +If you want to transfer non-fungible tokens to regular ERC721 tokens then use bottom-up composables. + +### Additional Reading Material +[Top-Down and Bottom-Up Composables, What's the Difference and Which One Should You Use?](https://hackernoon.com/top-down-and-bottom-up-composables-whats-the-difference-and-which-one-should-you-use-db939f6acf1d) + +## Backwards Compatibility +Composables are designed to work with ERC721, ERC223 and ERC20 tokens. + +Some older ERC721 contracts do not have a `safeTransferFrom` function. The `getChild` function can still be used to transfer a token to an ERC721 top-down composable. + +If an ERC20 contract does not have the ERC223 function `transfer(address _to, uint _value, bytes _data)` then the `getERC20` function can still be used to transfer ERC20 tokens to an ERC20 top-down composable. + + +## Implementations + +An implementation can be found here: https://github.com/mattlockyer/composables-998 + + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + + +