ERC-5615 ERC-1155 supply query extension (ERC-1155 Supply Extension)
Final · NFTs & multi-token · created 2023-05-25
Standardizes the totalSupply function, which queries the total supply of a given id for ERC-1155 tokens, and the exists function, which checks whether that id exists.
Why it is needed
ERC-1155 is a multi-token standard in which one contract handles multiple kinds of tokens distinguished by id. However, base ERC-1155 has no function that tells how many tokens of a given id have been issued in total. So even when a wallet or app wanted to know the total quantity of a token, there was no standard way to rely on. In practice, implementations that report supply, such as OpenZeppelin's ERC1155Supply, were already in use, but unless the function names and behavior are fixed by a standard, readers cannot safely write common code. There is also the problem that an answer of zero supply cannot tell whether an id has not been minted yet or will never be minted. This ERC standardizes the existing practice as it is, so that any ERC-1155 token lets you check the total supply per id and its existence with the same functions.
What to implement
function exists(uint256 id) external view returns (bool);: Returns whether the given token id exists, has existed in the past, or may exist in the future.function totalSupply(uint256 id) external view returns (uint256);: Returns the total number of tokens with the given id, and returns 0 if that id does not exist.
In depth
exists answers existence broadly
exists(id) MUST return a single boolean indicating whether the token id exists, previously existed, or may exist. In other words, it is not simply about whether there is currently any supply, but tells whether that id is a meaningful id in this contract. So even for an id whose totalSupply is 0, exists can be true.
totalSupply returns 0 for a missing id
totalSupply(id) MUST return the number of tokens with the given id, and MUST return 0 if that id does not exist. It does not revert for an id that does not exist, and the design intends that contracts for which the existence of an id matters use exists instead of totalSupply.
Distinguishes the two meanings of zero supply
There are two cases in which totalSupply is 0. Either no token of that id has been minted yet, or the id will never be minted. exists was included to tell these two apart. The original text states explicitly that exists can return false even when totalSupply is 0.
ERC-165 detection is not required
An implementation MAY support ERC-165 interface detection, but a consumer of this interface MUST NOT depend on ERC-165. This is because the interface is simple enough that the extra complexity is unnecessary, and requiring ERC-165 would be incompatible with existing implementations that are already deployed.
It standardizes existing practice as it is
This ERC does not invent a new feature but standardizes a practice that was already in use. The totalSupply and exists functions were modeled on ERC-721 and ERC-20, and designed to be backward compatible with OpenZeppelin's ERC1155Supply implementation. Because the status is Final, this is a finalized standard.