Supply and decimals

EN source master · P08-L02 · 45 minutes estimated · needs_review

A decimal error can turn nine thousand tokens into nine tokens without changing a single underlying balance. A mislabeled supply definition can make two correct calculations look contradictory. Before valuing an asset or describing distribution, establish units, context and exclusions.

This lesson teaches exact raw-to-display conversion and a supply reconciliation. It builds on verified identity rather than assuming every token uses eighteen decimals.

Keep integers and presentation separate

Let R be a raw integer amount and d the verified decimal count. Its ordinary displayed quantity is R divided by 10^d. The raw unit is the indivisible accounting unit in this model; decimals define presentation precision, not the number of owners or a market price. Solana mint state includes supply and decimals [S08-TOKENS]. The ERC-20 decimals method is optional in the standard [S08-ERC20]; unavailable metadata must not be replaced by a guessed default.

Use integer strings or exact decimal arithmetic. A spreadsheet or JavaScript floating-point number can round a large raw value before you divide it. Store the original integer, decimal count, context and display value as distinct fields. If a tool reports a rounded display value, calculate from raw input rather than treating the display as exact.

A reported zero and a missing result are different. Zero is a valid measurement under a stated source/context; null or timeout describes missing evidence. A missing decimal count prevents reliable ordinary-unit conversion even when raw balances remain available. Record the raw amount without claiming a token quantity.

Reconcile measures before comparing them

Total supply describes the protocol's accounting measure at a specified context. Circulating supply requires a defined inclusion policy. Treasury inventory, vesting and bridge custody may receive different treatment from different publishers. A label without a policy cannot resolve a discrepancy.

Solana getTokenSupply returns raw amount and decimals with response context [S08-SUPPLY]. This is not an independently defined circulating measure. Do not subtract a publisher's already-adjusted supply from raw totals without inspecting what it excluded.

For a closed standard accounting fixture, balances should reconcile to the supplied total. Real investigations must inspect whether the export is exhaustive, uses matching contexts and decodes extensions correctly. Some token mechanisms complicate simple balance summation; state that limitation rather than forcing every asset into this model.

Exclusions do not destroy tokens. Removing treasury units from an analytical denominator produces an adjusted statistic, not a supply-changing ledger event. Likewise, a transfer to an address described as a burn address is not automatically a reduction in the protocol's totalSupply. The actual burn mechanism and accounting change need evidence.

Track changes without changing the unit

A mint increases total accounting supply in the fixture. A protocol burn decreases it. Ordinary transfers between included accounts rearrange ownership without changing the total. If the supplied sequence is complete, new supply equals old supply plus minted units minus burned units.

Attach context to each event and amount. If a later snapshot differs from your event sum, test incomplete coverage, an inconsistent mint or incorrect precision before declaring manipulation. A difference is a reconciliation failure needing investigation; it is not an intent verdict.

Decimals must be verified for the exact object and context. Two assets with the same symbol can have different precision. An incorrect feed setting can produce a factor-of-one-thousand discrepancy when d differs by three. Never “repair” the raw balance to make it agree with a website.

Use a comparison bridge

When two reports disagree, lay out raw amount, decimals, unit conversion, snapshot context and exclusion policy in columns. This makes different questions visible. One report may be correct for total supply while another correctly uses an adjusted denominator. They should be named separately, not averaged.

If two sources claim the same definition at the same context and still disagree, retain both records and an unresolved discrepancy. Do not select the larger number because it looks safer or the smaller because it improves a concentration percentage. A bounded finding states the mismatch and the next check.

Percentages cancel a common decimal factor only when numerator and denominator refer to the same token precision and scope. Comparing a raw numerator with a displayed denominator produces a meaningless result. It can be numerically neat and still be wrong.

Communicate quantities reproducibly

Write units on every row. “2,500” alone could mean raw units, tokens or dollars. This lesson uses fictional token units and supplies no market price or dollar valuation. A correct supply reconciliation says nothing about executable liquidity, price appreciation or issuer legitimacy.

Preserve full precision in the answer key and round only for display. Explain rounding policy when a fraction repeats. For this fixture, conversions terminate exactly, so no rounded residual needs to be hidden.

• Raw amount: integer accounting units.
• Decimals: base-ten display precision.
• Total supply: protocol accounting measure at a context.
• Adjusted supply: analyst's declared exclusion measure.
• Reconciliation: comparison of compatible sums and changes.
• Snapshot context: state boundary for an observation.

ILLUSTRATIVE — FIX-P08-02. MINT-SUPPLY on SIM-SOL-A, basic standard accounting model, d=6 at synthetic S0. Exhaustive balances are supplied; all identifiers are invalid labels.

T0 raw total is 9,000,000,000. Feed F1 mistakenly sets d=9 and displays 9. Policy E excludes B3/B4 only. A complete synthetic event sequence to S1 burns 500,000,000 raw units and mints 750,000,000; there are no other supply changes. S1 account allocation is not supplied.

OBSERVED in fixture: S0 precision, total and balances are supplied. F1 uses the wrong precision.

INFERRED: S0 total is 9,000 tokens; policy E adjusted quantity is 4,000. Complete events imply S1 total 9,250 tokens.

UNKNOWN: Any real circulating measure, S1 allocation, price or liquidity.

INSUFFICIENT EVIDENCE: The adjusted 4,000 is not a protocol burn or universal circulating supply. The decimal mismatch is not proof of malicious intent.

Assuming eighteen decimals; mixing raw/display units; counting exclusions as burns; importing rounded integers; comparing unmatched contexts; and naming a policy-adjusted measure “the” circulating supply.

Convert T0 and all four balances. Reconcile S0. Calculate policy E's denominator, Owner A's share of total and adjusted quantity, and S1 total. Explain F1's factor error and whether S1 holder concentration can be calculated.

• Verify exact asset and decimal count.
• Preserve raw integers.
• Label units and rounding.
• Reconcile matching contexts.
• State every exclusion and its policy.
• Keep missing later balances unknown.

Precision and definition come before supply comparison. A policy exclusion changes the analytical denominator; a ledger event changes accounting supply.

Raw units are not displayed tokens. Different supply policies answer different questions. A correct total does not provide current distribution or liquidity.

Show raw→display conversion ladder d=6, S0 balance reconciliation, separate total 9,000 and policy E4,000 bars. Mark F1 d=9 as a precision mismatch; show S1 total 9,250 without a fabricated holder chart.

Illustrative units and supply policies; no price or real circulating estimate.

Use deterministic SVG/HTML or charts with text alternatives, dark navy/black and restrained cyan, electric blue and violet. Label every quantity and uncertainty. At 390px stack panels; 768px/desktop and Arabic RTL verification remain future asset work. Keep identifiers LTR and factual axes/edge directions unchanged. Use only the official supplied ZECOIN mark if branding is added. Both records are specifications, not delivered assets.

Use RADAR for the lesson's bounded educational purpose only if network support, exact identity, fields and provenance are verified. No runtime endpoint or provider capability is asserted by this content. Use the embedded offline fixture without paid access. Missing data stays unknown; no wallet connection, transaction signature, token launch or live trade is required. Academy progress, payments and referrals never change Radar evidence. A Diagnostic Passport preserves observations and limits, not a price prediction or safety certificate.

• Solana Assets — Mint/account/program identity and decimals; distinguish account ownership fields. Checked 2026-09-30.
• Solana getTokenSupply — Raw supply, decimals and RPC response context; not a circulating-supply definition. Checked 2026-09-30.
• ERC-20 Token Standard — Standard interface; optional name, symbol and decimals; not privilege or identity certification. Checked 2026-09-30.

Documentation supports mechanisms, not fictional dataset values. All examples and exercise records are original ILLUSTRATIVE material, frozen in this file. S0/S1 are synthetic context labels; observedAt is null because no live or historical ledger measurement was collected. Re-review documentation and actual deployed behavior before any publication or integration.

P08-L03 after the worked exercise and quiz review.