IntelliVault

Demo

About

IntelliVault is a dual-agent platform that combines AI-powered blockchain intelligence with an on-chain vault for trading tokenized real-world assets (RWAs). The system has two cooperating agents: Blockchain MCP Agent (HTTP server, Port 3000): uses the Model Context Protocol (Blockscout MCP) to perform multi-chain contract & address analysis across 5 networks (Ethereum, Sepolia, Base Sepolia, Optimism, Arbitrum). It offers contract security checks, verification status, transaction history, gas analytics, token-holdings aggregation and creator provenance. Vault Trading Agent (WebSocket server, Port 3002): provides real-time vault pricing, buy/sell calculations, MetaMask transaction preparation, and live user interactions for tokenized assets (example tokens: Tesla/TSLA, Google/GOOGL, Microsoft/MSFT). It can call the MCP Agent internally to perform contract/address analysis before preparing transactions. The frontend (React + TypeScript + Vite) exposes a polished dashboard and chat UI that connects to the Vault Agent over Socket.IO and to the MCP query services for richer analytics. All on-chain operations use PYUSD as settlement currency and an Ethers.js provider for Sepolia/Base Sepolia RPCs. Key user flows: Connect wallet → frontend triggers a pre-onboarding “Address Intelligence” check (cross-chain reputation + risk score). Ask the AI (chat) for token price, buy/sell cost, or contract analysis. Vault Agent resolves token symbol/address, fetches price from the vault contract, prepares MetaMask tx with auto network switching, and returns tool-call traces for auditability. When needed, Vault Agent queries MCP Agent for deep contract analysis before approving transaction preparation. IntelliVault emphasizes safety and transparency: automated address screening, cross-chain provenance from MCP, tool-call logging, and secure handling of API keys and RPC endpoints. It is designed to be both demo-friendly (hackathon) and production-extensible.

How it's made

Overall architecture Monorepo with three main packages: agent/ (dual agents + MCP client), frontend/ (React app), contracts/ (Hardhat + Solidity). Agents are decoupled services: MCP Agent (HTTP) and Vault Agent (WebSocket). They communicate via internal HTTP requests (Vault → MCP) so each can scale or run separately. Core technologies LLM / Agenting: Google Gemini 2.0 Flash (LLM) with LangChain / LangGraph style orchestration for tool-calling and stateful flows. MCP / Analytics: Model Context Protocol / Blockscout MCP (Docker) used as the authoritative multi-chain analytics backend and toolset. Frontend: React 18 + TypeScript, Vite, Tailwind CSS, shadcn/ui for components. Blockchain: Ethers.js v6 for contract reads/writes, Hardhat & OpenZeppelin for contracts, deployed to Sepolia / Base Sepolia testnets. Realtime: Socket.IO for Vault Agent ↔ Frontend, WebSocket server on Port 3002. Packaging / Runtime: Node.js >=18, Docker Desktop for MCP server, npm scripts for dev workflows. Other libs: @modelcontextprotocol/sdk, @langchain/google-genai (adapter), express, dotenv. Service specifics MCP Agent (Port 3000): Runs an Express HTTP API that exposes /chat, /tools, /health. Wraps MCP tools (get_address_info, get_transactions_by_address, get_tokens_by_address, etc.) and returns structured tool call traces for explainability. MCP runs as a Docker image invoked via a lightweight Docker client wrapper (stdin/stdout StdioTransport for deterministic tool execution). Vault Agent (Port 3002): WebSocket server that clients connect to for chat and transaction prep. Resolves tokens by symbol, name or address using vault-tokens.json. Pulls real-time pricing from the vault contract and computes buy/sell costs denominated in PYUSD. Prepares MetaMask transaction objects (network switching hints, calldata, gas estimates) but does not auto-sign — user signs via wallet. If a token/contract is unfamiliar or high risk, it calls MCP Agent for a pre-transaction analysis and includes the report in the response. Notable/hacky implementations LLM Tool Orchestration & Safe Tooling: Built a tool-calling pipeline where the LLM can request specific MCP tools and the backend executes them deterministically, returning both raw data and a sanitized human summary. This gives the LLM actionable facts and produces an auditable trace of tool calls. Docker MCP via StdioTransport: Instead of calling external MCP HTTP endpoints directly, we run Blockscout MCP inside Docker and use a minimal StdioTransport shim for robust local testing and hermetic tool execution during demos. Pre-onboarding on-chain KYC (address intelligence): The frontend triggers an address analysis before enabling full feature access; the backend composes risk heuristics from MCP results (suspicious interaction patterns, scam lists, previous phishing addresses) and surfaces a clear human summary and numeric score. Real-time cross-agent orchestration: Vault Agent can introspect and call MCP Agent mid-conversation — the LLM decides (via tool call) when to escalate to deep analysis, enabling safe pre-transaction checks. Token resolution & user shorthand: Users can say “Tesla” or paste partial addresses; a deterministic resolver maps to token metadata, decimals, and vault contract methods automatically. Explainability-first responses: Every chat response includes toolCalls with args/results and a short LLM narrative — useful for judges and audits. Deployment & dev Dev: cd agent && npm install && npm run dev (MCP Agent) cd agent && npm run dev:ai (Vault Agent) cd frontend && npm install && npm run dev Production (recommended): Run MCP as managed Docker service. Deploy agents to separate containers; secure GEMINI_API_KEY and RPC keys via environment variables/secret store. Frontend served on Vercel/Netlify with environment variables for RPC and agent endpoints. Partner integrations & benefits Blockscout MCP: provided cross-chain indexing and verified on-chain data — crucial for trustworthy address intelligence and contract analysis. Google Gemini: high-quality LLM enabling conversational workflows and complex tool orchestration. Hardhat/OpenZeppelin: rapid contract development, testing, and audit hygiene.