55fe7d10eb
- Fix all TypeScript compilation errors (40+ fixes) - Add missing type definitions (TransactionRequest, SafeInfo) - Fix TransactionRequestStatus vs TransactionStatus confusion - Fix import paths and provider type issues - Fix test file errors and mock providers - Implement comprehensive security features - AES-GCM encryption with PBKDF2 key derivation - Input validation and sanitization - Rate limiting and nonce management - Replay attack prevention - Access control and authorization - Add comprehensive test suite - Integration tests for transaction flow - Security validation tests - Wallet management tests - Encryption and rate limiter tests - E2E tests with Playwright - Add extensive documentation - 12 numbered guides (setup, development, API, security, etc.) - Security documentation and audit reports - Code review and testing reports - Project organization documentation - Update dependencies - Update axios to latest version (security fix) - Update React types to v18 - Fix peer dependency warnings - Add development tooling - CI/CD workflows (GitHub Actions) - Pre-commit hooks (Husky) - Linting and formatting (Prettier, ESLint) - Security audit workflow - Performance benchmarking - Reorganize project structure - Move reports to docs/reports/ - Clean up root directory - Organize documentation - Add new features - Smart wallet management (Gnosis Safe, ERC4337) - Transaction execution and approval workflows - Balance management and token support - Error boundary and monitoring (Sentry) - Fix WalletConnect configuration - Handle missing projectId gracefully - Add environment variable template
338 lines
11 KiB
Markdown
338 lines
11 KiB
Markdown
# Overview & Architecture
|
|
|
|
## System Overview
|
|
|
|
Impersonator is a smart wallet aggregation system that allows users to:
|
|
- Impersonate any Ethereum address for dApp interaction
|
|
- Aggregate multiple wallets into a single smart wallet
|
|
- Manage multi-signature wallets (Gnosis Safe)
|
|
- Execute transactions with approval workflows
|
|
- Connect via WalletConnect, iframe, or browser extension
|
|
|
|
## Architecture
|
|
|
|
### High-Level Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ User Interface Layer │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ WalletConnect│ │ iFrame │ │ Extension │ │
|
|
│ │ Tab │ │ Tab │ │ Tab │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Context Layer (State Management) │
|
|
│ ┌──────────────────┐ ┌──────────────────┐ │
|
|
│ │ SafeInjectContext│ │SmartWalletContext│ │
|
|
│ │ (iFrame Comm) │ │ (Wallet Mgmt) │ │
|
|
│ └──────────────────┘ └──────────────────┘ │
|
|
│ ┌──────────────────┐ │
|
|
│ │TransactionContext│ │
|
|
│ │ (Tx Management) │ │
|
|
│ └──────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Service Layer │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ Communicator│ │ Gnosis Safe │ │ Transaction │ │
|
|
│ │ (Messages) │ │ Helpers │ │ Execution │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ Balance │ │ Relayers │ │ Security │ │
|
|
│ │ Helpers │ │ Helpers │ │ Utils │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Utility Layer │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ Security │ │ Encryption │ │ Monitoring │ │
|
|
│ │ Utils │ │ Utils │ │ Service │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Blockchain Layer │
|
|
│ ethers.js | wagmi | viem │
|
|
│ Ethereum Provider │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Core Components
|
|
|
|
### 1. Context Providers
|
|
|
|
#### SafeInjectContext
|
|
Manages iframe communication and Safe App SDK integration.
|
|
- Handles postMessage communication
|
|
- Manages iframe state
|
|
- Integrates with Safe App SDK protocol
|
|
|
|
#### SmartWalletContext
|
|
Manages smart wallet configuration and state.
|
|
- Wallet creation and connection
|
|
- Owner management
|
|
- Threshold configuration
|
|
- Balance tracking
|
|
|
|
#### TransactionContext
|
|
Manages transaction lifecycle and approvals.
|
|
- Transaction creation
|
|
- Multi-sig approval workflow
|
|
- Transaction execution
|
|
- Transaction history
|
|
|
|
### 2. Helper Modules
|
|
|
|
#### Communicator (`helpers/communicator.ts`)
|
|
- Secure message passing between iframe and parent
|
|
- Replay attack prevention
|
|
- Origin validation
|
|
- Message routing
|
|
|
|
#### Gnosis Safe Helpers (`helpers/smartWallet/gnosisSafe.ts`)
|
|
- Safe contract interaction
|
|
- Safe SDK integration
|
|
- Safe deployment
|
|
- Safe info retrieval
|
|
|
|
#### Transaction Execution (`helpers/transaction/execution.ts`)
|
|
- Direct on-chain execution
|
|
- Relayer execution
|
|
- Transaction simulation
|
|
- Gas estimation
|
|
|
|
#### Balance Helpers (`helpers/balance/index.ts`)
|
|
- Native token balance
|
|
- ERC20 token balance
|
|
- Token metadata retrieval
|
|
|
|
### 3. Security Utilities
|
|
|
|
#### Security Utils (`utils/security.ts`)
|
|
- Address validation
|
|
- Transaction validation
|
|
- Rate limiting
|
|
- Nonce management
|
|
- Input sanitization
|
|
|
|
#### Encryption Utils (`utils/encryption.ts`)
|
|
- AES-GCM encryption
|
|
- PBKDF2 key derivation
|
|
- Secure storage wrapper
|
|
- Session-based keys
|
|
|
|
#### Monitoring Service (`utils/monitoring.ts`)
|
|
- Centralized logging
|
|
- Error tracking
|
|
- Security event tracking
|
|
- Performance metrics
|
|
|
|
### 4. UI Components
|
|
|
|
#### Smart Wallet Components
|
|
- `WalletManager` - Wallet list and selection
|
|
- `OwnerManagement` - Owner and threshold management
|
|
- `DeployWallet` - New wallet deployment
|
|
- `WalletBalance` - Balance display
|
|
|
|
#### Transaction Components
|
|
- `TransactionBuilder` - Transaction creation
|
|
- `TransactionApproval` - Approval interface
|
|
- `TransactionHistory` - Transaction list
|
|
|
|
#### Connection Components
|
|
- `WalletConnectTab` - WalletConnect integration
|
|
- `IFrameConnectTab` - iFrame dApp integration
|
|
- `BrowserExtensionTab` - Extension information
|
|
|
|
## Data Flow
|
|
|
|
### Wallet Connection Flow
|
|
|
|
```
|
|
User Input (Address/ENS)
|
|
│
|
|
▼
|
|
Address Validation
|
|
│
|
|
▼
|
|
Network Selection
|
|
│
|
|
▼
|
|
Provider Creation
|
|
│
|
|
▼
|
|
Wallet Connection
|
|
│
|
|
▼
|
|
Balance Fetch
|
|
│
|
|
▼
|
|
UI Update
|
|
```
|
|
|
|
### Transaction Flow
|
|
|
|
```
|
|
Transaction Request
|
|
│
|
|
▼
|
|
Input Validation
|
|
│
|
|
▼
|
|
Gas Estimation
|
|
│
|
|
▼
|
|
Transaction Creation
|
|
│
|
|
▼
|
|
Multi-Sig Approval
|
|
│
|
|
▼
|
|
Threshold Check
|
|
│
|
|
▼
|
|
Execution Method
|
|
├─► Simulation
|
|
├─► Direct On-Chain
|
|
└─► Relayer
|
|
│
|
|
▼
|
|
Transaction Status
|
|
```
|
|
|
|
### Multi-Sig Approval Flow
|
|
|
|
```
|
|
Transaction Created
|
|
│
|
|
▼
|
|
Owner Approval Request
|
|
│
|
|
▼
|
|
Approval Validation
|
|
├─► Owner Check
|
|
├─► Duplicate Check
|
|
└─► Lock Check
|
|
│
|
|
▼
|
|
Approval Count Update
|
|
│
|
|
▼
|
|
Threshold Check
|
|
│
|
|
├─► Insufficient → Wait for More
|
|
└─► Sufficient → Mark as Approved
|
|
│
|
|
▼
|
|
Ready for Execution
|
|
```
|
|
|
|
## Design Principles
|
|
|
|
### 1. Security First
|
|
- All sensitive data encrypted
|
|
- Comprehensive input validation
|
|
- Access control on all operations
|
|
- Replay attack prevention
|
|
- Rate limiting
|
|
|
|
### 2. Modular Architecture
|
|
- Separation of concerns
|
|
- Reusable components
|
|
- Clear interfaces
|
|
- Dependency injection
|
|
|
|
### 3. Type Safety
|
|
- Full TypeScript coverage
|
|
- Strict type checking
|
|
- Interface definitions
|
|
- Type guards
|
|
|
|
### 4. Error Handling
|
|
- Graceful error handling
|
|
- User-friendly messages
|
|
- Error boundaries
|
|
- Comprehensive logging
|
|
|
|
### 5. Performance
|
|
- Efficient algorithms
|
|
- Proper cleanup
|
|
- Memory management
|
|
- Timeout protection
|
|
|
|
## Technology Choices
|
|
|
|
### Why Next.js 14?
|
|
- Server-side rendering support
|
|
- App Router for modern routing
|
|
- Built-in optimizations
|
|
- Excellent TypeScript support
|
|
|
|
### Why ethers.js?
|
|
- Mature and stable
|
|
- Comprehensive API
|
|
- Good TypeScript support
|
|
- Active maintenance
|
|
|
|
### Why Chakra UI?
|
|
- Accessible components
|
|
- Theme customization
|
|
- Responsive design
|
|
- Good developer experience
|
|
|
|
### Why Jest?
|
|
- Fast execution
|
|
- Good mocking support
|
|
- Coverage reporting
|
|
- Active ecosystem
|
|
|
|
## Security Architecture
|
|
|
|
### Encryption Layer
|
|
- AES-GCM encryption for storage
|
|
- PBKDF2 key derivation
|
|
- Session-based keys
|
|
- Secure key management
|
|
|
|
### Validation Layer
|
|
- Input validation
|
|
- Address validation
|
|
- Transaction validation
|
|
- Network validation
|
|
|
|
### Access Control Layer
|
|
- Owner verification
|
|
- Threshold validation
|
|
- Caller authorization
|
|
- Operation locks
|
|
|
|
### Rate Limiting Layer
|
|
- Per-address rate limiting
|
|
- Request throttling
|
|
- Automatic cleanup
|
|
- Configurable limits
|
|
|
|
## Future Enhancements
|
|
|
|
### Planned Features
|
|
- ERC-4337 Account Abstraction support
|
|
- Hardware wallet integration
|
|
- Transaction batching
|
|
- Advanced analytics
|
|
- Multi-chain support expansion
|
|
|
|
### Architecture Improvements
|
|
- Service worker for offline support
|
|
- WebSocket for real-time updates
|
|
- GraphQL API layer
|
|
- Micro-frontend architecture
|