From 49fbbde7c7017e746e9e5817df5c8be802205822 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Fri, 3 May 2019 17:27:23 -0400 Subject: [PATCH 01/58] EDT-3069 Adding more clarity in transfer rules and other things, altered accept/reject logic to one mentioned in github discussion thread and compatibility section mentioning 1155+721 hybrid, plus we are now at Solidity 0.5.8 and my email should match github. --- EIPS/eip-1155.md | 135 ++++++++++++++++++++++++++++++++++------------- 1 file changed, 98 insertions(+), 37 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index edda721eb36ca..23801061477e8 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -1,7 +1,7 @@ --- eip: 1155 title: ERC-1155 Multi Token Standard -author: Witek Radomski , Andrew Cooke , Philippe Castonguay , James Therien , Eric Binet +author: Witek Radomski , Andrew Cooke , Philippe Castonguay , James Therien , Eric Binet type: Standards Track category: ERC status: Draft @@ -34,7 +34,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S **Smart contracts implementing the ERC-1155 standard MUST implement the `ERC1155` and `ERC165` interfaces.** ```solidity -pragma solidity ^0.5.7; +pragma solidity ^0.5.8; /** @title ERC-1155 Multi Token Standard @@ -63,7 +63,7 @@ interface ERC1155 /* is ERC165 */ { event TransferBatch(address indexed _operator, address indexed _from, address indexed _to, uint256[] _ids, uint256[] _values); /** - @dev MUST emit when an approval is updated. + @dev MUST emit when approval for a second party/operator address to manage all tokens for an owner address is enabled or disabled (absense of an event assumes disabled). */ event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved); @@ -77,34 +77,34 @@ interface ERC1155 /* is ERC165 */ { /** @notice Transfers value amount of an _id from the _from address to the _to address specified. @dev MUST emit TransferSingle event on success. - Caller must be approved to manage the _from account's tokens (see isApprovedForAll). - MUST throw if `_to` is the zero address. - MUST throw if balance of sender for token `_id` is lower than the `_value` sent. - MUST throw on any other error. - When transfer is complete, this function MUST check if `_to` is a smart contract (code size > 0). If so, it MUST call `onERC1155Received` on `_to` and revert if the return value is not `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))`. + Caller must be approved to manage the _from account's tokens (see "Approval" section of the standard). + MUST revert if `_to` is the zero address. + MUST revert if balance of sender for token `_id` is lower than the `_value` sent. + MUST revert on any other error. + After the transfer succeeds, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). @param _from Source address @param _to Target address @param _id ID of the token type @param _value Transfer amount - @param _data Additional data with no specified format, sent in call to `_to` + @param _data Additional data with no specified format, sent in call to `onERC1155Received` on `_to` */ function safeTransferFrom(address _from, address _to, uint256 _id, uint256 _value, bytes calldata _data) external; /** @notice Send multiple types of Tokens from a 3rd party in one transfer (with safety call). @dev MUST emit TransferBatch event on success. - Caller must be approved to manage the _from account's tokens (see isApprovedForAll). - MUST throw if `_to` is the zero address. - MUST throw if length of `_ids` is not the same as length of `_values`. - MUST throw if any of the balance of sender for token `_ids` is lower than the respective `_values` sent. - MUST throw on any other error. - When transfer is complete, this function MUST check if `_to` is a smart contract (code size > 0). If so, it MUST call `onERC1155BatchReceived` on `_to` and revert if the return value is not `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))`. + Caller must be approved to manage the _from account's tokens (see "Approval" section of the standard). + MUST revert if `_to` is the zero address. + MUST revert if length of `_ids` is not the same as length of `_values`. + MUST revert if any of the balance of sender for token `_ids` is lower than the respective `_values` sent. + MUST revert on any other error. Transfers and events MUST occur in the array order they were submitted (_ids[0] before _ids[1], etc). + After all the transfer(s) in the batch succeed, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155BatchReceived` on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). @param _from Source addresses @param _to Target addresses - @param _ids IDs of each token type - @param _values Transfer amounts per token type - @param _data Additional data with no specified format, sent in call to `_to` + @param _ids IDs of each token type (order and length must match _values array) + @param _values Transfer amounts per token type (order and length must match _ids array) + @param _data Additional data with no specified format, sent in call to `onERC1155BatchReceived` on `_to` */ function safeBatchTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external; @@ -144,58 +144,116 @@ interface ERC1155 /* is ERC165 */ { ### ERC-1155 Token Receiver -Smart contracts **MUST** implement this interface to accept transfers. +Smart contracts **MUST** implement this interface to accept transfers. See "Safe Transfer Rules" for further detail. ```solidity -pragma solidity ^0.5.7; +pragma solidity ^0.5.8; interface ERC1155TokenReceiver { /** @notice Handle the receipt of a single ERC1155 token type. - @dev An ERC1155-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeTransferFrom` after the balance has been updated. - This function MAY throw to revert and reject the transfer. - Return of other than the magic value MUST result in the transaction being reverted. + @dev An ERC1155-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeTransferFrom` after the balance has been updated. + This function MUST return whether it accepts or rejects the transfer via the prescribed keccak256 generated values. + Return of any other value than the prescribed keccak256 generated values WILL result in the transaction being reverted. Note: The contract address is always the message sender. - @param _operator The address which called the `safeTransferFrom` function + @param _operator The address which initiated the transfer (i.e. msg.sender) @param _from The address which previously owned the token @param _id The id of the token being transferred @param _value The amount of tokens being transferred @param _data Additional data with no specified format - @return `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))` + @return `bytes4(keccak256("accept_erc1155_tokens()"))`==0x4dc21a2f or `bytes4(keccak256("reject_erc1155_tokens()"))`==0xafed434d */ function onERC1155Received(address _operator, address _from, uint256 _id, uint256 _value, bytes calldata _data) external returns(bytes4); - + /** @notice Handle the receipt of multiple ERC1155 token types. - @dev An ERC1155-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeBatchTransferFrom` after the balances have been updated. - This function MAY throw to revert and reject the transfer. - Return of other than the magic value WILL result in the transaction being reverted. + @dev An ERC1155-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeBatchTransferFrom` after the balances have been updated. + This function MUST return whether it accepts or rejects the transfer via the prescribed keccak256 generated values. + Return of any other value than the prescribed keccak256 generated values WILL result in the transaction being reverted. Note: The contract address is always the message sender. - @param _operator The address which called the `safeBatchTransferFrom` function + @param _operator The address which initiated the batch transfer (i.e. msg.sender) @param _from The address which previously owned the token - @param _ids An array containing ids of each token being transferred - @param _values An array containing amounts of each token being transferred + @param _ids An array containing ids of each token being transferred (order and length must match _values array) + @param _values An array containing amounts of each token being transferred (order and length must match _ids array) @param _data Additional data with no specified format - @return `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` + @return `bytes4(keccak256("accept_batch_erc1155_tokens()"))`==0xac007889 or `bytes4(keccak256("reject_erc1155_tokens()"))`==0xafed434d */ function onERC1155BatchReceived(address _operator, address _from, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external returns(bytes4); } ``` +### Safe Transfer Rules + +To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST operate, a list of rules follows: + +* onERC1155Received and onERC1155BatchReceived MUST NOT be called on an EOA account. +* onERC1155Received and onERC1155BatchReceived MUST NOT be called outside of a mint or transfer process. + +##### When the recipient is a contract: + +* The onERC1155Received hook MUST be called every time one and only one token type is transferred to an address in the transaction. +* The onERC1155Received hook MUST NOT be called when more than one token type is transferred to an address in the transaction. +* The onERC1155BatchReceived hook MUST be called when more than one token type is transferred to an address in the transaction with the entire list of what was transferred to it. +* The onERC1155BatchReceived hook MUST NOT be called when only one token type is transferred to an address in the transaction. + +* If implementation specific functions are used to transfer 1155 tokens to a contract the appropriate hook MUST still be called with the same rules as if safeTransferFrom/safeBatchTransferFrom was used. +* If the destination/to contract does not implement the appropriate hook the transfer MUST be reverted with the one caveat below. + - If the tokens being sent are part of a hybrid implementation of another standard, that particular standard's rules on sending to a contract MAY now be followed instead. See "Compatibility with other standards" section. + +* When calling either onERC1155Received or onERC1155BatchReceived: + - operator MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). + - from MUST be the address of the holder whose balance is decreased. + - to MUST be the address of the recipient whose balance is increased. + - from MUST be 0x0 for a mint. + - data MUST contain the extra information provided by the sender (if any) for a transfer. + - the hook MUST be called after all the balances in the transaction have been updated to match the senders intent. + +* When calling onERC1155Received + - id MUST be the token type being transferred. + - value MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. + - If the return value is anything other than `bytes4(keccak256("accept_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. + +* When calling onERC1155BatchReceived + - ids MUST be the list of tokens being transferred. + - values MUST be the list of number of tokens (specified in ids) the holder balance is decreased by and match what the recipient balance is increased by. + - If the return value is anything other than `bytes4(keccak256("accept_batch_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. + +* The destination/to contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_erc1155_tokens()"))` for onERC1155Received or `bytes4(keccak256("accept_batch_erc1155_tokens()"))` for onERC1155BatchReceived. + - If such explicit acceptance happens the transfer MUST be completed, unless other conditions apply. +* The destination/to contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. + - If such explicit rejection happens, the transfer MUST be reverted with the one caveat below. + - If the tokens being sent are part of a hybrid implementation of another standard, that particular standard's rules on sending to a contract MAY now be followed instead. See "Compatibility with other standards" section. + +* A solidity example of the keccak256 generated constants for the return magic is: + - bytes4 constant public ERC1155_REJECTED = 0xafed434d; // keccak256("reject_erc1155_tokens()") + - bytes4 constant public ERC1155_ACCEPTED = 0x4dc21a2f; // keccak256("accept_erc1155_tokens()") + - bytes4 constant public ERC1155_BATCH_ACCEPTED = 0xac007889; // keccak256("accept_batch_erc1155_tokens()") + +##### Compatibility with other standards + +There have been requirements during the design discussions to have this standard be compatible with older standards when sending to contract addresses, specifically ERC721 at time of writing. +To cater for this there is some leeway with the rejection logic should a contract return `bytes4(keccack256("reject_erc1155_tokens()"))` from the call to onERC1155Received/onERC1155BatchReceived as detailed in the main "Safe Transfer Rules" section above. +In this case the hybrid implementation MAY now follow the secondary standard's rules when transferring token(s) to a contract address. + +Note however it is recommended that a hybrid solution NOT be followed and a pure implementation of a single standard is followed instead, as a hybrid solution is an unproven method to date. + +An example of a hybrid 1155+721 contract is linked in the references section under implementations. + ### Metadata -The URI value allows for ID substitution by clients. If the string `{id}` exists in any URI, clients MUST replace this with the actual token ID in hexadecimal form. This allows for large number of tokens to use the same on-chain string by defining a URI once, for a large collection of tokens. Example of such a URI: `https://token-cdn-domain/{id}.json` would be replaced with `https://token-cdn-domain/780000000000001e000000000000000000000000000000000000000000000000.json` if the client is referring to token ID `780000000000001e000000000000000000000000000000000000000000000000`. +The URI value allows for ID substitution by clients. If the string `{id}` exists in any URI, clients MUST replace this with the actual token ID in hexadecimal form. This allows for large number of tokens to use the same on-chain string by defining a URI once, for a large collection of tokens. Example of such a URI: `https://token-cdn-domain/{id}.json` would be replaced with `https://token-cdn-domain/000000000000000000000000000000000000000000000000000000000004CCE0.json` if the client is referring to token ID 314592/0x4CCE0. The string format of the substituted hexadecimal ID MUST be lowercase alphanumeric: `[0-9a-f]` with no 0x prefix. +The string format of the substituted hexadecimal ID MUST be leading zero padded to 64 hex characters length if necessary. #### Metadata Extensions The following optional extensions can be identified with the (ERC-165 Standard Interface Detection)[https://eips.ethereum.org/EIPS/eip-165]. -Changes to the URI MUST emit the `URI` event if the change can be expressed with an event. If the optional ERC1155Metadata_URI extension is included, the value returned by this function SHOULD be used to retrieve values for which no event was emitted. The function MUST return the same value as the event if it was emitted. +Changes to the URI MUST emit the `URI` event if the change can be expressed with an event (i.e. it isn't dynamic). If the optional ERC1155Metadata_URI extension is included, the 'uri' function SHOULD be used to retrieve values for which no event was emitted. The function MUST return the same value as the event if it was emitted. ```solidity -pragma solidity ^0.5.7; +pragma solidity ^0.5.8; /** Note: The ERC-165 identifier for this interface is 0x0e89341c. @@ -277,7 +335,7 @@ An example of an ERC-1155 Metadata JSON file follows. The properties array propo ##### Localization -Metadata localization should be standardized to increase presentation uniformity accross all languages. As such, a simple overlay method is proposed to enable localization. If the metadata JSON file contains a `localization` attribute, its content MAY be used to provide localized values for fields that need it. The `localization` attribute should be a sub-object with three attributes: `uri`, `default` and `locales`. If the string `{locale}` exists in any URI, it MUST be replaced with the chosen locale by all client software. +Metadata localization should be standardized to increase presentation uniformity across all languages. As such, a simple overlay method is proposed to enable localization. If the metadata JSON file contains a `localization` attribute, its content MAY be used to provide localized values for fields that need it. The `localization` attribute should be a sub-object with three attributes: `uri`, `default` and `locales`. If the string `{locale}` exists in any URI, it MUST be replaced with the chosen locale by all client software. ##### JSON Schema @@ -362,6 +420,9 @@ fr.json: ### Approval The function `setApprovalForAll` allows an operator to manage one's entire set of tokens on behalf of the approver. To permit approval of a subset of token IDs, an interface such as [ERC-1761 Scoped Approval Interface (DRAFT)](https://eips.ethereum.org/EIPS/eip-1761) is suggested. +The counterpart `isAprrovedForAll` provides introspection into status set by `setApprovalForAll`. + +An owner SHOULD be assumed to always be able to operate on their own tokens regardless of approval status, so should SHOULD NOT have to call `setApprovalForAll` to approve themselves as an operator before they can operate on them. ## Rationale From 73a3365000ab8644b9d31c533b7a35785f0313db Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Fri, 3 May 2019 20:09:08 -0400 Subject: [PATCH 02/58] EDT-3069 id substitution example was not lowercase. --- EIPS/eip-1155.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 23801061477e8..afcd5bfb37469 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -241,7 +241,7 @@ An example of a hybrid 1155+721 contract is linked in the references section und ### Metadata -The URI value allows for ID substitution by clients. If the string `{id}` exists in any URI, clients MUST replace this with the actual token ID in hexadecimal form. This allows for large number of tokens to use the same on-chain string by defining a URI once, for a large collection of tokens. Example of such a URI: `https://token-cdn-domain/{id}.json` would be replaced with `https://token-cdn-domain/000000000000000000000000000000000000000000000000000000000004CCE0.json` if the client is referring to token ID 314592/0x4CCE0. +The URI value allows for ID substitution by clients. If the string `{id}` exists in any URI, clients MUST replace this with the actual token ID in hexadecimal form. This allows for large number of tokens to use the same on-chain string by defining a URI once, for a large collection of tokens. Example of such a URI: `https://token-cdn-domain/{id}.json` would be replaced with `https://token-cdn-domain/000000000000000000000000000000000000000000000000000000000004cce0.json` if the client is referring to token ID 314592/0x4CCE0. The string format of the substituted hexadecimal ID MUST be lowercase alphanumeric: `[0-9a-f]` with no 0x prefix. The string format of the substituted hexadecimal ID MUST be leading zero padded to 64 hex characters length if necessary. From ed9f0d1fd8f45136f1b527fc4044176c48f51da0 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Tue, 7 May 2019 00:50:02 -0400 Subject: [PATCH 03/58] EDT-3069 Updated the "Safe Transfer Rules" section to match feedback given in discussion thread. This introduces specific scenarios and rules to match. --- EIPS/eip-1155.md | 111 ++++++++++++++++++++++++++++++----------------- 1 file changed, 71 insertions(+), 40 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index afcd5bfb37469..03cb57eab4a61 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -184,47 +184,77 @@ interface ERC1155TokenReceiver { ### Safe Transfer Rules -To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST operate, a list of rules follows: +To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST operate with respect to the ERC1155TokenReceiver, a list of scenarios and rules follows. +**_Scenario:_** The recipient is not a contract. * onERC1155Received and onERC1155BatchReceived MUST NOT be called on an EOA account. + +**_Scenario:_** The transaction is not a mint/transfer of a token. * onERC1155Received and onERC1155BatchReceived MUST NOT be called outside of a mint or transfer process. -##### When the recipient is a contract: - -* The onERC1155Received hook MUST be called every time one and only one token type is transferred to an address in the transaction. -* The onERC1155Received hook MUST NOT be called when more than one token type is transferred to an address in the transaction. -* The onERC1155BatchReceived hook MUST be called when more than one token type is transferred to an address in the transaction with the entire list of what was transferred to it. -* The onERC1155BatchReceived hook MUST NOT be called when only one token type is transferred to an address in the transaction. - -* If implementation specific functions are used to transfer 1155 tokens to a contract the appropriate hook MUST still be called with the same rules as if safeTransferFrom/safeBatchTransferFrom was used. -* If the destination/to contract does not implement the appropriate hook the transfer MUST be reverted with the one caveat below. - - If the tokens being sent are part of a hybrid implementation of another standard, that particular standard's rules on sending to a contract MAY now be followed instead. See "Compatibility with other standards" section. - -* When calling either onERC1155Received or onERC1155BatchReceived: - - operator MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). - - from MUST be the address of the holder whose balance is decreased. - - to MUST be the address of the recipient whose balance is increased. - - from MUST be 0x0 for a mint. - - data MUST contain the extra information provided by the sender (if any) for a transfer. - - the hook MUST be called after all the balances in the transaction have been updated to match the senders intent. - -* When calling onERC1155Received - - id MUST be the token type being transferred. - - value MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. - - If the return value is anything other than `bytes4(keccak256("accept_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. - -* When calling onERC1155BatchReceived - - ids MUST be the list of tokens being transferred. - - values MUST be the list of number of tokens (specified in ids) the holder balance is decreased by and match what the recipient balance is increased by. - - If the return value is anything other than `bytes4(keccak256("accept_batch_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. - -* The destination/to contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_erc1155_tokens()"))` for onERC1155Received or `bytes4(keccak256("accept_batch_erc1155_tokens()"))` for onERC1155BatchReceived. - - If such explicit acceptance happens the transfer MUST be completed, unless other conditions apply. +**_Scenario:_** The receiver does not implement the necessary ERC1155TokenReceiver interface function(s). +* The transfer MUST be reverted with the one caveat below. + - If the tokens being sent are part of a hybrid implementation of another standard, that particular standard's rules on sending to a contract MAY now be followed instead. See "Compatibility with other standards" section. + +**_Scenario:_** The receiver implements the necessary ERC1155TokenReceiver interface function(s) but returns an unknown value. +* The transfer MUST be reverted. + +**_Scenario:_** The receiver implements the necessary ERC1155TokenReceiver interface function(s) but throws an error. +* The transfer MUST be reverted. + +**_Scenario:_** The receiver implements the ERC1155TokenReceiver interface and is the recipient of one and only one balance change in the transaction (eg. safeTransferFrom called). +* All the balances in the transaction MUST have been updated to match the senders intent before any hook is called on a recipient. +* The appropriate choice of either onERC1155Received or onERC1155BatchReceived MUST be called on the recipient. +* The onERC1155Received hook SHOULD be called on the recipient contract and its rules followed. + - If this hook is called it MUST NOT be called again on the recipient in this transaction. + - See "onERC1155Received common rules" for further rules that MUST be followed. +* The onERC1155BatchReceived hook MAY be called on the recipient contract and its rules followed + - See "onERC1155BatchReceived common rules" for further rules that MUST be followed. + +**_Scenario:_** The receiver implements the ERC1155TokenReceiver interface and is the recipient of more than one balance change in the transaction (eg. safeBatchTransferFrom called). +* All the balances in the transaction MUST have been updated to match the senders intent before any hook is called on a recipient. +* The appropriate choice of either onERC1155Received or onERC1155BatchReceived MUST be called on the recipient. +* The onERC1155BatchReceived hook SHOULD be called on the recipient contract and its rules followed. + - If called the arguments MUST contain/list information on every balance change for the recipient (and only the recipient) in this transaction. + - See "onERC1155BatchReceived common rules" for further rules that MUST be followed. +* The onERC1155Received hook MAY be called on the recipient contract and its rules followed. + - If called it MUST be repeatedly called until information has been passed and return value checked for every balance change for the recipient (and only the recipient) in this transaction. + - See "onERC1155Received common rules" for further rules that MUST be followed. + +**_Scenario:_** Implementation specific functions are used to transfer 1155 tokens to a contract. +* If implementation specific functions are used to transfer 1155 tokens to a contract the appropriate hook(s) MUST still be called with the same rules as if safeTransferFrom/safeBatchTransferFrom was used. +* The appropriate events MUST be correctly emitted as if safeTransferFrom/safeBatchTransferFrom was used. + +##### onERC1155Received common rules: +* If this hook is called onERC1155BatchReceived MUST NOT also be called on the recipient in this transaction. +* The _operator argument MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). +* The _from argument MUST be the address of the holder whose balance is decreased. + - _from MUST be 0x0 for a mint. +* The _id argument MUST be the token type being transferred. +* The _value MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. +* The _data argument MUST contain the extra information provided by the sender (if any) for a transfer. +* The destination/to contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_erc1155_tokens()"))` + - If the return value is `bytes4(keccak256("accept_erc1155_tokens()"))` the transfer MUST be completed, unless other conditions necessitate a revert. * The destination/to contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. - - If such explicit rejection happens, the transfer MUST be reverted with the one caveat below. - - If the tokens being sent are part of a hybrid implementation of another standard, that particular standard's rules on sending to a contract MAY now be followed instead. See "Compatibility with other standards" section. - -* A solidity example of the keccak256 generated constants for the return magic is: + - If the return value is `bytes4(keccak256("reject_erc1155_tokens()"))` the transaction MUST be reverted. +* If the return value is anything other than `bytes4(keccak256("accept_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. + +##### onERC1155BatchReceived common rules: +* If this hook is called onERC1155Received MUST NOT also be called on the recipient in this transaction. +* If this hook is called it MUST NOT be called again on the recipient in this transaction. +* The _operator argument MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). +* The _from argument MUST be the address of the holder whose balance is decreased. + - _from MUST be 0x0 for a mint. +* The _ids argument MUST be the list of tokens being transferred. +* The _values argument MUST be the list of number of tokens (matching the list and order of tokens specified in _ids) the holder balance is decreased by and match what the recipient balance is increased by. +* The _data argument MUST contain the extra information provided by the sender (if any) for a transfer. +* The destination/to contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_batch_erc1155_tokens()"))` + - If the return value is `bytes4(keccak256("accept_batch_erc1155_tokens()"))` the transfer MUST be completed, unless other conditions necessitate a revert. +* The destination/to contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. + - If the return value is `bytes4(keccak256("reject_erc1155_tokens()"))` the transaction MUST be reverted. +* If the return value is anything other than `bytes4(keccak256("accept_batch_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. + +##### A solidity example of the keccak256 generated constants for the return magic is: - bytes4 constant public ERC1155_REJECTED = 0xafed434d; // keccak256("reject_erc1155_tokens()") - bytes4 constant public ERC1155_ACCEPTED = 0x4dc21a2f; // keccak256("accept_erc1155_tokens()") - bytes4 constant public ERC1155_BATCH_ACCEPTED = 0xac007889; // keccak256("accept_batch_erc1155_tokens()") @@ -232,12 +262,13 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op ##### Compatibility with other standards There have been requirements during the design discussions to have this standard be compatible with older standards when sending to contract addresses, specifically ERC721 at time of writing. -To cater for this there is some leeway with the rejection logic should a contract return `bytes4(keccack256("reject_erc1155_tokens()"))` from the call to onERC1155Received/onERC1155BatchReceived as detailed in the main "Safe Transfer Rules" section above. -In this case the hybrid implementation MAY now follow the secondary standard's rules when transferring token(s) to a contract address. +To cater for this there is some leeway with the rejection logic should a contract not implement the ERC1155TokenReceiver as per "Safe Transfer Rules" section above, specifically the scenario "The receiver does not implement the necessary ERC1155TokenReceiver interface function(s)". +In that particular scenario if the 1155 implementation is also a hybrid implementation of another token standard, it MAY now follow the secondary standard's rules when transferring token(s) to a contract address. + +*__Note that a pure implementation of a single standard is recommended__* rather than a hybrid solution, but an example of a hybrid 1155+721 contract is linked in the references section under implementations. -Note however it is recommended that a hybrid solution NOT be followed and a pure implementation of a single standard is followed instead, as a hybrid solution is an unproven method to date. +An important consideration is that even if the tokens are sent with another standard's rules the *__1155 transfer events MUST still be emitted.__* This is so the balances can still be determined via events alone as per 1155 standard rules. -An example of a hybrid 1155+721 contract is linked in the references section under implementations. ### Metadata From e331f582bec125e9e8379159888cb04a93d0d407 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Tue, 7 May 2019 00:58:03 -0400 Subject: [PATCH 04/58] EDT-3069 Some formatting changes to make it easier to digest/ --- EIPS/eip-1155.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 03cb57eab4a61..a6e1d586da351 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -186,6 +186,8 @@ interface ERC1155TokenReceiver { To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST operate with respect to the ERC1155TokenReceiver, a list of scenarios and rules follows. +###### Scenarios + **_Scenario:_** The recipient is not a contract. * onERC1155Received and onERC1155BatchReceived MUST NOT be called on an EOA account. @@ -225,7 +227,9 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * If implementation specific functions are used to transfer 1155 tokens to a contract the appropriate hook(s) MUST still be called with the same rules as if safeTransferFrom/safeBatchTransferFrom was used. * The appropriate events MUST be correctly emitted as if safeTransferFrom/safeBatchTransferFrom was used. -##### onERC1155Received common rules: +###### Rules + +**_onERC1155Received common rules:_** * If this hook is called onERC1155BatchReceived MUST NOT also be called on the recipient in this transaction. * The _operator argument MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). * The _from argument MUST be the address of the holder whose balance is decreased. @@ -239,7 +243,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - If the return value is `bytes4(keccak256("reject_erc1155_tokens()"))` the transaction MUST be reverted. * If the return value is anything other than `bytes4(keccak256("accept_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. -##### onERC1155BatchReceived common rules: +**_onERC1155BatchReceived common rules:_** * If this hook is called onERC1155Received MUST NOT also be called on the recipient in this transaction. * If this hook is called it MUST NOT be called again on the recipient in this transaction. * The _operator argument MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). @@ -254,7 +258,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - If the return value is `bytes4(keccak256("reject_erc1155_tokens()"))` the transaction MUST be reverted. * If the return value is anything other than `bytes4(keccak256("accept_batch_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. -##### A solidity example of the keccak256 generated constants for the return magic is: +###### A solidity example of the keccak256 generated constants for the return magic is: - bytes4 constant public ERC1155_REJECTED = 0xafed434d; // keccak256("reject_erc1155_tokens()") - bytes4 constant public ERC1155_ACCEPTED = 0x4dc21a2f; // keccak256("accept_erc1155_tokens()") - bytes4 constant public ERC1155_BATCH_ACCEPTED = 0xac007889; // keccak256("accept_batch_erc1155_tokens()") From 3e2a17631a1741bd99fe4c3933ad823cfa906be3 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Tue, 7 May 2019 01:01:28 -0400 Subject: [PATCH 05/58] EDT-3069 More formatting. --- EIPS/eip-1155.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index a6e1d586da351..9388ce4a4503f 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -186,7 +186,7 @@ interface ERC1155TokenReceiver { To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST operate with respect to the ERC1155TokenReceiver, a list of scenarios and rules follows. -###### Scenarios +#### Scenarios **_Scenario:_** The recipient is not a contract. * onERC1155Received and onERC1155BatchReceived MUST NOT be called on an EOA account. @@ -227,7 +227,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * If implementation specific functions are used to transfer 1155 tokens to a contract the appropriate hook(s) MUST still be called with the same rules as if safeTransferFrom/safeBatchTransferFrom was used. * The appropriate events MUST be correctly emitted as if safeTransferFrom/safeBatchTransferFrom was used. -###### Rules +#### Rules **_onERC1155Received common rules:_** * If this hook is called onERC1155BatchReceived MUST NOT also be called on the recipient in this transaction. @@ -263,7 +263,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - bytes4 constant public ERC1155_ACCEPTED = 0x4dc21a2f; // keccak256("accept_erc1155_tokens()") - bytes4 constant public ERC1155_BATCH_ACCEPTED = 0xac007889; // keccak256("accept_batch_erc1155_tokens()") -##### Compatibility with other standards +#### Compatibility with other standards There have been requirements during the design discussions to have this standard be compatible with older standards when sending to contract addresses, specifically ERC721 at time of writing. To cater for this there is some leeway with the rejection logic should a contract not implement the ERC1155TokenReceiver as per "Safe Transfer Rules" section above, specifically the scenario "The receiver does not implement the necessary ERC1155TokenReceiver interface function(s)". From 3ba6d4fe9b1b1e9085d0b667b4ca9c1843a7ec0b Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Tue, 7 May 2019 01:16:24 -0400 Subject: [PATCH 06/58] EDT-3069 Move impl specific functions rules to the rules section. --- EIPS/eip-1155.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 9388ce4a4503f..cb1f84593c604 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -223,10 +223,6 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - If called it MUST be repeatedly called until information has been passed and return value checked for every balance change for the recipient (and only the recipient) in this transaction. - See "onERC1155Received common rules" for further rules that MUST be followed. -**_Scenario:_** Implementation specific functions are used to transfer 1155 tokens to a contract. -* If implementation specific functions are used to transfer 1155 tokens to a contract the appropriate hook(s) MUST still be called with the same rules as if safeTransferFrom/safeBatchTransferFrom was used. -* The appropriate events MUST be correctly emitted as if safeTransferFrom/safeBatchTransferFrom was used. - #### Rules **_onERC1155Received common rules:_** @@ -257,6 +253,10 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * The destination/to contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. - If the return value is `bytes4(keccak256("reject_erc1155_tokens()"))` the transaction MUST be reverted. * If the return value is anything other than `bytes4(keccak256("accept_batch_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. + +**_Implementation specific functions are used to transfer 1155 tokens to a contract:_** +* If implementation specific functions are used to transfer 1155 tokens to a contract the appropriate hook(s) MUST still be called with the same rules as if safeTransferFrom/safeBatchTransferFrom was used. +* The appropriate events MUST be correctly emitted as if safeTransferFrom/safeBatchTransferFrom was used. ###### A solidity example of the keccak256 generated constants for the return magic is: - bytes4 constant public ERC1155_REJECTED = 0xafed434d; // keccak256("reject_erc1155_tokens()") From b3f567552031e2055b0f929fa0dd2cfb868ad480 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Tue, 7 May 2019 01:43:08 -0400 Subject: [PATCH 07/58] EDT-3069 Better wording on impl specific api rules. --- EIPS/eip-1155.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index cb1f84593c604..6ceeeb4e8b122 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -254,8 +254,8 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - If the return value is `bytes4(keccak256("reject_erc1155_tokens()"))` the transaction MUST be reverted. * If the return value is anything other than `bytes4(keccak256("accept_batch_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. -**_Implementation specific functions are used to transfer 1155 tokens to a contract:_** -* If implementation specific functions are used to transfer 1155 tokens to a contract the appropriate hook(s) MUST still be called with the same rules as if safeTransferFrom/safeBatchTransferFrom was used. +**_Implementation specific transfer api rules:_** +* If implementation specific api functions are used to transfer 1155 tokens to a contract the appropriate hook(s) MUST still be called with the same rules as if safeTransferFrom/safeBatchTransferFrom was used. * The appropriate events MUST be correctly emitted as if safeTransferFrom/safeBatchTransferFrom was used. ###### A solidity example of the keccak256 generated constants for the return magic is: From f7454438314ef86651494ac71a5f69ca5be12765 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Tue, 7 May 2019 14:41:12 -0400 Subject: [PATCH 08/58] EDT-3069 Added in rules for TransferSingle and TransferBatch events section and numbered the scenarios to be easily identifiable. --- EIPS/eip-1155.md | 80 ++++++++++++++++++++++++++++++------------------ 1 file changed, 51 insertions(+), 29 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 6ceeeb4e8b122..eed5a80d80c41 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -43,20 +43,20 @@ pragma solidity ^0.5.8; */ interface ERC1155 /* is ERC165 */ { /** - @dev Either TransferSingle or TransferBatch MUST emit when tokens are transferred, including zero value transfers as well as minting or burning. - Operator MUST be msg.sender. - When minting/creating tokens, the `_from` field MUST be set to `0x0` - When burning/destroying tokens, the `_to` field MUST be set to `0x0` + @dev Either TransferSingle or TransferBatch MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "TransferSingle and TransferBatch event rules" section of the standard). + `_operator` MUST be msg.sender. + When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address) + When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address) The total value transferred from address 0x0 minus the total value transferred to 0x0 MAY be used by clients and exchanges to be added to the "circulating supply" for a given token ID. To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the TransferSingle event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0. */ event TransferSingle(address indexed _operator, address indexed _from, address indexed _to, uint256 _id, uint256 _value); /** - @dev Either TransferSingle or TransferBatch MUST emit when tokens are transferred, including zero value transfers as well as minting or burning. - Operator MUST be msg.sender. - When minting/creating tokens, the `_from` field MUST be set to `0x0` - When burning/destroying tokens, the `_to` field MUST be set to `0x0` + @dev Either TransferSingle or TransferBatch MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "TransferSingle and TransferBatch event rules" section of the standard). + `_operator` MUST be msg.sender. + When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address) + When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address) The total value transferred from address 0x0 minus the total value transferred to 0x0 MAY be used by clients and exchanges to be added to the "circulating supply" for a given token ID. To broadcast the existence of multiple token IDs with no initial balance, this SHOULD emit the TransferBatch event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0. */ @@ -188,34 +188,34 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op #### Scenarios -**_Scenario:_** The recipient is not a contract. +**_Scenario#1 :_** The recipient is not a contract. * onERC1155Received and onERC1155BatchReceived MUST NOT be called on an EOA account. -**_Scenario:_** The transaction is not a mint/transfer of a token. +**_Scenario#2 :_** The transaction is not a mint/transfer of a token. * onERC1155Received and onERC1155BatchReceived MUST NOT be called outside of a mint or transfer process. -**_Scenario:_** The receiver does not implement the necessary ERC1155TokenReceiver interface function(s). +**_Scenario#3 :_** The receiver does not implement the necessary ERC1155TokenReceiver interface function(s). * The transfer MUST be reverted with the one caveat below. - If the tokens being sent are part of a hybrid implementation of another standard, that particular standard's rules on sending to a contract MAY now be followed instead. See "Compatibility with other standards" section. -**_Scenario:_** The receiver implements the necessary ERC1155TokenReceiver interface function(s) but returns an unknown value. +**_Scenario#4 :_** The receiver implements the necessary ERC1155TokenReceiver interface function(s) but returns an unknown value. * The transfer MUST be reverted. -**_Scenario:_** The receiver implements the necessary ERC1155TokenReceiver interface function(s) but throws an error. +**_Scenario#5 :_** The receiver implements the necessary ERC1155TokenReceiver interface function(s) but throws an error. * The transfer MUST be reverted. -**_Scenario:_** The receiver implements the ERC1155TokenReceiver interface and is the recipient of one and only one balance change in the transaction (eg. safeTransferFrom called). +**_Scenario#6 :_** The receiver implements the ERC1155TokenReceiver interface and is the recipient of one and only one balance change in the transaction (eg. safeTransferFrom called). * All the balances in the transaction MUST have been updated to match the senders intent before any hook is called on a recipient. -* The appropriate choice of either onERC1155Received or onERC1155BatchReceived MUST be called on the recipient. +* onERC1155Received or onERC1155BatchReceived MUST be called on the recipient. * The onERC1155Received hook SHOULD be called on the recipient contract and its rules followed. - If this hook is called it MUST NOT be called again on the recipient in this transaction. - See "onERC1155Received common rules" for further rules that MUST be followed. * The onERC1155BatchReceived hook MAY be called on the recipient contract and its rules followed - See "onERC1155BatchReceived common rules" for further rules that MUST be followed. -**_Scenario:_** The receiver implements the ERC1155TokenReceiver interface and is the recipient of more than one balance change in the transaction (eg. safeBatchTransferFrom called). +**_Scenario#7 :_** The receiver implements the ERC1155TokenReceiver interface and is the recipient of more than one balance change in the transaction (eg. safeBatchTransferFrom called). * All the balances in the transaction MUST have been updated to match the senders intent before any hook is called on a recipient. -* The appropriate choice of either onERC1155Received or onERC1155BatchReceived MUST be called on the recipient. +* onERC1155Received or onERC1155BatchReceived MUST be called on the recipient. * The onERC1155BatchReceived hook SHOULD be called on the recipient contract and its rules followed. - If called the arguments MUST contain/list information on every balance change for the recipient (and only the recipient) in this transaction. - See "onERC1155BatchReceived common rules" for further rules that MUST be followed. @@ -225,14 +225,36 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op #### Rules +**_TransferSingle and TransferBatch event rules:_** +* TransferSingle SHOULD be used to indicate a single balance transfer has occurred between a `_from` and `_to` pair. + - It MAY be emitted multiple times to indicate multiple balance changes in the transaction, but note that TransferBatch is designed for this to reduce gas consumption. + - The `_operator` argument MUST be msg.sender. + - The `_from` argument MUST be the address of the holder whose balance is decreased. + - The `_to` argument MUST be the address of the recipient whose balance is increased. + - The `_id` argument MUST be the token type being transferred. + - The `_value` MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. + - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). + - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). +* TransferBatch SHOULD be used to indicate multiple balance transfers have occurred between a `_from` and `_to` pair. + - It MAY be emitted with a single element in the list to indicate a singular balance change in the transaction, but note that TransferSingle is designed for this to reduce gas consumption. + - The `_operator` argument MUST be msg.sender. + - The `_from` argument MUST be the address of the holder whose balance is decreased. + - The `_to` argument MUST be the address of the recipient whose balance is increased. + - The `_ids` argument MUST be the list of tokens being transferred. + - The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified in _ids) the holder balance is decreased by and match what the recipient balance is increased by. + - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). + - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). +* The total value transferred from address 0x0 minus the total value transferred to 0x0 MAY be used by clients and exchanges to be added to the "circulating supply" for a given token ID. +* To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the TransferSingle event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0. + **_onERC1155Received common rules:_** * If this hook is called onERC1155BatchReceived MUST NOT also be called on the recipient in this transaction. -* The _operator argument MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). -* The _from argument MUST be the address of the holder whose balance is decreased. - - _from MUST be 0x0 for a mint. -* The _id argument MUST be the token type being transferred. -* The _value MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. -* The _data argument MUST contain the extra information provided by the sender (if any) for a transfer. +* The `_operator` argument MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). +* The `_from` argument MUST be the address of the holder whose balance is decreased. + - `_from` MUST be 0x0 for a mint. +* The `_id` argument MUST be the token type being transferred. +* The `_value` MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. +* The `_data` argument MUST contain the extra information provided by the sender (if any) for a transfer. * The destination/to contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_erc1155_tokens()"))` - If the return value is `bytes4(keccak256("accept_erc1155_tokens()"))` the transfer MUST be completed, unless other conditions necessitate a revert. * The destination/to contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. @@ -242,12 +264,12 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op **_onERC1155BatchReceived common rules:_** * If this hook is called onERC1155Received MUST NOT also be called on the recipient in this transaction. * If this hook is called it MUST NOT be called again on the recipient in this transaction. -* The _operator argument MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). -* The _from argument MUST be the address of the holder whose balance is decreased. - - _from MUST be 0x0 for a mint. -* The _ids argument MUST be the list of tokens being transferred. -* The _values argument MUST be the list of number of tokens (matching the list and order of tokens specified in _ids) the holder balance is decreased by and match what the recipient balance is increased by. -* The _data argument MUST contain the extra information provided by the sender (if any) for a transfer. +* The `_operator` argument MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). +* The `_from` argument MUST be the address of the holder whose balance is decreased. + - `_from` MUST be 0x0 for a mint. +* The `_ids` argument MUST be the list of tokens being transferred. +* The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified in _ids) the holder balance is decreased by and match what the recipient balance is increased by. +* The `_data` argument MUST contain the extra information provided by the sender (if any) for a transfer. * The destination/to contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_batch_erc1155_tokens()"))` - If the return value is `bytes4(keccak256("accept_batch_erc1155_tokens()"))` the transfer MUST be completed, unless other conditions necessitate a revert. * The destination/to contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. From 1f3a415c5660361b5e5e01d3ca1eee7f2484d16a Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Tue, 7 May 2019 23:37:01 -0400 Subject: [PATCH 09/58] EDT-3069 EOA explanation. --- EIPS/eip-1155.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index eed5a80d80c41..92147798b8395 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -189,7 +189,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op #### Scenarios **_Scenario#1 :_** The recipient is not a contract. -* onERC1155Received and onERC1155BatchReceived MUST NOT be called on an EOA account. +* onERC1155Received and onERC1155BatchReceived MUST NOT be called on an EOA (Externally Owned Account). **_Scenario#2 :_** The transaction is not a mint/transfer of a token. * onERC1155Received and onERC1155BatchReceived MUST NOT be called outside of a mint or transfer process. From 54a4fa1161c69517b4a9b3a46564881b566fd248 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Thu, 9 May 2019 11:36:47 -0400 Subject: [PATCH 10/58] EDT-3069 Updated text after feedback. --- EIPS/eip-1155.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 92147798b8395..cc3ab704a7908 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -204,17 +204,16 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op **_Scenario#5 :_** The receiver implements the necessary ERC1155TokenReceiver interface function(s) but throws an error. * The transfer MUST be reverted. -**_Scenario#6 :_** The receiver implements the ERC1155TokenReceiver interface and is the recipient of one and only one balance change in the transaction (eg. safeTransferFrom called). -* All the balances in the transaction MUST have been updated to match the senders intent before any hook is called on a recipient. -* onERC1155Received or onERC1155BatchReceived MUST be called on the recipient. -* The onERC1155Received hook SHOULD be called on the recipient contract and its rules followed. - - If this hook is called it MUST NOT be called again on the recipient in this transaction. +**_Scenario#6 :_** The receiver implements the ERC1155TokenReceiver interface and is the recipient of one and only one balance change (eg. safeTransferFrom called). +* All the balances in the transfer MUST have been updated to match the senders intent before any hook is called on a recipient. +* One of onERC1155Received or onERC1155BatchReceived MUST be called on the recipient. +* The onERC1155Received hook SHOULD be called on the recipient contract and its rules followed. - See "onERC1155Received common rules" for further rules that MUST be followed. -* The onERC1155BatchReceived hook MAY be called on the recipient contract and its rules followed +* The onERC1155BatchReceived hook MAY be called on the recipient contract and its rules followed. - See "onERC1155BatchReceived common rules" for further rules that MUST be followed. -**_Scenario#7 :_** The receiver implements the ERC1155TokenReceiver interface and is the recipient of more than one balance change in the transaction (eg. safeBatchTransferFrom called). -* All the balances in the transaction MUST have been updated to match the senders intent before any hook is called on a recipient. +**_Scenario#7 :_** The receiver implements the ERC1155TokenReceiver interface and is the recipient of more than one balance change (eg. safeBatchTransferFrom called). +* All the balances in the transfer MUST have been updated to match the senders intent before any hook is called on a recipient. * onERC1155Received or onERC1155BatchReceived MUST be called on the recipient. * The onERC1155BatchReceived hook SHOULD be called on the recipient contract and its rules followed. - If called the arguments MUST contain/list information on every balance change for the recipient (and only the recipient) in this transaction. @@ -248,7 +247,6 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the TransferSingle event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0. **_onERC1155Received common rules:_** -* If this hook is called onERC1155BatchReceived MUST NOT also be called on the recipient in this transaction. * The `_operator` argument MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). * The `_from` argument MUST be the address of the holder whose balance is decreased. - `_from` MUST be 0x0 for a mint. @@ -260,10 +258,11 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * The destination/to contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. - If the return value is `bytes4(keccak256("reject_erc1155_tokens()"))` the transaction MUST be reverted. * If the return value is anything other than `bytes4(keccak256("accept_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. +* onERC1155Received MAY be called multiple times in a single transaction and the following requirements must be met: + - All callbacks represent mutually exclusive balance changes. + - The set of all callbacks describes all balance changes that occurred during the transaction. **_onERC1155BatchReceived common rules:_** -* If this hook is called onERC1155Received MUST NOT also be called on the recipient in this transaction. -* If this hook is called it MUST NOT be called again on the recipient in this transaction. * The `_operator` argument MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). * The `_from` argument MUST be the address of the holder whose balance is decreased. - `_from` MUST be 0x0 for a mint. @@ -275,6 +274,9 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * The destination/to contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. - If the return value is `bytes4(keccak256("reject_erc1155_tokens()"))` the transaction MUST be reverted. * If the return value is anything other than `bytes4(keccak256("accept_batch_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. +* onERC1155BatchReceived MAY be called multiple times in a single transaction and the following requirements must be met: + - All callbacks represent mutually exclusive balance changes. + - The set of all callbacks describes all balance changes that occurred during the transaction. **_Implementation specific transfer api rules:_** * If implementation specific api functions are used to transfer 1155 tokens to a contract the appropriate hook(s) MUST still be called with the same rules as if safeTransferFrom/safeBatchTransferFrom was used. From 2f16e0fb2c8daaeca6c152da1fcd015c6623ace7 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Thu, 9 May 2019 12:16:00 -0400 Subject: [PATCH 11/58] EDT-3069 Another update. --- EIPS/eip-1155.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index cc3ab704a7908..8c81cfeedcfbb 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -207,20 +207,19 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op **_Scenario#6 :_** The receiver implements the ERC1155TokenReceiver interface and is the recipient of one and only one balance change (eg. safeTransferFrom called). * All the balances in the transfer MUST have been updated to match the senders intent before any hook is called on a recipient. * One of onERC1155Received or onERC1155BatchReceived MUST be called on the recipient. -* The onERC1155Received hook SHOULD be called on the recipient contract and its rules followed. - - See "onERC1155Received common rules" for further rules that MUST be followed. -* The onERC1155BatchReceived hook MAY be called on the recipient contract and its rules followed. - - See "onERC1155BatchReceived common rules" for further rules that MUST be followed. +* The onERC1155Received hook SHOULD be called on the recipient contract and its rules followed. + - See "onERC1155Received rules" for further rules that MUST be followed. +* The onERC1155BatchReceived hook MAY be called on the recipient contract and its rules followed. + - See "onERC1155BatchReceived rules" for further rules that MUST be followed. **_Scenario#7 :_** The receiver implements the ERC1155TokenReceiver interface and is the recipient of more than one balance change (eg. safeBatchTransferFrom called). * All the balances in the transfer MUST have been updated to match the senders intent before any hook is called on a recipient. -* onERC1155Received or onERC1155BatchReceived MUST be called on the recipient. -* The onERC1155BatchReceived hook SHOULD be called on the recipient contract and its rules followed. - - If called the arguments MUST contain/list information on every balance change for the recipient (and only the recipient) in this transaction. - - See "onERC1155BatchReceived common rules" for further rules that MUST be followed. -* The onERC1155Received hook MAY be called on the recipient contract and its rules followed. - - If called it MUST be repeatedly called until information has been passed and return value checked for every balance change for the recipient (and only the recipient) in this transaction. - - See "onERC1155Received common rules" for further rules that MUST be followed. +* onERC1155Received or onERC1155BatchReceived MUST be called on the recipient as many times as necessary such that every balance change for the recipient in the scenario is accounted for. + - The return magic value for every hook call MUST be checked and acted upon as per "onERC1155Received rules" and "onERC1155BatchReceived rules". +* The onERC1155BatchReceived hook SHOULD be called on the recipient contract and its rules followed. + - See "onERC1155BatchReceived rules" for further rules that MUST be followed. +* The onERC1155Received hook MAY be called on the recipient contract and its rules followed. + - See "onERC1155Received rules" for further rules that MUST be followed. #### Rules @@ -246,7 +245,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * The total value transferred from address 0x0 minus the total value transferred to 0x0 MAY be used by clients and exchanges to be added to the "circulating supply" for a given token ID. * To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the TransferSingle event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0. -**_onERC1155Received common rules:_** +**_onERC1155Received rules:_** * The `_operator` argument MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). * The `_from` argument MUST be the address of the holder whose balance is decreased. - `_from` MUST be 0x0 for a mint. @@ -262,7 +261,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - All callbacks represent mutually exclusive balance changes. - The set of all callbacks describes all balance changes that occurred during the transaction. -**_onERC1155BatchReceived common rules:_** +**_onERC1155BatchReceived rules:_** * The `_operator` argument MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). * The `_from` argument MUST be the address of the holder whose balance is decreased. - `_from` MUST be 0x0 for a mint. From cdc350b0709fc8363a74d7593d97ef9cb74757cc Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Thu, 9 May 2019 12:42:13 -0400 Subject: [PATCH 12/58] EDT- Minor wording changes, be consistent in how we name ERC numbers in text and make sure 1155 json schema title matches the standard section. --- EIPS/eip-1155.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 8c81cfeedcfbb..bdac3e9457e56 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -70,7 +70,7 @@ interface ERC1155 /* is ERC165 */ { /** @dev MUST emit when the URI is updated for a token ID. URIs are defined in RFC 3986. - The URI MUST point a JSON file that conforms to the "ERC-1155 Metadata JSON Schema". + The URI MUST point a JSON file that conforms to the "ERC-1155 Metadata URI JSON Schema". */ event URI(string _value, uint256 indexed _id); @@ -230,7 +230,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - The `_from` argument MUST be the address of the holder whose balance is decreased. - The `_to` argument MUST be the address of the recipient whose balance is increased. - The `_id` argument MUST be the token type being transferred. - - The `_value` MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. + - The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). * TransferBatch SHOULD be used to indicate multiple balance transfers have occurred between a `_from` and `_to` pair. @@ -250,11 +250,11 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * The `_from` argument MUST be the address of the holder whose balance is decreased. - `_from` MUST be 0x0 for a mint. * The `_id` argument MUST be the token type being transferred. -* The `_value` MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. +* The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. * The `_data` argument MUST contain the extra information provided by the sender (if any) for a transfer. -* The destination/to contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_erc1155_tokens()"))` +* The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_erc1155_tokens()"))` - If the return value is `bytes4(keccak256("accept_erc1155_tokens()"))` the transfer MUST be completed, unless other conditions necessitate a revert. -* The destination/to contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. +* The recipient contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. - If the return value is `bytes4(keccak256("reject_erc1155_tokens()"))` the transaction MUST be reverted. * If the return value is anything other than `bytes4(keccak256("accept_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. * onERC1155Received MAY be called multiple times in a single transaction and the following requirements must be met: @@ -268,9 +268,9 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * The `_ids` argument MUST be the list of tokens being transferred. * The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified in _ids) the holder balance is decreased by and match what the recipient balance is increased by. * The `_data` argument MUST contain the extra information provided by the sender (if any) for a transfer. -* The destination/to contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_batch_erc1155_tokens()"))` +* The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_batch_erc1155_tokens()"))` - If the return value is `bytes4(keccak256("accept_batch_erc1155_tokens()"))` the transfer MUST be completed, unless other conditions necessitate a revert. -* The destination/to contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. +* The recipient contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. - If the return value is `bytes4(keccak256("reject_erc1155_tokens()"))` the transaction MUST be reverted. * If the return value is anything other than `bytes4(keccak256("accept_batch_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. * onERC1155BatchReceived MAY be called multiple times in a single transaction and the following requirements must be met: @@ -279,7 +279,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op **_Implementation specific transfer api rules:_** * If implementation specific api functions are used to transfer 1155 tokens to a contract the appropriate hook(s) MUST still be called with the same rules as if safeTransferFrom/safeBatchTransferFrom was used. -* The appropriate events MUST be correctly emitted as if safeTransferFrom/safeBatchTransferFrom was used. +* The appropriate event(s) MUST be correctly emitted as if safeTransferFrom/safeBatchTransferFrom was used. ###### A solidity example of the keccak256 generated constants for the return magic is: - bytes4 constant public ERC1155_REJECTED = 0xafed434d; // keccak256("reject_erc1155_tokens()") @@ -288,8 +288,8 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op #### Compatibility with other standards -There have been requirements during the design discussions to have this standard be compatible with older standards when sending to contract addresses, specifically ERC721 at time of writing. -To cater for this there is some leeway with the rejection logic should a contract not implement the ERC1155TokenReceiver as per "Safe Transfer Rules" section above, specifically the scenario "The receiver does not implement the necessary ERC1155TokenReceiver interface function(s)". +There have been requirements during the design discussions to have this standard be compatible with older standards when sending to contract addresses, specifically ERC-721 at time of writing. +To cater for this there is some leeway with the rejection logic should a contract not implement the ERC1155TokenReceiver as per "Safe Transfer Rules" section above, specifically "Scenario#3 : The receiver does not implement the necessary ERC1155TokenReceiver interface function(s)". In that particular scenario if the 1155 implementation is also a hybrid implementation of another token standard, it MAY now follow the secondary standard's rules when transferring token(s) to a contract address. *__Note that a pure implementation of a single standard is recommended__* rather than a hybrid solution, but an example of a hybrid 1155+721 contract is linked in the references section under implementations. @@ -320,7 +320,7 @@ interface ERC1155Metadata_URI { /** @notice A distinct Uniform Resource Identifier (URI) for a given token. @dev URIs are defined in RFC 3986. - The URI may point to a JSON file that conforms to the "ERC-1155 Metadata JSON Schema". + The URI may point to a JSON file that conforms to the "ERC-1155 Metadata URI JSON Schema". @return URI string */ function uri(uint256 _id) external view returns (string memory); From 5083d1e1d2b8501aac2ceaf6f14aaeb6fb6ead89 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Thu, 9 May 2019 12:55:36 -0400 Subject: [PATCH 13/58] EDT-3069 Remove confusion on hook return vals and args. --- EIPS/eip-1155.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index bdac3e9457e56..ca70cc431ea9d 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -154,8 +154,7 @@ interface ERC1155TokenReceiver { @notice Handle the receipt of a single ERC1155 token type. @dev An ERC1155-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeTransferFrom` after the balance has been updated. This function MUST return whether it accepts or rejects the transfer via the prescribed keccak256 generated values. - Return of any other value than the prescribed keccak256 generated values WILL result in the transaction being reverted. - Note: The contract address is always the message sender. + Return of any other value than the prescribed keccak256 generated values MUST result in the transaction being reverted. @param _operator The address which initiated the transfer (i.e. msg.sender) @param _from The address which previously owned the token @param _id The id of the token being transferred @@ -169,8 +168,7 @@ interface ERC1155TokenReceiver { @notice Handle the receipt of multiple ERC1155 token types. @dev An ERC1155-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeBatchTransferFrom` after the balances have been updated. This function MUST return whether it accepts or rejects the transfer via the prescribed keccak256 generated values. - Return of any other value than the prescribed keccak256 generated values WILL result in the transaction being reverted. - Note: The contract address is always the message sender. + Return of any other value than the prescribed keccak256 generated values MUST result in the transaction being reverted. @param _operator The address which initiated the batch transfer (i.e. msg.sender) @param _from The address which previously owned the token @param _ids An array containing ids of each token being transferred (order and length must match _values array) From cbc7264612fdac2e6dfc10da17fbe501fc94132f Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Thu, 9 May 2019 14:15:30 -0400 Subject: [PATCH 14/58] EDT-3069 Drop the "DRAFT" text from linked standards, so when we go final and subsequently they do our text is not out of date. Users can see the current status of those other standards on the landing page for them. --- EIPS/eip-1155.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index ca70cc431ea9d..91d496c8d87b2 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -475,7 +475,7 @@ fr.json: ### Approval -The function `setApprovalForAll` allows an operator to manage one's entire set of tokens on behalf of the approver. To permit approval of a subset of token IDs, an interface such as [ERC-1761 Scoped Approval Interface (DRAFT)](https://eips.ethereum.org/EIPS/eip-1761) is suggested. +The function `setApprovalForAll` allows an operator to manage one's entire set of tokens on behalf of the approver. To permit approval of a subset of token IDs, an interface such as [ERC-1761 Scoped Approval Interface](https://eips.ethereum.org/EIPS/eip-1761) is suggested. The counterpart `isAprrovedForAll` provides introspection into status set by `setApprovalForAll`. An owner SHOULD be assumed to always be able to operate on their own tokens regardless of approval status, so should SHOULD NOT have to call `setApprovalForAll` to approve themselves as an operator before they can operate on them. @@ -553,7 +553,7 @@ balanceOf(baseToken + index, msg.sender); // Get balance of the Non-Fungible tok **Standards** - [ERC-721 Non-Fungible Token Standard](https://eips.ethereum.org/EIPS/eip-721) - [ERC-165 Standard Interface Detection](https://eips.ethereum.org/EIPS/eip-165) -- [ERC-1538 Transparent Contract Standard (DRAFT)](https://eips.ethereum.org/EIPS/eip-1538) +- [ERC-1538 Transparent Contract Standard](https://eips.ethereum.org/EIPS/eip-1538) - [JSON Schema](https://json-schema.org/) - [RFC 2119 Key words for use in RFCs to Indicate Requirement Levels](https://www.ietf.org/rfc/rfc2119.txt) From c62f69b2f22a75b385880e4dc267980f5a328cf2 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Thu, 9 May 2019 18:53:16 -0400 Subject: [PATCH 15/58] EDT-3069 Added safe and batch transferFrom rules to also be explicit there. --- EIPS/eip-1155.md | 56 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 39 insertions(+), 17 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 91d496c8d87b2..e0a5c6ec79a2d 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -44,21 +44,25 @@ pragma solidity ^0.5.8; interface ERC1155 /* is ERC165 */ { /** @dev Either TransferSingle or TransferBatch MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "TransferSingle and TransferBatch event rules" section of the standard). - `_operator` MUST be msg.sender. - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address) - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address) - The total value transferred from address 0x0 minus the total value transferred to 0x0 MAY be used by clients and exchanges to be added to the "circulating supply" for a given token ID. - To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the TransferSingle event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0. + The `_operator` argument MUST be msg.sender. + The `_from` argument MUST be the address of the holder whose balance is decreased. + The `_to` argument MUST be the address of the recipient whose balance is increased. + The `_id` argument MUST be the token type being transferred. + The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. + When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). + When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). */ event TransferSingle(address indexed _operator, address indexed _from, address indexed _to, uint256 _id, uint256 _value); /** @dev Either TransferSingle or TransferBatch MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "TransferSingle and TransferBatch event rules" section of the standard). - `_operator` MUST be msg.sender. - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address) - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address) - The total value transferred from address 0x0 minus the total value transferred to 0x0 MAY be used by clients and exchanges to be added to the "circulating supply" for a given token ID. - To broadcast the existence of multiple token IDs with no initial balance, this SHOULD emit the TransferBatch event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0. + The `_operator` argument MUST be msg.sender. + The `_from` argument MUST be the address of the holder whose balance is decreased. + The `_to` argument MUST be the address of the recipient whose balance is increased. + The `_ids` argument MUST be the list of tokens being transferred. + The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified in _ids) the holder balance is decreased by and match what the recipient balance is increased by. + When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). + When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). */ event TransferBatch(address indexed _operator, address indexed _from, address indexed _to, uint256[] _ids, uint256[] _values); @@ -76,10 +80,10 @@ interface ERC1155 /* is ERC165 */ { /** @notice Transfers value amount of an _id from the _from address to the _to address specified. - @dev MUST emit TransferSingle event on success. - Caller must be approved to manage the _from account's tokens (see "Approval" section of the standard). + @dev MUST emit one of TransferSingle or TransferBatch event on success (see "Safe Transfer Rules" section of the standard). + Caller must be approved to manage the `_from` account's tokens (see "Approval" section of the standard). MUST revert if `_to` is the zero address. - MUST revert if balance of sender for token `_id` is lower than the `_value` sent. + MUST revert if balance of holder for token `_id` is lower than the `_value` sent. MUST revert on any other error. After the transfer succeeds, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). @param _from Source address @@ -92,14 +96,14 @@ interface ERC1155 /* is ERC165 */ { /** @notice Send multiple types of Tokens from a 3rd party in one transfer (with safety call). - @dev MUST emit TransferBatch event on success. - Caller must be approved to manage the _from account's tokens (see "Approval" section of the standard). + @dev MUST emit one or more TransferSingle or TransferBatch event on success (see "Safe Transfer Rules" section of the standard). + Caller must be approved to manage the `_from` account's tokens (see "Approval" section of the standard). MUST revert if `_to` is the zero address. MUST revert if length of `_ids` is not the same as length of `_values`. - MUST revert if any of the balance of sender for token `_ids` is lower than the respective `_values` sent. + MUST revert if any of the balance(s) of the holder(s) for token(s) in `_ids` is lower than the respective amount(s) in `_values` sent to the recipient. MUST revert on any other error. Transfers and events MUST occur in the array order they were submitted (_ids[0] before _ids[1], etc). - After all the transfer(s) in the batch succeed, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155BatchReceived` on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). + After all the transfer(s) in the batch succeed, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call the relevant ERC1155TokenReceiver hook(s) on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). @param _from Source addresses @param _to Target addresses @param _ids IDs of each token type (order and length must match _values array) @@ -221,6 +225,24 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op #### Rules +**_safeTransferFrom rules:_** +* MUST emit one of TransferSingle or TransferBatch event on success (see "TransferSingle and TransferBatch event rules" section). +* Caller must be approved to manage the `_from` account's tokens (see "Approval" section). +* MUST revert if `_to` is the zero address. +* MUST revert if balance of holder for token `_id` is lower than the `_value` sent to the recipient. +* MUST revert on any other error. +* After the transfer succeeds, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "onERC1155Received rules" section). + +**_safeBatchTransferFrom rules:_** +* MUST emit one or more TransferSingle or TransferBatch event on success (see "TransferSingle and TransferBatch event rules" section). +* Caller must be approved to manage the `_from` account's tokens (see "Approval" section). +* MUST revert if `_to` is the zero address. +* MUST revert if length of `_ids` is not the same as length of `_values`. +* MUST revert if any of the balance(s) of the holder(s) for token(s) in `_ids` is lower than the respective amount(s) in `_values` sent to the recipient. +* MUST revert on any other error. +* Transfers and events MUST occur in the array order they were submitted (_ids[0] before _ids[1], etc). +* After all the transfer(s) in the batch succeed, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call the relevant ERC1155TokenReceiver hook(s) on `_to` and act appropriately (see "onERC1155Received rules" and "onERC1155BatchReceived rules" sections). + **_TransferSingle and TransferBatch event rules:_** * TransferSingle SHOULD be used to indicate a single balance transfer has occurred between a `_from` and `_to` pair. - It MAY be emitted multiple times to indicate multiple balance changes in the transaction, but note that TransferBatch is designed for this to reduce gas consumption. From dd6b5d7dc8b2e51cd39e375ef534d5df688ba334 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Thu, 9 May 2019 18:58:58 -0400 Subject: [PATCH 16/58] EDT-3069 Another small change to match the rules. --- EIPS/eip-1155.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index e0a5c6ec79a2d..c4adf3185a489 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -108,7 +108,7 @@ interface ERC1155 /* is ERC165 */ { @param _to Target addresses @param _ids IDs of each token type (order and length must match _values array) @param _values Transfer amounts per token type (order and length must match _ids array) - @param _data Additional data with no specified format, sent in call to `onERC1155BatchReceived` on `_to` + @param _data Additional data with no specified format, sent in call to the ERC1155TokenReceiver hook(s) on `_to` */ function safeBatchTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external; From 4f36207136de846cd3e0794047c742325a8b0314 Mon Sep 17 00:00:00 2001 From: James Therien Date: Fri, 10 May 2019 10:46:10 -0400 Subject: [PATCH 17/58] Changes to wording to clarify transfer rules. --- EIPS/eip-1155.md | 76 +++++++++++++++++++++++++----------------------- 1 file changed, 39 insertions(+), 37 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index c4adf3185a489..b8bd0bb5c5d6e 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -1,7 +1,7 @@ --- eip: 1155 title: ERC-1155 Multi Token Standard -author: Witek Radomski , Andrew Cooke , Philippe Castonguay , James Therien , Eric Binet +author: Witek Radomski , Andrew Cooke , Philippe Castonguay , James Therien , Eric Binet type: Standards Track category: ERC status: Draft @@ -49,11 +49,11 @@ interface ERC1155 /* is ERC165 */ { The `_to` argument MUST be the address of the recipient whose balance is increased. The `_id` argument MUST be the token type being transferred. The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). + When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). */ event TransferSingle(address indexed _operator, address indexed _from, address indexed _to, uint256 _id, uint256 _value); - + /** @dev Either TransferSingle or TransferBatch MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "TransferSingle and TransferBatch event rules" section of the standard). The `_operator` argument MUST be msg.sender. @@ -81,11 +81,12 @@ interface ERC1155 /* is ERC165 */ { /** @notice Transfers value amount of an _id from the _from address to the _to address specified. @dev MUST emit one of TransferSingle or TransferBatch event on success (see "Safe Transfer Rules" section of the standard). - Caller must be approved to manage the `_from` account's tokens (see "Approval" section of the standard). + Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section of the standard). MUST revert if `_to` is the zero address. MUST revert if balance of holder for token `_id` is lower than the `_value` sent. MUST revert on any other error. - After the transfer succeeds, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). + After the above conditions are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). + MUST emit TransferSingle event on transfer success. @param _from Source address @param _to Target address @param _id ID of the token type @@ -97,13 +98,14 @@ interface ERC1155 /* is ERC165 */ { /** @notice Send multiple types of Tokens from a 3rd party in one transfer (with safety call). @dev MUST emit one or more TransferSingle or TransferBatch event on success (see "Safe Transfer Rules" section of the standard). - Caller must be approved to manage the `_from` account's tokens (see "Approval" section of the standard). + Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section of the standard). MUST revert if `_to` is the zero address. MUST revert if length of `_ids` is not the same as length of `_values`. MUST revert if any of the balance(s) of the holder(s) for token(s) in `_ids` is lower than the respective amount(s) in `_values` sent to the recipient. MUST revert on any other error. - Transfers and events MUST occur in the array order they were submitted (_ids[0] before _ids[1], etc). - After all the transfer(s) in the batch succeed, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call the relevant ERC1155TokenReceiver hook(s) on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). + Transfers and events MUST follow the ordering of the arrays (_ids[0]/_values[0] before _ids[1]/_values[1], etc). + After the above conditions for the transfer(s) in the batch are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call the relevant ERC1155TokenReceiver hook(s) on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). + MUST emit TransferSingle or TransferBatch event on transfer success (see "Safe Transfer Rules" section of the standard). @param _from Source addresses @param _to Target addresses @param _ids IDs of each token type (order and length must match _values array) @@ -119,7 +121,7 @@ interface ERC1155 /* is ERC165 */ { @return The _owner's balance of the Token type requested */ function balanceOf(address _owner, uint256 _id) external view returns (uint256); - + /** @notice Get the balance of multiple account/token pairs @param _owners The addresses of the token holders @@ -136,7 +138,7 @@ interface ERC1155 /* is ERC165 */ { */ function setApprovalForAll(address _operator, bool _approved) external; - /** + /** @notice Queries the approval status of an operator for a given owner. @param _owner The owner of the Tokens @param _operator Address of authorized operator @@ -158,7 +160,7 @@ interface ERC1155TokenReceiver { @notice Handle the receipt of a single ERC1155 token type. @dev An ERC1155-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeTransferFrom` after the balance has been updated. This function MUST return whether it accepts or rejects the transfer via the prescribed keccak256 generated values. - Return of any other value than the prescribed keccak256 generated values MUST result in the transaction being reverted. + Return of any other value than the prescribed keccak256 generated values MUST result in the transaction being reverted by the caller. @param _operator The address which initiated the transfer (i.e. msg.sender) @param _from The address which previously owned the token @param _id The id of the token being transferred @@ -167,12 +169,12 @@ interface ERC1155TokenReceiver { @return `bytes4(keccak256("accept_erc1155_tokens()"))`==0x4dc21a2f or `bytes4(keccak256("reject_erc1155_tokens()"))`==0xafed434d */ function onERC1155Received(address _operator, address _from, uint256 _id, uint256 _value, bytes calldata _data) external returns(bytes4); - + /** @notice Handle the receipt of multiple ERC1155 token types. @dev An ERC1155-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeBatchTransferFrom` after the balances have been updated. This function MUST return whether it accepts or rejects the transfer via the prescribed keccak256 generated values. - Return of any other value than the prescribed keccak256 generated values MUST result in the transaction being reverted. + Return of any other value than the prescribed keccak256 generated values MUST result in the transaction being reverted by the caller. @param _operator The address which initiated the batch transfer (i.e. msg.sender) @param _from The address which previously owned the token @param _ids An array containing ids of each token being transferred (order and length must match _values array) @@ -222,26 +224,26 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - See "onERC1155BatchReceived rules" for further rules that MUST be followed. * The onERC1155Received hook MAY be called on the recipient contract and its rules followed. - See "onERC1155Received rules" for further rules that MUST be followed. - + #### Rules **_safeTransferFrom rules:_** -* MUST emit one of TransferSingle or TransferBatch event on success (see "TransferSingle and TransferBatch event rules" section). -* Caller must be approved to manage the `_from` account's tokens (see "Approval" section). +* Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section). * MUST revert if `_to` is the zero address. * MUST revert if balance of holder for token `_id` is lower than the `_value` sent to the recipient. * MUST revert on any other error. -* After the transfer succeeds, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "onERC1155Received rules" section). +* After the above conditions are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "onERC1155Received rules" section). +* MUST emit one of TransferSingle or TransferBatch event on success (see "TransferSingle and TransferBatch event rules" section). **_safeBatchTransferFrom rules:_** -* MUST emit one or more TransferSingle or TransferBatch event on success (see "TransferSingle and TransferBatch event rules" section). -* Caller must be approved to manage the `_from` account's tokens (see "Approval" section). +* Caller must be approved to manage all the tokens being transferred out of the `_from` account (see "Approval" section). * MUST revert if `_to` is the zero address. * MUST revert if length of `_ids` is not the same as length of `_values`. * MUST revert if any of the balance(s) of the holder(s) for token(s) in `_ids` is lower than the respective amount(s) in `_values` sent to the recipient. * MUST revert on any other error. -* Transfers and events MUST occur in the array order they were submitted (_ids[0] before _ids[1], etc). -* After all the transfer(s) in the batch succeed, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call the relevant ERC1155TokenReceiver hook(s) on `_to` and act appropriately (see "onERC1155Received rules" and "onERC1155BatchReceived rules" sections). +* After the above conditions are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` or `onERC1155BatchReceived` as on `_to` and act appropriately (see "onERC1155Received and onERC1155BatchReceived rules" section). +* MUST emit one or more TransferSingle or TransferBatch event on success (see "TransferSingle and TransferBatch event rules" section). +* Transfers and events MUST occur in the array order they were submitted (_ids[0]/_values[0] before _ids[1]/_values[1], etc). **_TransferSingle and TransferBatch event rules:_** * TransferSingle SHOULD be used to indicate a single balance transfer has occurred between a `_from` and `_to` pair. @@ -251,15 +253,16 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - The `_to` argument MUST be the address of the recipient whose balance is increased. - The `_id` argument MUST be the token type being transferred. - The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. - - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). + - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). * TransferBatch SHOULD be used to indicate multiple balance transfers have occurred between a `_from` and `_to` pair. - It MAY be emitted with a single element in the list to indicate a singular balance change in the transaction, but note that TransferSingle is designed for this to reduce gas consumption. - The `_operator` argument MUST be msg.sender. - - The `_from` argument MUST be the address of the holder whose balance is decreased. - - The `_to` argument MUST be the address of the recipient whose balance is increased. - - The `_ids` argument MUST be the list of tokens being transferred. - - The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified in _ids) the holder balance is decreased by and match what the recipient balance is increased by. + - The `_from` argument MUST be the address of the holder whose balance is decreased for each entry pair in `_ids` and `_values`. + - The `_to` argument MUST be the address of the recipient whose balance is increased for each entry pair in `_ids` and `_values`. + - The `_ids` array argument MUST contain the ids of the tokens being transferred. + - The `_values` array argument MUST contain the number of token to be transferred for each corresponding entry in `_ids`. + - `_ids` and `_values` MUST have the same length. - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). * The total value transferred from address 0x0 minus the total value transferred to 0x0 MAY be used by clients and exchanges to be added to the "circulating supply" for a given token ID. @@ -271,9 +274,9 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - `_from` MUST be 0x0 for a mint. * The `_id` argument MUST be the token type being transferred. * The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. -* The `_data` argument MUST contain the extra information provided by the sender (if any) for a transfer. +* The `_data` argument MAY contain the extra information provided by the sender for a transfer. * The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_erc1155_tokens()"))` - - If the return value is `bytes4(keccak256("accept_erc1155_tokens()"))` the transfer MUST be completed, unless other conditions necessitate a revert. + - If the return value is `bytes4(keccak256("accept_erc1155_tokens()"))` the transfer MUST be completed or MUST revert if any other conditions are not met for success. * The recipient contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. - If the return value is `bytes4(keccak256("reject_erc1155_tokens()"))` the transaction MUST be reverted. * If the return value is anything other than `bytes4(keccak256("accept_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. @@ -286,21 +289,20 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * The `_from` argument MUST be the address of the holder whose balance is decreased. - `_from` MUST be 0x0 for a mint. * The `_ids` argument MUST be the list of tokens being transferred. -* The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified in _ids) the holder balance is decreased by and match what the recipient balance is increased by. -* The `_data` argument MUST contain the extra information provided by the sender (if any) for a transfer. +* The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified in `_ids`) the holder balance is decreased by and match what the recipient balance is increased by. +* The `_data` argument MAY contain the extra information provided by the sender for a transfer. * The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_batch_erc1155_tokens()"))` - - If the return value is `bytes4(keccak256("accept_batch_erc1155_tokens()"))` the transfer MUST be completed, unless other conditions necessitate a revert. + - If the return value is `bytes4(keccak256("accept_batch_erc1155_tokens()"))` the transfer MUST be completed or MUST revert if any other conditions are not met for success. * The recipient contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. - If the return value is `bytes4(keccak256("reject_erc1155_tokens()"))` the transaction MUST be reverted. * If the return value is anything other than `bytes4(keccak256("accept_batch_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. * onERC1155BatchReceived MAY be called multiple times in a single transaction and the following requirements must be met: - All callbacks represent mutually exclusive balance changes. - - The set of all callbacks describes all balance changes that occurred during the transaction. + - The set of all callback to onERC1155BatchReceived describes all balance changes that occurred during the transaction in the order submitted. **_Implementation specific transfer api rules:_** -* If implementation specific api functions are used to transfer 1155 tokens to a contract the appropriate hook(s) MUST still be called with the same rules as if safeTransferFrom/safeBatchTransferFrom was used. -* The appropriate event(s) MUST be correctly emitted as if safeTransferFrom/safeBatchTransferFrom was used. - +* If implementation specific api functions are used to transfer 1155 tokens to a contract, the safeTransferFrom, or safeBatchTransferFrom (as appropriate) rules MUST be followed. + ###### A solidity example of the keccak256 generated constants for the return magic is: - bytes4 constant public ERC1155_REJECTED = 0xafed434d; // keccak256("reject_erc1155_tokens()") - bytes4 constant public ERC1155_ACCEPTED = 0x4dc21a2f; // keccak256("accept_erc1155_tokens()") @@ -308,8 +310,8 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op #### Compatibility with other standards -There have been requirements during the design discussions to have this standard be compatible with older standards when sending to contract addresses, specifically ERC-721 at time of writing. -To cater for this there is some leeway with the rejection logic should a contract not implement the ERC1155TokenReceiver as per "Safe Transfer Rules" section above, specifically "Scenario#3 : The receiver does not implement the necessary ERC1155TokenReceiver interface function(s)". +There have been requirements during the design discussions to have this standard be compatible with existing standards when sending to contract addresses, specifically ERC-721 at time of writing. +To cater for this scenario, there is some leeway with the rejection logic should a contract not implement the ERC1155TokenReceiver as per "Safe Transfer Rules" section above, specifically "Scenario#3 : The receiver does not implement the necessary ERC1155TokenReceiver interface function(s)". In that particular scenario if the 1155 implementation is also a hybrid implementation of another token standard, it MAY now follow the secondary standard's rules when transferring token(s) to a contract address. *__Note that a pure implementation of a single standard is recommended__* rather than a hybrid solution, but an example of a hybrid 1155+721 contract is linked in the references section under implementations. From b6f88290a7aa6e71f8f33712840b7f37b833e2d5 Mon Sep 17 00:00:00 2001 From: James Therien Date: Fri, 10 May 2019 11:08:38 -0400 Subject: [PATCH 18/58] Clarification for the _data parameter --- EIPS/eip-1155.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index b8bd0bb5c5d6e..cf69e175c3e8f 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -91,7 +91,7 @@ interface ERC1155 /* is ERC165 */ { @param _to Target address @param _id ID of the token type @param _value Transfer amount - @param _data Additional data with no specified format, sent in call to `onERC1155Received` on `_to` + @param _data Additional data with no specified format, MUST be sent in call to `onERC1155Received` on `_to` */ function safeTransferFrom(address _from, address _to, uint256 _id, uint256 _value, bytes calldata _data) external; @@ -110,7 +110,7 @@ interface ERC1155 /* is ERC165 */ { @param _to Target addresses @param _ids IDs of each token type (order and length must match _values array) @param _values Transfer amounts per token type (order and length must match _ids array) - @param _data Additional data with no specified format, sent in call to the ERC1155TokenReceiver hook(s) on `_to` + @param _data Additional data with no specified format, MUST be sent in call to the ERC1155TokenReceiver hook(s) on `_to` */ function safeBatchTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external; @@ -274,7 +274,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - `_from` MUST be 0x0 for a mint. * The `_id` argument MUST be the token type being transferred. * The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. -* The `_data` argument MAY contain the extra information provided by the sender for a transfer. +* The `_data` argument MUST contain the extra information provided by the sender for the transfer. * The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_erc1155_tokens()"))` - If the return value is `bytes4(keccak256("accept_erc1155_tokens()"))` the transfer MUST be completed or MUST revert if any other conditions are not met for success. * The recipient contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. @@ -290,7 +290,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - `_from` MUST be 0x0 for a mint. * The `_ids` argument MUST be the list of tokens being transferred. * The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified in `_ids`) the holder balance is decreased by and match what the recipient balance is increased by. -* The `_data` argument MAY contain the extra information provided by the sender for a transfer. +* The `_data` argument MUST contain the information provided by the sender for a transfer. * The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_batch_erc1155_tokens()"))` - If the return value is `bytes4(keccak256("accept_batch_erc1155_tokens()"))` the transfer MUST be completed or MUST revert if any other conditions are not met for success. * The recipient contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. From 67a42bcaa8a2a6637625b90618cfaa16b649d39f Mon Sep 17 00:00:00 2001 From: James Therien Date: Fri, 10 May 2019 11:12:37 -0400 Subject: [PATCH 19/58] Clarify rules of breaking down into multiple onReceived callbacks --- EIPS/eip-1155.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index cf69e175c3e8f..9983801e57b66 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -296,9 +296,9 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * The recipient contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. - If the return value is `bytes4(keccak256("reject_erc1155_tokens()"))` the transaction MUST be reverted. * If the return value is anything other than `bytes4(keccak256("accept_batch_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. -* onERC1155BatchReceived MAY be called multiple times in a single transaction and the following requirements must be met: +* onERC1155BatchReceived or onERC1155Received MAY be called multiple times in a single transaction and the following requirements must be met: - All callbacks represent mutually exclusive balance changes. - - The set of all callback to onERC1155BatchReceived describes all balance changes that occurred during the transaction in the order submitted. + - The set of all calls to onERC1155BatchReceived or onERC1155Received describes all balance changes that occurred during the transaction in the order submitted. **_Implementation specific transfer api rules:_** * If implementation specific api functions are used to transfer 1155 tokens to a contract, the safeTransferFrom, or safeBatchTransferFrom (as appropriate) rules MUST be followed. From 48cce31eb2f4ee5c9feaf34f6a271f98a2550b2f Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Fri, 10 May 2019 19:44:19 -0400 Subject: [PATCH 20/58] EDT-3069 Alter the rejection logic back to normal for regular 115 operation, add in "isERC1155TokenReceiver" function and rules around hybrid standard implementations around it. Also made use of `` on types consistent. --- EIPS/eip-1155.md | 136 +++++++++++++++++++++++++++-------------------- 1 file changed, 78 insertions(+), 58 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 9983801e57b66..aa0e2079cf952 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -19,7 +19,7 @@ A standard interface for contracts that manage multiple token types. A single de This standard outlines a smart contract interface that can represent any number of Fungible and Non-Fungible token types. Existing standards such as ERC-20 require deployment of separate contracts per token type. The ERC-721 standard's Token ID is a single non-fungible index and the group of these non-fungibles is deployed as a single contract with settings for the entire collection. In contrast, the ERC-1155 Multi Token Standard allows for each Token ID to represent a new configurable token type, which may have its own metadata, supply and other attributes. -The `_id` parameter is contained in each function's parameters and indicates a specific token or token type in a transaction. +The `_id` argument contained in each function's argument set indicates a specific token or token type in a transaction. ## Motivation @@ -43,7 +43,7 @@ pragma solidity ^0.5.8; */ interface ERC1155 /* is ERC165 */ { /** - @dev Either TransferSingle or TransferBatch MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "TransferSingle and TransferBatch event rules" section of the standard). + @dev Either `TransferSingle` or `TransferBatch` MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "Safe Transfer Rules" section of the standard). The `_operator` argument MUST be msg.sender. The `_from` argument MUST be the address of the holder whose balance is decreased. The `_to` argument MUST be the address of the recipient whose balance is increased. @@ -55,7 +55,7 @@ interface ERC1155 /* is ERC165 */ { event TransferSingle(address indexed _operator, address indexed _from, address indexed _to, uint256 _id, uint256 _value); /** - @dev Either TransferSingle or TransferBatch MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "TransferSingle and TransferBatch event rules" section of the standard). + @dev Either `TransferSingle` or `TransferBatch` MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "Safe Transfer Rules" section of the standard). The `_operator` argument MUST be msg.sender. The `_from` argument MUST be the address of the holder whose balance is decreased. The `_to` argument MUST be the address of the recipient whose balance is increased. @@ -79,14 +79,13 @@ interface ERC1155 /* is ERC165 */ { event URI(string _value, uint256 indexed _id); /** - @notice Transfers value amount of an _id from the _from address to the _to address specified. - @dev MUST emit one of TransferSingle or TransferBatch event on success (see "Safe Transfer Rules" section of the standard). - Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section of the standard). + @notice Transfers `_value` amount of an `_id` from the `_from` address to the `_to` address specified (with safety call). + @dev Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section of the standard). MUST revert if `_to` is the zero address. MUST revert if balance of holder for token `_id` is lower than the `_value` sent. MUST revert on any other error. After the above conditions are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). - MUST emit TransferSingle event on transfer success. + MUST emit `TransferSingle` event on transfer success (see "Safe Transfer Rules" section of the standard). @param _from Source address @param _to Target address @param _id ID of the token type @@ -96,21 +95,20 @@ interface ERC1155 /* is ERC165 */ { function safeTransferFrom(address _from, address _to, uint256 _id, uint256 _value, bytes calldata _data) external; /** - @notice Send multiple types of Tokens from a 3rd party in one transfer (with safety call). - @dev MUST emit one or more TransferSingle or TransferBatch event on success (see "Safe Transfer Rules" section of the standard). - Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section of the standard). + @notice Transfers `_values` amount(s) of `_ids` from the `_from` address to the `_to` address specified (with safety call). + @dev Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section of the standard). MUST revert if `_to` is the zero address. MUST revert if length of `_ids` is not the same as length of `_values`. MUST revert if any of the balance(s) of the holder(s) for token(s) in `_ids` is lower than the respective amount(s) in `_values` sent to the recipient. MUST revert on any other error. Transfers and events MUST follow the ordering of the arrays (_ids[0]/_values[0] before _ids[1]/_values[1], etc). - After the above conditions for the transfer(s) in the batch are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call the relevant ERC1155TokenReceiver hook(s) on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). - MUST emit TransferSingle or TransferBatch event on transfer success (see "Safe Transfer Rules" section of the standard). + After the above conditions for the transfer(s) in the batch are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call the relevant `ERC1155TokenReceiver` hook(s) on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). + MUST emit `TransferSingle` or `TransferBatch` event(s) on transfer success (see "Safe Transfer Rules" section of the standard). @param _from Source addresses @param _to Target addresses @param _ids IDs of each token type (order and length must match _values array) @param _values Transfer amounts per token type (order and length must match _ids array) - @param _data Additional data with no specified format, MUST be sent in call to the ERC1155TokenReceiver hook(s) on `_to` + @param _data Additional data with no specified format, MUST be sent in call to the `ERC1155TokenReceiver` hook(s) on `_to` */ function safeBatchTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external; @@ -159,70 +157,79 @@ interface ERC1155TokenReceiver { /** @notice Handle the receipt of a single ERC1155 token type. @dev An ERC1155-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeTransferFrom` after the balance has been updated. - This function MUST return whether it accepts or rejects the transfer via the prescribed keccak256 generated values. - Return of any other value than the prescribed keccak256 generated values MUST result in the transaction being reverted by the caller. + This function MUST return `bytes4(keccak256("accept_erc1155_tokens()"))` if it accepts the transfer. + This function MUST revert if it rejects the transfer. + Return of any other value than the prescribed keccak256 generated value MUST result in the transaction being reverted by the caller. @param _operator The address which initiated the transfer (i.e. msg.sender) @param _from The address which previously owned the token @param _id The id of the token being transferred @param _value The amount of tokens being transferred @param _data Additional data with no specified format - @return `bytes4(keccak256("accept_erc1155_tokens()"))`==0x4dc21a2f or `bytes4(keccak256("reject_erc1155_tokens()"))`==0xafed434d + @return `bytes4(keccak256("accept_erc1155_tokens()"))`==0x4dc21a2f */ function onERC1155Received(address _operator, address _from, uint256 _id, uint256 _value, bytes calldata _data) external returns(bytes4); /** @notice Handle the receipt of multiple ERC1155 token types. @dev An ERC1155-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeBatchTransferFrom` after the balances have been updated. - This function MUST return whether it accepts or rejects the transfer via the prescribed keccak256 generated values. - Return of any other value than the prescribed keccak256 generated values MUST result in the transaction being reverted by the caller. + This function MUST return `bytes4(keccak256("accept_batch_erc1155_tokens()"))` if it accepts the transfer(s). + This function MUST revert if it rejects the transfer(s). + Return of any other value than the prescribed keccak256 generated value MUST result in the transaction being reverted by the caller. @param _operator The address which initiated the batch transfer (i.e. msg.sender) @param _from The address which previously owned the token @param _ids An array containing ids of each token being transferred (order and length must match _values array) @param _values An array containing amounts of each token being transferred (order and length must match _ids array) @param _data Additional data with no specified format - @return `bytes4(keccak256("accept_batch_erc1155_tokens()"))`==0xac007889 or `bytes4(keccak256("reject_erc1155_tokens()"))`==0xafed434d + @return `bytes4(keccak256("accept_batch_erc1155_tokens()"))`==0xac007889 */ function onERC1155BatchReceived(address _operator, address _from, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external returns(bytes4); + + /** + @notice Indicates whether a contract implements the `ERC1155TokenReceiver` functions and so can accept ERC1155 token types. + @dev This function MUST return `bytes4(keccak256("isERC1155TokenReceiver()"))`. + @return `bytes4(keccak256("isERC1155TokenReceiver()"))`==0x0d912442 + */ + function isERC1155TokenReceiver() external pure returns (bytes4); } ``` ### Safe Transfer Rules -To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST operate with respect to the ERC1155TokenReceiver, a list of scenarios and rules follows. +To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST operate with respect to the `ERC1155TokenReceiver`, a list of scenarios and rules follows. #### Scenarios **_Scenario#1 :_** The recipient is not a contract. -* onERC1155Received and onERC1155BatchReceived MUST NOT be called on an EOA (Externally Owned Account). +* `onERC1155Received` and `onERC1155BatchReceived` MUST NOT be called on an EOA (Externally Owned Account). **_Scenario#2 :_** The transaction is not a mint/transfer of a token. -* onERC1155Received and onERC1155BatchReceived MUST NOT be called outside of a mint or transfer process. +* `onERC1155Received` and `onERC1155BatchReceived` MUST NOT be called outside of a mint or transfer process. -**_Scenario#3 :_** The receiver does not implement the necessary ERC1155TokenReceiver interface function(s). +**_Scenario#3 :_** The receiver does not implement the necessary `ERC1155TokenReceiver` interface function(s). * The transfer MUST be reverted with the one caveat below. - If the tokens being sent are part of a hybrid implementation of another standard, that particular standard's rules on sending to a contract MAY now be followed instead. See "Compatibility with other standards" section. -**_Scenario#4 :_** The receiver implements the necessary ERC1155TokenReceiver interface function(s) but returns an unknown value. +**_Scenario#4 :_** The receiver implements the necessary `ERC1155TokenReceiver` interface function(s) but returns an unknown value. * The transfer MUST be reverted. -**_Scenario#5 :_** The receiver implements the necessary ERC1155TokenReceiver interface function(s) but throws an error. +**_Scenario#5 :_** The receiver implements the necessary `ERC1155TokenReceiver` interface function(s) but throws an error. * The transfer MUST be reverted. -**_Scenario#6 :_** The receiver implements the ERC1155TokenReceiver interface and is the recipient of one and only one balance change (eg. safeTransferFrom called). +**_Scenario#6 :_** The receiver implements the `ERC1155TokenReceiver` interface and is the recipient of one and only one balance change (eg. safeTransferFrom called). * All the balances in the transfer MUST have been updated to match the senders intent before any hook is called on a recipient. -* One of onERC1155Received or onERC1155BatchReceived MUST be called on the recipient. -* The onERC1155Received hook SHOULD be called on the recipient contract and its rules followed. +* One of `onERC1155Received` or `onERC1155BatchReceived` MUST be called on the recipient. +* The `onERC1155Received` hook SHOULD be called on the recipient contract and its rules followed. - See "onERC1155Received rules" for further rules that MUST be followed. -* The onERC1155BatchReceived hook MAY be called on the recipient contract and its rules followed. +* The `onERC1155BatchReceived` hook MAY be called on the recipient contract and its rules followed. - See "onERC1155BatchReceived rules" for further rules that MUST be followed. -**_Scenario#7 :_** The receiver implements the ERC1155TokenReceiver interface and is the recipient of more than one balance change (eg. safeBatchTransferFrom called). +**_Scenario#7 :_** The receiver implements the `ERC1155TokenReceiver` interface and is the recipient of more than one balance change (eg. safeBatchTransferFrom called). * All the balances in the transfer MUST have been updated to match the senders intent before any hook is called on a recipient. -* onERC1155Received or onERC1155BatchReceived MUST be called on the recipient as many times as necessary such that every balance change for the recipient in the scenario is accounted for. +* `onERC1155Received` or `onERC1155BatchReceived` MUST be called on the recipient as many times as necessary such that every balance change for the recipient in the scenario is accounted for. - The return magic value for every hook call MUST be checked and acted upon as per "onERC1155Received rules" and "onERC1155BatchReceived rules". -* The onERC1155BatchReceived hook SHOULD be called on the recipient contract and its rules followed. +* The `onERC1155BatchReceived` hook SHOULD be called on the recipient contract and its rules followed. - See "onERC1155BatchReceived rules" for further rules that MUST be followed. -* The onERC1155Received hook MAY be called on the recipient contract and its rules followed. +* The `onERC1155Received` hook MAY be called on the recipient contract and its rules followed. - See "onERC1155Received rules" for further rules that MUST be followed. #### Rules @@ -233,7 +240,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * MUST revert if balance of holder for token `_id` is lower than the `_value` sent to the recipient. * MUST revert on any other error. * After the above conditions are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "onERC1155Received rules" section). -* MUST emit one of TransferSingle or TransferBatch event on success (see "TransferSingle and TransferBatch event rules" section). +* MUST emit `TransferSingle` event on transfer success (see "TransferSingle and TransferBatch event rules" section). **_safeBatchTransferFrom rules:_** * Caller must be approved to manage all the tokens being transferred out of the `_from` account (see "Approval" section). @@ -241,13 +248,13 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * MUST revert if length of `_ids` is not the same as length of `_values`. * MUST revert if any of the balance(s) of the holder(s) for token(s) in `_ids` is lower than the respective amount(s) in `_values` sent to the recipient. * MUST revert on any other error. -* After the above conditions are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` or `onERC1155BatchReceived` as on `_to` and act appropriately (see "onERC1155Received and onERC1155BatchReceived rules" section). -* MUST emit one or more TransferSingle or TransferBatch event on success (see "TransferSingle and TransferBatch event rules" section). +* After the above conditions are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` or `onERC1155BatchReceived` as on `_to` and act appropriately (see "`onERC1155Received` and onERC1155BatchReceived rules" section). +* MUST emit `TransferSingle` or `TransferBatch` event(s) on transfer success (see "TransferSingle and TransferBatch event rules" section). * Transfers and events MUST occur in the array order they were submitted (_ids[0]/_values[0] before _ids[1]/_values[1], etc). **_TransferSingle and TransferBatch event rules:_** -* TransferSingle SHOULD be used to indicate a single balance transfer has occurred between a `_from` and `_to` pair. - - It MAY be emitted multiple times to indicate multiple balance changes in the transaction, but note that TransferBatch is designed for this to reduce gas consumption. +* `TransferSingle` SHOULD be used to indicate a single balance transfer has occurred between a `_from` and `_to` pair. + - It MAY be emitted multiple times to indicate multiple balance changes in the transaction, but note that `TransferBatch` is designed for this to reduce gas consumption. - The `_operator` argument MUST be msg.sender. - The `_from` argument MUST be the address of the holder whose balance is decreased. - The `_to` argument MUST be the address of the recipient whose balance is increased. @@ -255,8 +262,8 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). -* TransferBatch SHOULD be used to indicate multiple balance transfers have occurred between a `_from` and `_to` pair. - - It MAY be emitted with a single element in the list to indicate a singular balance change in the transaction, but note that TransferSingle is designed for this to reduce gas consumption. +* `TransferBatch` SHOULD be used to indicate multiple balance transfers have occurred between a `_from` and `_to` pair. + - It MAY be emitted with a single element in the list to indicate a singular balance change in the transaction, but note that `TransferSingle` is designed for this to reduce gas consumption. - The `_operator` argument MUST be msg.sender. - The `_from` argument MUST be the address of the holder whose balance is decreased for each entry pair in `_ids` and `_values`. - The `_to` argument MUST be the address of the recipient whose balance is increased for each entry pair in `_ids` and `_values`. @@ -266,7 +273,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). * The total value transferred from address 0x0 minus the total value transferred to 0x0 MAY be used by clients and exchanges to be added to the "circulating supply" for a given token ID. -* To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the TransferSingle event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0. +* To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the `TransferSingle` event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0. **_onERC1155Received rules:_** * The `_operator` argument MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). @@ -277,12 +284,12 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * The `_data` argument MUST contain the extra information provided by the sender for the transfer. * The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_erc1155_tokens()"))` - If the return value is `bytes4(keccak256("accept_erc1155_tokens()"))` the transfer MUST be completed or MUST revert if any other conditions are not met for success. -* The recipient contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. - - If the return value is `bytes4(keccak256("reject_erc1155_tokens()"))` the transaction MUST be reverted. -* If the return value is anything other than `bytes4(keccak256("accept_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. -* onERC1155Received MAY be called multiple times in a single transaction and the following requirements must be met: +* The recipient contract MAY reject an increase of its balance by calling revert. + - If recipient contract throws/reverts the transaction MUST be reverted. +* If the return value is anything other than `bytes4(keccak256("accept_erc1155_tokens()"))` the transaction MUST be reverted. +* `onERC1155Received` (and/or `onERC1155BatchReceived`) MAY be called multiple times in a single transaction and the following requirements must be met: - All callbacks represent mutually exclusive balance changes. - - The set of all callbacks describes all balance changes that occurred during the transaction. + - The set of all calls to `onERC1155Received` and `onERC1155BatchReceived` describes all balance changes that occurred during the transaction in the order submitted. **_onERC1155BatchReceived rules:_** * The `_operator` argument MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). @@ -293,27 +300,40 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * The `_data` argument MUST contain the information provided by the sender for a transfer. * The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_batch_erc1155_tokens()"))` - If the return value is `bytes4(keccak256("accept_batch_erc1155_tokens()"))` the transfer MUST be completed or MUST revert if any other conditions are not met for success. -* The recipient contract MAY reject an increase of its balance by returning the rejection magic value `bytes4(keccack256("reject_erc1155_tokens()"))`. - - If the return value is `bytes4(keccak256("reject_erc1155_tokens()"))` the transaction MUST be reverted. -* If the return value is anything other than `bytes4(keccak256("accept_batch_erc1155_tokens()"))` or `bytes4(keccack256("reject_erc1155_tokens()"))` the transaction MUST be reverted. -* onERC1155BatchReceived or onERC1155Received MAY be called multiple times in a single transaction and the following requirements must be met: +* The recipient contract MAY reject an increase of its balance by calling revert. + - If recipient contract throws/reverts the transaction MUST be reverted. +* If the return value is anything other than `bytes4(keccak256("accept_batch_erc1155_tokens()"))` the transaction MUST be reverted. +* `onERC1155BatchReceived` (and/or `onERC1155Received`) MAY be called multiple times in a single transaction and the following requirements must be met: - All callbacks represent mutually exclusive balance changes. - - The set of all calls to onERC1155BatchReceived or onERC1155Received describes all balance changes that occurred during the transaction in the order submitted. + - The set of all calls to `onERC1155Received` and `onERC1155BatchReceived` describes all balance changes that occurred during the transaction in the order submitted. + +**_isERC1155TokenReceiver rules:_** +* The implementation of `isERC1155TokenReceiver` function SHOULD be as follows: + ``` + function isERC1155TokenReceiver() external pure returns (bytes4) { + return 0x0d912442; // bytes4(keccak256("isERC1155TokenReceiver()")) + } + ``` +* The implementation MAY differ from the above but it MUST return the same value. **_Implementation specific transfer api rules:_** * If implementation specific api functions are used to transfer 1155 tokens to a contract, the safeTransferFrom, or safeBatchTransferFrom (as appropriate) rules MUST be followed. ###### A solidity example of the keccak256 generated constants for the return magic is: - - bytes4 constant public ERC1155_REJECTED = 0xafed434d; // keccak256("reject_erc1155_tokens()") - - bytes4 constant public ERC1155_ACCEPTED = 0x4dc21a2f; // keccak256("accept_erc1155_tokens()") - - bytes4 constant public ERC1155_BATCH_ACCEPTED = 0xac007889; // keccak256("accept_batch_erc1155_tokens()") + - bytes4 constant public ERC1155_ACCEPTED = 0x4dc21a2f; // bytes4(keccak256("accept_erc1155_tokens()")) + - bytes4 constant public ERC1155_BATCH_ACCEPTED = 0xac007889; // bytes4(keccak256("accept_batch_erc1155_tokens()")) #### Compatibility with other standards There have been requirements during the design discussions to have this standard be compatible with existing standards when sending to contract addresses, specifically ERC-721 at time of writing. -To cater for this scenario, there is some leeway with the rejection logic should a contract not implement the ERC1155TokenReceiver as per "Safe Transfer Rules" section above, specifically "Scenario#3 : The receiver does not implement the necessary ERC1155TokenReceiver interface function(s)". -In that particular scenario if the 1155 implementation is also a hybrid implementation of another token standard, it MAY now follow the secondary standard's rules when transferring token(s) to a contract address. - +To cater for this scenario, there is some leeway with the rejection logic should a contract not implement the `ERC1155TokenReceiver` as per "Safe Transfer Rules" section above, specifically "Scenario#3 : The receiver does not implement the necessary `ERC1155TokenReceiver` interface function(s)". + +Hence in a hybrid 1155 contract implementation an extra call MUST be made on the recipient contract and checked before any hook calls to `onERC1155Received` or `onERC1155BatchReceived` are made. +Order of operation MUST therefore be: +1. The implementation MUST call the function `isERC1155TokenReceiver` on the recipient. +2. If the function call succeeds and the return value is `bytes4(keccak256("isERC1155TokenReceiver()"))` the implementation proceeds as a regular 1155 implementation, with the call(s) to the `onERC1155Received` or `onERC1155BatchReceived` hooks and rules associated. +3. If the function call fails or the return value is NOT `bytes4(keccak256("isERC1155TokenReceiver()"))` the implementation can assume the contract recipient is not an `ERC1155TokenReceiver` and follow its other standard's rules for transfers. + *__Note that a pure implementation of a single standard is recommended__* rather than a hybrid solution, but an example of a hybrid 1155+721 contract is linked in the references section under implementations. An important consideration is that even if the tokens are sent with another standard's rules the *__1155 transfer events MUST still be emitted.__* This is so the balances can still be determined via events alone as per 1155 standard rules. @@ -552,7 +572,7 @@ The `balanceOfBatch` function allows clients to retrieve balances of multiple ow In order to keep storage requirements light for contracts implementing ERC-1155, enumeration (discovering the IDs and values of tokens) must be done using event logs. It is RECOMMENDED that clients such as exchanges and blockchain explorers maintain a local database containing the Token ID, Supply, and URI at the minimum. This can be built from each TransferSingle, TransferBatch, and URI event, starting from the block the smart contract was deployed until the latest block. -ERC-1155 contracts must therefore carefully emit TransferSingle or TransferBatch events in any instance where tokens are created, minted, or destroyed. +ERC-1155 contracts must therefore carefully emit `TransferSingle` or `TransferBatch` events in any instance where tokens are created, minted, or destroyed. ### Non-Fungible Tokens From cd864853c49055294816584b8cbe0412417b5760 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Fri, 10 May 2019 23:32:37 -0400 Subject: [PATCH 21/58] EDT-3069 Small inconsistency and remove the == part from return text in case anyone is silly enough to copy-paste that and end up always returning true. --- EIPS/eip-1155.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index aa0e2079cf952..ecf6b14f687de 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -104,8 +104,8 @@ interface ERC1155 /* is ERC165 */ { Transfers and events MUST follow the ordering of the arrays (_ids[0]/_values[0] before _ids[1]/_values[1], etc). After the above conditions for the transfer(s) in the batch are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call the relevant `ERC1155TokenReceiver` hook(s) on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). MUST emit `TransferSingle` or `TransferBatch` event(s) on transfer success (see "Safe Transfer Rules" section of the standard). - @param _from Source addresses - @param _to Target addresses + @param _from Source address + @param _to Target address @param _ids IDs of each token type (order and length must match _values array) @param _values Transfer amounts per token type (order and length must match _ids array) @param _data Additional data with no specified format, MUST be sent in call to the `ERC1155TokenReceiver` hook(s) on `_to` @@ -157,7 +157,7 @@ interface ERC1155TokenReceiver { /** @notice Handle the receipt of a single ERC1155 token type. @dev An ERC1155-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeTransferFrom` after the balance has been updated. - This function MUST return `bytes4(keccak256("accept_erc1155_tokens()"))` if it accepts the transfer. + This function MUST return `bytes4(keccak256("accept_erc1155_tokens()"))` (i.e. 0x4dc21a2f) if it accepts the transfer. This function MUST revert if it rejects the transfer. Return of any other value than the prescribed keccak256 generated value MUST result in the transaction being reverted by the caller. @param _operator The address which initiated the transfer (i.e. msg.sender) @@ -165,14 +165,14 @@ interface ERC1155TokenReceiver { @param _id The id of the token being transferred @param _value The amount of tokens being transferred @param _data Additional data with no specified format - @return `bytes4(keccak256("accept_erc1155_tokens()"))`==0x4dc21a2f + @return `bytes4(keccak256("accept_erc1155_tokens()"))` */ function onERC1155Received(address _operator, address _from, uint256 _id, uint256 _value, bytes calldata _data) external returns(bytes4); /** @notice Handle the receipt of multiple ERC1155 token types. @dev An ERC1155-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeBatchTransferFrom` after the balances have been updated. - This function MUST return `bytes4(keccak256("accept_batch_erc1155_tokens()"))` if it accepts the transfer(s). + This function MUST return `bytes4(keccak256("accept_batch_erc1155_tokens()"))` (i.e. 0xac007889) if it accepts the transfer(s). This function MUST revert if it rejects the transfer(s). Return of any other value than the prescribed keccak256 generated value MUST result in the transaction being reverted by the caller. @param _operator The address which initiated the batch transfer (i.e. msg.sender) @@ -180,14 +180,14 @@ interface ERC1155TokenReceiver { @param _ids An array containing ids of each token being transferred (order and length must match _values array) @param _values An array containing amounts of each token being transferred (order and length must match _ids array) @param _data Additional data with no specified format - @return `bytes4(keccak256("accept_batch_erc1155_tokens()"))`==0xac007889 + @return `bytes4(keccak256("accept_batch_erc1155_tokens()"))` */ function onERC1155BatchReceived(address _operator, address _from, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external returns(bytes4); /** @notice Indicates whether a contract implements the `ERC1155TokenReceiver` functions and so can accept ERC1155 token types. - @dev This function MUST return `bytes4(keccak256("isERC1155TokenReceiver()"))`. - @return `bytes4(keccak256("isERC1155TokenReceiver()"))`==0x0d912442 + @dev This function MUST return `bytes4(keccak256("isERC1155TokenReceiver()"))` (i.e. 0x0d912442). + @return `bytes4(keccak256("isERC1155TokenReceiver()"))` */ function isERC1155TokenReceiver() external pure returns (bytes4); } From d7b07bdc65cc3ed424dd290ad11cea5a56fe5320 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Sat, 11 May 2019 00:02:49 -0400 Subject: [PATCH 22/58] EDT-3069 Add in ERC-165 interface identifier info for the ERC1155TokenReceiver interface. --- EIPS/eip-1155.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index ecf6b14f687de..6e93a48dc2056 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -153,6 +153,9 @@ Smart contracts **MUST** implement this interface to accept transfers. See "Safe ```solidity pragma solidity ^0.5.8; +/** + Note: The ERC-165 identifier for this interface is 0x43b236a2. +*/ interface ERC1155TokenReceiver { /** @notice Handle the receipt of a single ERC1155 token type. From 97fa9de5cb9283bb42249db9cb2c911d228b9c08 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Mon, 13 May 2019 15:53:40 -0400 Subject: [PATCH 23/58] EDT-3069 Very minor change to text, remove odd grammar. --- EIPS/eip-1155.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 6e93a48dc2056..144bf4082a0fb 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -251,7 +251,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * MUST revert if length of `_ids` is not the same as length of `_values`. * MUST revert if any of the balance(s) of the holder(s) for token(s) in `_ids` is lower than the respective amount(s) in `_values` sent to the recipient. * MUST revert on any other error. -* After the above conditions are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` or `onERC1155BatchReceived` as on `_to` and act appropriately (see "`onERC1155Received` and onERC1155BatchReceived rules" section). +* After the above conditions are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` or `onERC1155BatchReceived` on `_to` and act appropriately (see "`onERC1155Received` and onERC1155BatchReceived rules" section). * MUST emit `TransferSingle` or `TransferBatch` event(s) on transfer success (see "TransferSingle and TransferBatch event rules" section). * Transfers and events MUST occur in the array order they were submitted (_ids[0]/_values[0] before _ids[1]/_values[1], etc). From 15a67ab1b1f46ede08c2467b87469d6930341f2f Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Mon, 13 May 2019 16:01:26 -0400 Subject: [PATCH 24/58] EDT-3069 Consistency change on the isERC1155TokenReceiver gas requirement. --- EIPS/eip-1155.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index e9c903926d7d1..322738e3741b1 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -189,7 +189,8 @@ interface ERC1155TokenReceiver { /** @notice Indicates whether a contract implements the `ERC1155TokenReceiver` functions and so can accept ERC1155 token types. - @dev This function MUST return `bytes4(keccak256("isERC1155TokenReceiver()"))` (i.e. 0x0d912442). and MUST not consume more than 5,000 gas. + @dev This function MUST return `bytes4(keccak256("isERC1155TokenReceiver()"))` (i.e. 0x0d912442). + This function MUST NOT consume more than 5,000 gas. @return `bytes4(keccak256("isERC1155TokenReceiver()"))` */ function isERC1155TokenReceiver() external pure returns (bytes4); @@ -317,9 +318,9 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op return 0x0d912442; // bytes4(keccak256("isERC1155TokenReceiver()")) } ``` -* The implementation MAY differ from the above but : - - it MUST return the same value. - - it MUST not spend more than 5,000 gas +* The implementation MAY differ from the above but: + - It MUST return the same value. + - It MUST NOT consume more than 5,000 gas. **_Implementation specific transfer api rules:_** * If implementation specific api functions are used to transfer 1155 tokens to a contract, the safeTransferFrom, or safeBatchTransferFrom (as appropriate) rules MUST be followed. From 65052c6227720ae06a9d7e5c4d6f095d508627b1 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Sat, 18 May 2019 01:23:24 -0400 Subject: [PATCH 25/58] EDT-3069 Added wighawag as an author, alter isERC1155Receiver interface to view instead of pure (to cover fallback versions) but leave recommended impl as pure, be clearer about having to pass the _data arg to the hooks unaltered, make it so all events have to be emitted before any hooks are called so order is preserved. --- EIPS/eip-1155.md | 44 ++++++++++++++++++++++++++++---------------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 322738e3741b1..25ba544083aff 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -1,7 +1,7 @@ --- eip: 1155 title: ERC-1155 Multi Token Standard -author: Witek Radomski , Andrew Cooke , Philippe Castonguay , James Therien , Eric Binet +author: Witek Radomski , Andrew Cooke , Philippe Castonguay , James Therien , Eric Binet , Ronan Sandford type: Standards Track category: ERC status: Draft @@ -84,13 +84,13 @@ interface ERC1155 /* is ERC165 */ { MUST revert if `_to` is the zero address. MUST revert if balance of holder for token `_id` is lower than the `_value` sent. MUST revert on any other error. - After the above conditions are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). - MUST emit `TransferSingle` event on transfer success (see "Safe Transfer Rules" section of the standard). + MUST emit the `TransferSingle` event to reflect the balance change (see "Safe Transfer Rules" section of the standard). + After the above conditions are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). @param _from Source address @param _to Target address @param _id ID of the token type @param _value Transfer amount - @param _data Additional data with no specified format, MUST be sent in call to `onERC1155Received` on `_to` + @param _data Additional data with no specified format, MUST be sent unaltered in call to `onERC1155Received` on `_to` */ function safeTransferFrom(address _from, address _to, uint256 _id, uint256 _value, bytes calldata _data) external; @@ -100,15 +100,15 @@ interface ERC1155 /* is ERC165 */ { MUST revert if `_to` is the zero address. MUST revert if length of `_ids` is not the same as length of `_values`. MUST revert if any of the balance(s) of the holder(s) for token(s) in `_ids` is lower than the respective amount(s) in `_values` sent to the recipient. - MUST revert on any other error. - Transfers and events MUST follow the ordering of the arrays (_ids[0]/_values[0] before _ids[1]/_values[1], etc). - After the above conditions for the transfer(s) in the batch are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call the relevant `ERC1155TokenReceiver` hook(s) on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). - MUST emit `TransferSingle` or `TransferBatch` event(s) on transfer success (see "Safe Transfer Rules" section of the standard). + MUST revert on any other error. + MUST emit `TransferSingle` or `TransferBatch` event(s) such that all the balance changes are reflected (see "Safe Transfer Rules" section of the standard). + Balance changes and events MUST follow the ordering of the arrays (_ids[0]/_values[0] before _ids[1]/_values[1], etc). + After the above conditions for the transfer(s) in the batch are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call the relevant `ERC1155TokenReceiver` hook(s) on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). @param _from Source address @param _to Target address @param _ids IDs of each token type (order and length must match _values array) @param _values Transfer amounts per token type (order and length must match _ids array) - @param _data Additional data with no specified format, MUST be sent in call to the `ERC1155TokenReceiver` hook(s) on `_to` + @param _data Additional data with no specified format, MUST be sent unaltered in call to the `ERC1155TokenReceiver` hook(s) on `_to` */ function safeBatchTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external; @@ -193,13 +193,13 @@ interface ERC1155TokenReceiver { This function MUST NOT consume more than 5,000 gas. @return `bytes4(keccak256("isERC1155TokenReceiver()"))` */ - function isERC1155TokenReceiver() external pure returns (bytes4); + function isERC1155TokenReceiver() external view returns (bytes4); } ``` ### Safe Transfer Rules -To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST operate with respect to the `ERC1155TokenReceiver`, a list of scenarios and rules follows. +To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST operate with respect to the `ERC1155TokenReceiver` hook functions, a list of scenarios and rules follows. #### Scenarios @@ -221,6 +221,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op **_Scenario#6 :_** The receiver implements the `ERC1155TokenReceiver` interface and is the recipient of one and only one balance change (eg. safeTransferFrom called). * All the balances in the transfer MUST have been updated to match the senders intent before any hook is called on a recipient. +* All the transfer events for the transfer MUST have been emitted to reflect the balance changes before any hook is called on a recipient. * One of `onERC1155Received` or `onERC1155BatchReceived` MUST be called on the recipient. * The `onERC1155Received` hook SHOULD be called on the recipient contract and its rules followed. - See "onERC1155Received rules" for further rules that MUST be followed. @@ -229,12 +230,19 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op **_Scenario#7 :_** The receiver implements the `ERC1155TokenReceiver` interface and is the recipient of more than one balance change (eg. safeBatchTransferFrom called). * All the balances in the transfer MUST have been updated to match the senders intent before any hook is called on a recipient. +* All the transfer events for the transfer MUST have been emitted to reflect the balance changes before any hook is called on a recipient. * `onERC1155Received` or `onERC1155BatchReceived` MUST be called on the recipient as many times as necessary such that every balance change for the recipient in the scenario is accounted for. - The return magic value for every hook call MUST be checked and acted upon as per "onERC1155Received rules" and "onERC1155BatchReceived rules". * The `onERC1155BatchReceived` hook SHOULD be called on the recipient contract and its rules followed. - See "onERC1155BatchReceived rules" for further rules that MUST be followed. * The `onERC1155Received` hook MAY be called on the recipient contract and its rules followed. - See "onERC1155Received rules" for further rules that MUST be followed. + +**_Scenario#8 :_** You are the creator of a contract that implements the `ERC1155TokenReceiver` interface and you forward the token(s) onto another address in one or both of `onERC1155Received` and `onERC1155BatchReceived`. +* Forwarding should be considered acceptance and then initiating a new `safeTransferFrom` or `safeBatchTransferFrom` in a new context. + - The prescribed keccak256 acceptance value magic for the receiver hook being called MUST be returned after forwarding is successful. +* The `_data` argument MAY be re-purposed for the new context. +* If forwarding unexpectedly fails the transaction MUST be reverted. #### Rules @@ -243,8 +251,8 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * MUST revert if `_to` is the zero address. * MUST revert if balance of holder for token `_id` is lower than the `_value` sent to the recipient. * MUST revert on any other error. +* MUST emit the `TransferSingle` event to reflect the balance change (see "TransferSingle and TransferBatch event rules" section). * After the above conditions are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "onERC1155Received rules" section). -* MUST emit `TransferSingle` event on transfer success (see "TransferSingle and TransferBatch event rules" section). **_safeBatchTransferFrom rules:_** * Caller must be approved to manage all the tokens being transferred out of the `_from` account (see "Approval" section). @@ -252,9 +260,9 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * MUST revert if length of `_ids` is not the same as length of `_values`. * MUST revert if any of the balance(s) of the holder(s) for token(s) in `_ids` is lower than the respective amount(s) in `_values` sent to the recipient. * MUST revert on any other error. +* MUST emit `TransferSingle` or `TransferBatch` event(s) such that all the balance changes are reflected (see "TransferSingle and TransferBatch event rules" section). +* The balance changes and events MUST occur in the array order they were submitted (_ids[0]/_values[0] before _ids[1]/_values[1], etc). * After the above conditions are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` or `onERC1155BatchReceived` on `_to` and act appropriately (see "`onERC1155Received` and onERC1155BatchReceived rules" section). -* MUST emit `TransferSingle` or `TransferBatch` event(s) on transfer success (see "TransferSingle and TransferBatch event rules" section). -* Transfers and events MUST occur in the array order they were submitted (_ids[0]/_values[0] before _ids[1]/_values[1], etc). **_TransferSingle and TransferBatch event rules:_** * `TransferSingle` SHOULD be used to indicate a single balance transfer has occurred between a `_from` and `_to` pair. @@ -278,6 +286,8 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). * The total value transferred from address 0x0 minus the total value transferred to 0x0 MAY be used by clients and exchanges to be added to the "circulating supply" for a given token ID. * To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the `TransferSingle` event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0. +* All `TransferSingle` and `TransferBatch` events MUST be emitted to reflect all the balance changes that have occurred before any call(s) to `onERC1155Received` or `onERC1155BatchReceived`. + - To make sure event order is correct in the case of valid re-entry (for eg. when a receiver contract forwards tokens on receipt) state balance and events balance MUST match before calling an external contract. **_onERC1155Received rules:_** * The `_operator` argument MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). @@ -285,7 +295,8 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - `_from` MUST be 0x0 for a mint. * The `_id` argument MUST be the token type being transferred. * The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. -* The `_data` argument MUST contain the extra information provided by the sender for the transfer. +* The `_data` argument MUST contain the unaltered information provided by the sender for the transfer. + - i.e. it MUST pass on the unaltered `_data` argument sent via the `safeTransferFrom` or `safeBatchTransferFrom` call for this transfer. * The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_erc1155_tokens()"))` - If the return value is `bytes4(keccak256("accept_erc1155_tokens()"))` the transfer MUST be completed or MUST revert if any other conditions are not met for success. * The recipient contract MAY reject an increase of its balance by calling revert. @@ -301,7 +312,8 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - `_from` MUST be 0x0 for a mint. * The `_ids` argument MUST be the list of tokens being transferred. * The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified in `_ids`) the holder balance is decreased by and match what the recipient balance is increased by. -* The `_data` argument MUST contain the information provided by the sender for a transfer. +* The `_data` argument MUST contain the unaltered information provided by the sender for the transfer. + - i.e. it MUST pass on the unaltered `_data` argument sent via the `safeTransferFrom` or `safeBatchTransferFrom` call for this transfer. * The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_batch_erc1155_tokens()"))` - If the return value is `bytes4(keccak256("accept_batch_erc1155_tokens()"))` the transfer MUST be completed or MUST revert if any other conditions are not met for success. * The recipient contract MAY reject an increase of its balance by calling revert. From 8cb275651a969f07f4aef275ff55dfb7797bd9c9 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Sat, 18 May 2019 01:26:55 -0400 Subject: [PATCH 26/58] EDT-3069 Minor grammar and consistency changes on use of "for example" for example. --- EIPS/eip-1155.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 25ba544083aff..fcd8a6d18e7ea 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -13,7 +13,7 @@ requires: 165 ## Simple Summary -A standard interface for contracts that manage multiple token types. A single deployed contract may include any combination of fungible tokens, non-fungible tokens, or other configurations (for example, semi-fungible tokens). +A standard interface for contracts that manage multiple token types. A single deployed contract may include any combination of fungible tokens, non-fungible tokens, or other configurations (e.g. semi-fungible tokens). ## Abstract @@ -85,7 +85,7 @@ interface ERC1155 /* is ERC165 */ { MUST revert if balance of holder for token `_id` is lower than the `_value` sent. MUST revert on any other error. MUST emit the `TransferSingle` event to reflect the balance change (see "Safe Transfer Rules" section of the standard). - After the above conditions are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). + After the above conditions are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). @param _from Source address @param _to Target address @param _id ID of the token type @@ -103,7 +103,7 @@ interface ERC1155 /* is ERC165 */ { MUST revert on any other error. MUST emit `TransferSingle` or `TransferBatch` event(s) such that all the balance changes are reflected (see "Safe Transfer Rules" section of the standard). Balance changes and events MUST follow the ordering of the arrays (_ids[0]/_values[0] before _ids[1]/_values[1], etc). - After the above conditions for the transfer(s) in the batch are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call the relevant `ERC1155TokenReceiver` hook(s) on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). + After the above conditions for the transfer(s) in the batch are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call the relevant `ERC1155TokenReceiver` hook(s) on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). @param _from Source address @param _to Target address @param _ids IDs of each token type (order and length must match _values array) @@ -219,7 +219,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op **_Scenario#5 :_** The receiver implements the necessary `ERC1155TokenReceiver` interface function(s) but throws an error. * The transfer MUST be reverted. -**_Scenario#6 :_** The receiver implements the `ERC1155TokenReceiver` interface and is the recipient of one and only one balance change (eg. safeTransferFrom called). +**_Scenario#6 :_** The receiver implements the `ERC1155TokenReceiver` interface and is the recipient of one and only one balance change (e.g. safeTransferFrom called). * All the balances in the transfer MUST have been updated to match the senders intent before any hook is called on a recipient. * All the transfer events for the transfer MUST have been emitted to reflect the balance changes before any hook is called on a recipient. * One of `onERC1155Received` or `onERC1155BatchReceived` MUST be called on the recipient. @@ -228,7 +228,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * The `onERC1155BatchReceived` hook MAY be called on the recipient contract and its rules followed. - See "onERC1155BatchReceived rules" for further rules that MUST be followed. -**_Scenario#7 :_** The receiver implements the `ERC1155TokenReceiver` interface and is the recipient of more than one balance change (eg. safeBatchTransferFrom called). +**_Scenario#7 :_** The receiver implements the `ERC1155TokenReceiver` interface and is the recipient of more than one balance change (e.g. safeBatchTransferFrom called). * All the balances in the transfer MUST have been updated to match the senders intent before any hook is called on a recipient. * All the transfer events for the transfer MUST have been emitted to reflect the balance changes before any hook is called on a recipient. * `onERC1155Received` or `onERC1155BatchReceived` MUST be called on the recipient as many times as necessary such that every balance change for the recipient in the scenario is accounted for. @@ -252,7 +252,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * MUST revert if balance of holder for token `_id` is lower than the `_value` sent to the recipient. * MUST revert on any other error. * MUST emit the `TransferSingle` event to reflect the balance change (see "TransferSingle and TransferBatch event rules" section). -* After the above conditions are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "onERC1155Received rules" section). +* After the above conditions are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "onERC1155Received rules" section). **_safeBatchTransferFrom rules:_** * Caller must be approved to manage all the tokens being transferred out of the `_from` account (see "Approval" section). @@ -262,7 +262,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * MUST revert on any other error. * MUST emit `TransferSingle` or `TransferBatch` event(s) such that all the balance changes are reflected (see "TransferSingle and TransferBatch event rules" section). * The balance changes and events MUST occur in the array order they were submitted (_ids[0]/_values[0] before _ids[1]/_values[1], etc). -* After the above conditions are met, this function MUST check if `_to` is a smart contract (eg. code size > 0). If so, it MUST call `onERC1155Received` or `onERC1155BatchReceived` on `_to` and act appropriately (see "`onERC1155Received` and onERC1155BatchReceived rules" section). +* After the above conditions are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call `onERC1155Received` or `onERC1155BatchReceived` on `_to` and act appropriately (see "`onERC1155Received` and onERC1155BatchReceived rules" section). **_TransferSingle and TransferBatch event rules:_** * `TransferSingle` SHOULD be used to indicate a single balance transfer has occurred between a `_from` and `_to` pair. @@ -287,7 +287,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * The total value transferred from address 0x0 minus the total value transferred to 0x0 MAY be used by clients and exchanges to be added to the "circulating supply" for a given token ID. * To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the `TransferSingle` event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0. * All `TransferSingle` and `TransferBatch` events MUST be emitted to reflect all the balance changes that have occurred before any call(s) to `onERC1155Received` or `onERC1155BatchReceived`. - - To make sure event order is correct in the case of valid re-entry (for eg. when a receiver contract forwards tokens on receipt) state balance and events balance MUST match before calling an external contract. + - To make sure event order is correct in the case of valid re-entry (e.g. if a receiver contract forwards tokens on receipt) state balance and events balance MUST match before calling an external contract. **_onERC1155Received rules:_** * The `_operator` argument MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). From a560f914eff2437a446225f92ca33d4d54fba28f Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Sat, 18 May 2019 02:25:58 -0400 Subject: [PATCH 27/58] EDT-3069 Change the recommended isERC1155TokenReceiver function to use view mutability to match the interface as implementers will have to also if they include it. Rather surprisingly according to remix the "view" version costs 282 gas vs 305 for the "pure" version too. --- EIPS/eip-1155.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index fcd8a6d18e7ea..f7c1de4813aac 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -326,7 +326,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op **_isERC1155TokenReceiver rules:_** * The implementation of `isERC1155TokenReceiver` function SHOULD be as follows: ``` - function isERC1155TokenReceiver() external pure returns (bytes4) { + function isERC1155TokenReceiver() external view returns (bytes4) { return 0x0d912442; // bytes4(keccak256("isERC1155TokenReceiver()")) } ``` From cc3e971f8530a5679d4c02da8d9f32e140c13015 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Tue, 21 May 2019 19:19:03 -0400 Subject: [PATCH 28/58] EDT-3069 Small alteration to text by request. --- EIPS/eip-1155.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index f7c1de4813aac..e236934f68d04 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -253,6 +253,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * MUST revert on any other error. * MUST emit the `TransferSingle` event to reflect the balance change (see "TransferSingle and TransferBatch event rules" section). * After the above conditions are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "onERC1155Received rules" section). + - The `_data` argument provided by the sender for the transfer MUST be passed with its contents unaltered to the `onERC1155Received` hook function via its `_data` argument. **_safeBatchTransferFrom rules:_** * Caller must be approved to manage all the tokens being transferred out of the `_from` account (see "Approval" section). @@ -263,6 +264,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * MUST emit `TransferSingle` or `TransferBatch` event(s) such that all the balance changes are reflected (see "TransferSingle and TransferBatch event rules" section). * The balance changes and events MUST occur in the array order they were submitted (_ids[0]/_values[0] before _ids[1]/_values[1], etc). * After the above conditions are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call `onERC1155Received` or `onERC1155BatchReceived` on `_to` and act appropriately (see "`onERC1155Received` and onERC1155BatchReceived rules" section). + - The `_data` argument provided by the sender for the transfer MUST be passed with its contents unaltered to the `ERC1155TokenReceiver` hook function(s) via their `_data` argument. **_TransferSingle and TransferBatch event rules:_** * `TransferSingle` SHOULD be used to indicate a single balance transfer has occurred between a `_from` and `_to` pair. @@ -295,7 +297,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - `_from` MUST be 0x0 for a mint. * The `_id` argument MUST be the token type being transferred. * The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. -* The `_data` argument MUST contain the unaltered information provided by the sender for the transfer. +* The `_data` argument MUST contain the information provided by the sender for the transfer with its contents unaltered. - i.e. it MUST pass on the unaltered `_data` argument sent via the `safeTransferFrom` or `safeBatchTransferFrom` call for this transfer. * The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_erc1155_tokens()"))` - If the return value is `bytes4(keccak256("accept_erc1155_tokens()"))` the transfer MUST be completed or MUST revert if any other conditions are not met for success. @@ -312,8 +314,8 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - `_from` MUST be 0x0 for a mint. * The `_ids` argument MUST be the list of tokens being transferred. * The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified in `_ids`) the holder balance is decreased by and match what the recipient balance is increased by. -* The `_data` argument MUST contain the unaltered information provided by the sender for the transfer. - - i.e. it MUST pass on the unaltered `_data` argument sent via the `safeTransferFrom` or `safeBatchTransferFrom` call for this transfer. +* The `_data` argument MUST contain the information provided by the sender for the transfer with its contents unaltered. + - i.e. it MUST pass on the unaltered `_data` argument sent via the `safeBatchTransferFrom` call for this transfer. * The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_batch_erc1155_tokens()"))` - If the return value is `bytes4(keccak256("accept_batch_erc1155_tokens()"))` the transfer MUST be completed or MUST revert if any other conditions are not met for success. * The recipient contract MAY reject an increase of its balance by calling revert. From c2a0f1130500c09b7850e17a02f624c7408c28d0 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Tue, 21 May 2019 23:41:47 -0400 Subject: [PATCH 29/58] EDT-3069 Minor text consistency change. --- EIPS/eip-1155.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index e236934f68d04..0ffdcbc9e8e2c 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -17,7 +17,7 @@ A standard interface for contracts that manage multiple token types. A single de ## Abstract -This standard outlines a smart contract interface that can represent any number of Fungible and Non-Fungible token types. Existing standards such as ERC-20 require deployment of separate contracts per token type. The ERC-721 standard's Token ID is a single non-fungible index and the group of these non-fungibles is deployed as a single contract with settings for the entire collection. In contrast, the ERC-1155 Multi Token Standard allows for each Token ID to represent a new configurable token type, which may have its own metadata, supply and other attributes. +This standard outlines a smart contract interface that can represent any number of Fungible and Non-Fungible token types. Existing standards such as ERC-20 require deployment of separate contracts per token type. The ERC-721 standard's token ID is a single non-fungible index and the group of these non-fungibles is deployed as a single contract with settings for the entire collection. In contrast, the ERC-1155 Multi Token Standard allows for each token ID to represent a new configurable token type, which may have its own metadata, supply and other attributes. The `_id` argument contained in each function's argument set indicates a specific token or token type in a transaction. @@ -115,8 +115,8 @@ interface ERC1155 /* is ERC165 */ { /** @notice Get the balance of an account's Tokens. @param _owner The address of the token holder - @param _id ID of the Token - @return The _owner's balance of the Token type requested + @param _id ID of the token + @return The _owner's balance of the token type requested */ function balanceOf(address _owner, uint256 _id) external view returns (uint256); @@ -124,7 +124,7 @@ interface ERC1155 /* is ERC165 */ { @notice Get the balance of multiple account/token pairs @param _owners The addresses of the token holders @param _ids ID of the Tokens - @return The _owner's balance of the Token types requested (i.e. balance for each (owner, id) pair) + @return The _owner's balance of the token types requested (i.e. balance for each (owner, id) pair) */ function balanceOfBatch(address[] calldata _owners, uint256[] calldata _ids) external view returns (uint256[] memory); @@ -165,7 +165,7 @@ interface ERC1155TokenReceiver { Return of any other value than the prescribed keccak256 generated value MUST result in the transaction being reverted by the caller. @param _operator The address which initiated the transfer (i.e. msg.sender) @param _from The address which previously owned the token - @param _id The id of the token being transferred + @param _id The ID of the token being transferred @param _value The amount of tokens being transferred @param _data Additional data with no specified format @return `bytes4(keccak256("accept_erc1155_tokens()"))` @@ -572,7 +572,7 @@ As the Ethereum ecosystem continues to grow, many dapps are relying on tradition The function `setApprovalForAll` allows an operator to manage one's entire set of tokens on behalf of the approver. It enables frictionless interaction with exchange and trade contracts. -Restricting approval to a certain set of Token IDs, quantities or other rules MAY be done with an additional interface or an external contract. The rationale is to keep the ERC-1155 standard as generic as possible for all use-cases without imposing a specific approval scheme on implementations that may not need it. Standard token approval interfaces can be used, such as the suggested [ERC-1761 Scoped Approval Interface](https://github.com/ethereum/EIPs/issues/1761) which is compatible with ERC-1155. +Restricting approval to a certain set of token IDs, quantities or other rules MAY be done with an additional interface or an external contract. The rationale is to keep the ERC-1155 standard as generic as possible for all use-cases without imposing a specific approval scheme on implementations that may not need it. Standard token approval interfaces can be used, such as the suggested [ERC-1761 Scoped Approval Interface](https://github.com/ethereum/EIPs/issues/1761) which is compatible with ERC-1155. ## Usage @@ -590,7 +590,7 @@ The `balanceOfBatch` function allows clients to retrieve balances of multiple ow ### Enumerating from events -In order to keep storage requirements light for contracts implementing ERC-1155, enumeration (discovering the IDs and values of tokens) must be done using event logs. It is RECOMMENDED that clients such as exchanges and blockchain explorers maintain a local database containing the Token ID, Supply, and URI at the minimum. This can be built from each TransferSingle, TransferBatch, and URI event, starting from the block the smart contract was deployed until the latest block. +In order to keep storage requirements light for contracts implementing ERC-1155, enumeration (discovering the IDs and values of tokens) must be done using event logs. It is RECOMMENDED that clients such as exchanges and blockchain explorers maintain a local database containing the token ID, Supply, and URI at the minimum. This can be built from each TransferSingle, TransferBatch, and URI event, starting from the block the smart contract was deployed until the latest block. ERC-1155 contracts must therefore carefully emit `TransferSingle` or `TransferBatch` events in any instance where tokens are created, minted, or destroyed. From 4eaf2c70cfe5a0f909d1ea919615b751b2e16444 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Tue, 21 May 2019 23:48:04 -0400 Subject: [PATCH 30/58] EDT-3069 Fixed typo. --- EIPS/eip-1155.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 0ffdcbc9e8e2c..4513b30cf3454 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -540,7 +540,7 @@ fr.json: ### Approval The function `setApprovalForAll` allows an operator to manage one's entire set of tokens on behalf of the approver. To permit approval of a subset of token IDs, an interface such as [ERC-1761 Scoped Approval Interface](https://eips.ethereum.org/EIPS/eip-1761) is suggested. -The counterpart `isAprrovedForAll` provides introspection into status set by `setApprovalForAll`. +The counterpart `isApprovedForAll` provides introspection into status set by `setApprovalForAll`. An owner SHOULD be assumed to always be able to operate on their own tokens regardless of approval status, so should SHOULD NOT have to call `setApprovalForAll` to approve themselves as an operator before they can operate on them. From cc3a9d99c60e5528d7e3cf66cb136f3de7ef8db9 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Wed, 22 May 2019 19:10:24 -0400 Subject: [PATCH 31/58] EDT-3069 Spelling. --- EIPS/eip-1155.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 4513b30cf3454..05b4e768056c8 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -67,7 +67,7 @@ interface ERC1155 /* is ERC165 */ { event TransferBatch(address indexed _operator, address indexed _from, address indexed _to, uint256[] _ids, uint256[] _values); /** - @dev MUST emit when approval for a second party/operator address to manage all tokens for an owner address is enabled or disabled (absense of an event assumes disabled). + @dev MUST emit when approval for a second party/operator address to manage all tokens for an owner address is enabled or disabled (absence of an event assumes disabled). */ event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved); From caa8d27f8f3b6793c262b79ee21c3b9d69d64e26 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Wed, 22 May 2019 19:26:06 -0400 Subject: [PATCH 32/58] EDT-3069 Minor formatting change. --- EIPS/eip-1155.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 05b4e768056c8..7dccdcdc2ae49 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -263,7 +263,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * MUST revert on any other error. * MUST emit `TransferSingle` or `TransferBatch` event(s) such that all the balance changes are reflected (see "TransferSingle and TransferBatch event rules" section). * The balance changes and events MUST occur in the array order they were submitted (_ids[0]/_values[0] before _ids[1]/_values[1], etc). -* After the above conditions are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call `onERC1155Received` or `onERC1155BatchReceived` on `_to` and act appropriately (see "`onERC1155Received` and onERC1155BatchReceived rules" section). +* After the above conditions are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call `onERC1155Received` or `onERC1155BatchReceived` on `_to` and act appropriately (see "onERC1155Received and onERC1155BatchReceived rules" section). - The `_data` argument provided by the sender for the transfer MUST be passed with its contents unaltered to the `ERC1155TokenReceiver` hook function(s) via their `_data` argument. **_TransferSingle and TransferBatch event rules:_** From 8c96bfbb7d871779be2fec6beebc26b9fecc6d06 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Fri, 24 May 2019 02:53:35 -0400 Subject: [PATCH 33/58] EDT-3069 Some small changes to wording for clarity. --- EIPS/eip-1155.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 7dccdcdc2ae49..c736f9bf8f84e 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -44,7 +44,7 @@ pragma solidity ^0.5.8; interface ERC1155 /* is ERC165 */ { /** @dev Either `TransferSingle` or `TransferBatch` MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "Safe Transfer Rules" section of the standard). - The `_operator` argument MUST be msg.sender. + The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender). The `_from` argument MUST be the address of the holder whose balance is decreased. The `_to` argument MUST be the address of the recipient whose balance is increased. The `_id` argument MUST be the token type being transferred. @@ -56,7 +56,7 @@ interface ERC1155 /* is ERC165 */ { /** @dev Either `TransferSingle` or `TransferBatch` MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "Safe Transfer Rules" section of the standard). - The `_operator` argument MUST be msg.sender. + The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender). The `_from` argument MUST be the address of the holder whose balance is decreased. The `_to` argument MUST be the address of the recipient whose balance is increased. The `_ids` argument MUST be the list of tokens being transferred. @@ -242,7 +242,8 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * Forwarding should be considered acceptance and then initiating a new `safeTransferFrom` or `safeBatchTransferFrom` in a new context. - The prescribed keccak256 acceptance value magic for the receiver hook being called MUST be returned after forwarding is successful. * The `_data` argument MAY be re-purposed for the new context. -* If forwarding unexpectedly fails the transaction MUST be reverted. +* If forwarding fails the transaction MAY be reverted. + - If the contract logic wishes to keep the ownership of the token(s) itself in this case it MAY do so. #### Rules @@ -269,7 +270,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op **_TransferSingle and TransferBatch event rules:_** * `TransferSingle` SHOULD be used to indicate a single balance transfer has occurred between a `_from` and `_to` pair. - It MAY be emitted multiple times to indicate multiple balance changes in the transaction, but note that `TransferBatch` is designed for this to reduce gas consumption. - - The `_operator` argument MUST be msg.sender. + - The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender). - The `_from` argument MUST be the address of the holder whose balance is decreased. - The `_to` argument MUST be the address of the recipient whose balance is increased. - The `_id` argument MUST be the token type being transferred. @@ -278,7 +279,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). * `TransferBatch` SHOULD be used to indicate multiple balance transfers have occurred between a `_from` and `_to` pair. - It MAY be emitted with a single element in the list to indicate a singular balance change in the transaction, but note that `TransferSingle` is designed for this to reduce gas consumption. - - The `_operator` argument MUST be msg.sender. + - The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender). - The `_from` argument MUST be the address of the holder whose balance is decreased for each entry pair in `_ids` and `_values`. - The `_to` argument MUST be the address of the recipient whose balance is increased for each entry pair in `_ids` and `_values`. - The `_ids` array argument MUST contain the ids of the tokens being transferred. @@ -292,7 +293,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - To make sure event order is correct in the case of valid re-entry (e.g. if a receiver contract forwards tokens on receipt) state balance and events balance MUST match before calling an external contract. **_onERC1155Received rules:_** -* The `_operator` argument MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). +- The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender). * The `_from` argument MUST be the address of the holder whose balance is decreased. - `_from` MUST be 0x0 for a mint. * The `_id` argument MUST be the token type being transferred. @@ -309,7 +310,7 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - The set of all calls to `onERC1155Received` and `onERC1155BatchReceived` describes all balance changes that occurred during the transaction in the order submitted. **_onERC1155BatchReceived rules:_** -* The `_operator` argument MUST be the address of the account/contract that initiated the transfer (i.e. msg.sender). +- The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender). * The `_from` argument MUST be the address of the holder whose balance is decreased. - `_from` MUST be 0x0 for a mint. * The `_ids` argument MUST be the list of tokens being transferred. From 50d401cbcffab87a0ea755f7fd8363c053a2d113 Mon Sep 17 00:00:00 2001 From: Philippe Castonguay Date: Fri, 24 May 2019 19:47:39 -0400 Subject: [PATCH 34/58] Revert magic_values to original byte4 --- EIPS/eip-1155.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index c736f9bf8f84e..da614ed63b18d 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -160,7 +160,7 @@ interface ERC1155TokenReceiver { /** @notice Handle the receipt of a single ERC1155 token type. @dev An ERC1155-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeTransferFrom` after the balance has been updated. - This function MUST return `bytes4(keccak256("accept_erc1155_tokens()"))` (i.e. 0x4dc21a2f) if it accepts the transfer. + This function MUST return `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))` (i.e. 0xf23a6e61) if it accepts the transfer. This function MUST revert if it rejects the transfer. Return of any other value than the prescribed keccak256 generated value MUST result in the transaction being reverted by the caller. @param _operator The address which initiated the transfer (i.e. msg.sender) @@ -168,14 +168,14 @@ interface ERC1155TokenReceiver { @param _id The ID of the token being transferred @param _value The amount of tokens being transferred @param _data Additional data with no specified format - @return `bytes4(keccak256("accept_erc1155_tokens()"))` + @return `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))` */ function onERC1155Received(address _operator, address _from, uint256 _id, uint256 _value, bytes calldata _data) external returns(bytes4); /** @notice Handle the receipt of multiple ERC1155 token types. @dev An ERC1155-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeBatchTransferFrom` after the balances have been updated. - This function MUST return `bytes4(keccak256("accept_batch_erc1155_tokens()"))` (i.e. 0xac007889) if it accepts the transfer(s). + This function MUST return `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` (i.e. 0xbc197c81) if it accepts the transfer(s). This function MUST revert if it rejects the transfer(s). Return of any other value than the prescribed keccak256 generated value MUST result in the transaction being reverted by the caller. @param _operator The address which initiated the batch transfer (i.e. msg.sender) @@ -183,7 +183,7 @@ interface ERC1155TokenReceiver { @param _ids An array containing ids of each token being transferred (order and length must match _values array) @param _values An array containing amounts of each token being transferred (order and length must match _ids array) @param _data Additional data with no specified format - @return `bytes4(keccak256("accept_batch_erc1155_tokens()"))` + @return `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` */ function onERC1155BatchReceived(address _operator, address _from, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external returns(bytes4); @@ -300,11 +300,11 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. * The `_data` argument MUST contain the information provided by the sender for the transfer with its contents unaltered. - i.e. it MUST pass on the unaltered `_data` argument sent via the `safeTransferFrom` or `safeBatchTransferFrom` call for this transfer. -* The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_erc1155_tokens()"))` - - If the return value is `bytes4(keccak256("accept_erc1155_tokens()"))` the transfer MUST be completed or MUST revert if any other conditions are not met for success. +* The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))` + - If the return value is `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))` the transfer MUST be completed or MUST revert if any other conditions are not met for success. * The recipient contract MAY reject an increase of its balance by calling revert. - If recipient contract throws/reverts the transaction MUST be reverted. -* If the return value is anything other than `bytes4(keccak256("accept_erc1155_tokens()"))` the transaction MUST be reverted. +* If the return value is anything other than `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))` the transaction MUST be reverted. * `onERC1155Received` (and/or `onERC1155BatchReceived`) MAY be called multiple times in a single transaction and the following requirements must be met: - All callbacks represent mutually exclusive balance changes. - The set of all calls to `onERC1155Received` and `onERC1155BatchReceived` describes all balance changes that occurred during the transaction in the order submitted. @@ -317,11 +317,11 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified in `_ids`) the holder balance is decreased by and match what the recipient balance is increased by. * The `_data` argument MUST contain the information provided by the sender for the transfer with its contents unaltered. - i.e. it MUST pass on the unaltered `_data` argument sent via the `safeBatchTransferFrom` call for this transfer. -* The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("accept_batch_erc1155_tokens()"))` - - If the return value is `bytes4(keccak256("accept_batch_erc1155_tokens()"))` the transfer MUST be completed or MUST revert if any other conditions are not met for success. +* The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` + - If the return value is `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` the transfer MUST be completed or MUST revert if any other conditions are not met for success. * The recipient contract MAY reject an increase of its balance by calling revert. - If recipient contract throws/reverts the transaction MUST be reverted. -* If the return value is anything other than `bytes4(keccak256("accept_batch_erc1155_tokens()"))` the transaction MUST be reverted. +* If the return value is anything other than `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` the transaction MUST be reverted. * `onERC1155BatchReceived` (and/or `onERC1155Received`) MAY be called multiple times in a single transaction and the following requirements must be met: - All callbacks represent mutually exclusive balance changes. - The set of all calls to `onERC1155Received` and `onERC1155BatchReceived` describes all balance changes that occurred during the transaction in the order submitted. @@ -341,8 +341,8 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * If implementation specific api functions are used to transfer 1155 tokens to a contract, the safeTransferFrom, or safeBatchTransferFrom (as appropriate) rules MUST be followed. ###### A solidity example of the keccak256 generated constants for the return magic is: - - bytes4 constant public ERC1155_ACCEPTED = 0x4dc21a2f; // bytes4(keccak256("accept_erc1155_tokens()")) - - bytes4 constant public ERC1155_BATCH_ACCEPTED = 0xac007889; // bytes4(keccak256("accept_batch_erc1155_tokens()")) + - bytes4 constant public ERC1155_ACCEPTED = 0xf23a6e61; // bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")) + - bytes4 constant public ERC1155_BATCH_ACCEPTED = 0xbc197c81; // bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)")) #### Compatibility with other standards From d054f84ec953f32a1c4385a2a3c0890ac738d588 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Fri, 24 May 2019 19:56:10 -0400 Subject: [PATCH 35/58] EDT-3069 Adding in scenario for non-standard api call and allow it to send to contracts that don't have receiver functions if the implementation wishes (with warning on potentially unrecoverable tokens). --- EIPS/eip-1155.md | 42 +++++++++++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 9 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index c736f9bf8f84e..8b4173ca4b46c 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -199,7 +199,7 @@ interface ERC1155TokenReceiver { ### Safe Transfer Rules -To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST operate with respect to the `ERC1155TokenReceiver` hook functions, a list of scenarios and rules follows. +To be more explicit about how the standard `safeTransferFrom` and `safeBatchTransferFrom` functions MUST operate with respect to the `ERC1155TokenReceiver` hook functions, a list of scenarios and rules follows. #### Scenarios @@ -220,17 +220,17 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * The transfer MUST be reverted. **_Scenario#6 :_** The receiver implements the `ERC1155TokenReceiver` interface and is the recipient of one and only one balance change (e.g. safeTransferFrom called). -* All the balances in the transfer MUST have been updated to match the senders intent before any hook is called on a recipient. -* All the transfer events for the transfer MUST have been emitted to reflect the balance changes before any hook is called on a recipient. -* One of `onERC1155Received` or `onERC1155BatchReceived` MUST be called on the recipient. +* The balances for the transfer MUST have been updated before the `ERC1155TokenReceiver` hook is called on a recipient contract. +* The transfer event MUST have been emitted to reflect the balance changes before the `ERC1155TokenReceiver` hook is called on the recipient contract. +* One of `onERC1155Received` or `onERC1155BatchReceived` MUST be called on the recipient contract. * The `onERC1155Received` hook SHOULD be called on the recipient contract and its rules followed. - See "onERC1155Received rules" for further rules that MUST be followed. * The `onERC1155BatchReceived` hook MAY be called on the recipient contract and its rules followed. - See "onERC1155BatchReceived rules" for further rules that MUST be followed. **_Scenario#7 :_** The receiver implements the `ERC1155TokenReceiver` interface and is the recipient of more than one balance change (e.g. safeBatchTransferFrom called). -* All the balances in the transfer MUST have been updated to match the senders intent before any hook is called on a recipient. -* All the transfer events for the transfer MUST have been emitted to reflect the balance changes before any hook is called on a recipient. +* All the balances in the transfer related to the next hook call MUST have been updated before that `ERC1155TokenReceiver` hook is called on a recipient contract. +* All transfer events MUST have been emitted to reflect current balance changes before an `ERC1155TokenReceiver` hook is called on the recipient contract. * `onERC1155Received` or `onERC1155BatchReceived` MUST be called on the recipient as many times as necessary such that every balance change for the recipient in the scenario is accounted for. - The return magic value for every hook call MUST be checked and acted upon as per "onERC1155Received rules" and "onERC1155BatchReceived rules". * The `onERC1155BatchReceived` hook SHOULD be called on the recipient contract and its rules followed. @@ -244,6 +244,14 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op * The `_data` argument MAY be re-purposed for the new context. * If forwarding fails the transaction MAY be reverted. - If the contract logic wishes to keep the ownership of the token(s) itself in this case it MAY do so. + +**_Scenario#9 :_** You are transferring tokens via a non-standard api call i.e. an implementation specific api and NOT `safeTransferFrom` or `safeBatchTransferFrom`. +* In this scenario all balance updates and events outputs rules are the same as if a standard function had been called. + - i.e. an external viewer should still be able to query a balance via a function and it be identical to the balance as determined by `TransferSingle` and '`TransferBatch` events alone. +* If the receiver is a contract the `ERC1155TokenReceiver` hooks still need to be called on it and the return values respected the same as if a standard function had been called. + - However while the `safeTransferFrom` or `safeBatchTransferFrom` functions MUST revert if a receiving contract does not implement the `ERC1155TokenReceiver` interface, a non-standard function MAY proceed with the transfer. + - See "Implementation specific transfer api rules". + #### Rules @@ -338,7 +346,23 @@ To be more explicit about how safeTransferFrom and safeBatchTransferFrom MUST op - It MUST NOT consume more than 5,000 gas. **_Implementation specific transfer api rules:_** -* If implementation specific api functions are used to transfer 1155 tokens to a contract, the safeTransferFrom, or safeBatchTransferFrom (as appropriate) rules MUST be followed. +* If implementation specific api functions are used to transfer 1155 tokens to a contract, the `safeTransferFrom`, or `safeBatchTransferFrom` (as appropriate) rules MUST still be followed if the receiver implements the `ERC1155TokenReceiver` interface. If not it is up to the implementation to revert or proceed. +* An example: + 1. A approved user calls a function such as `function myTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values);`. + 2. `myTransferFrom` updates the balances for `_from` and `_to` addresses for all `_ids` and `_values`. + 3. `myTransferFrom` emits `TransferBatch` with the details of what was transferred from address `_from` to address `_to`. + 4. `myTransferFrom` checks if `_to` is a contract address and determines that it is (if not, then the transfer can be considered successful). + 5. `myTransferFrom` calls `onERC1155BatchReceived` on `_to` and it reverts or returns an unknown value (if it had returned `bytes4(keccak256("accept_batch_erc1155_tokens()"))` the transfer can be considered successful). + 6. At this point `myTransferFrom` MAY decide to revert the transaction immediately as receipt of the tokens was not explicitly accepted by the `onERC1155BatchReceived` function. + 7. If `myTransferFrom` wishes to continue it MUST call `isERC1155TokenReceiver()` on `_to` and if it returns `bytes4(keccak256("isERC1155TokenReceiver()"))` the transaction MUST be reverted, as it is a valid receiver and the previous step failed. + 8. If the above call to `isERC1155TokenReceiver()` on `_to` reverts or returns an unknown value the `myTransferFrom` function MAY consider this transfer successful (__NOTE__: this could result in unrecoverable tokens if sent to a bad/wrong address that doesn't expect 1155 tokens to be sent to it). +* The above example is not exhaustive but illustrates the major points (and shows that most are shared with `safeTransferFrom` and `safeBatchTransferFrom`): + - Balances that are updated MUST have equivalent transfer events emitted. + - A receiver address has to be checked if it is a contract and if so relevant `ERC1155TokenReceiver` hook function(s) have to be called on it. + - Balances (and events associated) that are referenced in a call to a receiver hook MUST be updated (and emitted) before the `ERC1155TokenReceiver` hook is called. + - The return values of the `ERC1155TokenReceiver` hook functions that are called MUST be respected if they are implemented. + - Only in the case that a recipient contract does NOT implement the necessary `ERC1155TokenReceiver` hook functions can a non-standard implementation allow tokens to be sent to it. A standard function MUST always revert regardless (unless it is a hybrid implementation see "Compatibility with other standards"). + ###### A solidity example of the keccak256 generated constants for the return magic is: - bytes4 constant public ERC1155_ACCEPTED = 0x4dc21a2f; // bytes4(keccak256("accept_erc1155_tokens()")) @@ -351,9 +375,9 @@ To cater for this scenario, there is some leeway with the rejection logic should Hence in a hybrid 1155 contract implementation an extra call MUST be made on the recipient contract and checked before any hook calls to `onERC1155Received` or `onERC1155BatchReceived` are made. Order of operation MUST therefore be: -1. The implementation MUST call the function `isERC1155TokenReceiver` on the recipient, providing at least 5,000 gas. +1. The implementation MUST call the function `isERC1155TokenReceiver` on the recipient contract, providing at least 5,000 gas. 2. If the function call succeeds and the return value is `bytes4(keccak256("isERC1155TokenReceiver()"))` the implementation proceeds as a regular 1155 implementation, with the call(s) to the `onERC1155Received` or `onERC1155BatchReceived` hooks and rules associated. -3. If the function call fails or the return value is NOT `bytes4(keccak256("isERC1155TokenReceiver()"))` the implementation can assume the contract recipient is not an `ERC1155TokenReceiver` and follow its other standard's rules for transfers. +3. If the function call fails or the return value is NOT `bytes4(keccak256("isERC1155TokenReceiver()"))` the implementation can assume the recipient contract is not an `ERC1155TokenReceiver` and follow its other standard's rules for transfers. *__Note that a pure implementation of a single standard is recommended__* rather than a hybrid solution, but an example of a hybrid 1155+721 contract is linked in the references section under implementations. From ca3278bfcf4a61021017da271a1ae2e22912839d Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Fri, 24 May 2019 20:48:09 -0400 Subject: [PATCH 36/58] EDT-3069 Minor consistency change. --- EIPS/eip-1155.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index d20c6a79b4ae9..11dd004c9b463 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -219,7 +219,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran **_Scenario#5 :_** The receiver implements the necessary `ERC1155TokenReceiver` interface function(s) but throws an error. * The transfer MUST be reverted. -**_Scenario#6 :_** The receiver implements the `ERC1155TokenReceiver` interface and is the recipient of one and only one balance change (e.g. safeTransferFrom called). +**_Scenario#6 :_** The receiver implements the `ERC1155TokenReceiver` interface and is the recipient of one and only one balance change (e.g. `safeTransferFrom` called). * The balances for the transfer MUST have been updated before the `ERC1155TokenReceiver` hook is called on a recipient contract. * The transfer event MUST have been emitted to reflect the balance changes before the `ERC1155TokenReceiver` hook is called on the recipient contract. * One of `onERC1155Received` or `onERC1155BatchReceived` MUST be called on the recipient contract. @@ -228,7 +228,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran * The `onERC1155BatchReceived` hook MAY be called on the recipient contract and its rules followed. - See "onERC1155BatchReceived rules" for further rules that MUST be followed. -**_Scenario#7 :_** The receiver implements the `ERC1155TokenReceiver` interface and is the recipient of more than one balance change (e.g. safeBatchTransferFrom called). +**_Scenario#7 :_** The receiver implements the `ERC1155TokenReceiver` interface and is the recipient of more than one balance change (e.g. `safeBatchTransferFrom` called). * All the balances in the transfer related to the next hook call MUST have been updated before that `ERC1155TokenReceiver` hook is called on a recipient contract. * All transfer events MUST have been emitted to reflect current balance changes before an `ERC1155TokenReceiver` hook is called on the recipient contract. * `onERC1155Received` or `onERC1155BatchReceived` MUST be called on the recipient as many times as necessary such that every balance change for the recipient in the scenario is accounted for. From cfae695345c247f82e105b1f7a655c29fcbcabcc Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Fri, 24 May 2019 21:20:46 -0400 Subject: [PATCH 37/58] EDT-3069 Updated return value to latest after merge. --- EIPS/eip-1155.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 11dd004c9b463..204f9378dff28 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -352,7 +352,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran 2. `myTransferFrom` updates the balances for `_from` and `_to` addresses for all `_ids` and `_values`. 3. `myTransferFrom` emits `TransferBatch` with the details of what was transferred from address `_from` to address `_to`. 4. `myTransferFrom` checks if `_to` is a contract address and determines that it is (if not, then the transfer can be considered successful). - 5. `myTransferFrom` calls `onERC1155BatchReceived` on `_to` and it reverts or returns an unknown value (if it had returned `bytes4(keccak256("accept_batch_erc1155_tokens()"))` the transfer can be considered successful). + 5. `myTransferFrom` calls `onERC1155BatchReceived` on `_to` and it reverts or returns an unknown value (if it had returned `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` the transfer can be considered successful). 6. At this point `myTransferFrom` MAY decide to revert the transaction immediately as receipt of the tokens was not explicitly accepted by the `onERC1155BatchReceived` function. 7. If `myTransferFrom` wishes to continue it MUST call `isERC1155TokenReceiver()` on `_to` and if it returns `bytes4(keccak256("isERC1155TokenReceiver()"))` the transaction MUST be reverted, as it is a valid receiver and the previous step failed. 8. If the above call to `isERC1155TokenReceiver()` on `_to` reverts or returns an unknown value the `myTransferFrom` function MAY consider this transfer successful (__NOTE__: this could result in unrecoverable tokens if sent to a bad/wrong address that doesn't expect 1155 tokens to be sent to it). From c21e7994ff6722a7534bf3924456acecce72f5b1 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Fri, 24 May 2019 21:21:29 -0400 Subject: [PATCH 38/58] EDT-3069 Consistency on calling "1155" "ERC-1155". --- EIPS/eip-1155.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 204f9378dff28..bb33ef2e55ead 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -346,7 +346,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran - It MUST NOT consume more than 5,000 gas. **_Implementation specific transfer api rules:_** -* If implementation specific api functions are used to transfer 1155 tokens to a contract, the `safeTransferFrom`, or `safeBatchTransferFrom` (as appropriate) rules MUST still be followed if the receiver implements the `ERC1155TokenReceiver` interface. If not it is up to the implementation to revert or proceed. +* If implementation specific api functions are used to transfer ERC-1155 tokens to a contract, the `safeTransferFrom`, or `safeBatchTransferFrom` (as appropriate) rules MUST still be followed if the receiver implements the `ERC1155TokenReceiver` interface. If not it is up to the implementation to revert or proceed. * An example: 1. A approved user calls a function such as `function myTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values);`. 2. `myTransferFrom` updates the balances for `_from` and `_to` addresses for all `_ids` and `_values`. @@ -355,7 +355,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran 5. `myTransferFrom` calls `onERC1155BatchReceived` on `_to` and it reverts or returns an unknown value (if it had returned `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` the transfer can be considered successful). 6. At this point `myTransferFrom` MAY decide to revert the transaction immediately as receipt of the tokens was not explicitly accepted by the `onERC1155BatchReceived` function. 7. If `myTransferFrom` wishes to continue it MUST call `isERC1155TokenReceiver()` on `_to` and if it returns `bytes4(keccak256("isERC1155TokenReceiver()"))` the transaction MUST be reverted, as it is a valid receiver and the previous step failed. - 8. If the above call to `isERC1155TokenReceiver()` on `_to` reverts or returns an unknown value the `myTransferFrom` function MAY consider this transfer successful (__NOTE__: this could result in unrecoverable tokens if sent to a bad/wrong address that doesn't expect 1155 tokens to be sent to it). + 8. If the above call to `isERC1155TokenReceiver()` on `_to` reverts or returns an unknown value the `myTransferFrom` function MAY consider this transfer successful (__NOTE__: this MAY result in unrecoverable tokens if sent to an address that does not expect to receive ERC-1155 tokens). * The above example is not exhaustive but illustrates the major points (and shows that most are shared with `safeTransferFrom` and `safeBatchTransferFrom`): - Balances that are updated MUST have equivalent transfer events emitted. - A receiver address has to be checked if it is a contract and if so relevant `ERC1155TokenReceiver` hook function(s) have to be called on it. @@ -373,15 +373,15 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran There have been requirements during the design discussions to have this standard be compatible with existing standards when sending to contract addresses, specifically ERC-721 at time of writing. To cater for this scenario, there is some leeway with the rejection logic should a contract not implement the `ERC1155TokenReceiver` as per "Safe Transfer Rules" section above, specifically "Scenario#3 : The receiver does not implement the necessary `ERC1155TokenReceiver` interface function(s)". -Hence in a hybrid 1155 contract implementation an extra call MUST be made on the recipient contract and checked before any hook calls to `onERC1155Received` or `onERC1155BatchReceived` are made. +Hence in a hybrid ERC-1155 contract implementation an extra call MUST be made on the recipient contract and checked before any hook calls to `onERC1155Received` or `onERC1155BatchReceived` are made. Order of operation MUST therefore be: 1. The implementation MUST call the function `isERC1155TokenReceiver` on the recipient contract, providing at least 5,000 gas. -2. If the function call succeeds and the return value is `bytes4(keccak256("isERC1155TokenReceiver()"))` the implementation proceeds as a regular 1155 implementation, with the call(s) to the `onERC1155Received` or `onERC1155BatchReceived` hooks and rules associated. +2. If the function call succeeds and the return value is `bytes4(keccak256("isERC1155TokenReceiver()"))` the implementation proceeds as a regular ERC-1155 implementation, with the call(s) to the `onERC1155Received` or `onERC1155BatchReceived` hooks and rules associated. 3. If the function call fails or the return value is NOT `bytes4(keccak256("isERC1155TokenReceiver()"))` the implementation can assume the recipient contract is not an `ERC1155TokenReceiver` and follow its other standard's rules for transfers. -*__Note that a pure implementation of a single standard is recommended__* rather than a hybrid solution, but an example of a hybrid 1155+721 contract is linked in the references section under implementations. +*__Note that a pure implementation of a single standard is recommended__* rather than a hybrid solution, but an example of a hybrid ERC-1155/ERC-721 contract is linked in the references section under implementations. -An important consideration is that even if the tokens are sent with another standard's rules the *__1155 transfer events MUST still be emitted.__* This is so the balances can still be determined via events alone as per 1155 standard rules. +An important consideration is that even if the tokens are sent with another standard's rules the *__1155 transfer events MUST still be emitted.__* This is so the balances can still be determined via events alone as per ERC-1155 standard rules. ### Metadata From 6dd5dc6cdc893a399d32f2246397e2024f3fee04 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Fri, 24 May 2019 21:39:14 -0400 Subject: [PATCH 39/58] EDT-3069 Minor wording change. --- EIPS/eip-1155.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index bb33ef2e55ead..6f317ff56ebab 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -229,7 +229,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran - See "onERC1155BatchReceived rules" for further rules that MUST be followed. **_Scenario#7 :_** The receiver implements the `ERC1155TokenReceiver` interface and is the recipient of more than one balance change (e.g. `safeBatchTransferFrom` called). -* All the balances in the transfer related to the next hook call MUST have been updated before that `ERC1155TokenReceiver` hook is called on a recipient contract. +* All balance transfers that are referenced in a call to an `ERC1155TokenReceiver` hook MUST be updated before the `ERC1155TokenReceiver` hook is called on the recipient contract. * All transfer events MUST have been emitted to reflect current balance changes before an `ERC1155TokenReceiver` hook is called on the recipient contract. * `onERC1155Received` or `onERC1155BatchReceived` MUST be called on the recipient as many times as necessary such that every balance change for the recipient in the scenario is accounted for. - The return magic value for every hook call MUST be checked and acted upon as per "onERC1155Received rules" and "onERC1155BatchReceived rules". @@ -359,7 +359,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran * The above example is not exhaustive but illustrates the major points (and shows that most are shared with `safeTransferFrom` and `safeBatchTransferFrom`): - Balances that are updated MUST have equivalent transfer events emitted. - A receiver address has to be checked if it is a contract and if so relevant `ERC1155TokenReceiver` hook function(s) have to be called on it. - - Balances (and events associated) that are referenced in a call to a receiver hook MUST be updated (and emitted) before the `ERC1155TokenReceiver` hook is called. + - Balances (and events associated) that are referenced in a call to an `ERC1155TokenReceiver` hook MUST be updated (and emitted) before the `ERC1155TokenReceiver` hook is called. - The return values of the `ERC1155TokenReceiver` hook functions that are called MUST be respected if they are implemented. - Only in the case that a recipient contract does NOT implement the necessary `ERC1155TokenReceiver` hook functions can a non-standard implementation allow tokens to be sent to it. A standard function MUST always revert regardless (unless it is a hybrid implementation see "Compatibility with other standards"). From 91815a0d5992ae3c1e585d3eea08e0dc81c47658 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Fri, 24 May 2019 22:17:36 -0400 Subject: [PATCH 40/58] EDT-3069 More wording changes for clarification. --- EIPS/eip-1155.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 6f317ff56ebab..ef843cb11a1b6 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -246,8 +246,8 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran - If the contract logic wishes to keep the ownership of the token(s) itself in this case it MAY do so. **_Scenario#9 :_** You are transferring tokens via a non-standard api call i.e. an implementation specific api and NOT `safeTransferFrom` or `safeBatchTransferFrom`. -* In this scenario all balance updates and events outputs rules are the same as if a standard function had been called. - - i.e. an external viewer should still be able to query a balance via a function and it be identical to the balance as determined by `TransferSingle` and '`TransferBatch` events alone. +* In this scenario all balance updates and events output rules are the same as if a standard function had been called. + - i.e. an external viewer should still be able to query a balance via a function and it be identical to the balance as determined by `TransferSingle` and `TransferBatch` events alone. * If the receiver is a contract the `ERC1155TokenReceiver` hooks still need to be called on it and the return values respected the same as if a standard function had been called. - However while the `safeTransferFrom` or `safeBatchTransferFrom` functions MUST revert if a receiving contract does not implement the `ERC1155TokenReceiver` interface, a non-standard function MAY proceed with the transfer. - See "Implementation specific transfer api rules". @@ -346,22 +346,22 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran - It MUST NOT consume more than 5,000 gas. **_Implementation specific transfer api rules:_** -* If implementation specific api functions are used to transfer ERC-1155 tokens to a contract, the `safeTransferFrom`, or `safeBatchTransferFrom` (as appropriate) rules MUST still be followed if the receiver implements the `ERC1155TokenReceiver` interface. If not it is up to the implementation to revert or proceed. +* If an implementation specific api function is used to transfer ERC-1155 token(s) to a contract, the `safeTransferFrom` or `safeBatchTransferFrom` (as appropriate) rules MUST still be followed if the receiver implements the `ERC1155TokenReceiver` interface. If it does not the non-standard implementation MAY revert or MAY proceed. * An example: 1. A approved user calls a function such as `function myTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values);`. 2. `myTransferFrom` updates the balances for `_from` and `_to` addresses for all `_ids` and `_values`. 3. `myTransferFrom` emits `TransferBatch` with the details of what was transferred from address `_from` to address `_to`. - 4. `myTransferFrom` checks if `_to` is a contract address and determines that it is (if not, then the transfer can be considered successful). + 4. `myTransferFrom` checks if `_to` is a contract address and determines that it is so (if not, then the transfer can be considered successful). 5. `myTransferFrom` calls `onERC1155BatchReceived` on `_to` and it reverts or returns an unknown value (if it had returned `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` the transfer can be considered successful). - 6. At this point `myTransferFrom` MAY decide to revert the transaction immediately as receipt of the tokens was not explicitly accepted by the `onERC1155BatchReceived` function. - 7. If `myTransferFrom` wishes to continue it MUST call `isERC1155TokenReceiver()` on `_to` and if it returns `bytes4(keccak256("isERC1155TokenReceiver()"))` the transaction MUST be reverted, as it is a valid receiver and the previous step failed. + 6. At this point `myTransferFrom` MAY decide to revert the transaction immediately as receipt of the token(s) was not explicitly accepted by the `onERC1155BatchReceived` function. + 7. If `myTransferFrom` wishes to continue it MUST call `isERC1155TokenReceiver()` on `_to` and if it returns `bytes4(keccak256("isERC1155TokenReceiver()"))` the transaction MUST be reverted, as it is now known to be a valid receiver and the previous acceptance step failed. 8. If the above call to `isERC1155TokenReceiver()` on `_to` reverts or returns an unknown value the `myTransferFrom` function MAY consider this transfer successful (__NOTE__: this MAY result in unrecoverable tokens if sent to an address that does not expect to receive ERC-1155 tokens). * The above example is not exhaustive but illustrates the major points (and shows that most are shared with `safeTransferFrom` and `safeBatchTransferFrom`): - Balances that are updated MUST have equivalent transfer events emitted. - A receiver address has to be checked if it is a contract and if so relevant `ERC1155TokenReceiver` hook function(s) have to be called on it. - Balances (and events associated) that are referenced in a call to an `ERC1155TokenReceiver` hook MUST be updated (and emitted) before the `ERC1155TokenReceiver` hook is called. - The return values of the `ERC1155TokenReceiver` hook functions that are called MUST be respected if they are implemented. - - Only in the case that a recipient contract does NOT implement the necessary `ERC1155TokenReceiver` hook functions can a non-standard implementation allow tokens to be sent to it. A standard function MUST always revert regardless (unless it is a hybrid implementation see "Compatibility with other standards"). + - Only non-standard transfer functions MAY allow tokens to be sent to a recipient contract that does NOT implement the necessary `ERC1155TokenReceiver` hook functions. `safeTransferFrom` and `safeBatchTransferFrom` MUST revert in that case (unless it is a hybrid standards implementation see "Compatibility with other standards"). ###### A solidity example of the keccak256 generated constants for the return magic is: From a3c61badc316b235a8730c41bd233960484eeafe Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Fri, 24 May 2019 22:44:52 -0400 Subject: [PATCH 41/58] EDT-3069 Small grammar change and capitalized API. --- EIPS/eip-1155.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index ef843cb11a1b6..f551d3ed4e427 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -245,12 +245,12 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran * If forwarding fails the transaction MAY be reverted. - If the contract logic wishes to keep the ownership of the token(s) itself in this case it MAY do so. -**_Scenario#9 :_** You are transferring tokens via a non-standard api call i.e. an implementation specific api and NOT `safeTransferFrom` or `safeBatchTransferFrom`. +**_Scenario#9 :_** You are transferring tokens via a non-standard API call i.e. an implementation specific API and NOT `safeTransferFrom` or `safeBatchTransferFrom`. * In this scenario all balance updates and events output rules are the same as if a standard function had been called. - i.e. an external viewer should still be able to query a balance via a function and it be identical to the balance as determined by `TransferSingle` and `TransferBatch` events alone. * If the receiver is a contract the `ERC1155TokenReceiver` hooks still need to be called on it and the return values respected the same as if a standard function had been called. - However while the `safeTransferFrom` or `safeBatchTransferFrom` functions MUST revert if a receiving contract does not implement the `ERC1155TokenReceiver` interface, a non-standard function MAY proceed with the transfer. - - See "Implementation specific transfer api rules". + - See "Implementation specific transfer API rules". #### Rules @@ -345,10 +345,10 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran - It MUST return the same value. - It MUST NOT consume more than 5,000 gas. -**_Implementation specific transfer api rules:_** -* If an implementation specific api function is used to transfer ERC-1155 token(s) to a contract, the `safeTransferFrom` or `safeBatchTransferFrom` (as appropriate) rules MUST still be followed if the receiver implements the `ERC1155TokenReceiver` interface. If it does not the non-standard implementation MAY revert or MAY proceed. +**_Implementation specific transfer API rules:_** +* If an implementation specific API function is used to transfer ERC-1155 token(s) to a contract, the `safeTransferFrom` or `safeBatchTransferFrom` (as appropriate) rules MUST still be followed if the receiver implements the `ERC1155TokenReceiver` interface. If it does not the non-standard implementation MAY revert or MAY proceed. * An example: - 1. A approved user calls a function such as `function myTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values);`. + 1. An approved user calls a function such as `function myTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values);`. 2. `myTransferFrom` updates the balances for `_from` and `_to` addresses for all `_ids` and `_values`. 3. `myTransferFrom` emits `TransferBatch` with the details of what was transferred from address `_from` to address `_to`. 4. `myTransferFrom` checks if `_to` is a contract address and determines that it is so (if not, then the transfer can be considered successful). From 4ff6c62ff7a707457fa31deecefe8d09619c091d Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Fri, 24 May 2019 23:07:19 -0400 Subject: [PATCH 42/58] EDT-3069 Change a MAY to SHOULD as a non-standard impl really should revert if a contract doesn't accept 1155's --- EIPS/eip-1155.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index f551d3ed4e427..24d5ebefea7fb 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -346,7 +346,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran - It MUST NOT consume more than 5,000 gas. **_Implementation specific transfer API rules:_** -* If an implementation specific API function is used to transfer ERC-1155 token(s) to a contract, the `safeTransferFrom` or `safeBatchTransferFrom` (as appropriate) rules MUST still be followed if the receiver implements the `ERC1155TokenReceiver` interface. If it does not the non-standard implementation MAY revert or MAY proceed. +* If an implementation specific API function is used to transfer ERC-1155 token(s) to a contract, the `safeTransferFrom` or `safeBatchTransferFrom` (as appropriate) rules MUST still be followed if the receiver implements the `ERC1155TokenReceiver` interface. If it does not the non-standard implementation SHOULD revert but MAY proceed. * An example: 1. An approved user calls a function such as `function myTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values);`. 2. `myTransferFrom` updates the balances for `_from` and `_to` addresses for all `_ids` and `_values`. From 4da1425f391c81316580b003f789428e7f19ac52 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Sun, 26 May 2019 11:46:35 -0400 Subject: [PATCH 43/58] EDT-3069 Minor changes for grammar and consistency. --- EIPS/eip-1155.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 24d5ebefea7fb..fdd33ab39f2fe 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -311,7 +311,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran * The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))` - If the return value is `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))` the transfer MUST be completed or MUST revert if any other conditions are not met for success. * The recipient contract MAY reject an increase of its balance by calling revert. - - If recipient contract throws/reverts the transaction MUST be reverted. + - If the recipient contract throws/reverts the transaction MUST be reverted. * If the return value is anything other than `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))` the transaction MUST be reverted. * `onERC1155Received` (and/or `onERC1155BatchReceived`) MAY be called multiple times in a single transaction and the following requirements must be met: - All callbacks represent mutually exclusive balance changes. @@ -328,7 +328,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran * The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` - If the return value is `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` the transfer MUST be completed or MUST revert if any other conditions are not met for success. * The recipient contract MAY reject an increase of its balance by calling revert. - - If recipient contract throws/reverts the transaction MUST be reverted. + - If the recipient contract throws/reverts the transaction MUST be reverted. * If the return value is anything other than `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` the transaction MUST be reverted. * `onERC1155BatchReceived` (and/or `onERC1155Received`) MAY be called multiple times in a single transaction and the following requirements must be met: - All callbacks represent mutually exclusive balance changes. @@ -381,7 +381,7 @@ Order of operation MUST therefore be: *__Note that a pure implementation of a single standard is recommended__* rather than a hybrid solution, but an example of a hybrid ERC-1155/ERC-721 contract is linked in the references section under implementations. -An important consideration is that even if the tokens are sent with another standard's rules the *__1155 transfer events MUST still be emitted.__* This is so the balances can still be determined via events alone as per ERC-1155 standard rules. +An important consideration is that even if the tokens are sent with another standard's rules the *__ERC-1155 transfer events MUST still be emitted.__* This is so the balances can still be determined via events alone as per ERC-1155 standard rules. ### Metadata From 7a61926fdfcc29f932514ef736457b40e22f9909 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Mon, 27 May 2019 16:09:15 -0400 Subject: [PATCH 44/58] EDT-3069 Slightly strong wording using SHOULD instead of a MAY in the case a receiver didn't explicitly accept. --- EIPS/eip-1155.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index fdd33ab39f2fe..a4248e35367e0 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -353,8 +353,8 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran 3. `myTransferFrom` emits `TransferBatch` with the details of what was transferred from address `_from` to address `_to`. 4. `myTransferFrom` checks if `_to` is a contract address and determines that it is so (if not, then the transfer can be considered successful). 5. `myTransferFrom` calls `onERC1155BatchReceived` on `_to` and it reverts or returns an unknown value (if it had returned `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` the transfer can be considered successful). - 6. At this point `myTransferFrom` MAY decide to revert the transaction immediately as receipt of the token(s) was not explicitly accepted by the `onERC1155BatchReceived` function. - 7. If `myTransferFrom` wishes to continue it MUST call `isERC1155TokenReceiver()` on `_to` and if it returns `bytes4(keccak256("isERC1155TokenReceiver()"))` the transaction MUST be reverted, as it is now known to be a valid receiver and the previous acceptance step failed. + 6. At this point `myTransferFrom` SHOULD revert the transaction immediately as receipt of the token(s) was not explicitly accepted by the `onERC1155BatchReceived` function. + 7. If however `myTransferFrom` wishes to continue it MUST call `isERC1155TokenReceiver()` on `_to` and if it returns `bytes4(keccak256("isERC1155TokenReceiver()"))` the transaction MUST be reverted, as it is now known to be a valid receiver and the previous acceptance step failed. 8. If the above call to `isERC1155TokenReceiver()` on `_to` reverts or returns an unknown value the `myTransferFrom` function MAY consider this transfer successful (__NOTE__: this MAY result in unrecoverable tokens if sent to an address that does not expect to receive ERC-1155 tokens). * The above example is not exhaustive but illustrates the major points (and shows that most are shared with `safeTransferFrom` and `safeBatchTransferFrom`): - Balances that are updated MUST have equivalent transfer events emitted. From a301bc6392797ac61746aa8e17787800942ec4ce Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Tue, 28 May 2019 16:56:22 -0400 Subject: [PATCH 45/58] EDT-3069 Solidity 0.5.9 is latest version (ref impl tested on this version). --- EIPS/eip-1155.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index a4248e35367e0..75a0e1f411ece 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -34,7 +34,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S **Smart contracts implementing the ERC-1155 standard MUST implement the `ERC1155` and `ERC165` interfaces.** ```solidity -pragma solidity ^0.5.8; +pragma solidity ^0.5.9; /** @title ERC-1155 Multi Token Standard @@ -151,7 +151,7 @@ interface ERC1155 /* is ERC165 */ { Smart contracts **MUST** implement this interface to accept transfers. See "Safe Transfer Rules" for further detail. ```solidity -pragma solidity ^0.5.8; +pragma solidity ^0.5.9; /** Note: The ERC-165 identifier for this interface is 0x43b236a2. @@ -398,7 +398,7 @@ The following optional extensions can be identified with the (ERC-165 Standard I Changes to the URI MUST emit the `URI` event if the change can be expressed with an event (i.e. it isn't dynamic). If the optional ERC1155Metadata_URI extension is included, the 'uri' function SHOULD be used to retrieve values for which no event was emitted. The function MUST return the same value as the event if it was emitted. ```solidity -pragma solidity ^0.5.8; +pragma solidity ^0.5.9; /** Note: The ERC-165 identifier for this interface is 0x0e89341c. From 16ad5b13fb239a48f4c90162d450a75560ecbf57 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Fri, 31 May 2019 20:29:57 -0400 Subject: [PATCH 46/58] EDT-3069 Some alteration to the standard as requested along with a section on minting and burning rules. --- EIPS/eip-1155.md | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 75a0e1f411ece..4383f89b8da06 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -148,7 +148,7 @@ interface ERC1155 /* is ERC165 */ { ### ERC-1155 Token Receiver -Smart contracts **MUST** implement this interface to accept transfers. See "Safe Transfer Rules" for further detail. +Smart contracts **MUST** implement all the functions in this interface to accept transfers. See "Safe Transfer Rules" for further detail. ```solidity pragma solidity ^0.5.9; @@ -283,8 +283,8 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran - The `_to` argument MUST be the address of the recipient whose balance is increased. - The `_id` argument MUST be the token type being transferred. - The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. - - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). - - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). + - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). See "Minting/creating and burning/destroying rules". + - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). See "Minting/creating and burning/destroying rules". * `TransferBatch` SHOULD be used to indicate multiple balance transfers have occurred between a `_from` and `_to` pair. - It MAY be emitted with a single element in the list to indicate a singular balance change in the transaction, but note that `TransferSingle` is designed for this to reduce gas consumption. - The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender). @@ -293,9 +293,9 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran - The `_ids` array argument MUST contain the ids of the tokens being transferred. - The `_values` array argument MUST contain the number of token to be transferred for each corresponding entry in `_ids`. - `_ids` and `_values` MUST have the same length. - - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). - - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). -* The total value transferred from address 0x0 minus the total value transferred to 0x0 MAY be used by clients and exchanges to be added to the "circulating supply" for a given token ID. + - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). See "Minting/creating and burning/destroying rules". + - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). See "Minting/creating and burning/destroying rules". +* The total value transferred from address `0x0` minus the total value transferred to `0x0` observed via the `TransferSingle` and `TransferBatch` events MAY be used by clients and exchanges to determine to the "circulating supply" for a given token ID. * To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the `TransferSingle` event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0. * All `TransferSingle` and `TransferBatch` events MUST be emitted to reflect all the balance changes that have occurred before any call(s) to `onERC1155Received` or `onERC1155BatchReceived`. - To make sure event order is correct in the case of valid re-entry (e.g. if a receiver contract forwards tokens on receipt) state balance and events balance MUST match before calling an external contract. @@ -354,7 +354,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran 4. `myTransferFrom` checks if `_to` is a contract address and determines that it is so (if not, then the transfer can be considered successful). 5. `myTransferFrom` calls `onERC1155BatchReceived` on `_to` and it reverts or returns an unknown value (if it had returned `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` the transfer can be considered successful). 6. At this point `myTransferFrom` SHOULD revert the transaction immediately as receipt of the token(s) was not explicitly accepted by the `onERC1155BatchReceived` function. - 7. If however `myTransferFrom` wishes to continue it MUST call `isERC1155TokenReceiver()` on `_to` and if it returns `bytes4(keccak256("isERC1155TokenReceiver()"))` the transaction MUST be reverted, as it is now known to be a valid receiver and the previous acceptance step failed. + 7. If however `myTransferFrom` wishes to continue it MUST call `isERC1155TokenReceiver()` on `_to` and if it returns `bytes4(keccak256("isERC1155TokenReceiver()"))` the transaction MUST be reverted, as it is now known to be a valid receiver and the previous acceptance step failed. NOTE: You could have called `isERC1155TokenReceiver()` at a previous step if you wanted to gather and act upon that information earlier. 8. If the above call to `isERC1155TokenReceiver()` on `_to` reverts or returns an unknown value the `myTransferFrom` function MAY consider this transfer successful (__NOTE__: this MAY result in unrecoverable tokens if sent to an address that does not expect to receive ERC-1155 tokens). * The above example is not exhaustive but illustrates the major points (and shows that most are shared with `safeTransferFrom` and `safeBatchTransferFrom`): - Balances that are updated MUST have equivalent transfer events emitted. @@ -363,6 +363,18 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran - The return values of the `ERC1155TokenReceiver` hook functions that are called MUST be respected if they are implemented. - Only non-standard transfer functions MAY allow tokens to be sent to a recipient contract that does NOT implement the necessary `ERC1155TokenReceiver` hook functions. `safeTransferFrom` and `safeBatchTransferFrom` MUST revert in that case (unless it is a hybrid standards implementation see "Compatibility with other standards"). +**_Minting/creating and burning/destroying rules:_** +* A mint/create operation is essentially a specialized transfer and MUST follow these rules: + - To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the `TransferSingle` event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0. + - The "TransferSingle and TransferBatch event rules" MUST be followed as appropriate for the mint(s) (i.e. singles or batches) however the `_from` argument MUST be set to `0x0` (i.e. zero address) to flag the transfer as a mint to contract observers. + - __NOTE:__ This includes tokens that are given an initial balance in the contract. This balance of the contract MUST also be able to be determined by events alone meaning initial contract balances (for eg. in construction) MUST emit events to reflect those balances too. +* A burn/destroy operation is essentially a specialized transfer and MUST follow these rules: + - The "TransferSingle and TransferBatch event rules" MUST be followed as appropriate for the burn(s) (i.e. singles or batches) however the `_to` argument MUST be set to `0x0` (i.e. zero address) to flag the transfer as a burn to contract observers. + - NOTE: When burning/destroying you do not have to actually transfer to `0x0` (that is impl specific), only the `_to` argument in the event MUST be set to `0x0` as above. +* The total value transferred from address `0x0` minus the total value transferred to `0x0` observed via the `TransferSingle` and `TransferBatch` events MAY be used by clients and exchanges to determine to the "circulating supply" for a given token ID. + + + ###### A solidity example of the keccak256 generated constants for the return magic is: - bytes4 constant public ERC1155_ACCEPTED = 0xf23a6e61; // bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")) From eb1207bd9a34d95ee6b3852987c931101fa60d6f Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Mon, 3 Jun 2019 14:59:20 -0400 Subject: [PATCH 47/58] EDT-3069 Minor grammar fix. --- EIPS/eip-1155.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 4383f89b8da06..45adfeeed157b 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -295,7 +295,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran - `_ids` and `_values` MUST have the same length. - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). See "Minting/creating and burning/destroying rules". - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). See "Minting/creating and burning/destroying rules". -* The total value transferred from address `0x0` minus the total value transferred to `0x0` observed via the `TransferSingle` and `TransferBatch` events MAY be used by clients and exchanges to determine to the "circulating supply" for a given token ID. +* The total value transferred from address `0x0` minus the total value transferred to `0x0` observed via the `TransferSingle` and `TransferBatch` events MAY be used by clients and exchanges to determine the "circulating supply" for a given token ID. * To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the `TransferSingle` event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0. * All `TransferSingle` and `TransferBatch` events MUST be emitted to reflect all the balance changes that have occurred before any call(s) to `onERC1155Received` or `onERC1155BatchReceived`. - To make sure event order is correct in the case of valid re-entry (e.g. if a receiver contract forwards tokens on receipt) state balance and events balance MUST match before calling an external contract. @@ -371,7 +371,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran * A burn/destroy operation is essentially a specialized transfer and MUST follow these rules: - The "TransferSingle and TransferBatch event rules" MUST be followed as appropriate for the burn(s) (i.e. singles or batches) however the `_to` argument MUST be set to `0x0` (i.e. zero address) to flag the transfer as a burn to contract observers. - NOTE: When burning/destroying you do not have to actually transfer to `0x0` (that is impl specific), only the `_to` argument in the event MUST be set to `0x0` as above. -* The total value transferred from address `0x0` minus the total value transferred to `0x0` observed via the `TransferSingle` and `TransferBatch` events MAY be used by clients and exchanges to determine to the "circulating supply" for a given token ID. +* The total value transferred from address `0x0` minus the total value transferred to `0x0` observed via the `TransferSingle` and `TransferBatch` events MAY be used by clients and exchanges to determine the "circulating supply" for a given token ID. From 219d72aa464711b61051cadb6e895de1b61375a8 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Tue, 4 Jun 2019 09:10:50 -0400 Subject: [PATCH 48/58] EDT-3069 Add in mention that mint/burn is a custom transfer so follows that rule set and that skipping hook calls is fine if the destination is the minting/transferring contract itself. --- EIPS/eip-1155.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 45adfeeed157b..98bf6687c7dea 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -316,6 +316,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran * `onERC1155Received` (and/or `onERC1155BatchReceived`) MAY be called multiple times in a single transaction and the following requirements must be met: - All callbacks represent mutually exclusive balance changes. - The set of all calls to `onERC1155Received` and `onERC1155BatchReceived` describes all balance changes that occurred during the transaction in the order submitted. +* A contract MAY skip calling the `onERC1155Received` hook function if the transfer operation is transferring the token to itself. **_onERC1155BatchReceived rules:_** - The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender). @@ -333,6 +334,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran * `onERC1155BatchReceived` (and/or `onERC1155Received`) MAY be called multiple times in a single transaction and the following requirements must be met: - All callbacks represent mutually exclusive balance changes. - The set of all calls to `onERC1155Received` and `onERC1155BatchReceived` describes all balance changes that occurred during the transaction in the order submitted. +* A contract MAY skip calling the `onERC1155BatchReceived` hook function if the transfer operation is transferring the token(s) to itself. **_isERC1155TokenReceiver rules:_** * The implementation of `isERC1155TokenReceiver` function SHOULD be as follows: @@ -354,8 +356,10 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran 4. `myTransferFrom` checks if `_to` is a contract address and determines that it is so (if not, then the transfer can be considered successful). 5. `myTransferFrom` calls `onERC1155BatchReceived` on `_to` and it reverts or returns an unknown value (if it had returned `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` the transfer can be considered successful). 6. At this point `myTransferFrom` SHOULD revert the transaction immediately as receipt of the token(s) was not explicitly accepted by the `onERC1155BatchReceived` function. - 7. If however `myTransferFrom` wishes to continue it MUST call `isERC1155TokenReceiver()` on `_to` and if it returns `bytes4(keccak256("isERC1155TokenReceiver()"))` the transaction MUST be reverted, as it is now known to be a valid receiver and the previous acceptance step failed. NOTE: You could have called `isERC1155TokenReceiver()` at a previous step if you wanted to gather and act upon that information earlier. - 8. If the above call to `isERC1155TokenReceiver()` on `_to` reverts or returns an unknown value the `myTransferFrom` function MAY consider this transfer successful (__NOTE__: this MAY result in unrecoverable tokens if sent to an address that does not expect to receive ERC-1155 tokens). + 7. If however `myTransferFrom` wishes to continue it MUST call `isERC1155TokenReceiver()` on `_to` and if it returns `bytes4(keccak256("isERC1155TokenReceiver()"))` the transaction MUST be reverted, as it is now known to be a valid receiver and the previous acceptance step failed. + - NOTE: You could have called `isERC1155TokenReceiver()` at a previous step if you wanted to gather and act upon that information earlier, such as in a hybrid standards scenario. + 8. If the above call to `isERC1155TokenReceiver()` on `_to` reverts or returns an unknown value the `myTransferFrom` function MAY consider this transfer successful. + - __NOTE__: this MAY result in unrecoverable tokens if sent to an address that does not expect to receive ERC-1155 tokens. * The above example is not exhaustive but illustrates the major points (and shows that most are shared with `safeTransferFrom` and `safeBatchTransferFrom`): - Balances that are updated MUST have equivalent transfer events emitted. - A receiver address has to be checked if it is a contract and if so relevant `ERC1155TokenReceiver` hook function(s) have to be called on it. @@ -367,13 +371,15 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran * A mint/create operation is essentially a specialized transfer and MUST follow these rules: - To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the `TransferSingle` event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0. - The "TransferSingle and TransferBatch event rules" MUST be followed as appropriate for the mint(s) (i.e. singles or batches) however the `_from` argument MUST be set to `0x0` (i.e. zero address) to flag the transfer as a mint to contract observers. - - __NOTE:__ This includes tokens that are given an initial balance in the contract. This balance of the contract MUST also be able to be determined by events alone meaning initial contract balances (for eg. in construction) MUST emit events to reflect those balances too. + - __NOTE:__ This includes tokens that are given an initial balance in the contract. The balance of the contract MUST also be able to be determined by events alone meaning initial contract balances (for eg. in construction) MUST emit events to reflect those balances too. + * A burn/destroy operation is essentially a specialized transfer and MUST follow these rules: - The "TransferSingle and TransferBatch event rules" MUST be followed as appropriate for the burn(s) (i.e. singles or batches) however the `_to` argument MUST be set to `0x0` (i.e. zero address) to flag the transfer as a burn to contract observers. - NOTE: When burning/destroying you do not have to actually transfer to `0x0` (that is impl specific), only the `_to` argument in the event MUST be set to `0x0` as above. * The total value transferred from address `0x0` minus the total value transferred to `0x0` observed via the `TransferSingle` and `TransferBatch` events MAY be used by clients and exchanges to determine the "circulating supply" for a given token ID. - - +* As mentioned above mint/create and burn/destroy operations are specialized transfers and so will likely be accomplished with a custom transfer functions rather than `safeTransferFrom` or `safeBatchTransferFrom`. If so the "Implementation specific transfer API rules" section would be appropriate. + - Even in a non-safe API and/or hybrid standards case the above event rules MUST still be adhered to when minting/creating or burning/destroying. +* A contract MAY skip calling the `ERC1155TokenReceiver` hook function(s) if the mint/create operation is transferring the token(s) to itself. In all other cases the `ERC1155TokenReceiver` rules MUST be followed as appropriate for the implementation (i.e. safe, custom and/or hybrid). ###### A solidity example of the keccak256 generated constants for the return magic is: From e57d7578f1c48e604cf6a24d0b224edd6d089b0c Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Tue, 4 Jun 2019 11:48:35 -0400 Subject: [PATCH 49/58] EDT-3069 Add in recommendation for wallets etc. to sort their batch transfers by ascending ID order when posting (including reference to Horizon's packed balance example) and add in a little formatting and consistency to the URI rules. --- EIPS/eip-1155.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 98bf6687c7dea..ccc075acb7355 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -404,10 +404,12 @@ An important consideration is that even if the tokens are sent with another stan ### Metadata -The URI value allows for ID substitution by clients. If the string `{id}` exists in any URI, clients MUST replace this with the actual token ID in hexadecimal form. This allows for large number of tokens to use the same on-chain string by defining a URI once, for a large collection of tokens. Example of such a URI: `https://token-cdn-domain/{id}.json` would be replaced with `https://token-cdn-domain/000000000000000000000000000000000000000000000000000000000004cce0.json` if the client is referring to token ID 314592/0x4CCE0. +The URI value allows for ID substitution by clients. If the string `{id}` exists in any URI, clients MUST replace this with the actual token ID in hexadecimal form. This allows for large number of tokens to use the same on-chain string by defining a URI once, for a large collection of tokens. -The string format of the substituted hexadecimal ID MUST be lowercase alphanumeric: `[0-9a-f]` with no 0x prefix. -The string format of the substituted hexadecimal ID MUST be leading zero padded to 64 hex characters length if necessary. +* The string format of the substituted hexadecimal ID MUST be lowercase alphanumeric: `[0-9a-f]` with no 0x prefix. +* The string format of the substituted hexadecimal ID MUST be leading zero padded to 64 hex characters length if necessary. + +Example of such a URI: `https://token-cdn-domain/{id}.json` would be replaced with `https://token-cdn-domain/000000000000000000000000000000000000000000000000000000000004cce0.json` if the client is referring to token ID 314592/0x4CCE0. #### Metadata Extensions @@ -436,7 +438,8 @@ interface ERC1155Metadata_URI { This JSON schema is loosely based on the "ERC721 Metadata JSON Schema", but includes optional formatting to allow for ID substitution by clients. If the string `{id}` exists in any JSON value, it MUST be replaced with the actual token ID, by all client software that follows this standard. -The string format of the substituted hexadecimal ID MUST be lowercase alphanumeric: `[0-9a-f]` with no 0x prefix. +* The string format of the substituted hexadecimal ID MUST be lowercase alphanumeric: `[0-9a-f]` with no 0x prefix. +* The string format of the substituted hexadecimal ID MUST be leading zero padded to 64 hex characters length if necessary. ```json { @@ -623,13 +626,15 @@ This standard can be used to represent multiple token types for an entire domain ### Batch Transfers -The `safeBatchTransferFrom` function allows for batch transfers of multiple token ids and values. The design of ERC-1155 makes batch transfers possible without the need for a wrapper contract, as with existing token standards. This reduces gas costs when more than one token type is included in a batch transfer, as compared to single transfers with multiple transactions. +The `safeBatchTransferFrom` function allows for batch transfers of multiple token IDs and values. The design of ERC-1155 makes batch transfers possible without the need for a wrapper contract, as with existing token standards. This reduces gas costs when more than one token type is included in a batch transfer, as compared to single transfers with multiple transactions. Another advantage of standardized batch transfers is the ability for a smart contract to respond to the batch transfer in a single operation using `onERC1155BatchReceived`. +It is RECOMMENDED that clients and wallets sort the token IDs and associated values (in ascending order) when posting a batch transfer, as some ERC-1155 implementations offer significant gas cost savings when IDs are sorted. See [Horizon Games - Multi-Token Standard](https://github.com/horizon-games/multi-token-standard) "packed balance" implementation for an example of this. + ### Batch Balance -The `balanceOfBatch` function allows clients to retrieve balances of multiple owners and token ids with a single call. +The `balanceOfBatch` function allows clients to retrieve balances of multiple owners and token IDs with a single call. ### Enumerating from events From 8390de7bd1d9d4588d72c0eaf4d5fbc69bc3c493 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Tue, 4 Jun 2019 14:15:56 -0400 Subject: [PATCH 50/58] EDT-3069 More minor grammar and formatting fixes. --- EIPS/eip-1155.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 56ed85b5ed34c..4add4994e8524 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -371,13 +371,12 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran * A mint/create operation is essentially a specialized transfer and MUST follow these rules: - To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the `TransferSingle` event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0. - The "TransferSingle and TransferBatch event rules" MUST be followed as appropriate for the mint(s) (i.e. singles or batches) however the `_from` argument MUST be set to `0x0` (i.e. zero address) to flag the transfer as a mint to contract observers. - - __NOTE:__ This includes tokens that are given an initial balance in the contract. The balance of the contract MUST also be able to be determined by events alone meaning initial contract balances (for eg. in construction) MUST emit events to reflect those balances too. - + - __NOTE:__ This includes tokens that are given an initial balance in the contract. The balance of the contract MUST also be able to be determined by events alone meaning initial contract balances (for eg. in construction) MUST emit events to reflect those balances too. * A burn/destroy operation is essentially a specialized transfer and MUST follow these rules: - The "TransferSingle and TransferBatch event rules" MUST be followed as appropriate for the burn(s) (i.e. singles or batches) however the `_to` argument MUST be set to `0x0` (i.e. zero address) to flag the transfer as a burn to contract observers. - - NOTE: When burning/destroying you do not have to actually transfer to `0x0` (that is impl specific), only the `_to` argument in the event MUST be set to `0x0` as above. + - When burning/destroying you do not have to actually transfer to `0x0` (that is impl specific), only the `_to` argument in the event MUST be set to `0x0` as above. * The total value transferred from address `0x0` minus the total value transferred to `0x0` observed via the `TransferSingle` and `TransferBatch` events MAY be used by clients and exchanges to determine the "circulating supply" for a given token ID. -* As mentioned above mint/create and burn/destroy operations are specialized transfers and so will likely be accomplished with a custom transfer functions rather than `safeTransferFrom` or `safeBatchTransferFrom`. If so the "Implementation specific transfer API rules" section would be appropriate. +* As mentioned above mint/create and burn/destroy operations are specialized transfers and so will likely be accomplished with custom transfer functions rather than `safeTransferFrom` or `safeBatchTransferFrom`. If so the "Implementation specific transfer API rules" section would be appropriate. - Even in a non-safe API and/or hybrid standards case the above event rules MUST still be adhered to when minting/creating or burning/destroying. * A contract MAY skip calling the `ERC1155TokenReceiver` hook function(s) if the mint/create operation is transferring the token(s) to itself. In all other cases the `ERC1155TokenReceiver` rules MUST be followed as appropriate for the implementation (i.e. safe, custom and/or hybrid). From 93cc841c1c4b6e233a9eaa6c65a1e90ef997186a Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Wed, 5 Jun 2019 16:44:40 -0400 Subject: [PATCH 51/58] DT-3069 Consistent use of MUST in uri event and function. --- EIPS/eip-1155.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 4add4994e8524..977c9f48c5c5b 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -74,7 +74,7 @@ interface ERC1155 /* is ERC165 */ { /** @dev MUST emit when the URI is updated for a token ID. URIs are defined in RFC 3986. - The URI MUST point a JSON file that conforms to the "ERC-1155 Metadata URI JSON Schema". + The URI MUST point to a JSON file that conforms to the "ERC-1155 Metadata URI JSON Schema". */ event URI(string _value, uint256 indexed _id); @@ -414,7 +414,7 @@ Example of such a URI: `https://token-cdn-domain/{id}.json` would be replaced wi The following optional extensions can be identified with the (ERC-165 Standard Interface Detection)[https://eips.ethereum.org/EIPS/eip-165]. -Changes to the URI MUST emit the `URI` event if the change can be expressed with an event (i.e. it isn't dynamic). If the optional ERC1155Metadata_URI extension is included, the 'uri' function SHOULD be used to retrieve values for which no event was emitted. The function MUST return the same value as the event if it was emitted. +Changes to the URI MUST emit the `URI` event if the change can be expressed with an event (i.e. it isn't dynamic). If the optional ERC1155Metadata_URI extension is included, the `uri` function SHOULD be used to retrieve values for which no event was emitted. The function MUST return the same value as the event if it was emitted. ```solidity pragma solidity ^0.5.9; @@ -426,7 +426,7 @@ interface ERC1155Metadata_URI { /** @notice A distinct Uniform Resource Identifier (URI) for a given token. @dev URIs are defined in RFC 3986. - The URI may point to a JSON file that conforms to the "ERC-1155 Metadata URI JSON Schema". + The URI MUST point to a JSON file that conforms to the "ERC-1155 Metadata URI JSON Schema". @return URI string */ function uri(uint256 _id) external view returns (string memory); From 4f21e3865b5ce1f36b847d9be2e349847bb001d6 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Thu, 6 Jun 2019 19:09:10 -0400 Subject: [PATCH 52/58] EDT-3069 Replace isERCTokenReceiver with usage of ERC165 supportsInterface. --- EIPS/eip-1155.md | 57 ++++++++++++++++++++++++------------------------ 1 file changed, 29 insertions(+), 28 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 977c9f48c5c5b..bcd0d0ae66e35 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -149,12 +149,13 @@ interface ERC1155 /* is ERC165 */ { ### ERC-1155 Token Receiver Smart contracts **MUST** implement all the functions in this interface to accept transfers. See "Safe Transfer Rules" for further detail. +Smart contracts **MUST** implement the ERC-165 `supportsInterface` function and signify support for this interface. See "ERC1155TokenReceiver ERC-165 rules" for further detail. ```solidity pragma solidity ^0.5.9; /** - Note: The ERC-165 identifier for this interface is 0x43b236a2. + Note: The ERC-165 identifier for this interface is 0x4e2312e0. */ interface ERC1155TokenReceiver { /** @@ -185,15 +186,7 @@ interface ERC1155TokenReceiver { @param _data Additional data with no specified format @return `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` */ - function onERC1155BatchReceived(address _operator, address _from, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external returns(bytes4); - - /** - @notice Indicates whether a contract implements the `ERC1155TokenReceiver` functions and so can accept ERC1155 token types. - @dev This function MUST return `bytes4(keccak256("isERC1155TokenReceiver()"))` (i.e. 0x0d912442). - This function MUST NOT consume more than 5,000 gas. - @return `bytes4(keccak256("isERC1155TokenReceiver()"))` - */ - function isERC1155TokenReceiver() external view returns (bytes4); + function onERC1155BatchReceived(address _operator, address _from, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external returns(bytes4); } ``` @@ -336,16 +329,19 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran - The set of all calls to `onERC1155Received` and `onERC1155BatchReceived` describes all balance changes that occurred during the transaction in the order submitted. * A contract MAY skip calling the `onERC1155BatchReceived` hook function if the transfer operation is transferring the token(s) to itself. -**_isERC1155TokenReceiver rules:_** -* The implementation of `isERC1155TokenReceiver` function SHOULD be as follows: - ``` - function isERC1155TokenReceiver() external view returns (bytes4) { - return 0x0d912442; // bytes4(keccak256("isERC1155TokenReceiver()")) +**_ERC1155TokenReceiver ERC-165 rules:_** +* The implementation of the ERC-165 `supportsInterface` function SHOULD be as follows: + ``` + function supportsInterface(bytes4 interfaceID) external view returns (bool) { + return interfaceID == 0x01ffc9a7 || // ERC-165 support (i.e. `bytes4(keccak256('supportsInterface(bytes4)'))`). + interfaceID == 0x4e2312e0; // ERC-1155 `ERC1155TokenReceiver` support (i.e. `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")) ^ bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))`). } - ``` + ``` * The implementation MAY differ from the above but: - - It MUST return the same value. - - It MUST NOT consume more than 5,000 gas. + - It MUST return the constant value `true` if `0x01ffc9a7` is passed through the `interfaceID` argument. This signifies ERC-165 support. + - It MUST return the constant value `true` if `0x4e2312e0` is passed through the `interfaceID` argument. This signifies ERC-1155 `ERC1155TokenReceiver` support. + - It MUST NOT consume more than 10,000 gas. + - This keeps it below the ERC-165 requirement of 30,000 gas, reduces the gas reserve needs and minimises possible side-effects of gas exhaustion during the call. **_Implementation specific transfer API rules:_** * If an implementation specific API function is used to transfer ERC-1155 token(s) to a contract, the `safeTransferFrom` or `safeBatchTransferFrom` (as appropriate) rules MUST still be followed if the receiver implements the `ERC1155TokenReceiver` interface. If it does not the non-standard implementation SHOULD revert but MAY proceed. @@ -356,9 +352,9 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran 4. `myTransferFrom` checks if `_to` is a contract address and determines that it is so (if not, then the transfer can be considered successful). 5. `myTransferFrom` calls `onERC1155BatchReceived` on `_to` and it reverts or returns an unknown value (if it had returned `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` the transfer can be considered successful). 6. At this point `myTransferFrom` SHOULD revert the transaction immediately as receipt of the token(s) was not explicitly accepted by the `onERC1155BatchReceived` function. - 7. If however `myTransferFrom` wishes to continue it MUST call `isERC1155TokenReceiver()` on `_to` and if it returns `bytes4(keccak256("isERC1155TokenReceiver()"))` the transaction MUST be reverted, as it is now known to be a valid receiver and the previous acceptance step failed. - - NOTE: You could have called `isERC1155TokenReceiver()` at a previous step if you wanted to gather and act upon that information earlier, such as in a hybrid standards scenario. - 8. If the above call to `isERC1155TokenReceiver()` on `_to` reverts or returns an unknown value the `myTransferFrom` function MAY consider this transfer successful. + 7. If however `myTransferFrom` wishes to continue it MUST call `supportsInterface(0x4e2312e0)` on `_to` and if it returns the constant value `true` the transaction MUST be reverted, as it is now known to be a valid receiver and the previous acceptance step failed. + - NOTE: You could have called `supportsInterface(0x4e2312e0)` at a previous step if you wanted to gather and act upon that information earlier, such as in a hybrid standards scenario. + 8. If the above call to `supportsInterface(0x4e2312e0)` on `_to` reverts or returns a value other than the constant value `true` the `myTransferFrom` function MAY consider this transfer successful. - __NOTE__: this MAY result in unrecoverable tokens if sent to an address that does not expect to receive ERC-1155 tokens. * The above example is not exhaustive but illustrates the major points (and shows that most are shared with `safeTransferFrom` and `safeBatchTransferFrom`): - Balances that are updated MUST have equivalent transfer events emitted. @@ -381,20 +377,25 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran * A contract MAY skip calling the `ERC1155TokenReceiver` hook function(s) if the mint/create operation is transferring the token(s) to itself. In all other cases the `ERC1155TokenReceiver` rules MUST be followed as appropriate for the implementation (i.e. safe, custom and/or hybrid). -###### A solidity example of the keccak256 generated constants for the return magic is: - - bytes4 constant public ERC1155_ACCEPTED = 0xf23a6e61; // bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")) - - bytes4 constant public ERC1155_BATCH_ACCEPTED = 0xbc197c81; // bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)")) +##### A solidity example of the keccak256 generated constants for the various magic values (these MAY be used by implementation): + +``` +bytes4 constant public ERC1155_ERC165 = 0xd9b67a26; // ERC-165 identifier for the main token standard. +bytes4 constant public ERC1155_ERC165_TOKENRECEIVER = 0x4e2312e0; // ERC-165 identifier for the `ERC1155TokenReceiver` support (i.e. `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")) ^ bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))`). +bytes4 constant public ERC1155_ACCEPTED = 0xf23a6e61; // Return value from `onERC1155Received` call if a contract accepts receipt (i.e `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))`). +bytes4 constant public ERC1155_BATCH_ACCEPTED = 0xbc197c81; // Return value from `onERC1155BatchReceived` call if a contract accepts receipt (i.e `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))`). +``` #### Compatibility with other standards There have been requirements during the design discussions to have this standard be compatible with existing standards when sending to contract addresses, specifically ERC-721 at time of writing. -To cater for this scenario, there is some leeway with the rejection logic should a contract not implement the `ERC1155TokenReceiver` as per "Safe Transfer Rules" section above, specifically "Scenario#3 : The receiver does not implement the necessary `ERC1155TokenReceiver` interface function(s)". +To cater for this scenario, there is some leeway with the revert logic should a contract not implement the `ERC1155TokenReceiver` as per "Safe Transfer Rules" section above, specifically "Scenario#3 : The receiver does not implement the necessary `ERC1155TokenReceiver` interface function(s)". Hence in a hybrid ERC-1155 contract implementation an extra call MUST be made on the recipient contract and checked before any hook calls to `onERC1155Received` or `onERC1155BatchReceived` are made. Order of operation MUST therefore be: -1. The implementation MUST call the function `isERC1155TokenReceiver` on the recipient contract, providing at least 5,000 gas. -2. If the function call succeeds and the return value is `bytes4(keccak256("isERC1155TokenReceiver()"))` the implementation proceeds as a regular ERC-1155 implementation, with the call(s) to the `onERC1155Received` or `onERC1155BatchReceived` hooks and rules associated. -3. If the function call fails or the return value is NOT `bytes4(keccak256("isERC1155TokenReceiver()"))` the implementation can assume the recipient contract is not an `ERC1155TokenReceiver` and follow its other standard's rules for transfers. +1. The implementation MUST call the function `supportsInterface(0x4e2312e0)` on the recipient contract, providing at least 10,000 gas. +2. If the function call succeeds and the return value is the constant value `true` the implementation proceeds as a regular ERC-1155 implementation, with the call(s) to the `onERC1155Received` or `onERC1155BatchReceived` hooks and rules associated. +3. If the function call fails or the return value is NOT the constant value `true` the implementation can assume the recipient contract is not an `ERC1155TokenReceiver` and follow its other standard's rules for transfers. *__Note that a pure implementation of a single standard is recommended__* rather than a hybrid solution, but an example of a hybrid ERC-1155/ERC-721 contract is linked in the references section under implementations. From 463d6b27c7c96c5acd5f0799dd90a92ca4602eb4 Mon Sep 17 00:00:00 2001 From: Andrew Cooke Date: Fri, 7 Jun 2019 05:51:24 -0400 Subject: [PATCH 53/58] URI event clarification --- EIPS/eip-1155.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index bcd0d0ae66e35..24c76699e7101 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -417,6 +417,8 @@ The following optional extensions can be identified with the (ERC-165 Standard I Changes to the URI MUST emit the `URI` event if the change can be expressed with an event (i.e. it isn't dynamic). If the optional ERC1155Metadata_URI extension is included, the `uri` function SHOULD be used to retrieve values for which no event was emitted. The function MUST return the same value as the event if it was emitted. +Note that if this extension is enabled: if the URI event is to be used for metadata uri's changes, it does not need to be emitted first at Mint time. Observer can fetch the metadata uri at mint time from the `uri` function. + ```solidity pragma solidity ^0.5.9; From 0a255c5cfc0878fe2b99235dfeb96b049a4c78d0 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Fri, 7 Jun 2019 07:04:40 -0400 Subject: [PATCH 54/58] EDT-3069 Altered Metadata Extension rules to be clear about the ERC-165 usage and the fact that URI events are for changes and not mandatory to output on a mint operation (if the ERC1155Metadata_URI interface is included). --- EIPS/eip-1155.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 24c76699e7101..e79c4d07fd11d 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -31,7 +31,8 @@ New functionality is possible with this design, such as transferring multiple to The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. -**Smart contracts implementing the ERC-1155 standard MUST implement the `ERC1155` and `ERC165` interfaces.** +**Smart contracts implementing the ERC-1155 standard MUST implement all of the functions in the `ERC1155` interface.** +**Smart contracts implementing the ERC-1155 standard MUST implement the ERC-165 `supportsInterface` function and MUST return the constant value `true` if `0xd9b67a26` is passed through the `interfaceID` argument.** ```solidity pragma solidity ^0.5.9; @@ -148,8 +149,8 @@ interface ERC1155 /* is ERC165 */ { ### ERC-1155 Token Receiver -Smart contracts **MUST** implement all the functions in this interface to accept transfers. See "Safe Transfer Rules" for further detail. -Smart contracts **MUST** implement the ERC-165 `supportsInterface` function and signify support for this interface. See "ERC1155TokenReceiver ERC-165 rules" for further detail. +**Smart contracts MUST implement all of the functions in the `ERC1155TokenReceiver` interface to accept transfers. See "Safe Transfer Rules" for further detail.** +**Smart contracts MUST implement the ERC-165 `supportsInterface` function and signify support for the `ERC1155TokenReceiver` interface to accept transfers. See "ERC1155TokenReceiver ERC-165 rules" for further detail.** ```solidity pragma solidity ^0.5.9; @@ -413,11 +414,14 @@ Example of such a URI: `https://token-cdn-domain/{id}.json` would be replaced wi #### Metadata Extensions -The following optional extensions can be identified with the (ERC-165 Standard Interface Detection)[https://eips.ethereum.org/EIPS/eip-165]. +The optional `ERC1155Metadata_URI` extension can be identified with the (ERC-165 Standard Interface Detection)[https://eips.ethereum.org/EIPS/eip-165]. -Changes to the URI MUST emit the `URI` event if the change can be expressed with an event (i.e. it isn't dynamic). If the optional ERC1155Metadata_URI extension is included, the `uri` function SHOULD be used to retrieve values for which no event was emitted. The function MUST return the same value as the event if it was emitted. - -Note that if this extension is enabled: if the URI event is to be used for metadata uri's changes, it does not need to be emitted first at Mint time. Observer can fetch the metadata uri at mint time from the `uri` function. +If the optional `ERC1155Metadata_URI` extension is included: +* The ERC-165 `supportsInterface` function MUST return the constant value `true` if `0x0e89341c` is passed through the `interfaceID` argument. +* _Changes_ to the URI MUST emit the `URI` event if the change can be expressed with an event (i.e. it isn't dynamic/programmatic). + - An implementation MAY emit the `URI` event during a mint operation but it is NOT mandatory. An observer MAY fetch the metadata uri at mint time from the `uri` function if it was not emitted. +* The `uri` function SHOULD be used to retrieve values if no event was emitted. +* The `uri` function MUST return the same value as the latest event for an `_id` if it was emitted. ```solidity pragma solidity ^0.5.9; From 4ef46878af3bc6e27a438e6657e9aa90be259c11 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Fri, 7 Jun 2019 07:42:57 -0400 Subject: [PATCH 55/58] DT-3069 Some minor changes for github formatting. --- EIPS/eip-1155.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index e79c4d07fd11d..b12fb2c853ca5 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -32,6 +32,7 @@ New functionality is possible with this design, such as transferring multiple to The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. **Smart contracts implementing the ERC-1155 standard MUST implement all of the functions in the `ERC1155` interface.** + **Smart contracts implementing the ERC-1155 standard MUST implement the ERC-165 `supportsInterface` function and MUST return the constant value `true` if `0xd9b67a26` is passed through the `interfaceID` argument.** ```solidity @@ -150,6 +151,7 @@ interface ERC1155 /* is ERC165 */ { ### ERC-1155 Token Receiver **Smart contracts MUST implement all of the functions in the `ERC1155TokenReceiver` interface to accept transfers. See "Safe Transfer Rules" for further detail.** + **Smart contracts MUST implement the ERC-165 `supportsInterface` function and signify support for the `ERC1155TokenReceiver` interface to accept transfers. See "ERC1155TokenReceiver ERC-165 rules" for further detail.** ```solidity @@ -332,12 +334,12 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran **_ERC1155TokenReceiver ERC-165 rules:_** * The implementation of the ERC-165 `supportsInterface` function SHOULD be as follows: - ``` + ```solidity function supportsInterface(bytes4 interfaceID) external view returns (bool) { return interfaceID == 0x01ffc9a7 || // ERC-165 support (i.e. `bytes4(keccak256('supportsInterface(bytes4)'))`). interfaceID == 0x4e2312e0; // ERC-1155 `ERC1155TokenReceiver` support (i.e. `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")) ^ bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))`). } - ``` + ``` * The implementation MAY differ from the above but: - It MUST return the constant value `true` if `0x01ffc9a7` is passed through the `interfaceID` argument. This signifies ERC-165 support. - It MUST return the constant value `true` if `0x4e2312e0` is passed through the `interfaceID` argument. This signifies ERC-1155 `ERC1155TokenReceiver` support. @@ -380,7 +382,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran ##### A solidity example of the keccak256 generated constants for the various magic values (these MAY be used by implementation): -``` +```solidity bytes4 constant public ERC1155_ERC165 = 0xd9b67a26; // ERC-165 identifier for the main token standard. bytes4 constant public ERC1155_ERC165_TOKENRECEIVER = 0x4e2312e0; // ERC-165 identifier for the `ERC1155TokenReceiver` support (i.e. `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")) ^ bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))`). bytes4 constant public ERC1155_ACCEPTED = 0xf23a6e61; // Return value from `onERC1155Received` call if a contract accepts receipt (i.e `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))`). From dee01f78226c7f7dc9b9d5409134b5c4c78e146f Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Tue, 11 Jun 2019 17:52:06 -0400 Subject: [PATCH 56/58] EDT-3069 Very minor clarification. --- EIPS/eip-1155.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index b12fb2c853ca5..bde3ebf4b79fb 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -648,7 +648,7 @@ The `balanceOfBatch` function allows clients to retrieve balances of multiple ow In order to keep storage requirements light for contracts implementing ERC-1155, enumeration (discovering the IDs and values of tokens) must be done using event logs. It is RECOMMENDED that clients such as exchanges and blockchain explorers maintain a local database containing the token ID, Supply, and URI at the minimum. This can be built from each TransferSingle, TransferBatch, and URI event, starting from the block the smart contract was deployed until the latest block. -ERC-1155 contracts must therefore carefully emit `TransferSingle` or `TransferBatch` events in any instance where tokens are created, minted, or destroyed. +ERC-1155 contracts must therefore carefully emit `TransferSingle` or `TransferBatch` events in any instance where tokens are created, minted, transferred or destroyed. ### Non-Fungible Tokens From b3d9945f2c63b279a77c450dd99d6e6b293ae91d Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Tue, 11 Jun 2019 22:28:08 -0400 Subject: [PATCH 57/58] EDT-3069 consistent use of "non-fungible" rather than mixing in "Non-Fungible". --- EIPS/eip-1155.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index bde3ebf4b79fb..8c092c7aa2460 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -13,19 +13,19 @@ requires: 165 ## Simple Summary -A standard interface for contracts that manage multiple token types. A single deployed contract may include any combination of fungible tokens, non-fungible tokens, or other configurations (e.g. semi-fungible tokens). +A standard interface for contracts that manage multiple token types. A single deployed contract may include any combination of fungible tokens, non-fungible tokens or other configurations (e.g. semi-fungible tokens). ## Abstract -This standard outlines a smart contract interface that can represent any number of Fungible and Non-Fungible token types. Existing standards such as ERC-20 require deployment of separate contracts per token type. The ERC-721 standard's token ID is a single non-fungible index and the group of these non-fungibles is deployed as a single contract with settings for the entire collection. In contrast, the ERC-1155 Multi Token Standard allows for each token ID to represent a new configurable token type, which may have its own metadata, supply and other attributes. +This standard outlines a smart contract interface that can represent any number of fungible and non-fungible token types. Existing standards such as ERC-20 require deployment of separate contracts per token type. The ERC-721 standard's token ID is a single non-fungible index and the group of these non-fungibles is deployed as a single contract with settings for the entire collection. In contrast, the ERC-1155 Multi Token Standard allows for each token ID to represent a new configurable token type, which may have its own metadata, supply and other attributes. The `_id` argument contained in each function's argument set indicates a specific token or token type in a transaction. ## Motivation -Tokens standards like ERC-20 and ERC-721 require a separate contract to be deployed for each token type or collection. This places a lot of redundant bytecode on the Ethereum blockchain and limits certain functionality by the nature of separating each token contract into its own permissioned address. With the rise of blockchain games and platforms like Enjin Coin, game developers may be creating thousands of token types, and a new type of token standard is needed to support them. However, ERC-1155 is not specific to games, and many other applications can benefit from this flexibility. +Tokens standards like ERC-20 and ERC-721 require a separate contract to be deployed for each token type or collection. This places a lot of redundant bytecode on the Ethereum blockchain and limits certain functionality by the nature of separating each token contract into its own permissioned address. With the rise of blockchain games and platforms like Enjin Coin, game developers may be creating thousands of token types, and a new type of token standard is needed to support them. However, ERC-1155 is not specific to games and many other applications can benefit from this flexibility. -New functionality is possible with this design, such as transferring multiple token types at once, saving on transaction costs. Trading (escrow / atomic swaps) of multiple tokens can be built on top of this standard and it removes the need to "approve" individual token contracts separately. It is also easy to describe and mix multiple fungible or non-fungible token types in a single contract. +New functionality is possible with this design such as transferring multiple token types at once, saving on transaction costs. Trading (escrow / atomic swaps) of multiple tokens can be built on top of this standard and it removes the need to "approve" individual token contracts separately. It is also easy to describe and mix multiple fungible or non-fungible token types in a single contract. ## Specification @@ -630,7 +630,7 @@ Restricting approval to a certain set of token IDs, quantities or other rules MA ## Usage -This standard can be used to represent multiple token types for an entire domain. Both Fungible and Non-Fungible tokens can be stored in the same smart-contract. +This standard can be used to represent multiple token types for an entire domain. Both fungible and non-fungible tokens can be stored in the same smart-contract. ### Batch Transfers @@ -654,7 +654,7 @@ ERC-1155 contracts must therefore carefully emit `TransferSingle` or `TransferBa The following strategy is an example of how to mix fungible and non-fungible tokens together in the same contract. The top 128 bits of the uint256 `_id` parameter in any ERC-1155 function could represent the base token ID, while the bottom 128 bits might be used for any extra data passed to the contract. -Non-Fungible tokens can be interacted with using an index based accessor into the contract/token data set. Therefore to access a particular token set within a mixed data contract and particular NFT within that set, `_id` could be passed as ``. +Non-fungible tokens can be interacted with using an index based accessor into the contract/token data set. Therefore to access a particular token set within a mixed data contract and particular NFT within that set, `_id` could be passed as ``. Inside the contract code the two pieces of data needed to access the individual NFT can be extracted with uint128(~0) and the same mask shifted by 128. @@ -665,7 +665,7 @@ uint256 baseToken = 12345 << 128; uint128 index = 50; balanceOf(baseToken, msg.sender); // Get balance of the base token -balanceOf(baseToken + index, msg.sender); // Get balance of the Non-Fungible token index +balanceOf(baseToken + index, msg.sender); // Get balance of the non-fungible token index ``` ## References From 9a297719648959ec6e5aa1897a6eb0a35dc45789 Mon Sep 17 00:00:00 2001 From: Andrew Cooke <36201133+AC0DEM0NK3Y@users.noreply.github.com> Date: Wed, 12 Jun 2019 00:06:26 -0400 Subject: [PATCH 58/58] EDT-3069 Minor grammar alterations. --- EIPS/eip-1155.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index 8c092c7aa2460..ba4f55416a701 100644 --- a/EIPS/eip-1155.md +++ b/EIPS/eip-1155.md @@ -115,7 +115,7 @@ interface ERC1155 /* is ERC165 */ { function safeBatchTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external; /** - @notice Get the balance of an account's Tokens. + @notice Get the balance of an account's tokens. @param _owner The address of the token holder @param _id ID of the token @return The _owner's balance of the token type requested @@ -125,7 +125,7 @@ interface ERC1155 /* is ERC165 */ { /** @notice Get the balance of multiple account/token pairs @param _owners The addresses of the token holders - @param _ids ID of the Tokens + @param _ids ID of the tokens @return The _owner's balance of the token types requested (i.e. balance for each (owner, id) pair) */ function balanceOfBatch(address[] calldata _owners, uint256[] calldata _ids) external view returns (uint256[] memory); @@ -140,7 +140,7 @@ interface ERC1155 /* is ERC165 */ { /** @notice Queries the approval status of an operator for a given owner. - @param _owner The owner of the Tokens + @param _owner The owner of the tokens @param _operator Address of authorized operator @return True if the operator is approved, false if not */ @@ -207,7 +207,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran **_Scenario#3 :_** The receiver does not implement the necessary `ERC1155TokenReceiver` interface function(s). * The transfer MUST be reverted with the one caveat below. - - If the tokens being sent are part of a hybrid implementation of another standard, that particular standard's rules on sending to a contract MAY now be followed instead. See "Compatibility with other standards" section. + - If the token(s) being sent are part of a hybrid implementation of another standard, that particular standard's rules on sending to a contract MAY now be followed instead. See "Compatibility with other standards" section. **_Scenario#4 :_** The receiver implements the necessary `ERC1155TokenReceiver` interface function(s) but returns an unknown value. * The transfer MUST be reverted. @@ -242,9 +242,9 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran - If the contract logic wishes to keep the ownership of the token(s) itself in this case it MAY do so. **_Scenario#9 :_** You are transferring tokens via a non-standard API call i.e. an implementation specific API and NOT `safeTransferFrom` or `safeBatchTransferFrom`. -* In this scenario all balance updates and events output rules are the same as if a standard function had been called. - - i.e. an external viewer should still be able to query a balance via a function and it be identical to the balance as determined by `TransferSingle` and `TransferBatch` events alone. -* If the receiver is a contract the `ERC1155TokenReceiver` hooks still need to be called on it and the return values respected the same as if a standard function had been called. +* In this scenario all balance updates and events output rules are the same as if a standard transfer function had been called. + - i.e. an external viewer MUST still be able to query the balance via a standard function and it MUST be identical to the balance as determined by `TransferSingle` and `TransferBatch` events alone. +* If the receiver is a contract the `ERC1155TokenReceiver` hooks still need to be called on it and the return values respected the same as if a standard transfer function had been called. - However while the `safeTransferFrom` or `safeBatchTransferFrom` functions MUST revert if a receiving contract does not implement the `ERC1155TokenReceiver` interface, a non-standard function MAY proceed with the transfer. - See "Implementation specific transfer API rules". @@ -377,7 +377,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran * The total value transferred from address `0x0` minus the total value transferred to `0x0` observed via the `TransferSingle` and `TransferBatch` events MAY be used by clients and exchanges to determine the "circulating supply" for a given token ID. * As mentioned above mint/create and burn/destroy operations are specialized transfers and so will likely be accomplished with custom transfer functions rather than `safeTransferFrom` or `safeBatchTransferFrom`. If so the "Implementation specific transfer API rules" section would be appropriate. - Even in a non-safe API and/or hybrid standards case the above event rules MUST still be adhered to when minting/creating or burning/destroying. -* A contract MAY skip calling the `ERC1155TokenReceiver` hook function(s) if the mint/create operation is transferring the token(s) to itself. In all other cases the `ERC1155TokenReceiver` rules MUST be followed as appropriate for the implementation (i.e. safe, custom and/or hybrid). +* A contract MAY skip calling the `ERC1155TokenReceiver` hook function(s) if the mint operation is transferring the token(s) to itself. In all other cases the `ERC1155TokenReceiver` rules MUST be followed as appropriate for the implementation (i.e. safe, custom and/or hybrid). ##### A solidity example of the keccak256 generated constants for the various magic values (these MAY be used by implementation): @@ -407,7 +407,7 @@ An important consideration is that even if the tokens are sent with another stan ### Metadata -The URI value allows for ID substitution by clients. If the string `{id}` exists in any URI, clients MUST replace this with the actual token ID in hexadecimal form. This allows for large number of tokens to use the same on-chain string by defining a URI once, for a large collection of tokens. +The URI value allows for ID substitution by clients. If the string `{id}` exists in any URI, clients MUST replace this with the actual token ID in hexadecimal form. This allows for a large number of tokens to use the same on-chain string by defining a URI once, for that large number of tokens. * The string format of the substituted hexadecimal ID MUST be lowercase alphanumeric: `[0-9a-f]` with no 0x prefix. * The string format of the substituted hexadecimal ID MUST be leading zero padded to 64 hex characters length if necessary. @@ -594,7 +594,7 @@ fr.json: ### Approval The function `setApprovalForAll` allows an operator to manage one's entire set of tokens on behalf of the approver. To permit approval of a subset of token IDs, an interface such as [ERC-1761 Scoped Approval Interface](https://eips.ethereum.org/EIPS/eip-1761) is suggested. -The counterpart `isApprovedForAll` provides introspection into status set by `setApprovalForAll`. +The counterpart `isApprovedForAll` provides introspection into any status set by `setApprovalForAll`. An owner SHOULD be assumed to always be able to operate on their own tokens regardless of approval status, so should SHOULD NOT have to call `setApprovalForAll` to approve themselves as an operator before they can operate on them.