IntelliVault

Problem Statement

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.

Solution

Overall architectureMonorepo 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 technologiesLLM / 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 specificsMCP 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 implementationsLLM 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 & devDev:cd agent && npm install && npm run dev (MCP Agent)cd agent && npm run dev:ai (Vault Agent)cd frontend && npm install && npm run devProduction (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 & benefitsBlockscout 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.