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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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)