How the dataset is structured, how source quality is evaluated, how entity relationships are classified, and where we know we have gaps.

Schema — Data Dictionary

Canonical enum values live in scripts/utils/schema.py and are enforced by scripts/99_validate.py. When updating this file, update schema.py in the same commit.

Table overview

Table	Role
`actions.csv`	Spine — one row per freeze, restrict, or non-action event
`triggers.csv`	External catalysts (OFAC designations, court orders, statutes)
`incidents.csv`	Real-world events that may precipitate requests
`requests.csv`	Explicit or plausible requests for Circle action (nullable `resulting_action_id` captures refusals)
`policies.csv`	Circle policies, versioned by effective date
`implementations.csv`	Mechanical execution records (on-chain tx or off-chain operational step)
`entities.csv`	Every relevant party, with YES/MAYBE/NO Circle relationship classification
`sources.csv`	Every citation, audit-trailed with SHA256
`action_sources.csv`	Many-to-many join between actions and sources

`actions.csv` — spine

One row per discrete freeze / restrict / non-action event.

Field	Type	Notes
`action_id`	string, PK	Stable ID, e.g. `CU-ACT-0001`
`action_date`	ISO 8601 UTC	Date of the action itself, not the date of disclosure
`mechanism_type`	enum	`BLACKLIST`, `UNBLACKLIST`, `PAUSE`, `UNPAUSE`, `REDEMPTION_REFUSAL`, `ACCOUNT_CLOSURE`, `JURISDICTIONAL`, `LAW_ENFORCEMENT_RESPONSE`, `NON_ACTION`, `POLICY_COMMITMENT`
`target_identifier`	string	Address, account ID, jurisdiction code, or counterparty name
`target_type`	enum	`ADDRESS`, `ACCOUNT`, `JURISDICTION`, `COUNTERPARTY`, `CATEGORY`, `NA`
`target_category`	string, nullable	Free-tag, e.g. `sanctioned_entity`, `stolen_funds`
`status`	enum	`ACTIVE`, `REVERSED`, `UNCLEAR`
`trigger_id`	FK → triggers, nullable	Legal / regulatory trigger
`implementation_id`	FK → implementations, nullable	Mechanical execution record
`confidence`	enum	`HIGH`, `MEDIUM`, `LOW`
`issuer`	string	Stablecoin issuer, e.g. `Circle`

Null trigger_id, policy_id, or implementation_id values are themselves findings — they signal a policy-versus-practice gap or opaque implementation and should be coded deliberately, not treated as missing data.

Sourcing Standards

Source tiers

Every source_id carries a source_tier:

PRIMARY — Circle itself or US / foreign government primary documents.
SECONDARY — Reputable news organizations and court-filed third-party documents.
TERTIARY — Forensics-firm reports, industry publications, research notes, social media.

Confidence mapping

Evidence available	`confidence`
On-chain event recovered via Dune / Etherscan	`HIGH`
PRIMARY source explicitly describing the action	`HIGH`
≥2 SECONDARY sources corroborating	`HIGH` or `MEDIUM`
1 SECONDARY source, no corroboration	`MEDIUM`
TERTIARY sources only	`LOW`
Inferred from context, no direct statement	`LOW`

Entity → Circle Relationship Classification

Every entities.csv row carries circle_relationship ∈ {YES, MAYBE, NO}.

`YES`

Requires at least one documented source showing: equity investment, Centre Consortium membership, revenue-share agreement, board/advisor interlock, banking counterparty named in Transparency Reports, or disclosed commercial partnership.

`NO`

Requires affirmative evidence of absence or adversarial distance (entity on a sanctions list Circle has complied with; Circle has publicly severed ties; entity is in active litigation against Circle).

`MAYBE`

Default residual. Used whenever we lack documented evidence in either direction. Expected to be the largest bucket.

Completeness Map

Summary

Total on-chain events: 2922 (2288 BLACKLIST + 634 UNBLACKLIST)
Chains covered: 6 EVM (Ethereum, Base, Polygon, Avalanche, Arbitrum, Optimism)
Date range: 2020-06-16 to 2026-04-15
Pause/Unpause events observed: 0 across all chains

Known Gaps

Non-EVM chains (Solana, NEAR, Stellar, Algorand, Hedera) are out of scope for Pass A. Internal Circle policies not published externally are unobservable. Requests Circle received but did not disclose and which produced no action are partially unobservable.