# Web3CLI: AI-Powered Smart Contract Tool [![npm version](https://badge.fury.io/js/%40web3ai%2Fcli.svg)](https://badge.fury.io/js/%40web3ai%2Fcli) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) A comprehensive suite for generating secure Solidity smart contracts and analyzing existing contracts using AI. ## Table of Contents - [Overview](#overview) - [Installation](#installation) - [Configuration](#configuration) - [Key Features](#key-features) - [Supported AI Models](#supported-ai-models) - [Usage Examples](#usage-examples) - [Agent Mode](#agent-mode) - [Options](#options) - [Vector Database](#vector-database) - [Design Tradeoffs](#design-tradeoffs) - [Project Structure](#project-structure) - [Core Technologies](#core-technologies) - [Recent Updates](#recent-updates) - [Future Plans](#future-plans) - [Contributing](#contributing) - [Community & Support](#community--support) - [License](#license) ## Overview Web3CLI is a powerful developer tool that leverages AI to solve two key problems in blockchain development: 1. **Natural Language to Smart Contract Logic** - Translates requirements into secure, minimal Solidity code 2. **Smart Contract Explainability** - Provides plain-English summaries of complex smart contracts The tool uses advanced AI models with specialized guardrails to ensure secure code generation, supported by a multi-agent system, web search, and vector database integration for enhanced security and quality. ## Installation ### NPM Package The easiest way to install Web3CLI is via npm: ```bash npm install -g @web3ai/cli ``` Or with pnpm: ```bash pnpm add -g @web3ai/cli ``` ### Manual Installation If you prefer to install from source: ```bash git clone https://github.com/shivatmax/web3cli.git ``` ```bash cd web3cli ``` ```bash pnpm install ``` ```bash pnpm build ``` ```bash npm link ``` ## Configuration Create a `web3cli.toml` file in your project directory: ```toml #:schema ./schema.json default_model = "gpt-4o-mini" # or another model # OpenAI Configuration openai_api_key = "your-openai-api-key" # Gemini Configuration - for Google Gemini models # gemini_api_key = "your-gemini-api-key" # Anthropic Configuration - for Claude models # anthropic_api_key = "your-anthropic-api-key" # Groq Configuration - for faster inference # groq_api_key = "your-groq-api-key" # Mistral Configuration # mistral_api_key = "your-mistral-api-key" # Ollama Configuration - for local models # ollama_host = "http://localhost:11434" # Etherscan API key (optional, for contract analysis) etherscan_api_key = "your-etherscan-api-key" ``` Or set environment variables: - `OPENAI_API_KEY` - For OpenAI models - `GEMINI_API_KEY` - For Google Gemini models - `ANTHROPIC_API_KEY` - For Claude models - `GROQ_API_KEY` - For Groq inference - `MISTRAL_API_KEY` - For Mistral models - `ETHERSCAN_API_KEY` - For contract analysis (optional) ## Key Features - **Multi-Provider AI Support** - Works with OpenAI, Anthropic/Claude, Google Gemini, Groq, Mistral, GitHub Copilot, and Ollama - **Natural Language to Solidity Code** - Generate smart contracts from plain English - **Security-First Approach** - Built-in guardrails to prevent insecure patterns - **Contract Explainability** - Analyze contracts for permissions and security patterns - **Multi-Agent System** - Specialized agents collaborate to enhance quality - **Vector Database** - Local storage of blockchain documentation and security patterns - **Web Search** - Up-to-date information for secure implementations - **CLI and Terminal Interface** - Developer-friendly command-line tools - **Robust File System Handling** - Automatically creates necessary directories for output ## Supported AI Models Web3CLI supports a wide range of AI models across multiple providers: ### OpenAI - GPT-4o, GPT-4o-mini, GPT-4.1, GPT-3.5-turbo - OpenAI "o" series: o1, o1-mini, o3, o4-mini, etc. ### Anthropic - Claude 3.7 Sonnet, Claude 3.5 Sonnet, Claude 3.5 Haiku, Claude 3 Opus ### Google Gemini - Gemini 2.5 Flash, Gemini 2.5 Pro, Gemini 2.0, Gemini 1.5 ### Groq - Llama 3.3 70B, Llama 3.1 8B, Mixtral 8x7B ### Mistral - Mistral Large, Mistral Medium, Mistral Small ### GitHub Copilot - Copilot models with GPT-4o, o1, Claude 3.5 backend options ### Ollama - Local models via Ollama server ## Usage Examples ### General Web3 Development Questions ```bash # Ask a general Web3 development question web3cli "What is the difference between ERC-20 and ERC-721?" # Ask with web search enabled web3cli "What is the current gas cost for token transfers?" --search # Ask with specific model web3cli "Explain the EIP-2981 royalty standard" --model gpt-4o # Ask with alternative providers web3cli "Explain the EIP-2981 royalty standard" --model claude-3-5-sonnet web3cli "Explain gas optimization" --model gemini-2.5-flash # List available models web3cli list ``` ### Natural Language to Smart Contract ```bash # Generate an upgradeable ERC-20 using Transparent Proxy web3cli generate "Create an ERC-20 token with upgradeability" --transparent-proxy --output MyToken.sol --no-stream # Generate an NFT collection using UUPS proxy pattern with agent mode web3cli generate "Create an NFT collection with royalties and upgradeability" --uups-proxy --agent --output NFTCollection.sol --no-stream # Generate with agent mode for enhanced security web3cli generate "Create an ERC-20 token with minting restricted to addresses in an allowlist" --agent --output Token.sol --no-stream # Generate with Hardhat tests web3cli generate "Create an NFT collection with royalties" --hardhat --output NFTCollection.sol --no-stream # Generate with web search for security best practices web3cli generate "Create a vesting contract" --search --no-stream # Generate with vector DB context web3cli generate "Create an NFT with royalties" --read-docs solidity ``` ### Smart Contract Explainability ```bash # Analyze a contract by address (Mainnet) web3cli contract 0xdac17f958d2ee523a2206206994597c13d831ec7 --network mainnet -o # Analyze a Solidity file web3cli contract --file MyContract.sol --no-stream # Explain a Solidity file web3cli contract:explain --file MyContract.sol --no-stream # Audit a contract web3cli contract:audit 0xdac17f958d2ee523a2206206994597c13d831ec7 --network mainnet -o # Ask custom questions about a contract web3cli contract:custom 0xdac17f958d2ee523a2206206994597c13d831ec7 "What security patterns does this contract implement?" --network mainnet ``` ## Agent Mode When using the agent mode with `--agent` flag, the system follows this workflow: 1. The **Coordinator Agent** receives the natural language request and plans the execution 2. The **Web Search Agent** gathers relevant information about the requested contract if needed 3. The **Vector Store Agent** retrieves security patterns and best practices from the vector database 4. The **Code Writer Agent** generates the initial Solidity implementation using all gathered context 5. The **Security Audit Agent** analyzes the code for vulnerabilities and provides improvements 6. The **Linting Agent** cleans up the code style and improves readability 7. The **Functionality Checker** verifies the contract works as intended and generates tests if requested 8. The **Coordinator Agent** finalizes the output, combining all the improvements This collaborative approach results in higher quality, more secure smart contracts than using a single AI model. ## Options - `--model `: Specify the model to use (default: gpt-4o-mini) - `--output `: Output file for the generated contract - `--hardhat`: Generate Hardhat test file - `--agent`: Use hierarchical multi-agent mode - `--transparent-proxy`: Generate an upgradeable contract using the Transparent Proxy pattern (OpenZeppelin) - `--uups-proxy`: Generate an upgradeable contract using the UUPS pattern (OpenZeppelin) - `--files `: Additional context files - `--url `: URLs to fetch as context - `--search`: Enable web search for context - `--read-docs `: Read from vector DB docs collection - `--no-stream`: Disable streaming responses ## Vector Database Web3CLI includes a local vector database for storing and searching documentation using semantic similarity. ### Vector Database Commands ```bash # List all collections in the vector database web3cli vdb-list # Add documents from a URL to the vector database web3cli vdb-add-docs --name --crawl --max-pages 30 # Add a file to the vector database web3cli vdb-add-file --name --title "Document Title" # Search the vector database web3cli vdb-search "ERC721 royalties implementation" --name solidity -k 5 # Add documentation from predefined sources web3cli setup --max-pages 50 # Initialize vector database (alias for backward compatibility) web3cli vector-db # Use vector search with generation web3cli generate "Create an NFT with royalties" --read-docs solidity ``` ### Document Structure The vector database stores and returns documents with this structure: ```typescript { pageContent: "The document text content...", metadata: { source: "https://example.com/docs/page", title: "Document Title", url: "https://example.com/docs/page", siteName: "Example Documentation", author: "Example Author", crawlTime: "2023-06-15T12:34:56Z" } } ``` ## Design Tradeoffs ### Model Choice - Multiple AI providers supported for flexibility and performance - **OpenAI/GPT-4o** - Superior understanding of Solidity but higher cost - **Claude models** - Strong reasoning for complex contracts - **Gemini models** - Good balance of capabilities and cost - **Groq models** - Fast inference for time-sensitive tasks - **Mistral models** - Efficient performance for routine tasks - **Ollama** - Local models for privacy and offline work - Security is prioritized over cost for critical smart contract generation - Lesser models used for non-critical tasks like search and documentation ### Security vs. Speed - Security is prioritized with multiple agent reviews - Vector database provides security patterns for faster reference - Tradeoff favors security at the cost of generation time ## Project Structure ``` web3cli/ ├── docs/ # Documentation ├── scripts/ # Utility scripts ├── src/ # Source code │ ├── agents/ # Agent system components │ │ ├── coordinator.ts # Agent orchestration │ │ ├── code-writer.ts # Code generation │ │ ├── security-audit.ts # Security auditing │ │ ├── linting.ts # Code quality │ │ ├── functionality.ts # Verify behavior │ │ ├── web-search.ts # Web search │ │ └── vector-store.ts # Documentation retrieval │ ├── cli/ # CLI interface │ │ └── commands/ # Command implementations │ ├── services/ # Core services │ │ ├── ai/ # AI model integration │ │ ├── config/ # Configuration │ │ ├── contract/ # Contract generation │ │ ├── search/ # Search services │ │ ├── ui/ # User interface helpers │ │ └── vector-db/ # Vector database │ └── utils/ # Shared utilities ``` ## Core Technologies Web3CLI is built with the following key technologies: - **Multiple AI Providers** - OpenAI, Anthropic, Google, Groq, Mistral, GitHub Copilot, and Ollama - **LangChain** - Framework for multi-agent operations - **OpenAI Embeddings** - For vector representation - **ethers.js** - Ethereum interaction library - **Solidity Compiler** - For validating contracts - **CAC** - Lightweight CLI framework ## Recent Updates - **Multi-Provider AI Support** - Added support for Claude, Gemini, Groq, Mistral, GitHub Copilot, and Ollama models - **Improved File System Handling** - Now automatically creates output directories as needed - **Enhanced Error Handling** - Better error messages for common issues - **Model Selection Improvements** - Simplified model selection and provider detection - **MetaMask Error Handling Utility** - Added support for better MetaMask error handling See the [CHANGELOG.md](CHANGELOG.md) for a full history of changes. ## Future Plans 1. **Formal Verification Integration** - Connect with formal verification tools for critical contracts 2. **Gas Optimization Analysis** - Add detailed gas estimation and optimization suggestions 3. **Custom Documentation Integration** - Allow developers to add proprietary documentation 4. **Web Interface** - Develop a web-based UI for easier adoption 5. **Expanded Chain Support** - Add support for additional EVM-compatible chains ## Contributing We welcome contributions to Web3CLI! If you're interested in helping, please: 1. Fork the repository. 2. Create a new branch for your feature or bug fix. 3. Make your changes. 4. Ensure your code adheres to the project's linting and formatting standards. 5. Submit a pull request with a clear description of your changes. Please check our [issues page](https://github.com/shivatmax/web3cli/issues) for areas where you can contribute. ## Community & Support - **Questions & Discussions:** For general questions, discussions, or support, please open an issue on our [GitHub Issues page](https://github.com/shivatmax/web3cli/issues). - **Bug Reports:** If you find a bug, please report it by creating an issue, providing as much detail as possible. ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details (though your project uses the standard MIT text, so a separate LICENSE file might not be strictly necessary if you clearly state "MIT" in `package.json` and here). MIT