An extension of the [ERC20](https://eips.ethereum.org/EIPS/eip-20) and [ERC223](https://github.com/ethereum/EIPs/issues/223) standards to enable ERC20 and ERC223 tokens to be owned by ERC721 tokens.
With composable tokens it is possible to compose lists or trees of ERC721 and ERC20 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.
Different composables, top-down and bottom-up, have their advantages and disadvantages which are explained in the [Rational section](#rationale). It is possible for a token to be one or more kinds of composable token.
ERC998ERC721 top-down, ERC998ERC20 top-down, and ERC998ERC721 bottom-up composable contracts must implement the [ERC721 interface](https://eips.ethereum.org/EIPS/eip-721).
Authenticating whether a user or contract can execute some action works the same for both ERC998ERC721 top-down and ERC998ERC721 bottom-up composables.
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 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. 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.
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.
ERC998ERC721 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 a composable will return the root owner address at the top of the ownership tree.
It is important to get the traversal logic of `rootOwnerOf` right. The logic for `rootOwnerOf` is the same whether or not a composable is bottom-up or top-down or both.
Here is the logic:
```
Logic for rootOwnerOf(uint256 _tokenId)
If the token is a bottom-up composable and has a parent token then call rootOwnerOf for the parent token.
If the call was successful then the returned address is the rootOwner.
Otherwise call rootOwnerOfChild for the parent token.
If the call was successful then the returned address is the rootOwner.
Otherwise get the owner address of the token and that is the rootOwner.
Otherwise call rootOwnerOfChild for the token
If the call was successful then the returned address is the rootOwner.
Otherwise get the owner address of the token and that is the rootOwner.
```
Calling `rootOwnerOfChild` for a token means the following logic:
```solidity
// Logic for calling rootOwnerOfChild for a tokenId
But understand that the real call to `rootOwnerOfChild` should be made with assembly so that the code can check if the call failed and so that the `staticcall` opcode is used to ensure that no state is modified.
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.
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(uint256 _fromTokenId, 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`.
ERC20 bottom-up composables are ERC20 tokens that attach themselves to ERC721 tokens, or are owned by a user address like standard ERC20 tokens.
When owned by an ERC721 token, ERC20 bottom-up composable contracts store the owning address of a token and the parent tokenId. ERC20 bottom-up composables add several methods to the ERC20 and ERC223 interfaces allowing for querying the balance of parent tokens, and transferring tokens to, from, and between parent tokens.
This functionality can be implemented by adding one additional mapping to track balances of tokens, in addition to the standard mapping for tracking user address balances.
```solidity
/// @dev This mapping tracks standard ERC20/ERC223 ownership, where an address owns
/// a particular amount of tokens.
mapping(address => uint) userBalances;
/// @dev This additional mapping tracks ERC998 ownership, where an ERC721 token owns
/// a particular amount of tokens. This tracks contractAddres => tokenId => balance
This function returns the balance of a non-fungible token. It mirrors the standard ERC20 method `balanceOf`, but accepts the address of the parent token's contract, and the parent token's ID. This method behaves identically to `balanceOf`, but checks for ownership by ERC721 tokens rather than user addresses.
#### transferToParent
```solidity
/// @notice Transfer tokens 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 _amount The amount of tokens to transfer
This function transfers an amount of tokens from a user address to an ERC721 token. This function MUST ensure that the recipient contract implements ERC721 using the ERC165 `supportsInterface` function. This function SHOULD ensure that the recipient token actually exists, by calling `ownerOf` on the recipient token's contract, and ensuring it neither throws nor returns the zero address. This function MUST emit the `TransferToParent` event upon a successful transfer (in addition to the standard ERC20 `Transfer` event!). This function MUST throw if the `_from` account balance does not have enough tokens to spend.
This function transfers an amount of tokens from an ERC721 token to an address. This function MUST emit the `TransferFromParent` event upon a successful transfer (in addition to the standard ERC20 `Transfer` event!). This function MUST throw if the balance of the sender ERC721 token is less than the `_amount` specified. This function MUST verify that the `msg.sender` owns the sender ERC721 token, and MUST throw otherwise.
#### transferFromParentERC223
```solidity
/// @notice Transfer token from a token to an address, using ERC223 semantics
/// @param _fromContract The address of the owning contract
/// @param _fromTokenId The owning token
/// @param _to The address the token is transferred to
/// @param _amount The amount of tokens to transfer
/// @param _data Additional data with no specified format, can be used to specify the sender tokenId
This function transfers an amount of tokens from an ERC721 token to an address. This function has identical requirements to `transferFromParent`, except that it additionally MUST invoke `tokenFallback` on the recipient address, if the address is a contract, as specified by ERC223.
This function transfers an amount of tokens from an ERC721 token to another ERC721 token. This function MUST emit BOTH the `TransferFromParent` and `TransferToParent` events (in addition to the standard ERC20 `Transfer` event!). This function MUST throw if the balance of the sender ERC721 token is less than the `_amount` specified. This function MUST verify that the `msg.sender` owns the sender ERC721 token, and MUST throw otherwise. This function MUST ensure that the recipient contract implements ERC721 using the ERC165 `supportsInterface` function. This function SHOULD ensure that the recipient token actually exists, by calling `ownerOf` on the recipient token's contract, and ensuring it neither throws nor returns the zero address.
### Notes
For backwards-compatibility, implementations MUST emit the standard ERC20 `Transfer` event when a transfer occurs, regardless of whether the sender and recipient are addresses or ERC721 tokens. In the case that either sender or recipient are tokens, the corresponding parameter in the `Transfer` event SHOULD be the contract address of the token.
Implementations MUST implement all ERC20 and ERC223 functions in addition to the functions specified in this interface.
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)
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/).
