IntelliVault

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.

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.