README.md

# 🏗️ 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 + LSTM yield prediction, with MEV-protected execution, auto-compounding, social sentiment analysis, and all decisions recorded on-chain via ERC-8004 agent identity NFTs. Ships with a **Binance-grade Next.js dashboard**.

---

## 🔥 What Makes This 10x Different

| Innovation | Description | Status |
|-----------|-------------|--------|
| **Ensemble AI Engine** | PPO RL optimizer + LSTM yield predictor + sentiment analyzer working in concert | ✅ Active |
| **MEV Protection Layer** | Sandwich detection, trade splitting, private mempool routing, optimal slippage | ✅ Active |
| **Auto-Compounding** | Gas-optimized yield restaking with mathematically optimal compound frequency | ✅ Active |
| **LSTM Yield Predictor** | 7-day yield forecasting with MC Dropout confidence intervals & regime detection | ✅ Active |
| **Social Sentiment** | Real-time crypto sentiment aggregation (Fear & Greed, social volume, news) | ✅ Active |
| **ERC-8004 Agent Identity** | Soulbound NFT with capabilities, attestations, reputation scoring, decision history | ✅ On-chain |
| **zkML-Ready Architecture** | Verifiable inference proofs for on-chain AI transparency (EZKL/Giza compatible) | 🔜 Planned |
| **Binance-Grade Dashboard** | Next.js + Tailwind + Recharts with full Binance design system (dark theme, trading UI) | ✅ Built |

---

## 📊 Portfolio Assets

| Asset | Type | Target APY | Risk | Protocol |
|-------|------|-----------|------|----------|
| **USDY** | Tokenized US T-Bills | ~4.25% + lending | Low | Ondo Finance |
| **mETH** | Liquid Staked ETH | ~3.9% + lending | Medium | Mantle LSP |
| **MI4** | Tokenized Index Fund | ~5.4% + lending | Medium | Securitize |

The agent captures **base yield + lending yield** (Aave V3 supply) for each asset, achieving total APYs of 4.7-6.2%.

---

## 🏛️ Architecture

```
┌──────────────────────────────────────────────────────────────────────────┐
│                     DYNAMIC RWA YIELD ROUTER v2.0                        │
│                                                                          │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐       │
│  │  OBSERVE   │→│   PREDICT  │→│   REASON   │→│    PLAN    │       │
│  │            │  │            │  │            │  │            │       │
│  │ DeFiLlama │  │ LSTM Yield │  │ PPO Policy │  │ Rebalance  │       │
│  │ CoinGecko │  │ Predictor  │  │  + Ensemble│  │ + MEV Opt  │       │
│  │ Mantle RPC│  │ + Sentiment│  │            │  │ + Splitter │       │
│  │ FRED/News │  │ + Regime   │  │            │  │            │       │
│  └────────────┘  └────────────┘  └────────────┘  └────────────┘       │
│       ↓                                                ↓               │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐     │
│  │  AUTHORIZE │→│  EXECUTE   │→│AUTOCOMPOUND│→│   VERIFY   │     │
│  │            │  │            │  │            │  │            │     │
│  │ 6-Layer    │  │ Unsigned Tx│  │ Gas-Optimal│  │ On-chain   │     │
│  │ Risk Mgr   │  │ + MEV Prot │  │ Restaking  │  │ + ERC-8004 │     │
│  │ + Sentiment│  │ + Whitelist│  │ Automation │  │ Attestation│     │
│  └────────────┘  └────────────┘  └────────────┘  └────────────┘     │
│                                                                        │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                    ON-CHAIN CONTRACTS                             │  │
│  │  YieldRouterAgent.sol │ AgentIdentity8004.sol │ RiskRegistry.sol│  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                                                                        │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │              BINANCE-STYLE NEXT.JS DASHBOARD                     │  │
│  │  Portfolio │ Markets │ AI Optimizer │ Risk │ Agent Identity      │  │
│  └──────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────┘
```

### 8-Stage Agent Pipeline (v2.0)

1. **OBSERVE** — Fetch real-time yield, price, macro, and sentiment data
2. **PREDICT** — LSTM yield forecasting with MC Dropout confidence + regime detection
3. **REASON** — PPO policy + ensemble (combine RL action with LSTM prediction + sentiment)
4. **PLAN** — Compute trades with MEV analysis (sandwich detection, trade splitting)
5. **AUTHORIZE** — 6-layer risk manager (depeg, volatility, concentration, drawdown, circuit breaker, sentiment)
6. **EXECUTE** — Construct MEV-protected unsigned transactions (private mempool, optimal deadline)
7. **AUTO-COMPOUND** — Gas-optimized yield restaking at mathematically optimal frequency
8. **VERIFY** — Confirm on-chain, update ERC-8004 reputation, generate strategy report

---

## 🧠 AI/ML Stack

### PPO Reinforcement Learning
- **Algorithm:** Proximal Policy Optimization with Actor-Critic MLP
- **State Space:** 18-dimensional (yields, prices, macro, risk signals, portfolio weights)
- **Action Space:** 3-dimensional continuous → softmax → weights [USDY, mETH, MI4]
- **Reward:** Risk-adjusted Sharpe ratio - drawdown penalty - depeg penalty - gas costs

### LSTM Yield Predictor *(Novel)*
- **Architecture:** 2-layer LSTM with attention mechanism
- **Input:** Yield history, price momentum, fed rate, volatility, sentiment
- **MC Dropout:** 50 forward passes for uncertainty estimation (confidence intervals)
- **Regime Detection:** Bull/Bear/Sideways classification head
- **Feature Importance:** Attention weights reveal which features drove the prediction

### Social Sentiment Analyzer *(Novel)*
- **Sources:** Fear & Greed Index, social volume, news sentiment
- **Integration:** Sentiment score feeds into both LSTM predictor and risk manager
- **Impact:** High fear → increase USDY (safe haven), High greed → lean into mETH/MI4

---

## 🛡️ Novel Risk & Execution Features

### MEV Protection Layer *(Novel)*
- **Sandwich Attack Detection:** Estimates price impact per trade
- **Trade Splitting:** Automatically splits large trades to reduce MEV exposure
- **Private Mempool:** Routes high-impact trades through private channels
- **Optimal Deadlines:** Shorter deadlines for high-risk trades, longer for low-risk

### Auto-Compounding Engine *(Novel)*
- **Optimal Frequency:** Calculates gas-optimal compound interval using calculus optimization
- **Formula:** `n* = √(APY × Principal / (2 × GasCost))` compounds per year
- **Break-even:** Computes minimum principal where compounding beats simple yield
- **Smart Triggers:** Only compounds when accumulated yield > 3× gas cost

### 6-Layer Risk Management
| Layer | Description | Trigger |
|-------|-------------|---------|
| Depeg Detection | USDY/USD and mETH/ETH peg monitoring | >0.5% / >2% |
| Volatility Guard | Dynamic exposure reduction in high-vol regimes | ETH 30d vol >80% |
| Concentration Limits | Position size enforcement | >60% or <5% |
| Smart Contract Risk | Protocol-weighted risk scoring | Per-protocol scores |
| Drawdown Protection | Circuit breaker on portfolio losses | DD >10% |
| Sentiment Guard *(Novel)* | Reduces risky exposure on extreme fear | Score <20 |

---

## 🎨 Dashboard (Next.js + Binance Design)

Full-featured financial dashboard built with the **Binance Design System**:

- **Dark canvas** (#0b0e11) with card surfaces (#1e2329)
- **Binance Yellow** (#FCD535) accent for CTAs and brand elements
- **Trading green/red** (#0ecb81/#f6465d) for price direction semantics
- **BinancePlex substitute** (JetBrains Mono) for all financial numbers
- **6 dashboard sections:** Portfolio, Markets, AI Optimizer, Risk Monitor, Reports, Agent Identity

### Dashboard Features
- 📈 Real-time portfolio value chart with timeframe selector
- 🥧 Live allocation pie chart + weight history area chart
- 📊 RWA markets table with yield comparison bar chart
- 🧠 LSTM yield predictions with confidence bars + AI recommendations
- 🌡️ Social sentiment gauge with source breakdown
- 🛡️ Risk score ring, protection layer status, activity log
- 🤖 ERC-8004 agent identity card with reputation, capabilities, attestations
- 📱 Fully responsive (mobile hamburger, tablet 2-up, desktop full layout)

```bash
# Run the dashboard
cd dashboard && npm install && npm run dev
```

---

## 🚀 Quick Start

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

# Install Python dependencies
pip install -r requirements.txt

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

# Train RL agent
python scripts/train.py

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

# Run tests (25 passing)
pytest tests/ -v

# Run dashboard
cd dashboard && npm install && npm run dev
```

---

## 📂 Project Structure

```
mantle-rwa-yield-router/
├── agent/
│   ├── main.py              # 8-stage orchestrator pipeline
│   ├── data_pipeline.py     # Real-time data aggregation (8 sources)
│   ├── rl_optimizer.py      # PPO agent + Gymnasium environment
│   ├── risk_manager.py      # 6-layer risk management
│   ├── executor.py          # MEV-protected unsigned tx builder
│   ├── strategy_reporter.py # LLM strategy letter generator
│   └── novel_features.py    # LSTM predictor, MEV shield, auto-compound, sentiment
├── contracts/
│   ├── YieldRouterAgent.sol  # On-chain allocation router
│   ├── AgentIdentity8004.sol # ERC-8004 soulbound agent identity
│   └── RiskRegistry.sol      # On-chain risk parameters
├── dashboard/                # Next.js Binance-style UI
│   ├── src/app/page.tsx      # Main dashboard page
│   ├── src/components/       # TopNav, Charts, RiskMonitor, AIOptimizer, AgentIdentity
│   └── src/lib/data.ts       # Data generators and mock data
├── telegram_bot/
│   └── bot.py               # Telegram UI (/status, /yields, /risk)
├── config/
│   └── constants.py         # All 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
```

---

## 📜 Smart Contracts

### `YieldRouterAgent.sol`
On-chain allocation records, position limits, circuit breaker, operator authorization.

### `AgentIdentity8004.sol` (ERC-8004)
Soulbound agent identity NFT: capabilities, attestations, reputation (0-10000), decision history.

### `RiskRegistry.sol`
On-chain risk parameters, depeg event tracking, allocation validation.

---

## 📊 Contract Addresses (Mantle Mainnet, Chain ID 5000)

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

---

## 🔑 Key Design Decisions

1. **Construct-Only Safety** — Never holds private keys. All outputs are unsigned tx payloads.
2. **Ensemble Intelligence** — PPO + LSTM + Sentiment provide richer signals than any single model.
3. **MEV-Aware** — Every trade goes through sandwich detection + optimal splitting.
4. **Gas-Optimized Compounding** — Mathematical optimization of compound frequency vs gas costs.
5. **On-Chain Audit Trail** — ERC-8004 records every decision with content hashes.
6. **Binance-Grade UI** — Production dashboard, not a demo. Full dark theme, live charts, responsive.

---

## 🏆 Hackathon Track

**Mantle Turing Test Hackathon 2026 — Phase 2 "AI Awakening"**
- **Track:** AI × RWA ($100K prize pool)
- **Focus:** Autonomous AI agents managing tokenized real-world assets
- **Key Tech:** RL optimization, LSTM prediction, ERC-8004, MEV protection, Mantle L2

## 📝 License

MIT

---

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