MVF-Composer: Trust-Weighted Mean-Variance Frontier Control for Stress-Resilient Stablecoin Reserves

Overview

This repository contains the reference implementation of MVF-Composer, a trust-weighted Mean-Variance Frontier reserve controller that addresses the "2020 Omission" vulnerability in stablecoin risk management. By integrating stress-augmented covariance estimation with trust-weighted signal aggregation, MVF-Composer anticipates tail volatility regimes that backward-looking methods systematically underestimate.

Key Results

Metric	SAS Baseline	MVF-Composer	Improvement
Peak Peg Deviation	7.45%	3.22%	57% reduction
Recovery Time	44 steps	14 steps	3.1× faster
Bad Debt Events	5.4	2.1	61% reduction
Liquidity Retention	84.8%	92.9%	+8.1 pp

Core Contributions

1. Trust Layer (§3.2): A four-feature trust scoring mechanism that down-weights adversarial agent signals
2. Stress-Augmented Covariance (§3.3): Dynamic blending of historical and stress covariances via α(R_T)
3. Constrained MVF Optimization (§3.4): Turnover-limited portfolio optimization with diversification floors

---

Quick Start

Installation

# Clone the repository and cd into the directory

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies (creates virtual environment automatically)
uv sync

Run Main Experiment (RQ1)

Reproduce the main results comparing MVF-Composer against baselines:

uv run python experiments/run_main_experiment.py

Expected output:

Peak Deviation Reduction: ~57% (target: 55-70%)
Recovery Time Improvement: ~3.1x (target: 2.5-4.0x)
Results saved to: output/rq1_results.json

Run Ablation Study (RQ3)

Quantify individual component contributions:

uv run python experiments/run_ablation.py

Expected output:

Trust Layer Contribution: ~23%
Stress Covariance Contribution: ~41%

---

Repository Structure

/
├── mvf_composer/               # Core algorithm implementation
│   ├── __init__.py
│   ├── trust_scorer.py         # Trust score computation T(a) ∈ [0,1]
│   ├── covariance_estimator.py # Stress-augmented covariance Σ_aug
│   └── mvf_optimizer.py        # Constrained MVF optimization w*
├── experiments/                # Experiment scripts
│   ├── run_main_experiment.py  # RQ1: Main results vs baselines
│   └── run_ablation.py         # RQ3: Component ablation study
├── data/                       # Precomputed covariance matrices
│   ├── cov_historical.npy      # Calm-period Σ^hist
│   ├── cov_stress.npy          # Stress-period Σ^stress
│   └── metadata.json           # Data provenance
├── pyproject.toml              # Project configuration and dependencies
└── README.md                   # This file

---

Algorithm Overview

MVF-Composer executes the following pipeline at each rebalancing epoch:

┌───────────────┐   ┌──────────────┐   ┌─────────────────┐   ┌──────────────┐
│ Agent Signals │──▶│ Trust Layer  │──▶│   Covariance    │──▶│     MVF      │
│  {R_a, f_a}   │   │   T(a)∈[0,1] │   │    Estimator    │   │  Optimizer   │
└───────────────┘   └──────────────┘   │   Σ_aug blend   │   │  w* ∈ Δ^n    │
                           │           └─────────────────┘   └──────────────┘
                           ▼                    ▲
                    R_T = Σ T(a)·R_a      α(R_T) = R_T²
                          ─────────
                           Σ T(a)

Key Equations

Trust Score (Equation 3):

T(a) = σ(w^T [f₁, f₂, -f₃, -f₄] + b)

Covariance Blending (Equation 5):

Σ_aug = (1 - α(R_T)) · Σ^hist + α(R_T) · Σ^stress
where α(R_T) = R_T²

Constrained Optimization (Equation 7):

w* = argmin  w^T Σ_aug w - λ · w^T μ
     s.t.    Σ w_i = 1
             ‖w - w_{t-1}‖₁ ≤ C
             w^min ≤ w_i ≤ w^max

---

Parameters

All parameters are derived from Section 4.1 of the paper:

Parameter	Symbol	Default	Description
Risk Aversion	λ	2.5	Mean-variance trade-off
Turnover Limit	C	0.15	Maximum L1 portfolio change
Weight Floor	w^min	0.05	Diversification minimum
Weight Cap	w^max	0.60	Concentration maximum
Alpha Power	-	2.0	Blending function: α(r) = r²
Trust Window	W	10	Historical window for features

---

Reproducing Paper Results

Table 1: Main Results (RQ1)

uv run python experiments/run_main_experiment.py --runs 100

Validates against expected ranges:

• Peak deviation reduction: 55-70% (paper: 57%)
• Recovery improvement: 2.5-4.0× (paper: 3.1×)

Table 3: Ablation Study (RQ3)

uv run python experiments/run_ablation.py --runs 50

Expected component contributions:

• Trust Layer: ~23%
• Stress Covariance: ~41%
• Other (turnover, news): ~36%

---

Data

The data/ directory contains precomputed covariance matrices derived from stablecoin price data (2020-2024). See data/metadata.json for provenance details.

Assets included: DAI, USDT, USDC, TUSD, BUSD, USTC

Time periods:

• Historical (calm): 2021-01-05 to 2025-03-31 (SAS paper period)
• Extended (stress): 2020-01-01 to 2025-03-31 (includes COVID crash)

---

License

MIT License. See LICENSE for details.

---

Contact

For questions about this implementation, please open an issue or contact the authors through the conference submission system.

---

Appendix: UV Package Manager

This project uses uv, a fast Python package manager written in Rust.

Installation and Usage Links

• Installation Guide: https://docs.astral.sh/uv/getting-started/installation/
• Getting Started: https://docs.astral.sh/uv/getting-started/
• Project Management: https://docs.astral.sh/uv/projects/
• Dependency Management: https://docs.astral.sh/uv/pip/dependency-management/
• Running Scripts: https://docs.astral.sh/uv/run/
• Virtual Environments: https://docs.astral.sh/uv/venv/
• GitHub Repository: https://github.com/astral-sh/uv