ERC-7632 Named token interface (Interfaces for Named Token)
Draft · Names & metadata · created 2024-02-08
An interface standard that attaches a string name (tokenName) to a token and allows conversion between the name and the numeric ID (tokenId). It lets marketplaces, wallets, and apps handle named tokens in the same way.
Why it is needed
Current token standards identify each token only by a numeric ID (tokenId) of type uint256. As a result, even if an NFT has a name, marketplaces, explorers, wallets, DeFi, and dApps have no standard way to read or handle that name. If each contract stores names and links them to numeric IDs differently, it becomes difficult for multiple services to build common features for looking up tokens by name or operating on input names. This standard defines a common interface and set of rules for converting between a name (tokenName) and a numeric ID (tokenId), allowing any service to display and manipulate named tokens in the same way.
What to implement
function idToName(uint256 _tokenId) external view returns (string);: Takes a token's numeric ID (tokenId) and returns that token's name (tokenName).function nameToId(string memory _tokenName) external returns (uint256);: Takes a token name and returns the corresponding numeric ID.newName(uint256 indexed tokenId, string tokenName): An event recommended to be emitted when a new name is introduced, signaling which name was attached to which ID.function isValidTokenName(string memory _tokenName) external view returns (string);: A function in the extension interface that checks whether a given token name is valid.function normalizeTokenName(string memory _tokenName) external view returns (string memory);: A function in the extension interface that normalizes a token name into a defined canonical form and returns it.
In depth
Two compliance approaches: implementing the interface or using the default mapping
A compliant contract MUST support tokenName and the mapping between tokenName and tokenId. There are two ways to do this. 1a is implementing the IERC_NamedTokenCore interface, where idToName(uint256 _tokenId) returns the name and nameToId(string memory _tokenName) returns the ID. This approach is RECOMMENDED for all compliant contracts. 1b is for cases where IERC_NamedTokenCore is not implemented, in which case the contract MAY follow the default mapping rule uint256 tokenId = uint256(keccak256(tokenName)). The Rationale explains that the default mapping is allowed for convenience, while also permitting contracts to implement their own mapping scheme for flexibility.
Bidirectional single mapping rule and the newName event
When implementing IERC_NamedTokenCore, tokenId and tokenName MUST be a bidirectional single mapping. That is, if a tokenId exists, its tokenName must also exist and vice versa, and tokenId = nameToId(idToName(tokenId)) and tokenName = idToName(nameToId(tokenName)) must always hold true. It is also RECOMMENDED to emit a newName(uint256 indexed tokenId, string tokenName) event whenever a new name is introduced.
ByName counterpart methods
For every method in a compliant contract that uses a tokenId, it is RECOMMENDED to provide a counterpart method whose name ends in ByName. The counterpart method replaces every parameter of type uint256 tokenId with string memory tokenName, and its behavior MUST match that of the original method. This lets you use the same functionality by passing in a name directly instead of a numeric ID.
The IERC_NamedTokenExtension extension interface
A compliant contract MAY additionally implement the IERC_NamedTokenExtension interface. isValidTokenName(string memory _tokenName) checks the validity of a name, and normalizeTokenName(string memory _tokenName) returns the normalized form of a name. The Security Considerations section states that if non-unique tokenNames are allowed, developers must use this extension interface to declare a normalization mechanism.
Compatibility with existing token standards
This proposal is fully backward compatible with existing token contracts that use uint256 tokenId as a unique identifier, because it adds naming functionality on top without changing the existing ID scheme. Per the requires field in the preamble, ERC-165 (the interface detection standard) is required.
A Draft-stage proposal
This proposal is still in Draft status. Its interface and rules may change during discussion, and it should be understood that it has not been finalized as a standard. In fact, Rationale item 2 in the original text is left as an incomplete sentence.
Things to watch out for
- The assumption of uniqueness for names and IDs: This proposal assumes that tokenName and tokenId are unique across all tokens. If this assumption breaks down, the mapping between names and IDs no longer holds.
- Risk of confusion from non-normalized names: If names are not normalized, two different names can look similar and confuse users. If non-unique tokenNames are allowed, developers must use IERC_NamedTokenExtension to declare a normalization mechanism.