Transparency & analytics (informative)
Status: informative — recommended data models and formulas for indexers and UIs
Related: TRANSPARENCY_ROADMAP.md · ÐMP spec.md
This note does not change consensus rules. It defines open, deterministic metrics so any Dogecoin indexer can re-verify marketplace health signals.
1. Event records
1.1 Inscription transfer (append-only)
Emitted when an inscription-carrying UTXO moves (including create → first owner).
| Field | Type | Notes |
|---|---|---|
inscription_id | string | txid i index |
seq | u32 | indexer sequence |
from_hash160 | hex20? | absent on create |
to_hash160 | hex20? | absent if burned / unassigned |
from_outpoint | string | txid:vout |
to_outpoint | string | txid:vout |
txid | hex64 | spending / reveal tx |
height | u32 | |
timestamp | u32 | block time |
reason | enum | create | transfer | burn |
1.2 ÐMP trade (append-only)
Emitted when a listing reaches verified settled status (not on list/cancel alone).
| Field | Type | Notes |
|---|---|---|
listed_inscription_id | string | asset sold |
list_inscription_id | string | list op |
seller | address | |
buyer | address | |
price_koinu | decimal string | |
currency | string | usually DOGE |
settlement_txid | hex64 | |
block_height | u32 | settle confirmation height |
timestamp | u32 | |
royalty_paid_koinu | string? | |
platform_fee_koinu | string? |
Pure ownership transfers without a settled ÐMP (or atomic PSBT settle indexed the same way) are not priced trades.
1.3 Collection membership
Prefer parent → children index (parents envelope tags). ÐMP collection ops may join later; do not invent off-chain collection IDs as chain truth.
For independently inscribed sets (no parent), membership is an operator-supplied id list. dogex dexpose walks transfer / ÐMP / marketplace CFs from the collection’s first mint (reveal tx confirm height). Today: dexpose --sync sidecar when live dogex has no era1 ord. Later: analysis-only on a full era1 index, any id list. Control clusters use a mint-star (genesis + direct collection counterparties) plus dense pairs (≥2 hops) so a one-hop sale does not merge an organic buyer into the minter set. The dexpose CLI then clusters first-credit funding (shared_funding_cluster: same parent tx / common-input / amount burst) so never-moved generated wallets do not look like diamond hands. See dogex docs/DEXPOSE.md.
2. Concentration
Given holdings weights w_i (inscription counts or fungible balances), total W = sum(w_i):
| Metric | Formula |
|---|---|
| Top-1 share | w_(1) / W |
| Top-10 share | sum(i=1..10, w_(i)) / W |
| HHI | sum_i (w_i / W)^2 (0–1) |
| Gini | standard Lorenz (0 = equal, 1 = one holder) |
Report holder_count, supply_or_items, and ranked top holders.
3. Wash heuristics (high precision first)
Each settled trade gets a wash score in [0,100] = weighted sum of flags (cap 100). Start conservative:
| Flag | Points | Condition |
|---|---|---|
same_wallet | 100 | buyer == seller |
round_trip | 40 | opposite ÐMP trade same asset within N blocks (default 144) |
pair_churn | 25 | same buyer↔seller pair ≥ K times in window (default 3 / 1008 blocks) |
new_wallet | 10 | buyer first seen < A blocks ago (default 144) — soft |
Collection wash volume % = volume (koinu) of trades with wash score ≥ 50 / total settled volume in window.
Never label a project “scam.” Prefer: elevated_wash_share, potential_circular_flow.
4. Organic / transparency score (0–100)
Explainable blend (weights sum to 1):
| Component | Weight | Mapping |
|---|---|---|
| Unique traders / trade count | 0.30 | clamp(unique/trades, 0–1) → ×100 |
| Inverse top-10 concentration | 0.25 | (1 − top10_share) × 100 |
| Inverse wash volume share | 0.30 | (1 − wash_vol_share) × 100 |
| Holder count depth | 0.15 | min(log10(1+holders)/log10(1001), 1) × 100 |
UI must show component breakdown + short explanations.
5. API shapes (dogex)
Recommended (implemented under /api/transparency/):
GET /api/transparency/collection/{parent_id}/concentrationGET /api/transparency/collection/{parent_id}/graph?from_height=&to_height=&limit=GET /api/transparency/collection/{parent_id}/bubblemap?at_height=&from_height=&to_height=&hide_exchanges=&limit=GET /api/transparency/collection/{parent_id}/risk?from_height=&to_height=GET /api/transparency/trades/{settlement_txid}/wash-scoreGET /api/transparency/formula
Responses are cacheable JSON; scores include formula_version (e.g. "transparency-v1") and bubble maps include bubblemap_version ("bubblemap-v1").
5.1 Bubble map (bubblemap-v1)
| Field | Meaning |
|---|---|
nodes[].holdings | Inscription count (or replayed count at at_height) |
nodes[].cluster_id | Union-find component over undirected transfer + ÐMP-trade edges in window |
nodes[].cluster_color_index | cluster_id % 12 for deterministic UI palettes |
edges[].weight | Aggregated edge multiplicity |
hide_exchanges | Omits addresses listed in indexer env DOGEX_TRANSPARENCY_HIDE_ADDRS (display filter only) |
Clusters mean linked by observed on-chain moves in the window — a potential coordination pattern, not proof of common control.
5.2 Time-travel
When inscription_transfer history exists for the collection’s children, at_height replays last to owner per inscription up to that height. Otherwise the API returns current tip owners and sets ownership_source accordingly.
5.3 Phase 3 — timeline, ranking, CSV, mempool hints
| Endpoint | Role |
|---|---|
GET /api/transparency/collection/{parent_id}/health-timeline?from_height=&to_height=&step= | Bucketed organic / wash / trade counts over height (step default 1008 ≈ 1 week) |
GET /api/transparency/marketplace/organic-ranking?from_height=&to_height=&limit=&min_trades= | Collections ranked by organic score (ÐMP settles → parent via parents tag) |
GET /api/transparency/collection/{parent_id}/export?format=csv | Investigator CSV of settled trades + wash flags |
GET /api/transparency/mempool/circular-hints?buyer=&seller=&listed_inscription_id= | Mempool settle candidates scored against confirmed dmp_trade history (round-trip / pair churn / same wallet) |
Health timeline uses tip concentration for the organic blend in each bucket (fast, reproducible); trade/wash series are window-true. Language remains non-accusatory.
Mempool hints are potential patterns only — unconfirmed txs may never confirm.
6. Best practices for legitimate projects (non-gatekeeping)
- Prefer wide, organic distribution; avoid self-trading for chart cosmetics.
- Use ÐMP settle so price is on-chain and verifiable.
- Document treasury / team wallets publicly if concentrated.
- Expect transparency scores to be public and reproducible.
Independent indexers should prefer these formulas so explorers agree.