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
362 lines
10 KiB
Markdown
362 lines
10 KiB
Markdown
# Project Structure
|
|
|
|
This document provides a detailed overview of the project's file structure and organization.
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
impersonator/
|
|
├── app/ # Next.js App Router
|
|
│ ├── layout.tsx # Root layout with metadata
|
|
│ ├── page.tsx # Home page component
|
|
│ ├── providers.tsx # Global context providers
|
|
│ └── icon.png # App icon
|
|
│
|
|
├── components/ # React components
|
|
│ ├── Body/ # Main body components
|
|
│ │ ├── index.tsx # Main body orchestrator
|
|
│ │ ├── TabsSelect.tsx # Tab navigation
|
|
│ │ ├── WalletConnectTab/ # WalletConnect integration
|
|
│ │ ├── IFrameConnectTab/ # iFrame integration
|
|
│ │ ├── BrowserExtensionTab.tsx
|
|
│ │ ├── TransactionRequests.tsx
|
|
│ │ ├── AddressInput/ # Address input with ENS
|
|
│ │ ├── NetworkInput.tsx # Network selection
|
|
│ │ └── TenderlySettings.tsx
|
|
│ │
|
|
│ ├── SmartWallet/ # Smart wallet components
|
|
│ │ ├── WalletManager.tsx # Wallet list and selection
|
|
│ │ ├── OwnerManagement.tsx # Owner and threshold management
|
|
│ │ └── DeployWallet.tsx # New wallet deployment
|
|
│ │
|
|
│ ├── TransactionExecution/ # Transaction components
|
|
│ │ ├── TransactionBuilder.tsx # Transaction creation
|
|
│ │ ├── TransactionApproval.tsx # Approval interface
|
|
│ │ └── TransactionHistory.tsx # Transaction list
|
|
│ │
|
|
│ ├── Balance/ # Balance components
|
|
│ │ ├── WalletBalance.tsx # Balance display
|
|
│ │ └── AddToken.tsx # Add custom token
|
|
│ │
|
|
│ ├── layouts/ # Layout components
|
|
│ ├── Navbar.tsx # Navigation bar
|
|
│ ├── Footer.tsx # Footer component
|
|
│ ├── ErrorBoundary.tsx # Error boundary
|
|
│ └── CustomConnectButton.tsx
|
|
│
|
|
├── contexts/ # React contexts
|
|
│ ├── SafeInjectContext.tsx # iFrame communication context
|
|
│ ├── SmartWalletContext.tsx # Smart wallet state
|
|
│ └── TransactionContext.tsx # Transaction state
|
|
│
|
|
├── helpers/ # Helper functions
|
|
│ ├── communicator.ts # Message communication
|
|
│ ├── messageFormatter.ts # Message formatting
|
|
│ ├── utils.ts # General utilities
|
|
│ │
|
|
│ ├── smartWallet/ # Smart wallet helpers
|
|
│ │ ├── gnosisSafe.ts # Gnosis Safe integration
|
|
│ │ └── erc4337.ts # ERC-4337 (placeholder)
|
|
│ │
|
|
│ ├── transaction/ # Transaction helpers
|
|
│ │ └── execution.ts # Transaction execution
|
|
│ │
|
|
│ └── balance/ # Balance helpers
|
|
│ └── index.ts # Balance fetching
|
|
│
|
|
├── utils/ # Utility functions
|
|
│ ├── security.ts # Security utilities
|
|
│ ├── encryption.ts # Encryption utilities
|
|
│ ├── monitoring.ts # Monitoring service
|
|
│ └── constants.ts # Application constants
|
|
│
|
|
├── __tests__/ # Test files
|
|
│ ├── security.test.ts # Security utility tests
|
|
│ ├── encryption.test.ts # Encryption tests
|
|
│ ├── rateLimiter.test.ts # Rate limiter tests
|
|
│ ├── nonceManager.test.ts # Nonce manager tests
|
|
│ └── integration/ # Integration tests
|
|
│ ├── walletManagement.test.ts
|
|
│ ├── transactionFlow.test.ts
|
|
│ └── multisigApproval.test.ts
|
|
│
|
|
├── docs/ # Documentation
|
|
│ ├── README.md # Documentation index
|
|
│ ├── 01-overview.md # Architecture overview
|
|
│ ├── 02-setup.md # Setup guide
|
|
│ ├── 03-structure.md # This file
|
|
│ └── ... # Other documentation
|
|
│
|
|
├── public/ # Static assets
|
|
│ └── ... # Images, icons, etc.
|
|
│
|
|
├── style/ # Styles and themes
|
|
│ └── theme.ts # Chakra UI theme
|
|
│
|
|
├── types.ts # TypeScript type definitions
|
|
├── package.json # Dependencies and scripts
|
|
├── tsconfig.json # TypeScript configuration
|
|
├── next.config.js # Next.js configuration
|
|
├── jest.config.js # Jest configuration
|
|
├── jest.setup.js # Jest setup
|
|
├── vercel.json # Vercel deployment config
|
|
└── README.md # Project README
|
|
```
|
|
|
|
## Key Files Explained
|
|
|
|
### Application Entry Points
|
|
|
|
#### `app/layout.tsx`
|
|
Root layout component that wraps all pages. Sets up metadata and global layout structure.
|
|
|
|
#### `app/page.tsx`
|
|
Main home page component. Renders the main application interface.
|
|
|
|
#### `app/providers.tsx`
|
|
Sets up all global React contexts:
|
|
- Chakra UI provider
|
|
- Wagmi configuration
|
|
- RainbowKit provider
|
|
- SafeInject provider
|
|
- SmartWallet provider
|
|
- Transaction provider
|
|
- Error boundary
|
|
|
|
### Core Components
|
|
|
|
#### `components/Body/index.tsx`
|
|
Main orchestrator component that:
|
|
- Manages connection methods (WalletConnect, iFrame, Extension)
|
|
- Handles address resolution
|
|
- Manages network selection
|
|
- Coordinates transaction creation
|
|
- Renders appropriate tabs
|
|
|
|
#### `components/SmartWallet/WalletManager.tsx`
|
|
Manages smart wallet list:
|
|
- Displays configured wallets
|
|
- Allows wallet selection
|
|
- Connects to existing wallets
|
|
- Opens deployment modal
|
|
|
|
#### `components/TransactionExecution/TransactionBuilder.tsx`
|
|
Transaction creation interface:
|
|
- Native token transfers
|
|
- ERC20 token transfers
|
|
- Raw transaction data
|
|
- Gas estimation
|
|
|
|
### Context Providers
|
|
|
|
#### `contexts/SafeInjectContext.tsx`
|
|
Manages iframe communication:
|
|
- Safe App SDK integration
|
|
- postMessage handling
|
|
- Transaction forwarding
|
|
- Safe info retrieval
|
|
|
|
#### `contexts/SmartWalletContext.tsx`
|
|
Manages smart wallet state:
|
|
- Wallet configuration
|
|
- Owner management
|
|
- Threshold configuration
|
|
- Balance tracking
|
|
- Encrypted storage
|
|
|
|
#### `contexts/TransactionContext.tsx`
|
|
Manages transaction lifecycle:
|
|
- Transaction creation
|
|
- Approval workflow
|
|
- Execution methods
|
|
- Transaction history
|
|
- Rate limiting
|
|
- Nonce management
|
|
|
|
### Helper Modules
|
|
|
|
#### `helpers/communicator.ts`
|
|
Secure message communication:
|
|
- Message validation
|
|
- Replay protection
|
|
- Origin validation
|
|
- Message routing
|
|
|
|
#### `helpers/smartWallet/gnosisSafe.ts`
|
|
Gnosis Safe integration:
|
|
- Safe contract interaction
|
|
- Safe SDK usage
|
|
- Safe deployment
|
|
- Safe info retrieval
|
|
|
|
#### `helpers/transaction/execution.ts`
|
|
Transaction execution:
|
|
- Direct on-chain execution
|
|
- Relayer execution
|
|
- Transaction simulation
|
|
- Gas estimation
|
|
|
|
### Utility Modules
|
|
|
|
#### `utils/security.ts`
|
|
Security utilities:
|
|
- Address validation
|
|
- Transaction validation
|
|
- Rate limiting
|
|
- Nonce management
|
|
- Input sanitization
|
|
|
|
#### `utils/encryption.ts`
|
|
Encryption utilities:
|
|
- AES-GCM encryption
|
|
- PBKDF2 key derivation
|
|
- Secure storage wrapper
|
|
- Session key management
|
|
|
|
#### `utils/monitoring.ts`
|
|
Monitoring service:
|
|
- Centralized logging
|
|
- Error tracking
|
|
- Security event tracking
|
|
- Performance metrics
|
|
|
|
#### `utils/constants.ts`
|
|
Application constants:
|
|
- Security constants
|
|
- Network constants
|
|
- Storage keys
|
|
- Error messages
|
|
- Default values
|
|
|
|
## Type Definitions
|
|
|
|
### `types.ts`
|
|
Central type definitions including:
|
|
- `SmartWalletConfig` - Wallet configuration
|
|
- `TransactionRequest` - Transaction data
|
|
- `SafeInfo` - Safe contract info
|
|
- `WalletBalance` - Balance information
|
|
- `TransactionStatus` - Transaction states
|
|
- SDK message types
|
|
- Network types
|
|
|
|
## Configuration Files
|
|
|
|
### `package.json`
|
|
- Dependencies
|
|
- Scripts
|
|
- Project metadata
|
|
|
|
### `tsconfig.json`
|
|
TypeScript configuration:
|
|
- Compiler options
|
|
- Path aliases
|
|
- Type definitions
|
|
|
|
### `next.config.js`
|
|
Next.js configuration:
|
|
- Webpack settings
|
|
- Environment variables
|
|
- Build optimizations
|
|
|
|
### `jest.config.js`
|
|
Jest test configuration:
|
|
- Test environment
|
|
- Coverage settings
|
|
- Module resolution
|
|
|
|
## File Naming Conventions
|
|
|
|
### Components
|
|
- PascalCase: `WalletManager.tsx`
|
|
- One component per file
|
|
- Descriptive names
|
|
|
|
### Utilities
|
|
- camelCase: `security.ts`
|
|
- Descriptive names
|
|
- Grouped by functionality
|
|
|
|
### Tests
|
|
- Same name as source file: `security.test.ts`
|
|
- Located in `__tests__/` directory
|
|
- Integration tests in `__tests__/integration/`
|
|
|
|
### Types
|
|
- PascalCase interfaces: `SmartWalletConfig`
|
|
- Enums: `TransactionStatus`
|
|
- Centralized in `types.ts`
|
|
|
|
## Import Patterns
|
|
|
|
### Absolute Imports
|
|
```typescript
|
|
import { useSmartWallet } from "@/contexts/SmartWalletContext";
|
|
import { validateAddress } from "@/utils/security";
|
|
```
|
|
|
|
### Relative Imports
|
|
```typescript
|
|
import WalletManager from "../SmartWallet/WalletManager";
|
|
import { getSafeInfo } from "../../helpers/smartWallet/gnosisSafe";
|
|
```
|
|
|
|
## Code Organization Principles
|
|
|
|
### 1. Separation of Concerns
|
|
- UI components separate from business logic
|
|
- Helpers separate from contexts
|
|
- Utilities separate from components
|
|
|
|
### 2. Single Responsibility
|
|
- Each file has one clear purpose
|
|
- Functions do one thing well
|
|
- Components are focused
|
|
|
|
### 3. Reusability
|
|
- Shared utilities in `utils/`
|
|
- Reusable components in `components/`
|
|
- Common helpers in `helpers/`
|
|
|
|
### 4. Type Safety
|
|
- All functions typed
|
|
- Interfaces for data structures
|
|
- Type guards where needed
|
|
|
|
## Adding New Features
|
|
|
|
### Adding a New Component
|
|
1. Create file in appropriate `components/` subdirectory
|
|
2. Export component
|
|
3. Add to parent component or page
|
|
4. Add tests in `__tests__/`
|
|
|
|
### Adding a New Helper
|
|
1. Create file in appropriate `helpers/` subdirectory
|
|
2. Export functions
|
|
3. Add JSDoc comments
|
|
4. Add tests
|
|
|
|
### Adding a New Utility
|
|
1. Create file in `utils/`
|
|
2. Export functions/classes
|
|
3. Add to constants if needed
|
|
4. Add tests
|
|
|
|
### Adding a New Context
|
|
1. Create file in `contexts/`
|
|
2. Export provider and hook
|
|
3. Add to `app/providers.tsx`
|
|
4. Add tests
|
|
|
|
## Best Practices
|
|
|
|
1. **Keep files focused** - One responsibility per file
|
|
2. **Use TypeScript** - Leverage type safety
|
|
3. **Add JSDoc** - Document public APIs
|
|
4. **Write tests** - Test new functionality
|
|
5. **Follow naming** - Use established conventions
|
|
6. **Group related code** - Keep related files together
|
|
7. **Avoid deep nesting** - Keep structure flat
|
|
8. **Use constants** - Extract magic numbers
|