omeswap

# 🌊 Omeswap — Mantle DEX **Omeswap** is a next-generation decentralized exchange (DEX) and DeFi platform built natively on **Mantle Network (L2)**. It combines a fully functional Uniswap V2-style Automated Market Maker (AMM) with advanced portfolio analytics, token research tools, and a visual AI agent builder — all wrapped in a stunning, modern interface.     --- ## 📖 Project Overview Omeswap is designed to be the all-in-one DeFi hub for traders, liquidity providers, and developers on Mantle. Unlike traditional DEXs that only offer swapping functionality, Omeswap provides: 1. **Decentralized Trading** — Swap tokens with optimal routing through multi-hop paths 2. **Liquidity Management** — Provide liquidity to pools and earn trading fees 3. **Portfolio Tracking** — Real-time wallet analysis across multiple chains 4. **Token Research** — Deep token analytics with audit scores, charts, and fundamental analysis 5. **DEX Explorer** — Browse all pools, tokens, and transactions on the protocol 6. **AI Agent Builder** — Visually design and deploy automated trading strategies ### 🎯 Why Omeswap? | Feature | Traditional DEX | Omeswap | |---------|----------------|---------| | Token Swaps | ✅ | ✅ | | Multi-hop Routing | ❌ | ✅ | | Portfolio Analytics | ❌ | ✅ | | Token Research & Audits | ❌ | ✅ | | AI Trading Agents | ❌ | ✅ | | L2 Low Gas Fees | Varies | ✅ (Mantle) | | Modern UI/UX | Basic | ✅ Premium | --- ## ✨ Core Features ### 🔄 Decentralized Exchange (AMM) - **Uniswap V2 Constant Product AMM** — `x * y = k` formula for fair, permissionless trading - **Multi-Hop Swap Router** — Automatically routes through multiple pools to find the best price (e.g., tUSDC → tWETH → tWBTC in a single transaction) - **0.3% LP Fees** — Liquidity providers earn fees on every trade proportional to their share - **Slippage Protection** — Configurable slippage tolerance to protect against price movements - **10 Testnet Tokens** — tUSDC, tUSDT, tDAI, tWETH, tWBTC, tLINK, tUNI, tAAVE, tCRV, tMKR ### 💧 Liquidity Provision - **Add Liquidity** — Deposit token pairs to liquidity pools and receive LP tokens - **Remove Liquidity** — Burn LP tokens to withdraw your proportional share anytime - **Pool Analytics** — View reserves, total supply, your position value, and fee earnings - **Dual Token Approval** — Streamlined UX for approving both tokens before adding liquidity ### 📊 DEX Explorer - **Tokens Table** — Browse all tokens with price, 24h volume, liquidity, and sparkline charts - **Pools Table** — View all liquidity pools with TVL, volume, APR estimates, and composition - **Transactions Feed** — Real-time feed of swaps, adds, and removes across the protocol - **Global Stats** — Total Value Locked (TVL), 24h volume, and protocol-wide metrics - **Advanced Filtering** — Search, sort, and filter by multiple criteria ### 💼 Portfolio Dashboard - **Wallet Analysis** — Connect your wallet to see real-time token holdings and values - **Multi-Chain Support** — Track assets across Ethereum, Polygon, and other EVM chains - **Net Worth Tracking** — Aggregated portfolio value with historical charts - **Custom Address Analysis** — Analyze any wallet address without connecting - **Dust Filtering** — Hide low-value tokens for a cleaner view - **Agent Wallet Cards** — Dedicated tracking for AI agent-managed funds ### 🔍 Token Detail Pages - **Comprehensive Analytics** — Price charts, market cap, volume, circulating supply - **Audit Scores** — Financial, fundamental, social, and security ratings (0-100) - **Fundamental Analysis** — AI-generated insights on tokenomics and project health - **Technical Analysis** — Chart indicators and trading signals - **Volume Breakdown** — CEX vs DEX volume distribution - **Related Tokens** — Discover similar tokens and alternatives - **Integrated Swap** — Trade directly from the token detail page ### 🤖 AI Agent Builder (No-Code Trading Bots) Build automated trading strategies visually with a drag-and-drop flow canvas: #### Block Types: - **Triggers** — Price threshold, price change %, time-based, manual, on-chain events - **Conditions** — If/else logic, comparisons, AND/OR gates, range checks - **Actions** — Buy, sell, swap, limit orders, stop-loss, take-profit - **Strategies** — DCA, grid trading, arbitrage, market making, trailing stops - **Indicators** — RSI, MACD, moving averages, Bollinger Bands, volume #### Agent Features: - Visual flow-based editor (React Flow) - Parameter configuration for each block - Save, load, and manage multiple agents - Execution status tracking - Draft → Testing → Active → Paused lifecycle ### 🎨 Premium UI/UX - **3D Spline Animations** — Interactive 3D scenes on the landing page - **Liquid Ether Background** — Fluid simulation background effects - **GSAP Animations** — Smooth scroll-triggered animations - **Framer Motion** — Delightful micro-interactions throughout - **Variable Font Proximity** — Text that reacts to cursor position - **Dark Theme** — Optimized for night trading sessions - **Responsive Design** — Seamless experience from mobile to 4K displays - **shadcn/ui Components** — Accessible, customizable UI primitives --- ## 🏗️ Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ FRONTEND (Next.js 15) │ │ React 19 • Tailwind CSS • shadcn/ui • Framer Motion • GSAP │ ├─────────────────────────────────────────────────────────────────┤ │ Pages: │ Components: │ │ • Landing (3D Hero + Bento) │ • SwapCard │ │ • Trade (Swap/Liquidity/Mint) │ • AddLiquidityCard │ │ • Explore (Tokens/Pools/Txns) │ • TokensTable / PoolsTable │ │ • Portfolio (Holdings/Analysis) │ • AgentBlockNode / Canvas │ │ • Token Detail (Charts/Audits) │ • WalletAnalysisPanel │ │ • Agent Builder (Flow Editor) │ • PriceChart / RadarChart │ └───────────────────┬─────────────────────────────────────────────┘ │ wagmi v2 + viem v2 + RainbowKit │ TanStack Query (caching) ▼ ┌─────────────────────────────────────────────────────────────────┐ │ WEB3 / BLOCKCHAIN LAYER │ ├─────────────────────────────────────────────────────────────────┤ │ Custom Hooks: │ External APIs: │ │ • use-dex-swap │ • CoinGecko (prices/metadata) │ │ • use-liquidity │ • Wallet Analysis Service │ │ • use-token-mint │ • OpenAI (agent logic) │ │ • use-dex-pools │ │ │ • use-wallet-analysis │ │ │ • use-pool-details │ │ └───────────────────┬─────────────────────────────────────────────┘ │ JSON-RPC (https://rpc.sepolia.mantle.xyz) ▼ ┌─────────────────────────────────────────────────────────────────┐ │ MANTLE SEPOLIA TESTNET (Chain ID: 5003) │ ├─────────────────────────────────────────────────────────────────┤ │ Smart Contracts (Solidity 0.8.20): │ │ │ │ ┌─────────────────────────────────────────┐ │ │ │ MultiTokenLiquidityPools (0xe635...) │ │ │ │ • createPool() │ │ │ │ • addLiquidity() / removeLiquidity() │ │ │ │ • swap() — single-hop swaps │ │ │ │ • getReserves() / getUserPosition() │ │ │ └─────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────┐ │ │ │ MultiHopSwapRouter (0xFe21...) │ │ │ │ • swapExactTokensForTokens() │ │ │ │ • getAmountsOut() — path simulation │ │ │ │ • Multi-hop routing (2-3+ hops) │ │ │ └─────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────┐ │ │ │ 10 Test ERC20 Tokens (Mintable) │ │ │ │ tUSDC, tUSDT, tDAI, tWETH, tWBTC... │ │ │ └─────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## 📝 Smart Contracts ### Deployed on Mantle Sepolia Testnet | Contract | Address | Description | |----------|---------|-------------| | **MultiTokenLiquidityPools** | `0xe63514C2B0842B58A16Ced0C63668BAA91B033Af` | AMM pools, liquidity, single-hop swaps | | **MultiHopSwapRouter** | `0xFe2108798dC74481d5cCE1588cBD00801758dD6d` | Multi-hop routing engine | | **tUSDC** | `0x6D13968b1Fe787ed0237D3645D094161CC165E4c` | Test USDC token | | **tUSDT** | `0x0828b7774ea41Db0fCbf13ADe31b5F61624A1364` | Test USDT token | | **tDAI** | `0x907fF6a35a3E030c11a02e937527402F0d3333ee` | Test DAI token | | **tWETH** | `0x95829976c0cd4a58fBaA4802410d10BDe15E3CA0` | Test Wrapped ETH | | **tWBTC** | `0xD781bf79d86112215F7bF141277f5782640cad5D` | Test Wrapped BTC | | **tLINK** | `0xCEbBd58F40c8CE0739327fDde1A52bb67557e37a` | Test Chainlink token | | **tUNI** | `0xe771E51F90D7176B6bd17a123f7D78c2231158a0` | Test Uniswap token | | **tAAVE** | `0x6b1F4e0Eea462745750dddaEB11FB85B968a87F6` | Test Aave token | | **tCRV** | `0xa6bAeA5811Bd070AeF343537b03A909597002526` | Test Curve token | | **tMKR** | `0x4296e3e1d3efbb5bac66a66f1E463BAc25Ec6189` | Test Maker token | [View on Mantle Sepolia Explorer →](https://explorer.sepolia.mantle.xyz) --- ## 🎯 Use Cases ### For Traders - Swap tokens with minimal slippage via intelligent multi-hop routing - Research tokens with comprehensive analytics and audit scores - Track your portfolio value and holdings in real-time - Build automated trading strategies without coding ### For Liquidity Providers - Earn 0.3% fees on all swaps in pools you provide liquidity to - Track your LP positions and accumulated fees - Add/remove liquidity anytime with no lock-up periods ### For Developers - Study a production-grade AMM implementation - Learn wagmi v2, viem v2, and modern React patterns - Explore visual programming concepts with the agent builder - Fork, customize, and deploy your own DEX ## 🚀 Quick Start ### 1. Install Dependencies ```bash npm install ``` ### 2. Setup Environment Create `.env.local`: ```bash NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_project_id ``` Get your WalletConnect Project ID from: https://cloud.walletconnect.com/ ### 3. Start Development Server ```bash npm run dev ``` Visit: **http://localhost:3000** ### 4. Connect & Trade 1. **Connect Wallet** (top right corner) 2. **Switch to Mantle Sepolia Testnet** 3. **Get testnet MNT** from https://faucet.sepolia.mantle.xyz 4. **Mint test tokens** (Mint Tokens tab) 5. **Add liquidity** or **start swapping**! ## 📋 Prerequisites - Node.js 18+ - MetaMask or compatible wallet - Testnet MNT (for gas fees) ## 🏗️ Tech Stack ### Frontend - **Framework:** Next.js 15 (App Router) - **UI Library:** React 19 - **Styling:** Tailwind CSS + shadcn/ui - **Web3:** wagmi v2 + viem v2 - **Wallet:** RainbowKit ### Smart Contracts - **Language:** Solidity 0.8.20 - **Framework:** Hardhat - **Network:** Mantle Sepolia Testnet - **Testing:** Chai + Ethers.js ## 📝 Smart Contracts ### Deployed on Mantle Sepolia | Contract | Address | |----------|---------| | **Liquidity Pools** | `0xe63514C2B0842B58A16Ced0C63668BAA91B033Af` | | **Swap Router** | `0xFe2108798dC74481d5cCE1588cBD00801758dD6d` | [View on Explorer →](https://explorer.sepolia.mantle.xyz) ## 🎯 Use Cases ### For Traders - Swap tokens with minimal slippage - Multi-hop routing finds best paths - Low gas costs on L2 ### For Liquidity Providers - Earn 0.3% on all swaps - Receive LP tokens - Remove liquidity anytime ### For Developers - Learn AMM mechanics - Study DeFi integration - Fork and customize ## 📚 Documentation - **[Implementation Summary](./IMPLEMENTATION_SUMMARY.md)** - Complete technical overview and implementation details ## 🧪 Testing ### Frontend Testing ```bash npm run dev ``` ### Smart Contract Testing ```bash cd ../Mantel_contract npx hardhat test ``` ### Backend Scripts ```bash # Mint test tokens npm run hardhat:mint # Add liquidity npm run hardhat:liquidity # Execute swap npm run hardhat:swap # Multi-hop swap npm run hardhat:multihop # Complete setup npm run hardhat:quickstart ``` ## 🔒 Security ⚠️ **Testnet Only**: This DEX is deployed on Mantle Sepolia Testnet. All tokens are for testing purposes and have **no real value**. For production use: - Professional security audit required - Implement additional safety checks - Add protocol fee mechanism - Enable emergency pause functionality ## 🛠️ Development ### Project Structure ``` Mantle_Dex/ ├── app/ # Next.js pages ├── components/ # React components │ ├── trade/ # DEX trading components │ ├── portfolio/ # Portfolio management │ └── features/ # Wallet integration ├── contracts/ # Contract ABIs & config ├── hooks/ # Custom React hooks ├── lib/ # Utilities └── scripts/ # Hardhat interaction scripts ``` ### Available Scripts ```bash npm run dev # Start dev server npm run build # Build for production npm run start # Start production server npm run lint # Run linter npm run hardhat:* # Hardhat operations ``` ## 🌐 Network Configuration ### Mantle Sepolia Testnet - **Chain ID:** 5003 - **RPC URL:** https://rpc.sepolia.mantle.xyz - **Explorer:** https://explorer.sepolia.mantle.xyz - **Faucet:** https://faucet.sepolia.mantle.xyz Add to MetaMask: 1. Networks → Add Network → Add Manually 2. Enter the details above 3. Save ## 🎨 Features Walkthrough ### 1. Token Swapping - Select input/output tokens - Enter amount - Review estimated output - Approve & swap - Track transaction on explorer ### 2. Liquidity Management - Choose token pair - Enter amounts (auto-calculated ratio) - Approve both tokens - Add liquidity - Receive LP tokens ### 3. Multi-Hop Routing - Swap tokens without direct pools - Example: DAI → USDC → WETH → WBTC - Atomic transaction (all-or-nothing) - Automatic path finding ## 🤝 Contributing Contributions are welcome! Please: 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Submit a pull request ## 📄 License MIT License - see [LICENSE](./LICENSE) file ## 🙏 Acknowledgments - Uniswap V2 for the AMM design - Mantle Network for L2 infrastructure - shadcn/ui for beautiful components - wagmi & viem for Web3 integration ## 📞 Support - **Issues:** GitHub Issues - **Docs:** [Integration Guide](./DEX_INTEGRATION_GUIDE.md) - **Explorer:** https://explorer.sepolia.mantle.xyz ## 🎉 Getting Started Ready to try it out? ```bash npm install npm run dev ``` Then visit **http://localhost:3000/trade** and start trading! --- **Built with ❤️ on Mantle Network** ⭐ Star this repo if you found it helpful!

na