Blacklist Tracker Changelog
Full version history of Blacklist Tracker methodology decisions, from v1.0 to v3.7.
Latest Version
Balance recovery accuracy and provider resilience
Remediates 16 audit findings across the balance recovery pipeline, freeze-ledger cache, and aggregation layer. Eliminates silent wrong-data paths, adds Ethereum mainnet dRPC/chain-RPC fallback, and fixes gold stablecoin USD conversion in all enrichment paths.
Impact Snapshot
- Invalid block tags now return null instead of silently querying latest balance (Critical)
- Ethereum mainnet historical balance lookups now fall through dRPC and chain-RPC before Etherscan (Critical)
- Tron REST API returns null for missing token entries instead of false zero (Major)
- PAXG/XAUT events now receive USD conversion in enrichment and backfill paths (Major)
v3.7Apr 8, 2026Balance recovery accuracy and provider resilience
Remediates 16 audit findings across the balance recovery pipeline, freeze-ledger cache, and aggregation layer. Eliminates silent wrong-data paths, adds Ethereum mainnet dRPC/chain-RPC fallback, and fixes gold stablecoin USD conversion in all enrichment paths.
- Invalid block tags now return null instead of silently querying latest balance (Critical)
- Ethereum mainnet historical balance lookups now fall through dRPC and chain-RPC before Etherscan (Critical)
- Tron REST API returns null for missing token entries instead of false zero (Major)
- PAXG/XAUT events now receive USD conversion in enrichment and backfill paths (Major)
DetailsHide details
Balance recovery accuracy and provider resilience
Remediates 16 audit findings across the balance recovery pipeline, freeze-ledger cache, and aggregation layer. Eliminates silent wrong-data paths, adds Ethereum mainnet dRPC/chain-RPC fallback, and fixes gold stablecoin USD conversion in all enrichment paths.
- Invalid block tags now return null instead of silently querying latest balance (Critical)
- Ethereum mainnet historical balance lookups now fall through dRPC and chain-RPC before Etherscan (Critical)
- Tron REST API returns null for missing token entries instead of false zero (Major)
- PAXG/XAUT events now receive USD conversion in enrichment and backfill paths (Major)
Impact Notes
- Invalid block tags now return null instead of silently querying latest balance (Critical)
- Ethereum mainnet historical balance lookups now fall through dRPC and chain-RPC before Etherscan (Critical)
- Tron REST API returns null for missing token entries instead of false zero (Major)
- PAXG/XAUT events now receive USD conversion in enrichment and backfill paths (Major)
- Zero-balance override restricted to gold stablecoins only, preventing false non-zero cache entries (Major)
- XAUT now uses its own price entry instead of PAXG price (Major)
- Destroyed records excluded from activeFrozenTotal (Major)
- New Tron blacklist/unblacklist events immediately marked permanently_unavailable (Major)
v3.6Mar 27, 2026Freeze-ledger quarter attribution for the public chart
The public blacklist chart now buckets the persistent freeze ledger by blacklist quarter instead of summing raw event-time blacklist rows, so the quarterly bars explain the same tracked frozen total shown in the summary cards.
- The `/api/blacklist-summary` chart now draws from `blacklist_current_balances` rather than raw `blacklist_events` intake amounts
- Each tracked balance is attributed to the latest recorded blacklist event for the same stablecoin/chain/address identity so re-blacklisted rows follow the active freeze cycle represented in the ledger
- Rows without a local blacklist timestamp fall back to the latest related event timestamp, then snapshot observation time, so tracked ledger value is not silently dropped from the chart
DetailsHide details
Freeze-ledger quarter attribution for the public chart
The public blacklist chart now buckets the persistent freeze ledger by blacklist quarter instead of summing raw event-time blacklist rows, so the quarterly bars explain the same tracked frozen total shown in the summary cards.
- The `/api/blacklist-summary` chart now draws from `blacklist_current_balances` rather than raw `blacklist_events` intake amounts
- Each tracked balance is attributed to the latest recorded blacklist event for the same stablecoin/chain/address identity so re-blacklisted rows follow the active freeze cycle represented in the ledger
- Rows without a local blacklist timestamp fall back to the latest related event timestamp, then snapshot observation time, so tracked ledger value is not silently dropped from the chart
Impact Notes
- The `/api/blacklist-summary` chart now draws from `blacklist_current_balances` rather than raw `blacklist_events` intake amounts
- Each tracked balance is attributed to the latest recorded blacklist event for the same stablecoin/chain/address identity so re-blacklisted rows follow the active freeze cycle represented in the ledger
- Rows without a local blacklist timestamp fall back to the latest related event timestamp, then snapshot observation time, so tracked ledger value is not silently dropped from the chart
v3.5Mar 27, 2026Persistent freeze-ledger snapshots and bootstrap reconciliation
The public frozen-total summary now uses a persistent freeze ledger instead of treating snapshot balances as a live current-state cache. Historical ETH/USDC, ETH/USDT, and TRON/USDT freeze rows were reconciled from the kyc.rip / stables.rip bootstrap so seized-and-burned balances remain visible after later unblacklist or destroy actions.
- Added tracked freeze-ledger metrics (`trackedAddressCount`, `trackedFrozenTotal`, `trackedAmountGapCount`) to blacklist summary responses
- Snapshot rows are now preserved across later unblacklist events instead of being deleted as if they were only live current balances
- Destroy events now persist their seized amount into the freeze ledger so burned balances remain counted
- Historical freeze-ledger bootstrap was reconciled against the external kyc.rip / stables.rip dataset for ETH USDC, ETH USDT, and TRON USDT
DetailsHide details
Persistent freeze-ledger snapshots and bootstrap reconciliation
The public frozen-total summary now uses a persistent freeze ledger instead of treating snapshot balances as a live current-state cache. Historical ETH/USDC, ETH/USDT, and TRON/USDT freeze rows were reconciled from the kyc.rip / stables.rip bootstrap so seized-and-burned balances remain visible after later unblacklist or destroy actions.
- Added tracked freeze-ledger metrics (`trackedAddressCount`, `trackedFrozenTotal`, `trackedAmountGapCount`) to blacklist summary responses
- Snapshot rows are now preserved across later unblacklist events instead of being deleted as if they were only live current balances
- Destroy events now persist their seized amount into the freeze ledger so burned balances remain counted
- Historical freeze-ledger bootstrap was reconciled against the external kyc.rip / stables.rip dataset for ETH USDC, ETH USDT, and TRON USDT
Impact Notes
- Added tracked freeze-ledger metrics (`trackedAddressCount`, `trackedFrozenTotal`, `trackedAmountGapCount`) to blacklist summary responses
- Snapshot rows are now preserved across later unblacklist events instead of being deleted as if they were only live current balances
- Destroy events now persist their seized amount into the freeze ledger so burned balances remain counted
- Historical freeze-ledger bootstrap was reconciled against the external kyc.rip / stables.rip dataset for ETH USDC, ETH USDT, and TRON USDT
v3.4Mar 27, 2026Active frozen-total ledger and Tron current-balance separation
Blacklist summary now distinguishes event-time amounts from active frozen balances, adds a dedicated current-balance cache for active blacklist records, and stops treating legacy Tron derived event amounts as authoritative history.
- Added `blacklist_current_balances` for current active blacklist balance snapshots
- Blacklist summary gained active-record metrics (`activeAddressCount`, `activeFrozenTotal`, `activeAmountGapCount`)
- Active Tron totals now prefer current TRC20 balances for active blacklist rows and destroy-event amounts when funds were seized and burned
- Legacy Tron `derived` blacklist/unblacklist event amounts are reset instead of being reused as event-time history
DetailsHide details
Active frozen-total ledger and Tron current-balance separation
Blacklist summary now distinguishes event-time amounts from active frozen balances, adds a dedicated current-balance cache for active blacklist records, and stops treating legacy Tron derived event amounts as authoritative history.
- Added `blacklist_current_balances` for current active blacklist balance snapshots
- Blacklist summary gained active-record metrics (`activeAddressCount`, `activeFrozenTotal`, `activeAmountGapCount`)
- Active Tron totals now prefer current TRC20 balances for active blacklist rows and destroy-event amounts when funds were seized and burned
- Legacy Tron `derived` blacklist/unblacklist event amounts are reset instead of being reused as event-time history
Impact Notes
- Added `blacklist_current_balances` for current active blacklist balance snapshots
- Blacklist summary gained active-record metrics (`activeAddressCount`, `activeFrozenTotal`, `activeAmountGapCount`)
- Active Tron totals now prefer current TRC20 balances for active blacklist rows and destroy-event amounts when funds were seized and burned
- Legacy Tron `derived` blacklist/unblacklist event amounts are reset instead of being reused as event-time history
v3.3Mar 24, 2026pyUSD and USD1 blacklist tracking coverage
Extended blacklist tracker to cover pyUSD (PayPal/Paxos) on Ethereum and Arbitrum, and USD1 (World Liberty Financial) on Ethereum, BSC, and Tron. Introduced configurable address topic index for two-indexed-address events.
- Added pyUSD FreezeAddress/UnfreezeAddress/FrozenAddressWiped event tracking (Paxos PaxosTokenV2 pattern)
- Added USD1 Freeze/Unfreeze event tracking with addressTopicIndex=2 for dual-indexed events
- EVM parser now supports configurable topic index for affected address extraction
- Tron parser extended with tronResultKey for non-standard event parameter names
DetailsHide details
pyUSD and USD1 blacklist tracking coverage
Extended blacklist tracker to cover pyUSD (PayPal/Paxos) on Ethereum and Arbitrum, and USD1 (World Liberty Financial) on Ethereum, BSC, and Tron. Introduced configurable address topic index for two-indexed-address events.
- Added pyUSD FreezeAddress/UnfreezeAddress/FrozenAddressWiped event tracking (Paxos PaxosTokenV2 pattern)
- Added USD1 Freeze/Unfreeze event tracking with addressTopicIndex=2 for dual-indexed events
- EVM parser now supports configurable topic index for affected address extraction
- Tron parser extended with tronResultKey for non-standard event parameter names
Impact Notes
- Added pyUSD FreezeAddress/UnfreezeAddress/FrozenAddressWiped event tracking (Paxos PaxosTokenV2 pattern)
- Added USD1 Freeze/Unfreeze event tracking with addressTopicIndex=2 for dual-indexed events
- EVM parser now supports configurable topic index for affected address extraction
- Tron parser extended with tronResultKey for non-standard event parameter names
- Aggregation layer (chart, summary stats) made dynamic to accommodate new stablecoins
v3.2Mar 24, 2026Provenance-aware rows and explicit amount semantics
Blacklist rows now persist emitting-contract provenance and explicit native/USD amount status fields so reprocessing and public consumers no longer rely on implicit inference.
- Rows now store config/contract provenance plus event signature metadata
- Amount semantics split into token-native and USD-at-event fields with explicit source/status flags
- Gap monitoring now tracks recoverable attribution failures rather than nullable amounts alone
DetailsHide details
Provenance-aware rows and explicit amount semantics
Blacklist rows now persist emitting-contract provenance and explicit native/USD amount status fields so reprocessing and public consumers no longer rely on implicit inference.
- Rows now store config/contract provenance plus event signature metadata
- Amount semantics split into token-native and USD-at-event fields with explicit source/status flags
- Gap monitoring now tracks recoverable attribution failures rather than nullable amounts alone
Impact Notes
- Rows now store config/contract provenance plus event signature metadata
- Amount semantics split into token-native and USD-at-event fields with explicit source/status flags
- Gap monitoring now tracks recoverable attribution failures rather than nullable amounts alone
v3.1Feb 25, 2026ReconstructedAPI-error-aware sync cursor protection
EVM scanning now distinguishes API failure from genuine no-event ranges so cursors do not advance on unreliable reads.
- EVM log fetching differentiates API failures (`null`) from valid empty responses (`[]`)
- On API failure, sync state is held and retried on the next cycle instead of advancing
- Metadata now reports `apiErrors` for operational observability
DetailsHide details
API-error-aware sync cursor protection
EVM scanning now distinguishes API failure from genuine no-event ranges so cursors do not advance on unreliable reads.
- EVM log fetching differentiates API failures (`null`) from valid empty responses (`[]`)
- On API failure, sync state is held and retried on the next cycle instead of advancing
- Metadata now reports `apiErrors` for operational observability
Impact Notes
- EVM log fetching differentiates API failures (`null`) from valid empty responses (`[]`)
- On API failure, sync state is held and retried on the next cycle instead of advancing
- Metadata now reports `apiErrors` for operational observability
- d40060a
v3.0Feb 25, 2026ReconstructedIndexer-lag safety margins for cursor advancement
Head advancement added explicit safety buffers to prevent permanently skipping late-indexed explorer events.
- EVM no-event advancement now uses `head - safetyMargin` instead of raw head
- Tron no-event advancement now uses `now - 15m` instead of wall-clock `now`
- Reduces permanent event loss when explorer indexing lags chain tip
DetailsHide details
Indexer-lag safety margins for cursor advancement
Head advancement added explicit safety buffers to prevent permanently skipping late-indexed explorer events.
- EVM no-event advancement now uses `head - safetyMargin` instead of raw head
- Tron no-event advancement now uses `now - 15m` instead of wall-clock `now`
- Reduces permanent event loss when explorer indexing lags chain tip
Impact Notes
- EVM no-event advancement now uses `head - safetyMargin` instead of raw head
- Tron no-event advancement now uses `now - 15m` instead of wall-clock `now`
- Reduces permanent event loss when explorer indexing lags chain tip
- e6de7eb
v2.2Feb 18, 2026ReconstructedPrecision and integrity hardening
Amount math and log parsing were hardened to reduce silent corruption and improve sync telemetry.
- Token amounts switched to BigInt-safe decimal conversion to avoid large-value precision loss
- Malformed EVM logs (invalid block/timestamp) are discarded instead of being inserted
- Sync now emits structured run metadata (`itemCount`, `contractsSkipped`, budget usage)
DetailsHide details
Precision and integrity hardening
Amount math and log parsing were hardened to reduce silent corruption and improve sync telemetry.
- Token amounts switched to BigInt-safe decimal conversion to avoid large-value precision loss
- Malformed EVM logs (invalid block/timestamp) are discarded instead of being inserted
- Sync now emits structured run metadata (`itemCount`, `contractsSkipped`, budget usage)
Impact Notes
- Token amounts switched to BigInt-safe decimal conversion to avoid large-value precision loss
- Malformed EVM logs (invalid block/timestamp) are discarded instead of being inserted
- Sync now emits structured run metadata (`itemCount`, `contractsSkipped`, budget usage)
- c6c1391
- 7bc5361
- e950f76
v2.1Feb 18, 2026ReconstructedPre-block balance sampling and zero-amount recovery
Balance attribution moved to pre-event block semantics, and backfill began explicitly reprocessing suspicious zero blacklist amounts.
- Balance enrichment samples `blockNumber - 1` for blacklist, unblacklist, and destroy
- Backfill now re-attempts rows with `amount = 0` for blacklist events
- Reduces same-block ordering artifacts that previously produced false zeros
DetailsHide details
Pre-block balance sampling and zero-amount recovery
Balance attribution moved to pre-event block semantics, and backfill began explicitly reprocessing suspicious zero blacklist amounts.
- Balance enrichment samples `blockNumber - 1` for blacklist, unblacklist, and destroy
- Backfill now re-attempts rows with `amount = 0` for blacklist events
- Reduces same-block ordering artifacts that previously produced false zeros
Impact Notes
- Balance enrichment samples `blockNumber - 1` for blacklist, unblacklist, and destroy
- Backfill now re-attempts rows with `amount = 0` for blacklist events
- Reduces same-block ordering artifacts that previously produced false zeros
- d7e0ad4
v2.0Feb 12, 2026ReconstructedL2 balance reliability and budgeted full-scan loop
Major tracking architecture shift for L2 correctness and deterministic scan coverage under strict subrequest budgets.
- Introduced shared per-run subrequest budgeting with least-synced-first config ordering
- L2 balance sourcing evolved from Etherscan-only to RPC/dRPC archive-aware historical balance fetches
- Backfill moved ahead of incremental scan and EVM head caching reduced redundant rescans
DetailsHide details
L2 balance reliability and budgeted full-scan loop
Major tracking architecture shift for L2 correctness and deterministic scan coverage under strict subrequest budgets.
- Introduced shared per-run subrequest budgeting with least-synced-first config ordering
- L2 balance sourcing evolved from Etherscan-only to RPC/dRPC archive-aware historical balance fetches
- Backfill moved ahead of incremental scan and EVM head caching reduced redundant rescans
Impact Notes
- Introduced shared per-run subrequest budgeting with least-synced-first config ordering
- L2 balance sourcing evolved from Etherscan-only to RPC/dRPC archive-aware historical balance fetches
- Backfill moved ahead of incremental scan and EVM head caching reduced redundant rescans
- 58c4f05
- 77dad70
- 28a7ead
- add68dc
- fb7e7d6
- 7d9e677
v1.2Feb 11, 2026ReconstructedCoverage expansion: USDT0 and gold contract families
Expanded event coverage beyond legacy USDT/USDC patterns and fixed multiple cross-chain parsing mismatches.
- Added USDT0 event signatures and indexed-address parsing for upgraded Tether contracts
- Added PAXG and XAUT contract/event support with contract-specific mappings
- Per-contract decimals and Tron `0x -> 41` address normalization improved amount fidelity
DetailsHide details
Coverage expansion: USDT0 and gold contract families
Expanded event coverage beyond legacy USDT/USDC patterns and fixed multiple cross-chain parsing mismatches.
- Added USDT0 event signatures and indexed-address parsing for upgraded Tether contracts
- Added PAXG and XAUT contract/event support with contract-specific mappings
- Per-contract decimals and Tron `0x -> 41` address normalization improved amount fidelity
Impact Notes
- Added USDT0 event signatures and indexed-address parsing for upgraded Tether contracts
- Added PAXG and XAUT contract/event support with contract-specific mappings
- Per-contract decimals and Tron `0x -> 41` address normalization improved amount fidelity
- b257569
- 9281531
- eeb92e9
- 2fd5065
- 29a4759
v1.1Feb 11, 2026ReconstructedIngestion-time enrichment and backfill foundation
Blacklist rows began storing balance context during ingestion, with a companion path for retroactive recovery of missing amounts.
- Blacklist/unblacklist rows are enriched with token balances before insert
- Backfill pipeline introduced for historical rows missing amount values
- Set groundwork for later destroy-event amount recovery hardening
DetailsHide details
Ingestion-time enrichment and backfill foundation
Blacklist rows began storing balance context during ingestion, with a companion path for retroactive recovery of missing amounts.
- Blacklist/unblacklist rows are enriched with token balances before insert
- Backfill pipeline introduced for historical rows missing amount values
- Set groundwork for later destroy-event amount recovery hardening
Impact Notes
- Blacklist/unblacklist rows are enriched with token balances before insert
- Backfill pipeline introduced for historical rows missing amount values
- Set groundwork for later destroy-event amount recovery hardening
- 1dec7aa
v1.0Feb 9, 2026ReconstructedInitial Blacklist Tracker release
Launched multi-chain blacklist event ingestion, persistence schema, public API, and dashboard surface.
- Initial incremental EVM + Tron event sync for major fiat-backed stablecoins
- Introduced `blacklist_events` and `blacklist_sync_state` tables
- Exposed tracker data through `/api/blacklist` and frontend event views
DetailsHide details
Initial Blacklist Tracker release
Launched multi-chain blacklist event ingestion, persistence schema, public API, and dashboard surface.
- Initial incremental EVM + Tron event sync for major fiat-backed stablecoins
- Introduced `blacklist_events` and `blacklist_sync_state` tables
- Exposed tracker data through `/api/blacklist` and frontend event views
Impact Notes
- Initial incremental EVM + Tron event sync for major fiat-backed stablecoins
- Introduced `blacklist_events` and `blacklist_sync_state` tables
- Exposed tracker data through `/api/blacklist` and frontend event views
- 093c11e
- ea9dbab
- 5158601
- ac0d823