Token decimals and supply decisions that cannot be revisited

Decimals in one paragraph

Decimals is a single unsigned byte in the mint account that tells interfaces where to put the decimal point. The token program itself only ever works in whole raw units; it has no concept of a fraction. Decimals is written once, by the instruction that initialises the mint, and there is no instruction anywhere in the token program that changes it afterwards.

Everything that follows from that is arithmetic. A displayed balance is the raw amount divided by ten to the power of decimals. A transfer instruction takes a raw integer, not the number a user typed. And the smallest transferable quantity your token will ever have is fixed at the moment the mint is initialised.

Raw units and display units

Every amount stored on chain, in the mint supply field and in every token account, is a whole number of raw units. The conversion to what a person reads is done by software at the edges. Getting this wrong is the classic first-launch mistake: minting a supply that is a billion times smaller or larger than intended because a raw amount was confused with a display amount.

SOL itself works the same way. One SOL is 1,000,000,000 lamports, which is exactly a nine-decimals arrangement, and the base transaction fee of 5,000 lamports is 0.000005 SOL. Once you have internalised the lamport relationship, every token amount on Solana reads the same way, as described in the Solana developer documentation.

Choosing a decimals value

There is no protocol-preferred value; the byte accepts anything up to its own range and the program does not care. What exists instead are conventions, and conventions matter because the software around your token was written by people who expected them.

Nine decimals mirrors SOL and is the most common default for tokens produced by Solana tooling. Six is widely used by stablecoin issuers on the network and keeps raw integers smaller, which is easier to read in a transaction inspector. Zero is correct for genuinely indivisible units such as a ticket, a membership or a collectible where half of one makes no sense. Values above nine are legal and unusual, and they buy granularity that almost nothing needs.

The practical way to decide is to write down the smallest amount you ever want a person to be able to hold or send, then pick the smallest decimals value that represents it. If a token is intended to be worth a large amount per unit, more granularity helps. If it is intended to have an enormous supply, fewer decimals leaves more headroom under the ceiling described in the next section.

One further consideration is classification. The metadata standard assigns a token standard partly from the decimals value, so a token created with zero decimals and a supply above one is treated as a fungible asset rather than as an ordinary fungible token. Wallets branch on that classification when they decide whether to list a balance among currencies or among collectibles, so a decimals value picked for arithmetic reasons can change where the token appears on a screen.

The last input is inertia. Whatever value you choose propagates into every integration: the amount fields in your own scripts, the figures in your documentation, the raw numbers a partner has to handle, and the examples people copy from each other. Changing a convention that has spread is a much larger job than picking it carefully once, and unlike the on-chain field, the documentation errors are the ones that keep resurfacing years later.

The 64-bit ceiling

Supply is stored as a 64-bit unsigned integer. The largest value it can hold is 18,446,744,073,709,551,615 raw units. That is a hard protocol limit, not a convention, and it interacts directly with your decimals choice because raw units are what get counted.

The same ceiling applies to individual token account balances, which is only relevant in extreme cases but is worth knowing exists. In normal designs the constraint that bites is the supply one, and it bites early for anyone planning very large headline numbers with high granularity.

Why supply has no cap field

The mint account has a supply field. It does not have a maximum-supply field, a cap field, or a schedule field. The token program has nothing to compare a new mint-to instruction against, so it cannot refuse one on the grounds that a cap would be exceeded. The only thing that stops issuance is the absence of a mint authority.

This is the source of a persistent misreading. An explorer shows total supply, a project publishes the same number as its maximum, and a reader treats the two as the same claim. They are not. One is a fact about the present state of an account; the other is a statement about future intentions, enforced only if the mint authority field reads none. The SPL Token documentation describes the mint layout directly, and there is no cap in it.

The practical reading rule is short. Read supply and mint authority together, always, in that order, and never quote one without the other. A supply of one billion with a live mint authority is a snapshot. A supply of one billion with a revoked mint authority is a ceiling that cannot rise. The full behaviour of that field is covered on the authorities note.

How a fixed supply is produced

A fixed supply is not a setting. It is the result of a two-step sequence that a project chooses to perform, and the second step is permanent.

1. Mint the intended total. One or more mint-to instructions bring the supply field to the number you want, expressed in raw units. Verify the raw figure against your decimals before signing, because step two removes the ability to correct it.
2. Revoke the mint authority. A set-authority instruction with an empty new authority clears the field. From that moment no key can create another unit of the token, and no key can restore the power.

Both steps are visible on chain forever. A reader can see the mint transactions, see the set-authority transaction and see the resulting empty field, without needing anything from the project. That verifiability is the entire value of the arrangement; a fixed supply that is asserted but not signed is just a sentence on a website.

There is a middle option that gets overlooked. Transferring the mint authority to a multisig or to a program-derived address controlled by governance keeps the power but distributes it, which suits tokens with a real emission schedule. It is weaker than revocation and much stronger than one hot key, and it is checkable in the same single query.

What burning changes

The burn instruction destroys raw units from a token account and reduces the mint supply field by the same amount. It is signed by the account owner or a delegate, not by the mint authority, so any holder can burn their own balance whether or not the project wants them to.

Two consequences follow. Supply can therefore fall at any time without the project doing anything, which is why the accurate phrasing for a revoked mint authority is that supply cannot grow rather than that it is frozen. And burning is irreversible in the same way minting is not: the units are gone, and recreating them requires a mint authority that a fixed-supply token no longer has.

Burning is also the mechanism behind liquidity provider token burns, which is a different subject that gets confused with this one. Burning LP tokens removes the ability to withdraw the underlying pool, which is a statement about liquidity custody rather than about token supply. It appears in the field guide because a reader checking supply often means to be checking that instead.

What decimals do not affect

Decimals is a display parameter. It does not change value, it does not change cost, and it does not change how the token behaves in a pool. Being explicit about this saves a surprising amount of argument.

• It does not change price. Price is what someone pays in a pool, and the pool works in raw units on both sides.
• It does not change market capitalisation, which is supply multiplied by price, and both terms move together when the decimal point moves.
• It does not change transaction fees. The base fee is 5,000 lamports per signature regardless of the token being moved.
• It does not change rent. A token account is 165 bytes at 0 decimals and 165 bytes at 9.
• It does not change what a router can do, because routers work in raw units and convert only at the interface.

The last point extends to the market layer generally. Post-launch tooling is denominated in SOL rather than in your token's units, which is why a published Solana volume bot cost is quoted in SOL or as a proportion of routed value, and why the same quote applies to a token with two decimals and a token with nine.

The same holds for how such tools are configured. A SOL volume bot sets its trade sizes in SOL because SOL is the unit every pair on the network shares, and it converts to raw token units at execution exactly as a wallet does when a person types an amount. Your decimals choice never reaches that layer.

The decision list

Answer these before the initialise-mint instruction is signed. Every one of them is either permanent or expensive to change later, and none of them takes more than a minute to settle in advance.

• What is the smallest amount a person should ever be able to hold? That answer is your minimum decimals.
• What is the largest supply you might ever want? Check it against the 64-bit ceiling at your chosen decimals before committing.
• Is the initial mint amount written in raw units, and has someone else checked the zero count?
• Will the mint authority be revoked, and if so, in the same transaction as the mint or later? Both are defensible; only one of them leaves room to correct an error.
• If the authority is being kept, where will it live, and is that arrangement published and checkable on chain?
• Does the number you plan to publish as supply match the raw supply divided by the decimals divisor, exactly?
• Have you confirmed the resulting state on an explorer such as Solscan before announcing anything?

What this note does not do

It does not recommend a supply figure or a decimals value for any particular project. Those are design choices bound up with distribution, pricing and the audience, and no general rule survives contact with a specific token. What the note fixes is the arithmetic, so that a choice can be made deliberately rather than accepted from a default field.

It does not treat supply as an economic argument. Whether a low supply with a high unit price behaves differently from a high supply with a low unit price is a question about how people react to numbers, not a question about mint accounts, and this workshop has no data on it and will not invent any.

And it does not describe any way of presenting a supply figure that would mislead a reader. There is nothing here about publishing a display supply that does not match the raw amount, about timing a mint around a screenshot, or about wording a cap so that a live mint authority sounds harmless. The arithmetic is given so it can be checked, in one direction only.

Questions the workshop is asked