# 🏗️ Dynamic RWA Yield Router

> **Mantle Turing Test Hackathon 2026 — Phase 2 "AI Awakening" — AI × RWA Track**

An autonomous AI agent that dynamically allocates capital across Mantle's Real World Asset (RWA) stack using reinforcement learning, with all decisions recorded on-chain via ERC-8004 agent identity NFTs.

## 📊 What It Does

The Dynamic RWA Yield Router manages a portfolio across three core RWA assets on Mantle L2:

| Asset | Type | Target APY | Risk Profile |
|-------|------|-----------|--------------|
| **USDY** (Ondo Finance) | Tokenized US T-Bills | ~4.25% | Low — USD-pegged, regulated |
| **mETH** (Mantle LSP) | Liquid Staked ETH | ~3-5% | Medium — ETH price exposure |
| **MI4** (Mantle Index Four) | Tokenized Index Fund | ~5-8% | Medium — diversified basket |

The agent uses a **PPO (Proximal Policy Optimization)** reinforcement learning policy to learn optimal allocation weights given real-time market conditions, yield rates, and risk signals.

## 🏛️ Architecture

```
┌──────────────────────────────────────────────────────────────────┐
│                    DYNAMIC RWA YIELD ROUTER                      │
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │ OBSERVE  │→│  REASON  │→│   PLAN   │→│ AUTHORIZE│       │
│  │          │  │          │  │          │  │          │       │
│  │DeFiLlama│  │RL Policy │  │Rebalance │  │  Risk    │       │
│  │CoinGecko│  │  (PPO)   │  │ Trades   │  │ Manager  │       │
│  │Mantle   │  │          │  │          │  │          │       │
│  │RPC/FRED │  │          │  │          │  │          │       │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘       │
│       ↓                                          ↓               │
│  ┌──────────┐                            ┌──────────┐           │
│  │ EXECUTE  │←───────────────────────────│  VERIFY  │           │
│  │          │                            │          │           │
│  │Unsigned  │    Mantle L2 (Chain 5000)  │On-chain  │           │
│  │Tx Builder│    Fluxion / Agni DEX      │Confirm   │           │
│  └──────────┘                            └──────────┘           │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              ON-CHAIN CONTRACTS                          │    │
│  │  YieldRouterAgent.sol  │  AgentIdentity8004.sol        │    │
│  │  (Allocation Records)  │  (ERC-8004 Reputation)        │    │
│  │  RiskRegistry.sol      │  (Risk Parameters)            │    │
│  └─────────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────────┘
```

### 6-Stage Agent Pipeline

1. **OBSERVE** — Fetch real-time yield rates, prices, and macro data from DeFiLlama, CoinGecko/Bybit, Mantle RPC, and FRED
2. **REASON** — RL policy (PPO with actor-critic MLP) predicts optimal allocation weights
3. **PLAN** — Compute required trades if weights drift beyond threshold (5%)
4. **AUTHORIZE** — Multi-layer risk manager validates: depeg detection, volatility guard, position limits, drawdown protection, circuit breaker
5. **EXECUTE** — Construct unsigned transaction payloads (construct-only safety: never holds private keys)
6. **VERIFY** — Confirm execution, update portfolio state, record on-chain via ERC-8004

## 🧠 RL Model

**Algorithm:** Proximal Policy Optimization (PPO)

**State Space** (18-dimensional):
- Yield rates: USDY APY, mETH APY, MI4 APY, Aave supply APYs
- Prices: ETH, BTC, MNT (normalized)
- Macro: Fed funds rate, BTC dominance
- Risk: USDY peg, mETH peg, ETH 30d volatility
- Portfolio: current weights [USDY, mETH, MI4]

**Action Space** (3-dimensional, continuous):
- Raw logits → softmax → portfolio weights [USDY, mETH, MI4]
- Position limits enforced: 5-60% per asset

**Reward Function:**
```
reward = sharpe_ratio × 100 
       - drawdown × 50 
       - depeg_penalty 
       - rebalance_cost × 1000
```

**Training Environment:** Custom Gymnasium env with synthetic yield processes (Ornstein-Uhlenbeck for mean-reverting yields, GBM for prices).

## 🛡️ Risk Management

| Layer | Description | Trigger |
|-------|-------------|---------|
| **Depeg Detection** | Monitors USDY/USD and mETH/ETH pegs | USDY > 0.5%, mETH > 2% deviation |
| **Volatility Guard** | Reduces risky assets in high-vol regimes | ETH 30d vol > 80% |
| **Concentration Limits** | Enforces min/max position sizes | Any asset > 60% or < 5% |
| **Smart Contract Risk** | Weights by protocol audit status | Per-protocol risk scores |
| **Drawdown Protection** | Circuit breaker on losses | Portfolio DD > 10% |
| **Emergency Exit** | Flee to USDC on critical risk | Severe depeg or compounding risks |

## 📜 Smart Contracts

### `YieldRouterAgent.sol`
- Records allocation decisions on-chain (audit trail)
- Enforces position limits and rebalance intervals
- Circuit breaker mechanism (OPEN/CLOSED/HALF_OPEN)
- Operator authorization for ERC-4337 wallets

### `AgentIdentity8004.sol` (ERC-8004)
- **Soulbound** agent identity NFT (non-transferable)
- Capability registration and verification
- Attestation system (performance audits, security reviews)
- On-chain reputation scoring (0-10000 bps)
- Decision history references with outcome scoring

### `RiskRegistry.sol`
- Per-asset risk parameters (max/min weights, depeg thresholds)
- Global risk parameters (max drawdown, slippage, gas limits)
- Depeg event tracking and resolution
- Allocation validation function

## 🚀 Quick Start

```bash
# Clone
git clone https://huggingface.co/muthuk1/mantle-rwa-yield-router
cd mantle-rwa-yield-router

# Install dependencies
pip install -r requirements.txt

# Run demo (3 cycles, live data)
python scripts/demo.py

# Train RL agent (optional, uses synthetic data)
python scripts/train.py

# Run continuous agent
python -m agent.main --mode run --interval 3600 --capital 100000

# Run tests
pytest tests/ -v
```

### Environment Variables
```bash
cp .env.example .env
# Edit .env with your configuration
```

## 📂 Project Structure

```
mantle-rwa-yield-router/
├── agent/
│   ├── main.py              # 6-stage orchestrator pipeline
│   ├── data_pipeline.py     # Real-time yield & price data aggregation
│   ├── rl_optimizer.py      # PPO agent + Gymnasium environment
│   ├── risk_manager.py      # Multi-layer risk management
│   ├── executor.py          # Unsigned transaction builder
│   └── strategy_reporter.py # LLM strategy letter generator
├── contracts/
│   ├── YieldRouterAgent.sol  # On-chain allocation router
│   ├── AgentIdentity8004.sol # ERC-8004 agent identity NFT
│   └── RiskRegistry.sol      # On-chain risk parameters
├── telegram_bot/
│   └── bot.py               # Telegram UI (/status, /yields, /risk)
├── config/
│   └── constants.py         # Contract addresses, ABIs, parameters
├── scripts/
│   ├── demo.py              # Demo runner
│   └── train.py             # RL training script
├── tests/
│   └── test_agent.py        # 25 unit + integration tests
├── requirements.txt
├── .env.example
└── README.md
```

## 🔑 Key Design Decisions

1. **Construct-Only Safety** — The agent constructs unsigned transaction payloads but NEVER holds private keys. Execution requires external signing via ERC-4337 wallet or multisig.

2. **Python-Native** — Built in Python (not TypeScript) because RL/ML libraries (PyTorch, stable-baselines3, Gymnasium) are Python-native.

3. **Fluxion DEX Primary** — Fluxion is Mantle's native RWA-focused AMM, primary routing for RWA token swaps.

4. **Risk-Parity Adaptive** — Portfolio construction adapts to risk regimes. High volatility → more USDY (safe haven). Depeg → emergency exit to USDC.

5. **On-Chain Audit Trail** — Every allocation decision is recorded on-chain with content hashes linking to IPFS-stored strategy reports.

6. **ERC-8004 + ERC-4337** — Agent identity via ERC-8004 (reputation, capabilities, attestations) + account abstraction via ERC-4337 (spending limits, session keys).

## 📊 Contract Addresses (Mantle Mainnet)

| Contract | Address |
|----------|---------|
| USDY (Ondo) | `0x5bE26527e817998A7206475496fDE1E68957c5A6` |
| mETH | `0xcDA86A272531e8640cD7F1a92c01839911B90bb0` |
| USDC | `0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9` |
| WMNT | `0x78c1b0C915c4FAA5FffA6CAbf0219DA63d7f4cb8` |
| Fluxion Router | `0x5628a59df0ecac3f3171f877a94beb26ba6dfaa0` |
| Agni Router | `0x319B69888b0d11cEC22caA5034e25FfFBDc88421` |
| Aave V3 Pool | `0x458F293454fE0d67EC0655f3672301301DD51422` |

## 🏆 Hackathon Track

**Mantle Turing Test Hackathon 2026 — Phase 2 "AI Awakening"**
- Track: AI × RWA
- Focus: Autonomous AI agents managing tokenized real-world assets
- Key Technologies: RL optimization, ERC-8004 agent identity, Mantle L2

## 📝 License

MIT

---

*Built with 🤖 for the Mantle Turing Test Hackathon 2026*