Aave V3 Liquidation Early Warning

Reproducibility package for Does Machine Learning Add Early-Warning Value Beyond the Health Factor? Evidence from Aave V3 Liquidations. It contains the formal data-construction and QA code, frozen rare-event modeling code, required documentation, result tables, and publication figures. It does not include private credentials, raw API caches, or the processed borrower-level parquet dataset.

Study design

• Protocol/network: Aave V3, Ethereum Mainnet
• Study period: 2025-01-01 to 2026-06-30
• Observation unit: borrower x observation timestamp
• Target: LiquidationCall during (t, t+24h]
• Mandatory predictors: Health Factor, LTV, collateral value, debt value, weighted liquidation threshold, WETH 24-hour return, and WETH 24-hour volatility
• Event coverage: PARTIALLY_VALIDATED; no claim of perfect all-history completeness is made

Environment

Python 3.11 or newer is recommended.

python -m venv .venv
source .venv/bin/activate
pip install -r requirements-modeling.txt

Reproduction routes

1. Rebuild from public endpoints

The networked pipeline retrieves Aave V3 Ethereum events and historical states from the providers documented in DATA_PROVENANCE.md. Endpoint availability and runtime are external constraints.

python 03_code/fetch_liquidations.py --refresh
python 03_code/fetch_borrow_events.py --refresh
python 03_code/build_formal_dataset.py --weekly-cap 500
python 03_code/qa_formal_dataset.py
python 03_code/model_rare_events.py

2. Reproduce modeling from the frozen processed dataset

Place the author-provided aave_v3_formal_dataset.parquet at 02_data/processed/aave_v3_formal_dataset.parquet, then run:

python 03_code/qa_formal_dataset.py
python 03_code/model_rare_events.py

The Task 001 pilot is excluded from all formal modeling and final descriptive statistics. Exact sampling, leakage, data-dictionary, and QA rules are in 02_data/. Exact model settings and frozen outputs are in 03_code/model_rare_events.py and 03_results/.

Limitations

The formal sample contains 27,375 observations and 25 positive labels. Liquidation coverage is PARTIALLY_VALIDATED, the 90-day recent-Borrow rule is a proxy for the active debt risk set, and test uncertainty is substantial because only eight positive events occur in the independent test period.

License

Code and documentation are released under the MIT License. Third-party protocol data and trademarks remain subject to their respective terms.