address feedback

EIPS/eip-1238.md

@@ -38,24 +38,14 @@ Every contract compliant with this EIP must implement the following interface:
 ```solidity
 interface IERC1238 is IERC165 {
     /**
-     * @dev Emitted when `amount` tokens of token type `id` are minted to `to` by `minter`.
+     * @dev Emitted when some `amounts` of tokens with their respective `ids` are minted to `to` by `minter`.
      */
-    event MintSingle(address indexed minter, address indexed to, uint256 indexed id, uint256 amount);
+    event Minted(address indexed minter, address indexed to, uint256[] ids, uint256[] amounts);
 
     /**
-     * @dev Equivalent to multiple {MintSingle} events, where `minter` and `to` is the same for all token types.
+     * @dev Emitted when some `amounts` of tokens with their respective `ids` are burned by `burner`.
      */
-    event MintBatch(address indexed minter, address indexed to, uint256[] ids, uint256[] amounts);
-
-    /**
-     * @dev Emitted when `amount` tokens of token type `id` owned by `owner` are burned by `burner`.
-     */
-    event BurnSingle(address indexed burner, address indexed owner, uint256 indexed id, uint256 amount);
-
-    /**
-     * @dev Equivalent to multiple {BurnSingle} events, where `owner` and `burner` is the same for all token types.
-     */
-    event BurnBatch(address indexed burner, address indexed owner, uint256[] ids, uint256[] amounts);
+    event Burned(address indexed burner, address indexed owner, uint256[] ids, uint256[] amounts);
 
     /**
      * @dev Returns the amount of tokens of token type `id` owned by `account`.
@@ -113,7 +103,7 @@ interface IERC1238URIStorage is IERC1238 {
 }
 ```
 
-The **Expirable extension** is OPTIONAL for smart contracts that implement this EIP. This allows your contract to associate a unique URI for each token id.
+The **Expirable extension** is OPTIONAL for smart contracts that implement this EIP. This allows your contract to associate a expiry date for each token id.
 
 ```solidity
 interface IERC1238Expirable is IERC1238 {
@@ -139,7 +129,12 @@ interface IERC1238Expirable is IERC1238 {
 }
 ```
 
-The **Holdable extension** is OPTIONAL for smart contracts that implement this EIP. This enables token owners to let their tokens be held by another address or to stake them in a smart contract.
+The **Holdable extension** is OPTIONAL for smart contracts that implement this EIP. This extension enables token owners to let their tokens be held by another address, including "staking" them in a smart contract.
+Since NTTs are non-transferable, the usual way of staking tokens by transferring ownership over them is not possible. In order to make staking possible, this extension introduces the notion of token holders, in addition to token owners:
+- When minting tokens to Alice's address A, address A is the token owner but also the initial token holder. Alice can then call the `entrust` function to entrust address B with her tokens. Address B becomes the token holder while Alice remains the token owner.
+- Only one address can hold specific tokens at a time.
+- A token holder can transfer tokens to another holder. Still, the important point is that this does not change ownership of the tokens.
+- Because token holders can “transfer” tokens they hold (via the `entrust` function) to any address they choose, they can also send them to the zero address and have it hold these tokens forever. So token owners are effectively putting their tokens at stake with this mechanism.
 
 ```solidity
 interface IERC1238Holdable is IERC1238 {
@@ -160,7 +155,7 @@ interface IERC1238Holdable is IERC1238 {
 
     /**
      * @dev Lets sender entrusts `to` with `amount`
-     * of tokens which gets transferred between their respective balances
+     * of tokens, which gets transferred between their respective balances
      * of tokens held.
      */
     function entrust(
@@ -171,6 +166,21 @@ interface IERC1238Holdable is IERC1238 {
 }
 ```
 
+Smart contracts holding tokens MUST implement the following interface:
+```solidity
+/**
+ * @dev Interface proposal for contracts that need to hold ERC1238 tokens.
+ */
+interface IERC1238Holder is IERC1238Receiver {
+    /**
+     * @dev This function is called when tokens with id `id` are burnt.
+     * Returns `true` as a sign that the burn was acknowledged and processed.
+     */
+    function onBurn(uint256 id, uint256 amount) external returns (bool);
+}
+```
+
+When burning tokens, implementers MUST try to call the `onBurn` function if the holder is a smart contract. This allows smart contract token holders to get notified when tokens that they hold are being burnt and gives them a chance to react and handle the situation as they see fit.
 
 ## Rationale
 ### Fungibility
@@ -185,10 +195,10 @@ EIP-1155 presents several interesting features that are also applicable to these
 2. EIP-1155 is fungibility-agnostic: the same smart contract can track both fungible tokens and NFTs
 3. Batch operations are possible such as minting or querying the balance for multiple token ids in just one call
 4. No more tokens stuck in contracts because they were sent by mistake. For transfers and batch transfers, if the recipient is a contract, the transaction will revert if it does not implement the `ERC1155TokenReceiver` interface
-5. Smart contracts which implement the `ERC1155TokenReceiver` interface may reject an increase in balance 
+5. Smart contracts which implement the `ERC1155TokenReceiver` interface may reject an increase in balance
 
-EIP-1155 conveniently supports **batch** operations, where a batch is represented by an array of token ids and an amount for each token id. 
-However a batch often times only concerns one address. While minting a batch of tokens to an address in one transaction is convenient, we felt the need to support minting to multiple addresses in one transaction. 
+EIP-1155 conveniently supports **batch** operations, where a batch is represented by an array of token ids and an amount for each token id.
+However a batch often times only concerns one address. While minting a batch of tokens to an address in one transaction is convenient, we felt the need to support minting to multiple addresses in one transaction.
 As a result and keeping the strict definition that a batch is only for one address, this standard introduces the notion of a **bundle***.* A bundle is simply a collection of batches for multiple addresses.
 
 ### Consent
@@ -198,9 +208,10 @@ Discussions within the community have highlighted the risk of having unwanted, n
 In order to remedy to this, implementations of this standard must not let tokens being minted without approval from the recipient. In the case of a smart contract recipient, this is achieved via the `IERC1238Receiver` interface and returning a specific value to approve a minting. For recipients that are Externally Owned Accounts (EOAs), they must provide a [EIP-712](./eip-712.md) signature to approve token minting which gets passed to the smart contract when calling a mint function.
 
 ## Backwards Compatibility
-Because of the inspiration drawn from EIP-1155, many concepts and methods remain identical, namely the concept of minting and burning tokens, a batch, the `ERC1238TokenReceiver`, the `balanceOf` and `balanceOfBatch` functions and to some extent the base extension for URI storage.
+Because of the inspiration drawn from EIP-1155, many concepts and methods remain identical, namely the concept of minting and burning tokens, a batch, the `ERC1238TokenReceiver`, the `balanceOf` and `balanceOfBatch` functions and to some extent the base extension for URI storage. Similarly, tokens whose owner is the zero address are considered burnt and invalid, therefore the zero address is not a valid input to call `balanceOf` with.
+
+Transfers events have been replaced by the `Minted` and `Burned` events whose names are less misleading in the context of this standard.
 
-Transfers events have been replaced by the MintSingle, MintBatch, BurnSingle and BurnBatch events whose names are less misleading in the context of this standard.
 
 ## Security Considerations
 Given that the tokens are non-transferable, it becomes impossible to transfer them to another address in case of a suspected compromised account. Issuers should remain open to perform necessary checks on their end and allow tokens to be burnt and re-issued to someone.