Skip to main content

​
Overview

The Circulation Supply Detector processes every incoming transaction and inspects its logs for ERC-20 Transfer events that represent token minting or burning. It maintains an in-memory circulating supply counter and fires alerts in two scenarios:
  1. Supply change alert — a single mint or burn moves the circulating supply by more than the configured percentage threshold
  2. Unexpected inflation/deflation alert — the actual supply change on a scheduled date differs from the expected value defined in the inflation/deflation schedule
Inflation/deflation schedule checks occur at most once per calendar day — on the first transaction processed after midnight UTC.

​
Threshold

The minimum relative supply change (as a decimal fraction) that triggers a circulation_supply_change alert. Applied independently to each mint and burn event. The comparison uses the absolute value of the change, so both large mints and large burns trigger at the same threshold.

​
Locker Addresses

A list of contract addresses that hold locked or vested tokens. Their balances are excluded from the circulating supply when the initial supply is fetched from the Transpose API at startup. Common examples include team vesting contracts, treasury multisigs, and future-reserve allocations. Tokens held in these addresses are not considered to be in active circulation.
Locker addresses affect only the initial supply baseline. Runtime mint/burn events are always applied to the full tracked supply regardless of recipient.

​
Inflation/Deflation Schedule

An optional list of expected supply change events on specific calendar dates. When the schedule is configured the detector verifies, on the first transaction of each day, whether the previous day’s actual supply change matched the expectation. Examples: If the actual supply change on a scheduled date does not match expected_change, an inflation_detected alert is fired.
The schedule check compares the end-of-previous-day supply against the supply at the time of the first transaction of the next day. If no schedule entry exists for a date, no check is performed.

​
Alert Types

​
Alert Metadata

​
circulation_supply_change

Fired when a mint or burn in a single transaction causes the supply to move beyond the threshold.

​
inflation_detected

Fired once per day when the previous day’s supply change deviates from the scheduled expectation.

​
FAQ

What is a locker address? A contract that holds locked or vested tokens excluded from the circulating supply — such as team allocation wallets, vesting contracts, or reserve funds. These are subtracted from the total supply when the baseline is established at startup. How should I define the threshold? Use a decimal fraction representing the minimum percentage change that warrants an alert. For example, 0.01 means 1%. The detector applies the threshold to the absolute size of each individual mint or burn relative to the supply at the time of the event. What is the inflation/deflation schedule? A predefined list of dates and expected fractional supply changes. The detector checks the previous day’s actual change against the schedule each morning. Positive values indicate expected inflation; negative values indicate expected deflation.