🤖 AI Smart Wallet

Intent-Centric Autonomous Wallet with ZK Privacy & Social Recovery

🇨🇳 中文文档 • Features • Quick Start • Architecture • Documentation

---

📖 Introduction

AI Smart Wallet is a next-generation smart contract wallet that combines:

• 🧠 AI-Powered Intent Parsing - Natural language transaction commands
• 🔐 Zero-Knowledge Privacy - Hide strategy details with ZK proofs
• 👥 Social Recovery - Guardian-based wallet recovery mechanism
• 🔗 ERC-7579 Compatible - Modular smart account architecture

"Transfer 0.1 ETH to 0x1234..." → AI parses intent → Execute transaction

✨ Features

🤖 AI Intent Parser

Transform natural language into blockchain transactions:

"Send 0.5 ETH to alice.eth"
"Transfer 100 USDC to 0xabcd..."

🔒 ZK Privacy Strategy

• Circom Circuits for strategy verification
• Poseidon Hash for commitment generation
• Groth16 Proofs for privacy-preserving execution

👥 Social Recovery

• Add trusted guardians
• Configurable recovery threshold
• Time-locked recovery process
• Cancel/expire mechanisms

🏗️ Modular Architecture

• ERC-7579 compatible modules
• Pluggable strategy modules
• Upgradeable via proxy pattern

🚀 Quick Start

Prerequisites

• Node.js >= 18
• pnpm or npm
• Git

Installation

# Clone the repository
git clone https://github.com/aimerfeng/AI-Smart-Wallet.git
cd AI-Smart-Wallet

# Install dependencies
npm install

# Install frontend dependencies
cd frontend && npm install && cd ..

# Install circuit dependencies
cd circuits && npm install && cd ..

Run Tests

# Smart contract tests
npm test

# Frontend tests
cd frontend && npm test

# Build ZK circuits
cd circuits && npm run build

Start Development Server

cd frontend
npm run dev

Open http://localhost:3000 in your browser.

🏛️ Architecture

graph TB
    subgraph Frontend["Frontend (Next.js 15)"]
        UI[React Components]
        Hooks[Custom Hooks]
        Parser[Intent Parser]
        ZKLib[ZK Proof Library]
    end
    
    subgraph Contracts["Smart Contracts (Solidity)"]
        SW[SmartWallet]
        SWV2[SmartWalletV2]
        ZKM[ZKStrategyModule]
    end
    
    subgraph ZK["ZK System (Circom)"]
        Circuit[strategy.circom]
        Prover[snarkjs Prover]
    end
    
    UI --> Hooks
    Hooks --> Parser
    Hooks --> ZKLib
    ZKLib --> Prover
    Prover --> Circuit
    Hooks --> SW
    Hooks --> SWV2
    Hooks --> ZKM
    
    SWV2 --> |Social Recovery| Guardians[(Guardians)]
    ZKM --> |Verify Proof| Verifier[ZK Verifier]

Loading

📁 Project Structure

AI-Smart-Wallet/
├── contracts/              # Solidity smart contracts
│   ├── SmartWallet.sol     # Base wallet contract
│   ├── SmartWalletV2.sol   # Enhanced with social recovery
│   ├── ZKStrategyModule.sol # ZK privacy module
│   └── interfaces/         # Contract interfaces
├── circuits/               # Circom ZK circuits
│   ├── strategy.circom     # Strategy verification circuit
│   └── scripts/            # Build & prove scripts
├── frontend/               # Next.js frontend
│   ├── app/                # App router pages
│   ├── components/         # React components
│   ├── hooks/              # Custom React hooks
│   └── lib/                # Utility libraries
├── test/                   # Property-based tests
├── docs/                   # Documentation
└── scripts/                # Deployment scripts

🧪 Testing

This project uses Property-Based Testing with fast-check for comprehensive test coverage.

Test Suite	Tests	Status
SmartWallet	23	✅
SmartWalletV2	30	✅
ZKStrategyModule	18	✅
Frontend	30	✅
Total	101	✅

🛠️ Tech Stack

Category	Technology
Smart Contracts	Solidity 0.8.19, Hardhat
ZK Proofs	Circom 2.0, snarkjs, Poseidon
Frontend	Next.js 15, React 19, TypeScript
Styling	Tailwind CSS, Framer Motion
Web3	wagmi, viem
Testing	Vitest, fast-check

📚 Documentation

• Technical Guide - Deep dive into implementation
• Code Analysis - Core code walkthrough
• Troubleshooting - Common issues & solutions
• 中文技术指南 - Chinese documentation

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• OpenZeppelin - Smart contract libraries
• circomlib - Circom component library
• snarkjs - zkSNARK implementation
• wagmi - React hooks for Ethereum

---

Made with ❤️ by aimerfeng

⭐ Star this repo if you find it useful!