Total Supply Monitor

Overview

The Total Supply Monitor is a daily monitoring tool that tracks the total supply of a token contract on a blockchain network. It queries on-chain mint and burn event logs via Dune Analytics and compares the result against user-defined expected values.

An alert is emitted on every scheduled run:

• Info — the current issued supply is within the expected limit (no anomaly detected)

• Warning / custom — the current issued supply exceeds the expected issued amount (potential over-minting)

---

Expected Total Supply

The hard cap or maximum authorised supply of the token, expressed as a whole-unit integer (i.e. already divided by token decimals).

Field	Type	Required
expected_total_supply	int	Yes

Example: for a token with a 1 billion cap and 18 decimals, set this to 1000000000.

---

Expected Total Issued

The maximum number of tokens that should currently be in circulation. The detector compares the live on-chain issued supply against this value.

Field	Type	Required
expected_total_issued	int	Yes

• If current issued supply ≤ expected_total_issued → Info alert (supply is within bounds)

• If current issued supply > expected_total_issued → Warning alert (supply exceeds expectation)

---

Decimals

The number of decimal places used by the token contract. Used to convert raw on-chain values to human-readable units before comparison.

Field	Type	Default
decimals	int	18

Most ERC-20 tokens use 18 decimals. Override this for tokens that use a different precision (e.g. USDC uses 6).

---

Severity

Controls the severity level assigned to mismatch alerts (when the issued supply exceeds expected_total_issued).

Value	Behaviour
(not set)	Defaults to Medium (0.5) on mismatch; Info (0.1) on match
Custom value	Applied on mismatch; Info is always used on match

• Info alerts are always emitted when the supply is within bounds, regardless of this setting.

• This field only affects the severity of anomaly alerts.

---

Alert Metadata

Every alert emitted by this monitor includes the following fields in its metadata:

Field	Description
monitored_contract	Address of the token contract being monitored
expected_supply	Configured expected_total_supply value
expected_issued	Configured expected_total_issued value
current_issued	Live total supply queried from Dune Analytics (adjusted for decimals)
current_minted	Total tokens minted to date (adjusted for decimals)
current_burned	Total tokens burned to date (adjusted for decimals)

---

Alert Types

Event Type	Severity	Trigger Condition
total_supply_issued_match	Info	current_issued ≤ expected_total_issued
total_supply_issued_mismatch	Warning (or custom)	current_issued > expected_total_issued