Bitcoins Rainbow / Knowledge library · Foundations · 2 min read
Display units are a convention
Many fungible token contracts store balances as whole-number quantities. A decimals value tells interfaces how to display those quantities in familiar units. If a token uses six decimals, a raw balance of 1,000,000 is commonly displayed as one token. More decimals do not make a token more valuable or increase its economic scarcity.
Names and symbols are also display information. Two unrelated contracts can share the same symbol while having different decimals and completely different rights. Identify an asset by network and contract before interpreting its balance, especially when importing a token manually.
A hypothetical reconciliation
A finance team reads a raw balance of 12,345,678 from a token using six decimals. The human-readable amount is 12.345678. For a second token using eighteen decimals, the same raw integer represents a far smaller displayed amount. Comparing raw integers directly would make the balances look equal when they are not.
Suppose the team wants to send 2.5 units of the six-decimal token. Its transaction input represents 2,500,000 base units. A script accidentally applying eighteen decimals would request a vastly different amount. A wallet may reject the transfer for insufficient balance, but that rejection is not an adequate substitute for correct conversion.
| Decimals | Raw quantity | Displayed units |
|---|---|---|
| 0 | 25 | 25 |
| 6 | 2,500,000 | 2.5 |
| 18 | 2,500,000,000,000,000,000 | 2.5 |
Rounding can hide real differences
A dashboard showing two decimal places may display a very small balance as zero even though the raw quantity is nonzero. Conversely, rounding an available balance upward can produce an attempted transfer larger than the actual spendable amount. Preserve precision in records and round only for presentation.
Prices and balances need compatible units. Multiplying a price per whole token by a raw base-unit balance overstates value by the decimal scaling factor. The same issue affects total-supply calculations, portfolio imports, and spreadsheets assembled from different APIs.
For software, use integer arithmetic or an appropriate decimal representation rather than ordinary floating-point numbers for monetary quantities. Explicitly label whether each field contains raw units or display units. A column called simply “amount” invites errors when data passes between systems.
Unit handling checklist
- Confirm decimals from the actual contract and check whether the metadata is supported.
- Keep raw quantities and formatted amounts in separately named fields.
- Record price units alongside prices and snapshot times.
- Apply rounding rules consciously when displaying or preparing a transaction.
- Test tiny, fractional, and large example amounts before processing real transfers.
A useful manual check is to convert a small displayed amount to base units and back. If the round trip does not reproduce the intended quantity, stop before signing. This catches mismatched metadata and scaling errors with little effort.
Frequently asked questions
Do eighteen decimals mean more tokens exist?
No. Decimals control subdivision and display. Supply depends on issuance rules and quantities, not the number of decimal places alone.
Can I assume every ERC-20 exposes decimals?
No. The original standard treats that metadata as optional. Applications need a deliberate strategy for missing or unusual metadata.
