Local Development Setup

Set up your local development environment for MetaVault AI

Prerequisites

Before you begin, ensure you have the following installed on your system:

Node.js

Version 18 or higher recommended

pnpm

Fast, disk space efficient package manager

MetaMask

Or another Web3 wallet for blockchain interactions

Git

For cloning the repository

Installing Prerequisites

Install Node.js

Download and install Node.js from nodejs.org. We recommend using the LTS version.

Verify installation:

node --version
# Should show v18.x.x or higher

Install pnpm

MetaVault AI uses pnpm as its package manager. Install it globally:

npm install -g pnpm

Verify installation:

pnpm --version
# Should show 10.18.3 or higher

Install MetaMask

Install the MetaMask browser extension from metamask.io.

You’ll need this to interact with the vault through the frontend.

Repository Structure

MetaVault AI is a monorepo containing three main packages:

metavault-ai/
├── packages/
│   ├── contracts/       # Hardhat project with smart contracts
│   ├── frontend/        # Next.js web application
│   └── agents/          # AI agents built with ADK-TS
│       └── defi-portfolio/
├── package.json         # Root package with workspace scripts
└── pnpm-workspace.yaml  # pnpm workspace configuration

Each package can be developed independently, but they work together to form the complete MetaVault AI system.

Initial Setup

1. Clone the Repository

   Clone the MetaVault AI repository to your local machine:

   git clone <repository-url>
   cd metavault-ai
   
2. Install Dependencies

   Install all dependencies for the entire monorepo:

   pnpm install
   

   This command will:

   • Install root-level dependencies
   • Install dependencies for all packages (contracts, frontend, agents)
   • Set up workspace links between packages

   The installation uses pnpm workspaces, which efficiently manages dependencies across the monorepo and creates symlinks between packages.

3. Configure Smart Contracts

   Navigate to the contracts package and set up environment variables:

   cd packages/contracts
   cp .env.example .env
   

   Edit .env and add your configuration:

   # Deployer Wallet Private Key
   PRIVATE_KEY=your_private_key_here
   
   # INFURA API Key (optional for local development)
   INFURA_KEY=your_infura_key
   

   Never commit your .env file or share your private key. Use a test wallet with no real funds for development.

4. Configure AI Agents

   Navigate to the agents package and set up environment variables:

   cd packages/agents/defi-portfolio
   cp .env.example .env
   

   Edit .env and configure the following:

   # ADK Configuration
   ADK_DEBUG="false"
   
   # OpenRouter API Key for LLM
   OPEN_ROUTER_KEY=your_openrouter_key
   LLM_MODEL=anthropic/claude-3.5-sonnet
   
   # Server Ports
   PORT=3001
   CHAT_PORT=3002
   
   # Telegram (optional)
   TELEGRAM_BOT_TOKEN=
   TELEGRAM_CHANNEL_ID=
   
   # Blockchain
   RPC_URL=http://127.0.0.1:8545
   PRIVATE_KEY=your_private_key_here
   
   # Contract addresses (will be filled after deployment)
   VAULT_ADDRESS=
   ROUTER_ADDRESS=
   STRATEGY_LEVERAGE_ADDRESS=
   STRATEGY_AAVE_ADDRESS=
   LINK_ADDRESS=
   MOCK_AAVE_POOL_ADDRESS=
   

   You’ll need to obtain an OpenRouter API key from openrouter.ai to run the AI agents. Contract addresses will be populated after deploying the contracts.

5. Configure Frontend

   Navigate to the frontend package and set up environment variables:

   cd packages/frontend
   cp .env.example .env.local
   

   Edit .env.local:

   # RPC
   RPC_URL=http://127.0.0.1:8545
   PRIVATE_KEY=your_private_key_here
   
   # Agent API
   AGENT_API_URL=http://localhost:3002
   
   # Contract addresses (will be filled after deployment)
   NEXT_PUBLIC_VAULT_ADDRESS=
   NEXT_PUBLIC_ROUTER_ADDRESS=
   NEXT_PUBLIC_STRATEGY_LEVERAGE_ADDRESS=
   NEXT_PUBLIC_STRATEGY_AAVE_ADDRESS=
   NEXT_PUBLIC_LINK_ADDRESS=
   
6. Compile Contracts

   Return to the contracts directory and compile the smart contracts:

   cd packages/contracts
   pnpm hardhat compile
   

   Or from the root:

   pnpm contracts:compile
   

   This will generate TypeScript types and compile all Solidity contracts.

Verify Installation

To verify your setup is complete, run these checks:

Contracts

cd packages/contracts
pnpm hardhat compile

Should compile without errors.

Agents

cd packages/agents/defi-portfolio
pnpm build

Should build TypeScript files successfully.

Frontend

cd packages/frontend
pnpm build

Should build the Next.js application.

Tech Stack Overview

Smart Contracts

• Solidity 0.8.28
• Hardhat 2.26.5
• OpenZeppelin 5.4.0

Frontend

• Next.js 14
• TypeScript 5.5
• Wagmi & Viem
• Tailwind CSS

AI Agents

• ADK-TS 0.5.7
• Express 5.2.1
• TypeScript 5.9
• node-cron 4.2.1

Common Issues

pnpm command not found

Make sure pnpm is installed globally:

npm install -g pnpm

Node version mismatch

Check your Node.js version:

node --version

Update to Node.js 18 or higher if needed.

Compilation errors in contracts

Try cleaning and reinstalling:

cd packages/contracts
rm -rf cache artifacts node_modules
pnpm install
pnpm hardhat compile

Port already in use

If ports 3000, 3001, 3002, or 8545 are already in use, you can:

• Change the ports in your .env files
• Kill the process using the port
• Use different port numbers in your configuration

Next Steps

Now that your environment is set up, you can:

Run Locally

Learn how to run the full stack locally

Testing Guide

Run tests and verify functionality