🛡️ Vetrix — Research-Grade Autonomous Web3 Agent

Vetrix is an advanced autonomous Web3 assistant built as a Final Year Project constraint. Unlike standard dApps where users must manually click through MetaMask popups to sign transactions, Vetrix handles execution entirely on the server via a dedicated "burner wallet".

You just type naturally. Vetrix understands your intent, requests missing details, verifies balances, and autonomously executes blockchain transactions on your behalf.

✨ Key Features

• 🧠 Context Intelligence Layer: Vetrix converts human-native names (e.g., "John") and fiat-native values (e.g., "$10 worth") into precise blockchain parameters via a local persistent identity store and CoinGecko price feeds.
• 🔄 Transaction Context Recall: Remembers your history. "Send the same as last time" autonomously pre-fills recipients and amounts from the audit log.
• 📇 Persistent Contact Book: Zero-Setup local database managing custom name-to-address mappings for a friction-less experience.
• 🤖 Neural Processing UI: Features a high-fidelity interaction layer with real-time feedback, processing transaction intents with zero-latency visual confirmation.
• 🛡️ Autonomous Shield Guard: A deterministic multi-factor controller that enforces min(0.1 ETH, 80% balance) safety thresholds and protects gas reserves.
• 📜 Verifiable Execution Model: Maps natural language intent directly to on-chain txHash in a persistent audit trail.

📚 Project Documentation

To understand the architecture, UI design, and development lifecycle of Aura V3.0, please refer to the following internal documents:

• 📘 Project Plan — The academic evolution, technical stack, and feature summary.
• 🚀 Handover & UI Blueprint — A complete guide for successors, detailing the Neural UI and technical architecture.
• 📋 Test Manifest — Step-by-step presentation manual to verify every feature.
• 📊 Codebase & Feature Report — Details codebase structure and verified working features.
• ⚙️ Architecture Overview — System overviews, core component relationships, and data flow.
• 🔄 User Workflow Blueprint — Step-by-step lifecycle of an autonomous transaction execution.
• 🧠 Context Layer Deep Dive — Breakdown of memory, identity mapping, and price rendering details.
• ✅ QA Report — Testing history and error handling validations.

🏗️ Version 2 Architecture Transition

In V1 (Non-Custodial), the bot was simply an intent parser that prepared transaction payloads for the user to manually sign in their browser extension.

In V2 (Vetrix Agent), the architecture shifts execution logic to the backend:

1. Natural Input: User types "Send 0.05 Sepolia ETH to Vitalik."
2. Neural Parsing: Gemini 2.0 extracts parameters and Zod validates the schema.
3. Shield Verification: Vetrix verifies balances and gas thresholds via the Guardrail engine.
4. Execution: The backend signs the transaction with the BOT_PRIVATE_KEY and broadcasts via Alchemy.
5. Real-time Pulse: The user receives a clickable Etherscan hash and a "pulsing shield" UI status while the block confirms.

---

🛠️ Tech Stack

Frontend (User Interface)

• Framework: Next.js (App Router), React 19
• Styling: Tailwind CSS V4, Framer Motion
• Web3 Integration: ethers.js (BrowserProvider)

Backend (Agent Brain & Context)

• Server: Node.js, Express.js
• Intelligence: @google/generative-ai (Gemini SDK)
• Data Layer: Lightweight Edge-Persistence (JSON-based audit & contact store)
• Pricing: CoinGecko API for real-time USD conversion
• Web3 Engine: ethers.js (V6) for server-side signing and broadcast
• Validation: zod for strict intent schema enforcement

---

🚀 Getting Started

Prerequisites

You need Node.js installed and an Alchemy API Key.

1. Environment Variables Setup

You must create two .env files.

Backend (backend/.env):

GEMINI_API_KEY=your_gemini_api_key
GEMINI_MODEL=gemini-2.5-flash
PORT=3001
ALCHEMY_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_ALCHEMY_KEY
BOT_PRIVATE_KEY=your_burner_wallet_private_key

Note: The BOT_PRIVATE_KEY must have real Sepolia ETH to pay for transaction gas! Use a free Sepolia Faucet to fund it.

Frontend (frontend/.env):

NEXT_PUBLIC_API_BASE_URL=http://localhost:3001/api/chat

2. Installation & Running

Open two separate terminals:

Terminal 1 (Backend):

cd backend
npm install
npm run dev

Terminal 2 (Frontend):

cd frontend
npm install
npm run dev

Visit http://localhost:3000 to interact with Vetrix!

---

⚠️ Technical Limitations & Academic Notice

IMPORTANT: This system is a Research-Grade Autonomous Prototype developed as part of a Final Year Project for Rathinam College of Arts and Science | Bharathiar University.

Core Limitations

• Burner Wallet Risk: The system uses a "Burner Wallet" pattern. The private key resides on the backend server. Do NOT use with significant real assets.
• Centralized Dependencies: Real-time information relies on external APIs (Gemini, CoinGecko, Alchemy). Failure of these services will degrade system functionality.
• Single-User Architecture: This prototype currently lacks a robust multi-user authentication layer.
• Asynchronous Confirmation: Transaction confirmation is handled asynchronously; real-time block-status polling is out of scope for this version.

Future Work

• Implementation of MPC (Multi-Party Computation) for secure key management.
• Integration of local Lightweight LLMs to remove external API dependency.
• On-chain intent verification via smart contract event logs.

---

📄 Publication & Citation

This research and project have been officially published on Zenodo. If you use this work in your research, please cite it accordingly.

• Zenodo DOI:
• Paper Title: Vetrix: An Autonomous Web3 Agent for Natural Language Transaction Execution
• Repository: arun6184/aura-web3-bot-V2

---

Made with ❤️ for the Web3 Ecosystem