From 9fa08d11a65e6c44b7b7a1e266017c3d0f9fa197 Mon Sep 17 00:00:00 2001 From: Andrew Cooke Date: Fri, 24 May 2019 22:49:29 -0400 Subject: [PATCH] Automatically merged updates to draft EIP(s) 1155 (#2084) Hi, I'm a bot! This change was automatically merged because: - It only modifies existing Draft or Last Call EIP(s) - The PR was approved or written by at least one author of each modified EIP - The build is passing --- EIPS/eip-1155.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/EIPS/eip-1155.md b/EIPS/eip-1155.md index bb33ef2e..f551d3ed 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". @@ -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`. -* 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. +**_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,23 +345,23 @@ 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 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. +**_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 (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 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"). + - 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: