Submit EIP-4973 - Account-bound tokens

EIPS/eip-4973.md

@@ -0,0 +1,102 @@
+---
+eip: 4973
+title: Account-bound Tokens
+description: A standard interface for non-transferrable non-fungible tokens, also known as "account-bound" or "soulbound tokens" or "badges".
+author: Tim Daubenschütz (TimDaub), Raphael Roullet (@ra-phael), Nicola Greco (@nicola)
+discussions-to: https://ethereum-magicians.org/t/eip-4973-non-transferrable-non-fungible-tokens-soulbound-tokens-or-badges/8825
+status: Draft
+type: Standards Track
+category: ERC
+created: 2022-04-01
+requires: 165, 721
+---
+
+## Abstract
+
+Proposes a standard API for account-bound Tokens (ABT) within smart contracts. An ABT is a non-fungible token bound to a single account, and cannot be transferred between accounts. This EIP defines basic functionality to gift, mint, and track ABTs.
+
+## Motivation
+
+The Ethereum community has expressed a need for non-transferrable, non-fungible tokens. Common use cases include tracking an individual's achievements (which can be used as credentials), or items that cannot be transferred (like certain loot in multiplayer online games).
+
+The purpose of this document is to make ABTs a reality on Ethereum by creating consensus around a **maximally backward-compatible** but otherwise **minimal** interface definition.
+
+## Specification
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
+
+`EIP-4973` tokens _must_ implement the interfaces:
+
+- [EIP-165](./eip-165.md)'s `ERC165` (`0x01ffc9a7`)
+- [EIP-721](./eip-721.md)'s `ERC721Metadata` (`0x5b5e139f`)
+
+`EIP-4973` tokens _must not_ implement the interfaces:
+
+- [EIP-721](./eip-721.md)'s `ERC721` (`0x80ac58cd`)
+
+```solidity
+// SPDX-License-Identifier: CC0-1.0
+pragma solidity ^0.8.6;
+
+/// @title Account-bound tokens
+/// @dev See https://eips.ethereum.org/EIPS/eip-4973
+///  Note: the ERC-165 identifier for this interface is 0x6352211e.
+interface IERC4973 /* is ERC165, ERC721Metadata */ {
+  /// @dev This emits when a new token is created and bound to an account by
+  /// any mechanism.
+  /// Note: For a reliable `_from` parameter, retrieve the transaction's
+  /// authenticated `from` field.
+  event Attest(address indexed _to, uint256 indexed _tokenId);
+  /// @dev This emits when an existing ABT is revoked from an account and
+  /// destroyed by any mechanism.
+  /// Note: For a reliable `_from` parameter, retrieve the transaction's
+  /// authenticated `from` field.
+  event Revoke(address indexed _to, uint256 indexed _tokenId);
+  /// @notice Find the address bound to an ERC4973 account-bound token
+  /// @dev ABTs assigned to zero address are considered invalid, and queries
+  ///  about them do throw.
+  /// @param _tokenId The identifier for an ABT
+  /// @return The address of the owner bound to the ABT
+  function ownerOf(uint256 _tokenId) external view returns (address);
+}
+```
+
+See [`EIP-721`](./eip-721.md) for a definition of its metadata JSON Schema.
+
+## Rationale
+
+### Interface
+
+`EIP-4973` shall be maximally backward-compatible but still only expose a minimal and simple to implement interface definition.
+
+As [`EIP-721`](./eip-721.md) tokens have seen widespread adoption with wallet providers and marketplaces, using its `ERC721Metadata` interface with [`EIP-165`](./eip-165.md) for feature-detection potentially allows implementers to support `EIP-4973` tokens out of the box.
+
+If an implementer of [`EIP-721`](./eip-721.md) properly built [`EIP-165`](./eip-165.md)'s `function supportsInterface(bytes4 interfaceID)` function, already by recognizing that [`EIP-721`](./eip-721.md)'s track and transfer interface component with the identifier `0x80ac58cd` is not implemented, transferring of a token should not be suggested as a user interface option.
+
+Still, however, since `EIP-4973` supports [`EIP-721`](./eip-721.md)'s `ERC721Metadata` extension, an account-bound token should be displayed in wallets and marketplaces with no changes needed.
+
+Although other possible implementations of account-bound tokens are possible, e.g., by having all transfer functions revert, `EIP-4973` is superior as it supports feature detection through [`EIP-165`](./eip-165.md).
+
+### Exception handling
+
+Given the non-transferable between accounts property of ABTs, if a user's keys to an account or a contract get compromised or rotated, a user may lose the ability to associate themselves with the token. In some cases, this can be the desired effect. Therefore, it is suggested to implement re-issuance and potential revocation processes on the issuer side to enable recourse when it is not.
+
+This document is deliberately abstaining from offering a standardized form of exception handling in cases where user keys are compromised or rotated.
+
+In cases where implementers want to make account-bound tokens sharable among different accounts, e.g., to avoid losing access when keys get compromised, we suggest issuing the account-bound token towards a contract's account that implements a multi-signature functionality.
+
+### Provenance Indexing
+
+ABTs can be indexed by tracking the emission of `event Attest` and `event Revoke`. To guarantee reliable and implementation-independent indexable information, neither `event Attest` nor `event Revoke` include a `from` argument to depict the transaction sender. Instead, as a `from` property wouldn't be authenticated and hence opens a security vector, we omit it and advise indexers to substitute it with the transaction-level `from` field which gets authenticated through Ethereum's transaction signature validation prior to inclusion in a block.
+
+## Backwards Compatibility
+
+We have adopted the [`EIP-165`](./eip-165.md) and `ERC721Metadata` functions purposefully to create a high degree of backward compatibility with [`EIP-721`](./eip-721.md). We have deliberately used [`EIP-721`](./eip-721md`) terminology such as `function ownerOf(...)` to minimize the effort of familiarization for `EIP-4973` implementers already familiar with, e.g., [`EIP-20`](./eip-20.md) or [`EIP-721`](./eip-721.md).
+
+## Reference Implementation
+
+You can find an implementation of this standard in [../assets/eip-4973](../assets/eip-4973).
+
+## Copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

assets/eip-4973/src/ERC165.sol

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts v4.4.1 (utils/introspection/ERC165.sol)
+
+pragma solidity ^0.8.0;
+
+import "./interfaces/IERC165.sol";
+
+/**
+ * @dev Implementation of the {IERC165} interface.
+ *
+ * Contracts that want to implement ERC165 should inherit from this contract and override {supportsInterface} to check
+ * for the additional interface id that will be supported. For example:
+ *
+ * ```solidity
+ * function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) {
+ *     return interfaceId == type(MyInterface).interfaceId || super.supportsInterface(interfaceId);
+ * }
+ * ```
+ *
+ * Alternatively, {ERC165Storage} provides an easier to use but more expensive implementation.
+ */
+abstract contract ERC165 is IERC165 {
+    /**
+     * @dev See {IERC165-supportsInterface}.
+     */
+    function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) {
+        return interfaceId == type(IERC165).interfaceId;
+    }
+}

assets/eip-4973/src/ERC4973.sol

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: CC0-1.0
+pragma solidity ^0.8.6;
+
+import {ERC165} from "./ERC165.sol";
+
+import {IERC721Metadata} from "./interfaces/IERC721Metadata.sol";
+import {IERC4973} from "./interfaces/IERC4973.sol";
+
+
+abstract contract ERC4973 is ERC165, IERC721Metadata, IERC4973 {
+  string private _name;
+  string private _symbol;
+
+  mapping(uint256 => address) private _owners;
+  mapping(uint256 => string) private _tokenURIs;
+
+  constructor(
+    string memory name_,
+    string memory symbol_
+  ) {
+    _name = name_;
+    _symbol = symbol_;
+  }
+
+  function supportsInterface(bytes4 interfaceId) public view override returns (bool) {
+    return
+      interfaceId == type(IERC721Metadata).interfaceId ||
+      interfaceId == type(IERC4973).interfaceId ||
+      super.supportsInterface(interfaceId);
+  }
+
+  function name() public view virtual override returns (string memory) {
+    return _name;
+  }
+
+  function symbol() public view virtual override returns (string memory) {
+    return _symbol;
+  }
+
+  function tokenURI(uint256 tokenId) public view virtual override returns (string memory) {
+    require(_exists(tokenId), "tokenURI: token doesn't exist");
+    return _tokenURIs[tokenId];
+  }
+
+  function _exists(uint256 tokenId) internal view virtual returns (bool) {
+    return _owners[tokenId] != address(0);
+  }
+
+  function ownerOf(uint256 tokenId) public view virtual returns (address) {
+    address owner = _owners[tokenId];
+    require(owner != address(0), "ownerOf: token doesn't exist");
+    return owner;
+  }
+
+  function _mint(
+    address to,
+    uint256 tokenId,
+    string calldata uri
+  ) internal virtual returns (uint256) {
+    require(!_exists(tokenId), "mint: tokenID exists");
+    _owners[tokenId] = to;
+    _tokenURIs[tokenId] = uri;
+    emit Attest(to, tokenId);
+    return tokenId;
+  }
+
+  function _burn(uint256 tokenId) internal virtual {
+    address owner = ownerOf(tokenId);
+
+    delete _owners[tokenId];
+    delete _tokenURIs[tokenId];
+
+    emit Revoke(owner, tokenId);
+  }
+}

assets/eip-4973/src/ERC4973.t.sol

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: CC0-1.0
+pragma solidity ^0.8.6;
+
+import {DSTest} from "ds-test/test.sol";
+import {IERC165} from "./interfaces/IERC165.sol";
+
+import {IERC721Metadata} from "./interfaces/IERC721Metadata.sol";
+import {IERC4973} from "./interfaces/IERC4973.sol";
+import {ERC4973} from "./ERC4973.sol";
+
+contract AccountBoundToken is ERC4973 {
+  constructor() ERC4973("Name", "Symbol") {}
+
+  function mint(
+    address to,
+    uint256 tokenId,
+    string calldata uri
+  ) external returns (uint256) {
+    return super._mint(to, tokenId, uri);
+  }
+
+  function burn(uint256 tokenId) external {
+    super._burn(tokenId);
+  }
+}
+
+contract ERC4973Test is DSTest {
+  AccountBoundToken abt;
+
+  function setUp() public {
+    abt = new AccountBoundToken();
+  }
+
+  function testIERC165() public {
+    assertTrue(abt.supportsInterface(type(IERC165).interfaceId));
+  }
+
+  function testIERC721Metadata() public {
+    assertTrue(abt.supportsInterface(type(IERC721Metadata).interfaceId));
+  }
+
+  function testIERC4973() public {
+    assertTrue(abt.supportsInterface(type(IERC4973).interfaceId));
+  }
+
+  function testCheckMetadata() public {
+    assertEq(abt.name(), "Name");
+    assertEq(abt.symbol(), "Symbol");
+  }
+
+  function testMint() public {
+    string memory tokenURI = "https://example.com/metadata.json";
+    uint256 tokenId = 0;
+    abt.mint(msg.sender, tokenId, tokenURI);
+    assertEq(abt.tokenURI(tokenId), tokenURI);
+    assertEq(abt.ownerOf(tokenId), msg.sender);
+  }
+
+  function testMintToExternalAddress() public {
+    address thirdparty = address(1337);
+    string memory tokenURI = "https://example.com/metadata.json";
+    uint256 tokenId = 0;
+    abt.mint(thirdparty, tokenId, tokenURI);
+    assertEq(abt.tokenURI(tokenId), tokenURI);
+    assertEq(abt.ownerOf(tokenId), thirdparty);
+  }
+
+  function testMintAndBurn() public {
+    string memory tokenURI = "https://example.com/metadata.json";
+    uint256 tokenId = 0;
+    abt.mint(msg.sender, tokenId, tokenURI);
+    assertEq(abt.tokenURI(tokenId), tokenURI);
+    assertEq(abt.ownerOf(tokenId), msg.sender);
+    abt.burn(tokenId);
+  }
+
+  function testFailToMintTokenToPreexistingTokenId() public {
+    string memory tokenURI = "https://example.com/metadata.json";
+    uint256 tokenId = 0;
+    abt.mint(msg.sender, tokenId, tokenURI);
+    assertEq(abt.tokenURI(tokenId), tokenURI);
+    assertEq(abt.ownerOf(tokenId), msg.sender);
+    abt.mint(msg.sender, tokenId, tokenURI);
+  }
+
+  function testFailRequestingNonExistentTokenURI() public view {
+    abt.tokenURI(1337);
+  }
+
+  function testFailGetBonderOfNonExistentTokenId() public view {
+    abt.ownerOf(1337);
+  }
+}
+

assets/eip-4973/src/interfaces/IERC165.sol

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts v4.4.1 (utils/introspection/IERC165.sol)
+
+pragma solidity ^0.8.0;
+
+/**
+ * @dev Interface of the ERC165 standard, as defined in the
+ * https://eips.ethereum.org/EIPS/eip-165[EIP].
+ *
+ * Implementers can declare support of contract interfaces, which can then be
+ * queried by others ({ERC165Checker}).
+ *
+ * For an implementation, see {ERC165}.
+ */
+interface IERC165 {
+    /**
+     * @dev Returns true if this contract implements the interface defined by
+     * `interfaceId`. See the corresponding
+     * https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[EIP section]
+     * to learn more about how these ids are created.
+     *
+     * This function call must use less than 30 000 gas.
+     */
+    function supportsInterface(bytes4 interfaceId) external view returns (bool);
+}

assets/eip-4973/src/interfaces/IERC4973.sol

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: CC0-1.0
+pragma solidity ^0.8.6;
+
+/// @title Account-bound tokens
+/// @dev See https://eips.ethereum.org/EIPS/eip-4973
+///  Note: the ERC-165 identifier for this interface is 0x6352211e.
+interface IERC4973 /* is ERC165, ERC721Metadata */ {
+  /// @dev This emits when a new token is created and bound to an account by
+  /// any mechanism.
+  /// Note: For a reliable `_from` parameter, retrieve the transaction's
+  /// authenticated `from` field.
+  event Attest(address indexed _to, uint256 indexed _tokenId);
+  /// @dev This emits when an existing ABT is revoked from an account and
+  /// destroyed by any mechanism.
+  /// Note: For a reliable `_from` parameter, retrieve the transaction's
+  /// authenticated `from` field.
+  event Revoke(address indexed _to, uint256 indexed _tokenId);
+  /// @notice Find the address bound to an ERC4973 account-bound token
+  /// @dev ABTs assigned to zero address are considered invalid, and queries
+  ///  about them do throw.
+  /// @param _tokenId The identifier for an ABT
+  /// @return The address of the owner bound to the ABT
+  function ownerOf(uint256 _tokenId) external view returns (address);
+}

assets/eip-4973/src/interfaces/IERC721Metadata.sol

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: CC0-1.0
+pragma solidity ^0.8.6;
+
+interface IERC721Metadata {
+  function name() external view returns (string memory);
+  function symbol() external view returns (string memory);
+  function tokenURI(uint256 tokenId) external view returns (string memory);
+}