MetaVault AI

An AI-Powered DeFi Vault managed by AI Agents created using ADK-TS by IQAI. This project combines a secure smart contract vault, a modern Next.js frontend, and intelligent agents to optimize DeFi strategies.

📂 Repository Structure

This is a monorepo containing the following packages:

• packages/contracts: Hardhat project containing the smart contracts for the vault and strategies.
• packages/frontend: Next.js web application for users to interact with the vault.
• packages/agents: AI agents built with ADK-TS that monitor and manage the vault strategies.

🧠 Powered by ADK-TS (Agent Development Kit)

This project is a showcase of the ADK-TS (Agent Development Kit) by IQAI, demonstrating how to build complex, autonomous DeFi agents using TypeScript.

How ADK-TS Powers MetaVault AI:

1. Conversation Orchestration Layer:

   • Session Memory: Handles conversation memory for the session.
   • Tool Management: Manages structured tool response formatting and guides the agent to use tools correctly.
   • Frontend Simplicity: Reduces frontend logic complexity as the agent handles user interaction.

2. TypeScript Integration:

   • Developer Experience: Tools, agent logic, and types are all written in TypeScript, making it developer-friendly and strongly typed.
   • Seamless Integration: Easy to integrate with the Next.js/React frontend.

3. Context State Management: Built-in state management for storing context, such as caching the latest APY updates.

4. Modular Architecture: Uses AgentBuilder to orchestrate specialized agents (StrategySentinel, YieldSimulator) for distinct responsibilities.

---

🤖 AI Agent System

The vault is managed by a team of specialized AI agents:

1. Strategy Sentinel Agent 🛡️

Role: Guardian & Portfolio Manager

• Responsibilities:
  • Continuously monitors strategy health (LTV, Liquidation Risk).
  • Fetches real-time token prices (LINK/WETH) to make market-aware decisions.
  • Risk Management: Automatically pauses strategies or reduces leverage during high volatility.
  • Rebalancing: Adjusts portfolio weights between safe and leveraged strategies based on market conditions.
  • Harvesting: Collects yields and compounds them back into the vault.

2. Chat Agent 💬

Role: User Assistant

• Responsibilities:
  • Provides a natural language interface for users to interact with the vault.
  • Checks user balances and vault statistics securely.
  • Facilitates deposits and withdrawals via chat commands.
  • Privacy: Strictly enforces security boundaries, ensuring it never exposes admin functions or other users' data.

3. Yield Simulator Agent 📈

Role: Yield Generator

• Responsibilities:
  • Simulates yield accrual scenarios for testing and demonstration purposes.
  • Helps validate the vault's profit distribution logic.

---

🏦 Vault Strategies

The MetaVault allocates user funds into multiple strategies to maximize yield while managing risk.
For development and testing purposes, all strategies currently run on mock contracts to simulate Aave mechanics, liquidity indices, borrowing flows, and interest behavior.

---

1. Aave V3 Strategy (Safe)

• Description: A low-risk strategy that supplies assets (LINK) to a mock Aave V3 lending pool used for testing.
• Mechanism: Earns simulated passive supply APY using a mocked liquidity index.
• Risk Profile: Low. In production, this maps to real Aave behavior, but in the current environment it operates on mock contracts for predictable testing.
• Mock Note: The entire interest accrual is driven by a mock liquidity index set to 1e18 unless programmatically updated.

---

2. Aave Leverage Strategy (Aggressive)

• Description: A high-yield strategy that simulates leveraged looping by interacting with a mocked Aave pool and mock swap router.

• Mechanism:

  1. Supplies LINK to mocked Aave.
  2. Borrows mock WETH against the LINK collateral.
  3. Swaps borrowed WETH for LINK using a mock swap contract.
  4. Resupplies the LINK.
  5. Repeats the loop for maxDepth iterations.

• Risk Profile: High. Reflects the risks of real leverage (e.g., liquidation), though all liquidation thresholds and LTV calculations are currently performed through mocked logic.

• AI Management:
  The Strategy Sentinel Agent monitors mock LTV values and real LINK/WETH prices and then performs simulated auto-deleveraging when the position approaches the configured danger zone.

---

🚀 Getting Started

Prerequisites

• Node.js (v18+ recommended)
• pnpm (Package manager)
• MetaMask or another Web3 wallet

Installation

1. Clone the repository:

   git clone <repository-url>
   cd defi-portfolio

2. Install dependencies for all packages:

   pnpm install

🛠️ Running the Project

To run the full stack, you need to start the blockchain (or deploy to testnet), run the agent server, and start the frontend.

1. Smart Contracts (packages/contracts)

Navigate to the contracts directory:

cd packages/contracts

• Compile contracts:

  pnpm hardhat compile

• Run local node:

  pnpm hardhat node

• Deploy contracts:

  pnpm hardhat run scripts/deploy_mocks.ts --network localhost

  (Note: Update the deployment script path as necessary based on your specific modules)

2. AI Agents (packages/agents/defi-portfolio)

Navigate to the agent directory:

cd packages/agents/defi-portfolio

• Setup Environment: Copy .env.example to .env and configure your keys.

  cp .env.example .env

• Run Agent Server:

  pnpm run dev:server

• Run Automation Cron:

  pnpm run automate:cron

3. Frontend (packages/frontend)

Navigate to the frontend directory:

cd packages/frontend

• Setup Environment: Create a .env.local file with the deployed contract addresses.

  cp .env.example .env.local

  Update NEXT_PUBLIC_VAULT_ADDRESS and other variables with addresses from the contract deployment step.

• Start Development Server:

  pnpm dev

• Open http://localhost:3000 in your browser.

💻 Tech Stack

• Smart Contracts: Solidity, Hardhat, OpenZeppelin
• Frontend: Next.js 14, TypeScript, Tailwind CSS, Wagmi, Viem
• AI Agents: ADK-TS (Agent Development Kit), Node.js, Express

📄 License

MIT