Compare circulating supply with unlock disclosures

Practical guide · prepared 19 September 2026. Sources were checked for this workflow; linked interfaces and policies can change. Research scope.

Three quantities are usually being collapsed

totalSupply() is an ERC-20 contract read. Unlocked supply is an allocation-schedule claim. Circulating supply is a classification of which unlocked units are actually available to the market. They can differ without any arithmetic error. Treasury tokens may be technically transferable but excluded by a data provider; vested tokens may remain unclaimed; emissions may mint over time; burns may reduce supply; and the token may exist on several chains. Record every figure with an as-of date and definition before comparing percentages.

Build a supply bridge

1. Identify every canonical token contract and chain. Read totalSupply() at a recorded block, then add or reconcile chain-specific supplies according to the issuer's architecture.
2. List mint and burn powers, caps and their controllers. A displayed maximum supply is not the same as present supply.
3. Copy each allocation bucket from first-party tokenomics: community, team, investors, treasury, liquidity and any emissions pool. Preserve cliffs, start dates, cadence and whether a date is fixed or governance-controlled.
4. Map vesting contracts and disclosed treasury addresses where available. Separate 'unlocked by contract' from 'transferred into active circulation'.
5. Compare the project's stated circulating figure with the methodology of each dashboard. Put unexplained differences in an unknown row instead of forcing the totals to agree.

The contract interface described in the ERC-20 standard guide gives a total, not an ownership map. The next workflow, tracing revenue to token rights, addresses a different question; neither supply scarcity nor an unlock schedule creates an entitlement.

Hypothetical example

Hypothetical: SAMPLE reports a one-billion cap, totalSupply() returns 800 million, the project calls 240 million circulating and a dashboard shows 270 million. The schedule says 100 million team tokens are unlocked, but 70 million remain in a disclosed vesting address. A defensible worksheet has separate rows for minted supply, burned units, contract-locked units, unlocked-but-held units, treasury-controlled units and provider-classified circulation. The 30-million disagreement becomes a question about definitions or undisclosed addresses, not evidence of fraud.

Use disclosures as claims with control paths

World's whitepaper labels its unlock curve an upper bound on circulating supply because governance controls how quickly community tokens enter circulation. OpenLedger's documentation separately specifies cliffs and linear schedules for allocation buckets. Those examples show why 'unlock' cannot be interpreted without reading who controls distribution after the cliff. For every bucket, ask whether release is enforced by immutable code, an upgradeable vesting contract, a multisig or a written commitment.

Limits and decision criteria

A useful comparison reconciles all known categories to present total supply, quantifies the unexplained remainder and leaves material unknowns unresolved rather than declaring the worksheet sufficient. Address ownership can change, custodians aggregate users, bridges create representations, and an unlocked holder may never sell. Unlock analysis estimates potential availability and control concentration. It does not predict market supply, price or holder behaviour, and it is not investment advice.