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.
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 {
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".
### 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**.
Another example is the `safeTransferChild(uint256 _fromTokenId, address _to, address _childContract, uint256 _childTokenId)` function. The `_fromTokenId` is the **from**, the `_to` is the **to** and the `address _childContract, address _childTokenId` parameters are the **what**.
### transferFrom/safeTransferFrom Functions Do Not Transfer Tokens Owned By Tokens
In bottom-up and top-down composable contracts the `transferFrom` and `safeTransferFrom` functions must throw if they are called directly to transfer a token that is owned by another token.
The reason for this is that these functions do not explicitly specify which token owns a token to be transferred. [See the rational section for more information about this.](#explicit-transfer-parameters)
`transferFrom/safeTransferFrom` functions must be used to transfer tokens that are owned by an address.
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.
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 first four bytes of the `rootOwner` return value must be compared to `0xcd740db5`.
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 `rootOwnerOfChild` function then the first four bytes of the `rootOwner` return value must be compared to `0xcd740db5`.
The first 4 bytes of parentTokenOwner contain the ERC998 magic value `0xcd740db5`. The last 20 bytes contain the parent token owner address.
The magic value is returned because this function may be called on contracts when it is unknown if the contracts have a `ownerOfChild` 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 `ownerOfChild` function then the first four bytes of the `parentTokenOwner` return value must be compared to `0xcd740db5`.
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)")))`.
#### 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.
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.
/// @notice Transfer bottom-up composable child token from top-down composable to other ERC721 token.
/// @param _fromTokenId The owning token to transfer from.
/// @param _toContract The ERC721 contract of the receiving token
/// @param _toToken The receiving token
/// @param _childContract The bottom-up composable contract of the child token.
/// @param _childTokenId The token that is being transferred.
/// @param _data Additional data with no specified format
function transferChildToParent(
uint256 _fromTokenId,
address _toContract,
uint256 _toTokenId,
address _childContract,
uint256 _childTokenId,
bytes _data
)
external
```
This function authenticates `msg.sender` and transfers a child bottom-up composable token from a top-down composable to a different ERC721 token. This function can only be used when the child token is a bottom-up composable token. It is designed to transfer a bottom-up composable token from a top-down composable to an ERC721 token (bottom-up style) in one transaction.
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.
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:
/// @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
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
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.
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 first four bytes of the `rootOwner` return value must be compared to `0xcd740db5`.
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.
The first 4 bytes of `tokenOwner` contain the ERC998 magic value `0xcd740db5`. The last 20 bytes contain the token owner address.
The magic value is returned because this function may be called on contracts when it is unknown if the contracts have a `tokenOwnerOf` 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 first four bytes of the `tokenOwner` return value must be compared to `0xcd740db5`.
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.
Every ERC998 transfer function includes explicit parameters to specify the prior owner and the new owner of a token. Explicitly providing **from** and **to** is done intentionally to avoid situations where tokens are transferred in unintended ways.
Here is an example of what could occur if **from** was not explicitly provided in transfer functions:
> An exchange contract is an approved operator in a specific composable contract for user A, user B and user C.
>
> User A transfers token 1 to user B. At the same time the exchange contract transfers token 1 to user C (with the implicit intention to transfer from user A). User B gets token 1 for a minute before it gets incorrectly transferred to user C. The second transfer should have failed but it didn't because no explicit **from** was provided to ensure that token 1 came from user A.
[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/).
