Mantle RealFi Console

# Mantle RealFi Console Documentation (User Guide)

This document is for product users. It covers both the user-facing portal and the admin console.

## Part A. User Portal (Investors)
### 1. Wallet Connection
- Click Connect Wallet in the header.
- Supported: MetaMask and WalletConnect.
- Networks: Mantle Mainnet (5000) and Mantle Testnet (5003). Use the network switcher in the header.

### 2. Marketplace
Entry: Home page
Key capabilities:
- Search and filter by asset type, status, and risk level.
- Sort by APY, risk, AUM, and price.
- Switch between list and grid views.
- Compare up to three assets side by side.
- Favorite assets for quick access later.
- Invest action (requires wallet connection).

### 3. Asset Detail
Entry: Click any asset from the marketplace
You can view:
- APY, risk score, duration, price, and next payout date.
- Yield breakdown and confidence metrics.
- 30-day yield and NAV charts.
- Cash flow sources and on-chain addresses.
You can do:
- Add Position (buy more units)
- Redeem (sell units)
- Ask Copilot for AI insights

### 4. Portfolio Dashboard
Entry: Dashboard
You can view:
- Total portfolio AUM, weighted APY, and risk score.
- Holdings list with performance indicators.
- Quick actions: browse market, transaction history, AI assist, rebalance hints.

### 5. Transaction History
Entry: Dashboard > Transaction History
You can view:
- Investments, redemptions, and yield payouts.
- Filters by transaction type.
- On-chain transaction links when available.

### 6. AI Copilot
Entry: Copilot
Capabilities:
- Explain portfolio risk and allocation.
- Suggest rebalancing ideas.
- Use full portfolio context or a single asset context.

## Part B. Admin Console (Operations)
### 1. Admin Access
- Admins are verified by wallet address.
- Roles: `super_admin`, `admin`, `reviewer`.
- Permissions vary by role (e.g., delete actions require super admin).

### 2. Admin Dashboard
Entry: `/admin`
You can view:
- AUM, active users, investment count, pending yields.
- Application status counts and shortcuts.
- Asset distribution and platform health highlights.

### 3. Asset Applications
Entry: `/admin/applications`
You can:
- Review all applications and filter by status.
- Open details and inspect on-chain registration info.
- Approve, reject, or request changes.

### 4. Create New Application
Entry: `/admin/applications/new`
Workflow:
- Fill basic data (name, type, description).
- Add financial details (APY, AUM, minimum investment, duration, risk).
- Provide type-specific fields (fixed income, real estate, private credit, alternatives).
- On submit, the app writes metadata to `AssetRegistry.registerAsset` and stores the application.

### 5. Asset Management
Entry: `/admin/assets`
You can:
- Activate/pause assets.
- Edit APY, price, and status.
- Delete assets (super admin only).

### 6. User Management and KYC
Entry: `/admin/users`
You can:
- Review KYC status and freeze/unfreeze accounts.
- Open user detail view for balances and activity.

### 7. Yield Distribution
Entry: `/admin/yields`
You can:
- See pending distributions by asset.
- Execute yield payouts.
- Export distribution history.

### 8. Analytics
Entry: `/admin/analytics`
You can:
- Inspect AUM by asset type.
- Review risk distribution.
- Monitor operational health signals (KYC backlog, high-risk exposure).

## FAQ
### Q1: I cannot see assets.
- Check if you are on the correct network.
- Ensure the backend has assets seeded in the database.

### Q2: I cannot invest.
- Confirm wallet is connected.
- Ensure the asset status is Active.

### Q3: I cannot access the admin console.
- Your wallet address must exist in the `admins` table and be active.

## Notes
- This build is demo-focused and includes simulated yields in some flows.
- For production, ensure strict permission controls and audited on-chain integrations.
# Mantle RealFi Console Documentation (Technical)

This document targets engineers and delivery teams. It summarizes architecture, modules, data model, APIs, and environment setup.

## 1. Project Overview
- Goal: Provide a full-stack console for RWA (Real World Assets) onboarding, investment, yield distribution, and operations.
- Architecture: Smart contracts + Next.js App Router (frontend + API routes) + Supabase/PostgreSQL + wallet/chain integration.
- Frontend workspace: `Frontend/` (both user and admin experiences live in one Next.js app).

## 2. Tech Stack
- Frontend: Next.js 16 App Router, React 19, Tailwind CSS 4, Lucide Icons, Recharts
- Wallet: wagmi + viem (Mantle Mainnet / Sepolia)
- Backend: Next.js Route Handlers (`Frontend/app/api/*`)
- Database: PostgreSQL (Supabase), Prisma schema at `Frontend/prisma/schema.prisma`
- Contracts: Solidity ^0.8.20, OpenZeppelin

## 3. Core Structure
- `contracts/` smart contracts
- `Frontend/app/` pages and API routes
- `Frontend/components/` UI and business components
- `Frontend/lib/` hooks, chain clients, Supabase, mock data
- `Frontend/prisma/` database schema

## 4. Smart Contracts
### 4.1 Asset Registry
- `contracts/AssetRegistry.sol`
  - Minimal on-chain registry storing key fields and off-chain metadata hash.
  - Events: `AssetRegistered`, `AssetStatusUpdated`.

### 4.2 Asset Vault
- `contracts/AssetVault.sol`
  - Handles invest/redeem by assetId with price and minimum checks.
  - Tracks user units and total units per asset.

### 4.3 Platform Token + Exchange
- `contracts/RWAExchange.sol`
  - Platform-wide RWA token and exchange from supported assets (e.g., MNT).
  - Supports token list, pricing, exchange and redeem flows.

### 4.4 Per-Asset Token
- `contracts/RWAToken.sol`
  - ERC20 token per asset with metadata (APY, risk, duration, AUM, etc.).
  - Includes demo invest/redeem and payout tracking logic.

### 4.5 Yield Distribution
- `contracts/YieldDistributor.sol`
  - Records or schedules yield distributions (demo logic, event-based).

## 5. Frontend Pages
### 5.1 User Experience
- Marketplace: `Frontend/app/page.tsx`
  - Search, filter, sort, compare, favorite, invest entry.
- Asset Detail: `Frontend/app/assets/[id]/page.tsx`
  - Yield breakdown, risk, NAV/yield charts, on-chain info, add/redeem.
- Portfolio Dashboard: `Frontend/app/dashboard/page.tsx`
  - Holdings, summary metrics, quick actions.
- Transactions: `Frontend/app/dashboard/transactions/page.tsx`
  - Invest/redeem/yield history with filters.
- Copilot: `Frontend/app/copilot/page.tsx`
  - AI assistant for portfolio questions and rebalance hints.

### 5.2 Admin Experience
- Admin Dashboard: `Frontend/app/admin/page.tsx`
  - AUM, users, yields, applications summary.
- Applications: `Frontend/app/admin/applications/*`
  - Create, review, approve/reject, detail view.
- Assets: `Frontend/app/admin/assets/page.tsx`
  - Manage listing status, edit pricing/APY, delete (super admin).
- Users: `Frontend/app/admin/users/page.tsx`
  - KYC status, freeze/unfreeze, user detail panel.
- Yields: `Frontend/app/admin/yields/page.tsx`
  - Pending distributions and history.
- Analytics: `Frontend/app/admin/analytics/page.tsx`
  - AUM distribution, risk distribution, operational health.

## 6. API Routes
### 6.1 User APIs
- Assets: `GET /api/assets`, `GET /api/assets/[id]`
- Portfolio: `GET /api/portfolio`, `POST /api/portfolio` (invest/redeem)
- Transactions: `GET /api/transactions`, `POST /api/transactions`
- Balance: `/api/balance`, `/api/balance/recharge`
- AI Copilot: `/api/ai/copilot`

### 6.2 Admin APIs
- Verify admin: `/api/admin/verify`
- Applications: `GET/POST /api/admin/applications`, `GET/PATCH/DELETE /api/admin/applications/[id]`
- Assets: `GET /api/admin/assets`, `PATCH/DELETE /api/admin/assets/[id]`
- Users: `GET /api/admin/users`, `POST /api/admin/users/[id]/kyc`, `POST /api/admin/users/[id]/freeze`
- Yields: `GET/POST /api/admin/yields`
- Stats: `GET /api/admin/stats`

### 6.3 Authorization Model
- Admin APIs read `x-wallet-address` and validate against the `admins` table.
- Roles: `super_admin`, `admin`, `reviewer` (see `Frontend/lib/supabase.ts`).

## 7. Data Model (Highlights)
- `assets`: master asset table (type, APY, risk, AUM, price, status, token info)
- `asset_*`: yield breakdown, confidence, real world info, verification, cash flow, history
- `users`: wallet identities and registration
- `portfolios` / `portfolio_holdings`: holdings and cash
- `user_transactions`: invest/redeem/yield transactions
- `asset_applications`: asset onboarding and review workflow
- `admins` / `admin_logs`: admin users and audit logs

## 8. Key Flows
### 8.1 Asset Application to Listing
1. Admin creates application, and writes on-chain metadata hash via `AssetRegistry.registerAsset`.
2. Application stored in `asset_applications`.
3. Approval triggers creation in `assets` and auto listing.

### 8.2 Investment and Holdings
1. User connects wallet and fetches assets.
2. Invest/redeem via `/api/portfolio`, updates holdings and events.
3. Asset detail view pulls per-asset data for charts and insights.

### 8.3 Yield Distribution
1. Admin fetches pending yield assets.
2. Execute distribution, record results, update history.

## 9. Environment and Config
### 9.1 Network and Contracts
- `Frontend/lib/config/networks.ts`: Mantle Mainnet/Testnet definitions
- `Frontend/lib/contracts`: contract addresses and ABI used by the app

### 9.2 Env Variables (Example)
`Frontend/.env.local`:
```
DATABASE_URL=postgresql://postgres:postgres123@localhost:5432/mantle
NEXT_PUBLIC_SUPABASE_URL=...
SUPABASE_SERVICE_KEY=...
SUPABASE_ANON_KEY=...
WALLETCONNECT_PROJECT_ID=...
```

## 10. Development
### Contracts
```
npm install
npm run compile
npm run test
npm run deploy:testnet
```

### Frontend
```
cd Frontend
pnpm install
pnpm dev
pnpm build
pnpm start
```

## 11. Notes and Limitations
- Current version includes demo logic and simulated yields.
- Production rollout should harden permissions, on-chain integration, and operational monitoring.