# BTC and ETH VVIX Pipeline

## Scope
The first analytics stack in the repo is now a shared BTC/ETH VVIX pipeline.

Implemented pieces:
- Deribit `DVOL` ingestion
- BTC/ETH option-chain snapshot normalization
- `DVOLProvider`
- `BVIXProvider` using VIX-style 30-day variance replication
- `rVVIX` from rolling log-return variance of the vol index
- `qVVIX` from surface features plus a bootstrapped VAR model
- validation command and tests

## Main modules
- `src/uforia/analytics/vol_index.py`
- `src/uforia/analytics/surface.py`
- `src/uforia/signals/vvix.py`
- `src/uforia/models/var.py`
- `src/uforia/validation.py`

## Datasets
Implemented dataset contracts:
- `option_chain_snapshot`
- `dvol_snapshot`
- `raw_deribit_option_snapshot`
- `vol_index_series`
- `surface_features`
- `vvix_series`
- `razor_series`
- `ingestion_runs`

## CLI surface
Main commands:
- `uv run uforia-admin ingest deribit-dvol --underlying BTC|ETH --start ... --end ...`
- `uv run uforia-admin ingest deribit-options-once --underlying BTC|ETH --as-of ...`
- `uv run uforia-admin ingest deribit-options-daemon --underlying BTC|ETH`
- `uv run uforia-admin build vol-index --underlying BTC|ETH --source dvol|bvix --start ... --end ...`
- `uv run uforia-admin build rvvix --underlying BTC|ETH --source dvol --start ... --end ...`
- `uv run uforia-admin build surface-features --underlying BTC|ETH --start ... --end ...`
- `uv run uforia-admin build qvvix --underlying BTC|ETH --source dvol --ts ...`
- `uv run uforia-admin validate vol-suite --underlying BTC|ETH --start ... --end ...`

## Current constraint
Historical Deribit option-chain backfill is not available from the live public adapter alone. The repo supports:
- live hourly archiving going forward
- rebuilds from archived raw payloads
- later integration of a historical vendor or another capture source
