Documentation Index
Fetch the complete documentation index at: https://docs.extractor.live/llms.txt
Use this file to discover all available pages before exploring further.
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:
- Supply change alert — a single mint or burn moves the circulating supply by more than the configured percentage threshold
- 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.
| Field | Type | Required |
|---|
threshold | float | Yes |
| Example value | Meaning |
|---|
0.01 | Alert when supply changes by ≥ 1% in a single event |
0.05 | Alert when supply changes by ≥ 5% in a single event |
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.
| Field | Type | Default |
|---|
locker_address | list[string] | [] |
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.
| Sub-field | Type | Description |
|---|
expected_date | string (YYYY-MM-DD) | The date on which the scheduled supply change should occur |
expected_change | float | Expected fractional change (positive = inflation, negative = deflation) |
| Schedule entry | Meaning |
|---|
expected_date: 2025-06-01, expected_change: 0.05 | Expect a 5% increase in supply on 1 June 2025 |
expected_date: 2025-09-01, expected_change: -0.02 | Expect a 2% decrease in supply on 1 September 2025 |
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
| Event Type | Trigger |
|---|
circulation_supply_change | A single mint or burn changes the supply by ≥ threshold |
inflation_detected | The actual daily supply change differs from the scheduled expected_change |
circulation_supply_change
Fired when a mint or burn in a single transaction causes the supply to move beyond the threshold.
| Field | Description |
|---|
tx_hash | Hash of the transaction containing the mint or burn |
tx_from | Sender of the outer transaction |
tx_to | Recipient of the outer transaction |
contract | Monitored contract address (the transaction target) |
monitored_contract | Token contract address that emitted the Transfer event |
recipient | Address that received the minted tokens, or the burn address |
prev_supply | Circulating supply before the event (raw integer) |
curr_supply | Circulating supply after the event (raw integer) |
diff | Raw token amount minted (positive) or burned (negative) |
change_percentage | Relative supply change, formatted to 4 decimal places (e.g. 1.2345%) |
inflation_detected
Fired once per day when the previous day’s supply change deviates from the scheduled expectation.
| Field | Description |
|---|
tx_hash | Hash of the first transaction of the new day that triggered the check |
tx_from | Sender of that transaction |
tx_to | Recipient of that transaction |
contract | Monitored contract address |
monitored_contract | Token contract address |
previous_supply | End-of-day supply from the previous day |
current_supply | Supply at the time of the check |
current_change | Actual fractional supply change, formatted to 10 decimal places |
expected_change | Scheduled expected fractional change, formatted to 10 decimal places |
expected_date | The date (YYYY-MM-DD) for which the deviation was detected |
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.