feat: comprehensive project improvements and fixes
- 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
This commit is contained in:
defiQUG
301
docs/02-setup.md
Normal file
301
docs/02-setup.md
Normal file
@@ -0,0 +1,301 @@
|
||||
# Installation & Setup
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you begin, ensure you have the following installed:
|
||||
|
||||
- **Node.js** 18.x or higher
|
||||
- **pnpm** 9.x or higher (or npm/yarn)
|
||||
- **Git** for version control
|
||||
- A code editor (VS Code recommended)
|
||||
|
||||
## Environment Setup
|
||||
|
||||
### 1. Clone the Repository
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd impersonator
|
||||
```
|
||||
|
||||
### 2. Install Dependencies
|
||||
|
||||
```bash
|
||||
# Using pnpm (recommended)
|
||||
pnpm install
|
||||
|
||||
# Or using npm
|
||||
npm install
|
||||
|
||||
# Or using yarn
|
||||
yarn install
|
||||
```
|
||||
|
||||
### 3. Environment Variables
|
||||
|
||||
Create a `.env.local` file in the root directory:
|
||||
|
||||
```env
|
||||
# WalletConnect Project ID
|
||||
NEXT_PUBLIC_WC_PROJECT_ID=your_walletconnect_project_id
|
||||
|
||||
# Optional: Tenderly API Key (for fork simulation)
|
||||
TENDERLY_API_KEY=your_tenderly_api_key
|
||||
|
||||
# Optional: Sentry DSN (for error tracking)
|
||||
NEXT_PUBLIC_SENTRY_DSN=your_sentry_dsn
|
||||
```
|
||||
|
||||
#### Getting a WalletConnect Project ID
|
||||
|
||||
1. Visit [WalletConnect Cloud](https://cloud.walletconnect.com/)
|
||||
2. Create a new project
|
||||
3. Copy the Project ID
|
||||
4. Add it to your `.env.local` file
|
||||
|
||||
### 4. Verify Installation
|
||||
|
||||
```bash
|
||||
# Check Node version
|
||||
node --version # Should be 18.x or higher
|
||||
|
||||
# Check pnpm version
|
||||
pnpm --version # Should be 9.x or higher
|
||||
|
||||
# Verify dependencies
|
||||
pnpm list
|
||||
```
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Start Development Server
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
The application will be available at `http://localhost:3000`
|
||||
|
||||
### Development Scripts
|
||||
|
||||
```bash
|
||||
# Start development server
|
||||
pnpm dev
|
||||
|
||||
# Build for production
|
||||
pnpm build
|
||||
|
||||
# Start production server
|
||||
pnpm start
|
||||
|
||||
# Run linter
|
||||
pnpm lint
|
||||
|
||||
# Run tests
|
||||
pnpm test
|
||||
|
||||
# Run tests in watch mode
|
||||
pnpm test:watch
|
||||
|
||||
# Run tests with coverage
|
||||
pnpm test:coverage
|
||||
|
||||
# Run security tests
|
||||
pnpm test:security
|
||||
|
||||
# Run integration tests
|
||||
pnpm test:integration
|
||||
|
||||
# Run all tests
|
||||
pnpm test:all
|
||||
```
|
||||
|
||||
## IDE Setup
|
||||
|
||||
### VS Code Recommended Extensions
|
||||
|
||||
Install the following VS Code extensions for the best development experience:
|
||||
|
||||
```json
|
||||
{
|
||||
"recommendations": [
|
||||
"dbaeumer.vscode-eslint",
|
||||
"esbenp.prettier-vscode",
|
||||
"bradlc.vscode-tailwindcss",
|
||||
"ms-vscode.vscode-typescript-next",
|
||||
"orta.vscode-jest"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### VS Code Settings
|
||||
|
||||
Create `.vscode/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"editor.formatOnSave": true,
|
||||
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
||||
"editor.codeActionsOnSave": {
|
||||
"source.fixAll.eslint": true
|
||||
},
|
||||
"typescript.tsdk": "node_modules/typescript/lib",
|
||||
"typescript.enablePromptUseWorkspaceTsdk": true
|
||||
}
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
impersonator/
|
||||
├── app/ # Next.js App Router pages
|
||||
│ ├── layout.tsx # Root layout
|
||||
│ ├── page.tsx # Home page
|
||||
│ └── providers.tsx # Context providers
|
||||
├── components/ # React components
|
||||
│ ├── Body/ # Main body components
|
||||
│ ├── SmartWallet/ # Smart wallet components
|
||||
│ ├── TransactionExecution/ # Transaction components
|
||||
│ └── Balance/ # Balance components
|
||||
├── contexts/ # React contexts
|
||||
│ ├── SafeInjectContext.tsx
|
||||
│ ├── SmartWalletContext.tsx
|
||||
│ └── TransactionContext.tsx
|
||||
├── helpers/ # Helper functions
|
||||
│ ├── communicator.ts # Message communication
|
||||
│ ├── smartWallet/ # Smart wallet helpers
|
||||
│ ├── transaction/ # Transaction helpers
|
||||
│ └── balance/ # Balance helpers
|
||||
├── 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
|
||||
│ ├── encryption.test.ts
|
||||
│ └── integration/ # Integration tests
|
||||
├── docs/ # Documentation
|
||||
├── public/ # Static assets
|
||||
├── style/ # Styles and themes
|
||||
├── 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
|
||||
```
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### TypeScript Configuration (`tsconfig.json`)
|
||||
|
||||
The project uses strict TypeScript configuration:
|
||||
- Strict mode enabled
|
||||
- Path aliases configured (`@/` for root)
|
||||
- Next.js types included
|
||||
|
||||
### Next.js Configuration (`next.config.js`)
|
||||
|
||||
Key configurations:
|
||||
- Webpack fallbacks for Node.js modules
|
||||
- Styled-components support
|
||||
- Environment variable handling
|
||||
|
||||
### Jest Configuration (`jest.config.js`)
|
||||
|
||||
Test configuration:
|
||||
- jsdom environment
|
||||
- Path aliases
|
||||
- Coverage thresholds
|
||||
- Test file patterns
|
||||
|
||||
## Database/Storage
|
||||
|
||||
The application uses browser storage:
|
||||
- **localStorage** - Encrypted storage for wallet configs and transactions
|
||||
- **sessionStorage** - Encryption keys and session data
|
||||
|
||||
No external database is required for basic functionality.
|
||||
|
||||
## Network Configuration
|
||||
|
||||
### Supported Networks
|
||||
|
||||
The application supports the following networks:
|
||||
- Ethereum Mainnet (1)
|
||||
- Goerli Testnet (5)
|
||||
- Polygon (137)
|
||||
- Arbitrum (42161)
|
||||
- Optimism (10)
|
||||
- Base (8453)
|
||||
- Gnosis Chain (100)
|
||||
- BSC (56)
|
||||
- Fantom (250)
|
||||
- Avalanche (43114)
|
||||
|
||||
### RPC Endpoints
|
||||
|
||||
RPC endpoints are configured per network. You can:
|
||||
- Use default public RPCs
|
||||
- Configure custom RPCs via environment variables
|
||||
- Use Tenderly forks for testing
|
||||
|
||||
## Troubleshooting Setup
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Port Already in Use
|
||||
|
||||
```bash
|
||||
# Kill process on port 3000
|
||||
lsof -ti:3000 | xargs kill -9
|
||||
|
||||
# Or use a different port
|
||||
PORT=3001 pnpm dev
|
||||
```
|
||||
|
||||
#### Dependency Installation Issues
|
||||
|
||||
```bash
|
||||
# Clear cache and reinstall
|
||||
rm -rf node_modules pnpm-lock.yaml
|
||||
pnpm install
|
||||
```
|
||||
|
||||
#### TypeScript Errors
|
||||
|
||||
```bash
|
||||
# Restart TypeScript server in VS Code
|
||||
# Cmd/Ctrl + Shift + P → "TypeScript: Restart TS Server"
|
||||
```
|
||||
|
||||
#### Environment Variables Not Loading
|
||||
|
||||
- Ensure `.env.local` is in the root directory
|
||||
- Restart the development server
|
||||
- Variables must start with `NEXT_PUBLIC_` for client-side access
|
||||
|
||||
### Verification Checklist
|
||||
|
||||
- [ ] Node.js 18+ installed
|
||||
- [ ] pnpm 9+ installed
|
||||
- [ ] Dependencies installed successfully
|
||||
- [ ] `.env.local` file created with required variables
|
||||
- [ ] Development server starts without errors
|
||||
- [ ] Tests run successfully
|
||||
- [ ] Linter passes
|
||||
|
||||
## Next Steps
|
||||
|
||||
Once setup is complete:
|
||||
1. Read the [Development Guide](./04-development.md)
|
||||
2. Review the [API Reference](./05-api-reference.md)
|
||||
3. Check the [Security Guide](./06-security.md)
|
||||
4. Explore the [Testing Guide](./07-testing.md)
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Next.js Documentation](https://nextjs.org/docs)
|
||||
- [TypeScript Documentation](https://www.typescriptlang.org/docs/)
|
||||
- [Chakra UI Documentation](https://chakra-ui.com/)
|
||||
- [ethers.js Documentation](https://docs.ethers.org/)
|
||||
Reference in New Issue
Block a user