Skip to main content

​
Overview

MetaVault AI consists of three main components that need to run together:
  1. Smart Contracts - Local blockchain node with deployed contracts
  2. AI Agents - Backend server managing vault strategies
  3. Frontend - Web interface for users
Make sure you’ve completed the Local Setup guide before proceeding.

​
Quick Start

You can run all components at once or start them individually.

​
Step-by-Step Setup

For first-time setup, follow these steps in order:
1

Start Local Blockchain

Open a terminal and start the Hardhat local node:
pnpm dev:contracts
The node will start on http://127.0.0.1:8545 and display 20 test accounts with private keys.
Keep this terminal window open. The blockchain will reset if you stop the process.
Expected Output:
Started HTTP and WebSocket JSON-RPC server at http://127.0.0.1:8545/

Accounts
========
Account #0: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 (10000 ETH)
Private Key: 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
...
2

Deploy Smart Contracts

Open a new terminal and deploy the contracts to your local node:
pnpm contracts:deploy:local
This script will deploy:
  • Mock LINK token
  • Mock WETH token
  • Mock Aave Pool
  • Mock Swap Router
  • MetaVault contract
  • Aave V3 Strategy
  • Leverage Strategy
Save the deployed addresses - you’ll need them for the next step.
The deployment script deploys mock versions of Aave and Uniswap for testing purposes. These simulate the behavior of real DeFi protocols.
3

Update Environment Variables

Copy the deployed contract addresses and update your environment files:For AI Agents (packages/agents/defi-portfolio/.env):
VAULT_ADDRESS=0x...
ROUTER_ADDRESS=0x...
STRATEGY_LEVERAGE_ADDRESS=0x...
STRATEGY_AAVE_ADDRESS=0x...
LINK_ADDRESS=0x...
MOCK_AAVE_POOL_ADDRESS=0x...
For Frontend (packages/frontend/.env.local):
NEXT_PUBLIC_VAULT_ADDRESS=0x...
NEXT_PUBLIC_ROUTER_ADDRESS=0x...
NEXT_PUBLIC_STRATEGY_LEVERAGE_ADDRESS=0x...
NEXT_PUBLIC_STRATEGY_AAVE_ADDRESS=0x...
NEXT_PUBLIC_LINK_ADDRESS=0x...
You can automate this by creating a deployment script that outputs a .env file or use the addresses from the console output.
4

Start AI Agent Server

Open a new terminal and start the AI agent server:
pnpm dev:agents
The server will start on the port specified in your .env file (default: 3001).Expected Output:
🚀 Agent server running on port 3001
🤖 Strategy Sentinel Agent initialized
💬 Chat Agent initialized
📈 Yield Simulator Agent initialized
The agents will automatically connect to your local blockchain and start monitoring the vault.
5

Start Frontend Development Server

Open a new terminal and start the Next.js frontend:
pnpm dev
The frontend will be available at http://localhost:3000.Expected Output:
▲ Next.js 14.2.0
- Local:        http://localhost:3000
- Environments: .env.local

✓ Ready in 2.3s
6

Configure MetaMask

To interact with your local blockchain through the frontend:
  1. Open MetaMask and add a custom network:
    • Network Name: Localhost 8545
    • RPC URL: http://127.0.0.1:8545
    • Chain ID: 31337
    • Currency Symbol: ETH
  2. Import a test account using one of the private keys from the Hardhat node output
  3. Connect MetaMask to the frontend at http://localhost:3000
Only use test accounts from Hardhat for development. Never use accounts that hold real funds.

​
Available Scripts

Here are all the npm scripts available for development:

​
Root Package Scripts

# Run frontend only
pnpm dev

# Run AI agents
pnpm dev:agents

# Run contracts (compile + node)
pnpm dev:contracts

# Run everything
pnpm dev:all

​
Package-Specific Scripts

Navigate to packages/contracts and run:
# Compile contracts
pnpm hardhat compile

# Run local node
pnpm hardhat node

# Run tests
pnpm hardhat test

# Deploy to localhost
pnpm hardhat run scripts/deploy_mocks.ts --network localhost

# Clean artifacts and cache
pnpm hardhat clean

​
Running AI Agent Automation

The AI agents can run automated tasks on a schedule: 
cd packages/agents/defi-portfolio
pnpm run automate:cron
This starts the Strategy Sentinel Agent to:
  • Monitor strategy health every 5 minutes
  • Check LTV ratios and liquidation risks
  • Automatically rebalance portfolios
  • Harvest and compound yields
The automation is optional for development but recommended to see the full AI agent capabilities.

​
Development Workflow

Here’s a typical development workflow:
1

Start Services

Open 3-4 terminal windows and start:
  1. Hardhat node
  2. AI agent server
  3. Frontend
  4. (Optional) Automation cron
2

Deploy Contracts

Deploy or redeploy contracts as needed:
pnpm contracts:deploy:local
3

Make Changes

Edit code in any package:
  • Contracts: Update .sol files, recompile with pnpm hardhat compile
  • Agents: TypeScript changes auto-reload with tsx watch
  • Frontend: Next.js hot-reloads automatically
4

Test Changes

  • Interact through frontend at http://localhost:3000
  • Call agent API directly at http://localhost:3001
  • Use Hardhat console for contract interactions

​
Accessing the Application

Once everything is running:

Frontend

URL: http://localhost:3000Main user interface for depositing, withdrawing, and chatting with AI

Agent API

URL: http://localhost:3001AI agent REST API endpoints

Chat Agent

URL: http://localhost:3002Chat interface endpoint

​
Common Issues

Make sure:
  • Hardhat node is running
  • You’re using the correct network (--network localhost)
  • Your .env has a valid private key
Try restarting the Hardhat node:
# Stop current node (Ctrl+C)
pnpm dev:contracts
Verify:
  • Contract addresses in .env match deployed addresses
  • RPC_URL points to http://127.0.0.1:8545
  • Hardhat node is running
Check agent logs for connection errors.
Ensure:
  • MetaMask is connected to Localhost 8545 network (Chain ID: 31337)
  • Contract addresses in .env.local are correct and prefixed with NEXT_PUBLIC_
  • You’ve refreshed the browser after updating .env.local
Find and kill the process using the port:
# For port 3000 (frontend)
lsof -ti:3000 | xargs kill -9

# For port 8545 (blockchain)
lsof -ti:8545 | xargs kill -9

# For port 3001 (agents)
lsof -ti:3001 | xargs kill -9
Or change the port in your configuration files.
If you restart the Hardhat node, all state is lost. You need to:
  1. Redeploy contracts
  2. Update environment variables
  3. Restart agents and frontend
  4. Reconfigure MetaMask (import accounts again)

​
Development Tips

Use Hardhat Console

Interact with contracts directly:
cd packages/contracts
pnpm hardhat console --network localhost

Enable Debug Logs

Set ADK_DEBUG="true" in agents .env for detailed agent logs

Watch Contract Changes

Auto-recompile on changes:
pnpm hardhat watch compilation

Use Hardhat Network Helper

Time travel and snapshot in tests:
import { time } from "@nomicfoundation/hardhat-network-helpers";

​
Next Steps

Testing Guide

Learn how to run tests and verify functionality

Architecture

Understand the system architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us