README.md

---
license: mit
library_name: xgboost
pipeline_tag: tabular-regression
tags:
  - tabular-regression
  - ens
  - ethereum
  - web3
  - domain-names
  - price-prediction
  - nft
datasets:
  - quantumly/ens-appraiser-data
base_model: sentence-transformers/all-mpnet-base-v2
metrics:
  - r_squared
  - mape
  - rmse
model-index:
  - name: ENS Appraiser v0.2
    results:
      - task:
          type: tabular-regression
          name: ENS Domain Price Prediction
        dataset:
          name: ENS Appraiser Multi-source Training Data
          type: quantumly/ens-appraiser-data
        metrics:
          - type: r_squared
            value: 0.3081
            name: R² (log USD, test)
          - type: median_ape
            value: 1.383
            name: Median APE (test)
          - type: rmse
            value: 1.5469
            name: RMSE (log USD, test)
---

# ENS Appraiser v0.2

A gradient-boosted regressor that predicts the USD sale price of an
ENS (`.eth`) domain name from on-chain history, semantic embeddings of the
label, and macro-market context.

This is the **v0 baseline** — handcrafted features + mpnet PCA + KNN
comparable-sale aggregates. Built to establish an honest, leakage-free
floor that future versions improve on.

## Quick numbers

Trained on ~265k ENS secondary sales (Jan 2022 – Sep 2023), evaluated on
2,744 sales in **Q1–Q2 2024** (held out by date, never seen during training):

| Split | n      | R² (log USD) | RMSE (log USD) | Median APE | Bias  |
|-------|--------|--------------|----------------|------------|-------|
| Train | 265,240 | 0.7700      | 0.7744         | 32.5%      | +0.000 |
| Val   | 3,545   | 0.6602      | 1.0678         | 57.0%      | +0.203 |
| Test  | 2,744   | **0.3081**  | 1.5469         | 138.3%     | +0.732 |

**Plain-English read:** for a typical mid-tier name in test, the model is
within ~2× of the actual sale price. The long tail — celebrity names,
3-letter premiums, regime shifts — is where it misses, often by 100×+ in
either direction.

## What's good

- **Mid-tier names, $50–$5,000 range:** usually within 2× of actual.
- **Length and character composition:** strong signals captured well.
  The model knows 3-letter ASCII names are premium and 12-letter random
  handles are cheap.
- **Wordlist hits:** matches against Wikipedia, GeoNames, US first names,
  stock tickers, and SEC EDGAR are picked up correctly. `paris.eth` is
  flagged as a city, `nike.eth` as a brand.
- **Comparable-sale anchoring:** the top two features are `knn_mean_log`
  and `knn_p90_log` — the model leans heavily on "what did similar names
  sell for recently?" which is the right intuition for valuation.

## What's not

- **Celebrity / brand premium:** a name's value to a known buyer
  (Coinbase wanting `coinbase.eth`, a luxury brand wanting their mark)
  is invisible to this model. It can detect that `nike.eth` is a brand
  word, but not that the sale price reflects Nike's interest specifically.
- **3-letter premium tail:** names like `mph.eth`, `uma.eth` sold for
  $20k–$40k in test; the model predicted $100–$200. The training set
  underweights short premiums because most sales there are 5+ letters.
- **Regime shift on test:** test set median price is ~4× higher than
  training median due to the 2023 → 2024 ENS market shift. Recency-weighted
  training (1-year half-life) helps but doesn't fully close the gap.
- **Bidirectional errors:** worst predictions split roughly evenly
  between under-prediction (hot names the model didn't recognize) and
  over-prediction (cold names that just didn't move). 138% MedianAPE is
  honest but uncomfortable.

## How it's built

| Component | Detail |
|---|---|
| Algorithm | XGBoost regressor (170 boosted trees, max_depth=7) |
| Target | `log(sale_price_usd)` |
| Features | 146 total |
| Training data | 265,240 sales, Jan 2022 – Sep 2023 |
| Training time | ~10 min on a single A100 |
| Model size | 3.3 MB |

### Feature breakdown

- **Handcrafted (15):** length, n_digits, n_letters, n_special, palindrome,
  is_all_digits, is_all_letters, is_ascii, has_unicode, starts/ends_digit,
  max_char_run, n_unique_chars
- **Wordlist hits (8):** Wikipedia titles, GeoNames cities, US first names,
  ISO 3166 countries, stock tickers, SEC EDGAR companies, Wiktionary EN,
  plus a `wordlist_hits` total
- **Grails clubs (~45):** binary membership in each curated `.eth` club
  (`999club`, `pre-punks`, `palindromes`, `pokemon_gen1`, etc.)
- **Trademark conflict (1):** active USPTO mark in Nice classes 9, 35, 36,
  38, 41, 42, 45 with matching `mark_text_norm`
- **Holder behavior (2):** `name_age_days`, `prior_transfer_count`
  (leakage-safe — only counts transfers strictly before the sale block)
- **Macro context (5):** Fear & Greed Index, ETH chain TVL, ETH stablecoin
  market cap, ETH DEX volume, total NFT marketplace fees on the sale day
- **mpnet PCA (64):** 768-dim `all-mpnet-base-v2` embeddings of the label,
  PCA-reduced to 64 dims (95% explained variance)
- **KNN comparable sales (8):** for each label, FAISS-retrieve top-50
  semantic neighbors (HNSW index), filter near-duplicates (sim > 0.999),
  take the most-recent prior sale of each, aggregate as `knn_count`,
  `knn_mean_log`, `knn_median_log`, `knn_p90_log`, `knn_max_sim`,
  `knn_min_sim`, `knn_log_max`, `knn_log_min`. **Strict leakage prevention:**
  only neighbors with sales **before** the current sale's date count.

### Top 10 features by gain

| Rank | Feature | Gain |
|---:|---|---:|
| 1 | `knn_mean_log` | 1,714 |
| 2 | `knn_p90_log` | 1,613 |
| 3 | `len` | 1,364 |
| 4 | `in_wikipedia` | 1,052 |
| 5 | `is_all_digits` | 944 |
| 6 | `knn_median_log` | 604 |
| 7 | `n_digits` | 338 |
| 8 | `pca_000` | 289 |
| 9 | `n_clubs` | 282 |
| 10 | `ends_digit` | 277 |

Five of the top ten are KNN-comp or PCA features, which means the
embedding pipeline is doing real work — it's not just paying for itself,
it's the dominant signal alongside length.

## Training data + leakage controls

Built from the [`quantumly/ens-appraiser-data`](https://huggingface.co/datasets/quantumly/ens-appraiser-data)
dataset:

- **Sales labels:** Alchemy `getNFTSales` for ENS BaseRegistrar + NameWrapper
  contracts. Wei amounts converted to USD via CoinGecko hourly OHLC at
  the sale's block timestamp. **Coverage gap:** Alchemy `getNFTSales` v2
  truncates at block 19,768,978 (May 2024) and does not index Blur
  marketplace sales. v0 ships with this gap; closing it is a v1 priority.
- **Registrations + transfers:** The Graph's [ENS subgraph](https://thegraph.com/explorer/subgraphs/5XqPmWe6gjyrJtFn9cLy237i4cWw2j9HcUJEXsP5qGtH).
- **Wordlists:** Wiktionary dumps, Wikipedia EN article titles, GeoNames
  `cities500`, US Census baby names, NASDAQ Trader ticker dumps,
  SEC EDGAR company tickers, ISO 3166 country list.
- **Macro:** alternative.me Fear & Greed Index, DefiLlama (TVL, stablecoin
  mcap, DEX volume, NFT marketplace fees).
- **Trademarks:** USPTO Trademark Case Files Dataset (annual research dump).
- **Embeddings:** `sentence-transformers/all-mpnet-base-v2`, encoded once
  for all 3.5M ENS labels in the dataset.

### Leakage controls

The first version of this model accidentally leaked future information
through `lifetime_transfer_count` (it counted *all* transfers ever for a
labelhash, including transfers that happened *after* the sale being
predicted). The leaky model showed **train R² 0.81 / test R² −0.29** — the
classic catastrophic-overfit signature where the model collapses to
predicting the population mean on held-out data.

The current model uses `prior_transfer_count`, which only counts transfers
where `transfer_block < sale_block` per row. It moved to rank #11 in
feature importance (was #1 by 3.3×). KNN comparable-sale features have a
similar safeguard: a neighbor's sale only counts if it happened strictly
before the sale being predicted.

### Train/Val/Test split

Fixed-window temporal split:

- **Train:** sales with `sale_date < 2023-10-01`
- **Val:** sales 2023-10-01 → 2023-12-31
- **Test:** sales 2024-01-01 onwards

This prevents the v0.1 mistake of training on 2022 prices and asking the
model to extrapolate to a 2024 market regime that's ~4× more expensive
on average. Val and test are in the same regime so val RMSE is a
meaningful proxy for test.

Training rows are weighted with an exponential recency decay (1-year
half-life, normalized to mean=1.0) so the model leans on 2023 dynamics
without throwing away the older data entirely.

## Intended use

This model is intended for **research and analytics**, not as a price
oracle and not for live trading.

**Reasonable uses:**

- Bulk valuation of mid-tier ENS portfolios for tax/accounting purposes
- Identifying obviously over- or under-listed names on secondary markets
- Sanity-checking a listing price before posting
- Producing comparable-sale ranges for negotiation context

**Out of scope:**

- Pricing 3-letter, 1-2 letter, or otherwise-premium names with confidence
- Pricing celebrity / known-brand names where the buyer pool is concentrated
- Predicting prices for names in the post-May-2024 marketplace mix
  (Blur dominance, marketplace fee changes)
- Any high-stakes financial decision based on a single point estimate

## Limitations

- **Sales coverage**: Jan 2022 – May 2024 only, no Blur. ~2 years of recent
  sales (mid-2024 onwards) are missing entirely from training. Closing
  this gap requires either a new sales source (Reservoir/SimpleHash both
  defunct as of 2024–2025) or direct `eth_getLogs` decoding of Seaport,
  Blur, X2Y2, LooksRare events, planned for v1.
- **Celebrity premium**: there's no feature here for "is this a famous
  person/place/thing?" beyond Wikipedia-title matching. v1 adds
  LLM-derived structured features (`fame_score`, `name_kind`,
  `crypto_relevance`, `brand_collision_risk`) which should close most
  of this gap.
- **Out-of-distribution labels**: pure-digit labels (`0001`),
  punycode/emoji, and l33tspeak get less benefit from mpnet embeddings
  since they're out of distribution for the pretrained model. Length and
  charset features partially compensate.
- **Time drift**: the ENS market shifts noticeably every 6–12 months as
  marketplace dominance, fee structures, and DAO actions move. Predictions
  on names sold "right now" will lag any regime shift since the training
  cutoff.
- **Test-set thinness**: only 2,744 sales meet the $10 floor and post-Jan-2024
  cutoff. The reported test R² has roughly ±0.08 95% CI — useful as a
  ballpark, not a precise number.

## How to use

```python
from huggingface_hub import hf_hub_download
import xgboost as xgb
import pickle

model_path = hf_hub_download(
    repo_id="quantumly/ens-appraiser",
    filename="v0_appraiser_xgb.json",
)
pca_path = hf_hub_download(
    repo_id="quantumly/ens-appraiser",
    filename="v0_pca_mpnet.pkl",
)

booster = xgb.Booster()
booster.load_model(model_path)
with open(pca_path, "rb") as f:
    pca = pickle.load(f)

# Inference also requires:
#  1. mpnet embedding for the label (sentence-transformers/all-mpnet-base-v2)
#  2. Handcrafted/wordlist/club/trademark/holder/macro features
#  3. KNN comp lookup against the dataset repo's FAISS index
#
# A self-contained inference notebook is planned in the dataset repo.
```

The 146 features expected by the booster are listed in `v0_metadata.json`
under `feature_cols`, in the exact order required by `xgb.DMatrix`.

## Reproducibility

The training notebook ([`v0_appraiser_v2.ipynb`](https://huggingface.co/datasets/quantumly/ens-appraiser-data/blob/main/notebooks/v0_appraiser_v2.ipynb))
runs end-to-end on a Colab A100 high-RAM instance in ~25 minutes:

1. Downloads all source parquets from the dataset repo
2. Reconstructs USD prices via CoinGecko hourly OHLC join
3. Resolves labels for both BaseRegistrar and NameWrapper sales
4. Computes all features
5. Builds HNSW index for KNN
6. Trains XGBoost with early stopping
7. Saves model + metadata + diagnostics
8. Uploads to this model repo

All randomness is seeded (`seed=42` for XGBoost, PCA, sample weights).

## Roadmap

**v1 priorities** (in expected R² delta order):

1. **LLM-derived features** — Llama 3.1 8B local inference over all 3.5M
   labels, extracting `fame_score`, `name_kind`, `cultural_origin`,
   `crypto_relevance`, `brand_collision_risk`, plus a description-embedding.
   Expected delta: +0.05–0.10 test R².
2. **Recent sales backfill** via direct `eth_getLogs` decoding of
   Seaport / Blur / Wyvern / X2Y2 / LooksRare events. Closes the
   May 2024 → present coverage gap and adds Blur. Expected delta:
   +0.03–0.06 test R² and a much bigger test set.
3. **Multi-embedding ensemble** — concatenate mpnet with `bge-base-en-v1.5`
   and `e5-base-v2`, PCA the joint space. Expected delta: +0.02–0.04.
4. **Cross-encoder reranker** for KNN comps. Expected delta: +0.02–0.03.
5. **Contrastive fine-tuning** of mpnet on price-similarity triplets.
   Expected delta: +0.03–0.05.

## Citation

```bibtex
@misc{ens_appraiser_2026,
  author    = {Drobnič, Nejc},
  title     = {ENS Appraiser v0.2},
  year      = {2026},
  publisher = {Hugging Face},
  url       = {https://huggingface.co/quantumly/ens-appraiser}
}
```

## License + contact

MIT. Questions, corrections, pull requests: nejc@nejc.dev