ERC-7538 Multiplier token (Multiplicative Tokens)
Draft · Tokens · created 2023-10-18
A standard that adds a multiplier field to token metadata so that wallets and other clients display the user's balance multiplied by this factor. It enables fractional-unit tokens and increments like 0.5.
Why it is needed
Various projects need to create a range of tokens, including fungible and non-fungible tokens. Existing standards are well suited to such issuance, but some do not support expressing tokens in fractional units. Some tokens also want to build in inflation or deflation mechanisms that automatically increase or decrease supply, and may want to allow transfers in unconventional increments like 0.5. The existing decimals approach can only divide values in powers of 10, making it hard to accommodate these needs. This standard solves the problem by adding a multiplier field to ERC-1046 metadata and computing the displayed value as the multiplier times the amount.
What to implement
multiplier: string | undefined;: A positive multiplier used when constructing the value shown to the user. If undefined, it is treated as 1, and because it is an exact base-10 value, implementers must be careful of floating-point errors.decimals: never;: This means the standard no longer supports the decimals field.
In depth
ERC-1046 metadata extension
This standard extends token types compatible with ERC-1046, in particular ERC-20 and ERC-1155. Tokens that use a multiplier MUST implement the MultiplierMetadata interface within the resolved ERC-1046 tokenURI. In other words, the multiplier goes into the metadata document reached via tokenURI rather than into a contract function. The Rationale explains that leveraging ERC-1046 improves gas efficiency in most cases.
Rules for the multiplier field
multiplier is a positive factor used to construct the representation shown to the user. Its type is string | undefined, and if undefined it is treated as the default value of 1. This value is an EXACT VALUE in base 10, so implementers must be careful of floating-point errors. The Rationale explains that representing the number as a string allows higher precision when needed, and that using a multiplier instead of decimals allows handling increments that are not powers of 10 and makes inflation and deflation handling smoother.
decimals prohibited
In the metadata interface, the decimals field is declared with type never and is no longer supported. Furthermore, token contracts that use a multiplier MUST NOT have a method named decimals. If both approaches coexist, the computation of the displayed value would conflict, so this standard unifies on a single multiplier.
Incompatibility with the existing approach
This standard is incompatible with the method named decimals on ERC-1046-compatible token standards, and with the decimals field of ERC-1046. This means you cannot simply add a multiplier on top of an existing implementation that displays balances based on decimals.
Proposal status
This document is a proposal in Draft status, created on October 18, 2023. The content may change going forward, so it is advisable to check the latest status before implementing.
Things to watch out for
- Potential exploitation of rounding errors: Mishandling the multiplier field can produce rounding errors, and a malicious actor could exploit this. Contracts MUST handle the multiplier precisely to avoid such issues.
- The multiplier must be positive: To prevent display problems, the multiplier MUST be positive. Zero is not positive.
- Display problems with extreme multipliers: Particularly large or small multipliers MAY cause display difficulties. Even so, wallets SHOULD try to display the full number as long as doing so does not create UI/UX problems or additional security issues.