EDT-3069 Updated the "Safe Transfer Rules" section to match feedback …

…given in discussion thread. This introduces specific scenarios and rules to match.
ethereum · eip-automerger · Jun 7, 2019 · May 3, 2019 · May 3, 2019 · May 4, 2019
commit ed9f0d1fd8f45136f1b527fc4044176c48f51da0
@@ -184,60 +184,91 @@ 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()")
 
 ##### 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