Add ERC: ERC-721 Ownership Shares Extension

ERCS/erc-7628.md

@@ -0,0 +1,195 @@
+---
+eip: 7628
+title: ERC-721 Ownership Shares Extension
+description: Introduces ownership shares to ERC-721 tokens, allowing for queryable, transferable, and approvable fractional ownership.
+author: Chen Liaoyuan (@chenly) <cly@kip.pro>
+discussions-to: https://ethereum-magicians.org/t/erc-7628-erc-721-ownership-shares-extension/18744
+status: Draft
+type: Standards Track
+category: ERC
+created: 2024-02-20
+requires: 721
+---
+
+## Abstract
+
+The proposal introduces an attribute of ownership and profit share quantities for each token under an NFT. This attribute signifies a stake in the ownership and profit rights associated with the NFT's specific privileges, enabling the querying, transferring, and approval of these shares, thereby making the shares represented by each token applicable in a broader range of use cases.
+
+## Motivation
+
+At times, when we wish to distribute dividends or assign rights to tokens of an NFT based on their share of ownership, it becomes necessary to equip each token with an attribute indicating the number of ownership shares. While [ERC-1155](./eip-1155.md) allows for the representation of ownership stakes through the balance of a token held by a wallet address, it sacrifices the uniqueness of each token. Conversely, [ERC-721](./eip-721.md) maintains the uniqueness of each token but lacks an attribute to signify the share of ownership rights, and its metadata does not allow for the free transfer of these share quantities by the token owner. This extension seeks to merge the features of [ERC-1155](./eip-1155.md) and [ERC-721](./eip-721.md), enabling holders of each share to possess characteristics akin to those of a token owner, thus bridging the gap between share representation and token uniqueness.
+
+## 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 ownership shares.
+    /// @return The number of decimal places for ownership shares.
+    function shareDecimals() external view returns (uint8);
+
+    /// @notice Returns the total sum of ownership shares in existence for all tokens.
+    /// @return The total sum of ownership shares.
+    function totalShares() external view returns (uint256);
+
+    /// @notice Returns the ownership share of the specified token.
+    /// @param tokenId The identifier of the token.
+    /// @return The ownership share of the token.
+    function shareOf(uint256 tokenId) external view returns (uint256);
+
+    /// @notice Returns the share 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 share allowance granted to the spender.
+    function shareAllowance(uint256 tokenId, address spender) external view returns (uint256);
+
+    /// @notice Approves the specified address to spend a specified amount of shares on behalf of the caller.
+    /// @param tokenId The identifier of the token.
+    /// @param spender The address of the spender.
+    /// @param shares The amount of shares to approve.
+    function approveShare(uint256 tokenId, address spender, uint256 shares) external;
+
+    /// @notice Transfers ownership shares from one token to another.
+    /// @param fromTokenId The identifier of the sender token.
+    /// @param toTokenId The identifier of the recipient token.
+    /// @param shares The amount of shares to transfer.
+    function transferShares(uint256 fromTokenId, uint256 toTokenId, uint256 shares) external;
+
+    /// @notice Transfers ownership shares from one token to another address (resulting in a new token or increased shares at the recipient address).
+    /// @param fromTokenId The identifier of the sender token.
+    /// @param to The address of the recipient.
+    /// @param shares The amount of shares to transfer.
+    function transferSharesToAddress(uint256 fromTokenId, address to, uint256 shares) external; 
+
+    /// @notice Adds a specified amount of shares to a token, only callable by the contract owner.
+    /// @param tokenId The identifier of the token.
+    /// @param shares The amount of shares to add.
+    function addSharesToToken(uint256 tokenId, uint256 shares) external;
+
+    /// @notice Emitted when ownership shares are transferred from 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 shares transferred.
+    event SharesTransfered(uint256 indexed fromTokenId, uint256 indexed toTokenId, uint256 amount);
+
+    /// @notice Emitted when an approval is granted for a spender to spend shares on behalf of an owner.
+    /// @param tokenId The token identifier.
+    /// @param spender The address of the spender.
+    /// @param amount The amount of shares approved.
+    event SharesApproved(uint256 indexed tokenId, address indexed spender, uint256 amount);
+}
+```
+
+## Rationale
+
+#### Share Issuance to a Token
+
+Issuing additional shares to a token allows for flexible management of ownership stakes in digital assets, catering to the evolving needs of stakeholders. It ensures transparency and security in modifying ownership structures directly on the blockchain, facilitating scenarios like profit sharing or investment adjustments.
+
+#### Transferring Shares to an Address
+
+Enabling shares to be transferred to an address enhances NFT liquidity and accessibility by allowing fractional ownership. This feature supports diverse use cases like fractional sales or collateralization, making NFTs more adaptable and inclusive for a broader audience.
+
+## Backwards Compatibility
+
+This standard is fully [ERC-721](./eip-721.md) compatible.
+
+## Reference Implementation
+
+```solidity
+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 IERC7628, ERC721, Ownable, ReentrancyGuard {
+    mapping(uint256 => uint256) private _shareBalances;
+    mapping(uint256 => mapping(address => uint256)) private _shareAllowances;
+    uint256 private _totalShares;
+    uint256 private _nextTokenId;
+
+    constructor(address initialOwner)
+        ERC721("MyToken", "MTK")
+        Ownable(initialOwner)
+    {}
+
+    function addSharesToToken(uint256 tokenId, uint256 shares) public override onlyOwner {
+        require(tokenId > 0, "ERC7628: tokenId cannot be zero");
+        _shareBalances[tokenId] += shares;
+        _totalShares += shares;
+        emit SharesTransfered(0, tokenId, shares);
+    }
+
+    function shareDecimals() external pure override returns (uint8) {
+        return 18;
+    }
+
+    function totalShares() external view override returns (uint256) {
+        return _totalShares;
+    }
+
+    function shareOf(uint256 tokenId) external view override returns (uint256) {
+        return _shareBalances[tokenId];
+    }
+
+    function shareAllowance(uint256 tokenId, address spender) external view override returns (uint256) {
+        return _shareAllowances[tokenId][spender];
+    }
+
+    function approveShare(uint256 tokenId, address spender, uint256 shares) external override {
+        require(spender != ownerOf(tokenId), "ERC7628: approval to current owner");
+        require(msg.sender == ownerOf(tokenId), "ERC7628: approve caller is not owner");
+
+        _shareAllowances[tokenId][spender] = shares;
+        emit SharesApproved(tokenId, spender, shares);
+    }
+
+    function transferShares(uint256 fromTokenId, uint256 toTokenId, uint256 shares) external override nonReentrant {
+        require(_shareBalances[fromTokenId] >= shares, "ERC7628: insufficient shares for transfer");
+        require(_isApprovedOrOwner(msg.sender, fromTokenId), "ERC7628: transfer caller is not owner nor approved");
+
+        _shareBalances[fromTokenId] -= shares;
+        _shareBalances[toTokenId] += shares;
+        emit SharesTransfered(fromTokenId, toTokenId, shares);
+    }
+
+    function transferSharesToAddress(uint256 fromTokenId, address to, uint256 shares) external override nonReentrant {
+        require(_shareBalances[fromTokenId] >= shares, "ERC7628: insufficient shares for transfer");
+        require(_isApprovedOrOwner(msg.sender, fromTokenId), "ERC7628: transfer caller is not owner nor approved");
+
+        _nextTokenId++;
+        _safeMint(to, _nextTokenId);
+        _shareBalances[_nextTokenId] = shares;
+        emit SharesTransfered(fromTokenId, _nextTokenId, shares);
+    }
+
+    // Helper function to check if an address is the owner or approved
+    function _isApprovedOrOwner(address spender, uint256 tokenId) internal view returns (bool) {
+        return (spender == ownerOf(tokenId) || getApproved(tokenId) == spender || isApprovedForAll(ownerOf(tokenId), spender));
+    }
+}
+```
+
+## Security Considerations
+
+#### Clear Approvals on Transfer
+When transferring token ownership, it is crucial to clear all existing approvals. This precaution prevents previously authorized parties from retaining access after the token has changed hands.
+
+#### Prevent Reentrancy
+Implementations must guard against reentrancy attacks. This involves ensuring that functions altering balances or ownership are secure against such vulnerabilities, particularly during share transfers.
+
+#### Validate IDs and Addresses
+Verifying the legitimacy of token IDs and wallet addresses in all operations is essential. This step helps avoid errors and ensures that tokens and their associated shares are handled correctly.
+
+#### Manage Shares on Ownership Change
+Proper management of share quantities is vital during a token ownership transfer. It's important to ensure that shares are accurately accounted for and transferred alongside the token to maintain the integrity of ownership stakes.
+
+## Copyright
+
+Copyright and related rights waived via [CC0](../LICENSE.md).