Add ERC: ERC-721 Ownership Shares Extension

ERCS/erc-7628.md

@@ -0,0 +1,111 @@
+---
+eip: 7628
+title: ERC-721 Balance Extension
+description: Extend ERC-721 to include balance functionalities similar to ERC-20.
+author: Chen Liaoyuan (@chenly) <cly@kip.pro>
+discussions-to: https://ethereum-magicians.org/t/erc-7628-erc-721-balance-extension/18744
+status: Draft
+type: Standards Track
+category: ERC
+created: 2024-02-20
+requires: 20, 721
+---
+
+## Abstract
+
+This extension defines an interface that adds balance functionalities to [ERC-721](./eip-721.md) tokens, enabling functions and events for balance querying, transfer, and approval similar to [ERC-20](./eip-20.md) tokens.
+
+## Motivation
+
+Some NFTs represent divisible ownership stakes or shares of associated rights, such as those pertaining to digital assets, real estate, or intellectual property. The ability to accurately query and exchange these shares is crucial for facilitating efficient market operations. However, the absence of built-in support for token balances within the current [ERC-721](./eip-721.md) standard poses challenges and limitations in managing and trading these rights effectively. By introducing functionalities that mirror those of [ERC-20](./eip-20.md) token balances, we can offer a comprehensive solution for [ERC-721](./eip-721.md) tokens. This enhancement empowers holders to effortlessly inquire about and exchange their respective ownership shares, thereby promoting wider acceptance and circulation of NFTs.
+
+## Specification
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
+
+Implementers of this extension **MUST** have all of the following functions:
+
+```solidity
+pragma solidity ^0.8.0;
+
+interface IERC7628 /* is IERC721 */ {
+    /// @notice Returns the number of decimal places used for token balances.
+    /// @return The number of decimal places.
+    function balanceDecimals() external view returns (uint8);
+
+    /// @notice Returns the total sum of token balances in existence.
+    /// @return The total sum of balances for all tokens.
+    function totalBalances() external view returns (uint256);
+
+    /// @notice Returns the balance of the specified token.
+    /// @param tokenId The identifier of the token.
+    /// @return The balance of the token.
+    function balanceOf(uint256 tokenId) external view returns (uint256);
+
+    /// @notice Returns the allowance granted to the specified spender by the owner for the specified token.
+    /// @param tokenId The identifier of the token.
+    /// @param spender The address of the spender.
+    /// @return The allowance granted to the spender.
+    function allowance(uint256 tokenId, address spender) external view returns (uint256);
+
+    /// @notice Approves the specified address to spend the specified amount of tokens on behalf of the caller.
+    /// @param tokenId The identifier of the token.
+    /// @param to The address of the spender.
+    /// @param amount The amount of tokens to approve.
+    function approve(uint256 tokenId, address to, uint256 amount) external;
+
+    /// @notice Transfers tokens from the balance of one token to another.
+    /// @param _fromTokenId The identifier of the sender token.
+    /// @param _toTokenId The identifier of the recipient token.
+    /// @param amount The amount of tokens to transfer.
+    function transferFrom(uint256 _fromTokenId, uint256 _toTokenId, uint256 amount) external;
+
+    /// @notice Transfers tokens from the balance of one token to another address.
+    /// @param _fromTokenId The identifier of the sender token.
+    /// @param _to to The address of the recipient.
+    /// @param amount The amount of tokens to transfer.
+    function transferFrom(uint256 _fromTokenId, address _to, uint256 amount) external;
+
+    /// @notice Emitted when tokens are transferred from the balance of one token to another.
+    /// @param _fromTokenId The identifier of the sender token.
+    /// @param _toTokenId The identifier of the recipient token.
+    /// @param value The amount of tokens transferred.
+    event Transfer(uint256 indexed _fromTokenId, uint256 indexed _toTokenId, uint256 value);
+
+    /// @notice Emitted when an approval is granted for a spender to spend tokens on behalf of an owner.
+    /// @param _tokenId The token identifier.
+    /// @param spender The address of the spender.
+    /// @param value The amount of tokens approved.
+    event Approval(uint256 indexed _tokenId, address indexed spender, uint256 value);
+}
+```
+
+## Rationale
+
+Integrating a balance feature into each token and adopting mechanisms similar to those found in [ERC-20](./eip-20.md), we enable the seamless exchange of balances between tokens. This development allows token holders to effortlessly inquire about and transact the ownership shares represented by their token balances. Furthermore, should there be a necessity to increase the overall balance, new NFTs can be minted and their balances augmented accordingly. The omission of the `transfer` function from [ERC-20](./eip-20.md) is necessitated by the need to use `tokenId` for executing transfers. Including it would be redundant, as it overlaps with the functionality of the `transferFrom` function. Additionally, in situations where a token owner desires to transfer a balance to a specific address, a viable method involves first minting a new token for that address, then proceeding with the balance transfer, ensuring a smooth transition of value.
+
+## Backwards Compatibility
+
+This standard is fully [ERC-721](./eip-721.md) compatible.
+
+## Reference Implementation
+
+A full interface of a smart account can be found in [`ERC7628.sol`](../assets/eip-7628/ERC7628.sol).
+
+## Security Considerations
+
+#### Clearing Approvals upon Ownership Transfer
+It is crucial to clear any existing approvals when the ownership of a token is transferred. This measure prevents previously approved addresses from retaining access to the tokens once their ownership has changed.
+
+#### Guarding Against Reentrancy Attacks
+Implementations must protect against reentrancy attacks, especially in functions that modify balances or ownership, such as `transferFrom`. Employing reentrancy guards can help prevent attackers from exploiting vulnerabilities during the execution process.
+
+#### Validating Token IDs and Addresses
+Ensuring the validity of token IDs and addresses in all transfer or approval operations is essential. This includes verifying that token IDs are legitimate and that addresses are not zero, thereby preventing accidental loss or incorrect handling of tokens.
+
+#### Transferring Balances with Ownership
+When the ownership of a token is transferred, it is important to also transfer any associated balances to the new owner. This approach ensures that the ownership and any financial value or rights linked to the token remain consistently aligned.
+
+## Copyright
+
+Copyright and related rights waived via [CC0](../LICENSE.md).

assets/erc-7628/ERC7628.sol

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: CC0-1.0
+
+pragma solidity ^0.8.0;
+
+import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
+import "@openzeppelin/contracts/access/Ownable.sol";
+import "@openzeppelin/contracts/security/ReentrancyGuard.sol";
+
+contract ERC7628 is ERC721, Ownable, ReentrancyGuard {
+    mapping(uint256 => uint256) private _balances;
+    mapping(uint256 => mapping(address => uint256)) private _allowances;
+    uint256 private _totalBalance;
+    uint256 private _nextTokenId;
+
+    constructor(address initialOwner)
+        ERC721("MyToken", "MTK")
+        Ownable(initialOwner)
+    {}
+
+    function addBalance(uint256 tokenId, uint256 amount) public onlyOwner {
+        require(tokenId > 0, "ERC7628: tokenId cannot be zero");
+        _balances[tokenId] += amount;
+        _totalBalance += amount;
+        emit Transfer(0, tokenId, amount);
+    }
+
+    function balanceDecimals() external pure returns (uint8) {
+        return 18;
+    }
+
+    function totalBalances() external view returns (uint256) {
+        return _totalBalance;
+    }
+
+    function balanceOf(uint256 tokenId) external view returns (uint256) {
+        return _balances[tokenId];
+    }
+
+    function allowance(uint256 tokenId, address spender) external view returns (uint256) {
+        return _allowances[tokenId][spender];
+    }
+
+    function approve(uint256 tokenId, address to, uint256 amount) external {
+        require(to != ownerOf(tokenId), "ERC7628: approval to current owner");
+        require(msg.sender == ownerOf(tokenId), "ERC7628: approve caller is not owner");
+
+        _allowances[tokenId][to] = amount;
+        emit Approval(tokenId, to, amount);
+    }
+
+    function transferFrom(uint256 _fromTokenId, uint256 _toTokenId, uint256 amount) external nonReentrant {
+        require(_isApprovedOrOwner(msg.sender, _fromTokenId), "ERC7628: transfer caller is not owner nor approved");
+        _transfer(_fromTokenId, _toTokenId, amount);
+    }
+
+    function transferFrom(uint256 _fromTokenId, address _to, uint256 amount) external nonReentrant {
+        require(_isApprovedOrOwner(msg.sender, _fromTokenId), "ERC7628: transfer caller is not owner nor approved");
+        _nextTokenId++;
+        _safeMint(_to, _nextTokenId);
+        _transfer(_fromTokenId, _nextTokenId, amount);
+    }
+
+    function _transfer(uint256 fromTokenId, uint256 toTokenId, uint256 amount) internal nonReentrant {
+        require(_balances[fromTokenId] >= amount, "ERC7628: transfer amount exceeds balance");
+
+        // Check allowance for non-owner transfers
+        if (msg.sender != ownerOf(fromTokenId)) {
+            require(_allowances[fromTokenId][msg.sender] >= amount, "ERC7628: transfer amount exceeds allowance");
+            _allowances[fromTokenId][msg.sender] -= amount;
+        }
+
+        _balances[fromTokenId] -= amount;
+        _balances[toTokenId] += amount;
+
+        emit Transfer(fromTokenId, toTokenId, amount);
+    }
+
+    function _isApprovedOrOwner(address spender, uint256 tokenId) internal view returns (bool) {
+        return (spender == ownerOf(tokenId) || _allowances[tokenId][spender] > 0);
+    }
+
+    event Transfer(uint256 indexed fromTokenId, uint256 indexed toTokenId, uint256 value);
+    event Approval(uint256 indexed tokenId, address indexed spender, uint256 value);
+}