impersonator/docs/02-setup.md

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

git clone <repository-url>
cd impersonator

2. Install Dependencies

# 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:

# 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
2. Create a new project
3. Copy the Project ID
4. Add it to your .env.local file

4. Verify Installation

# 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

pnpm dev

The application will be available at http://localhost:3000

Development Scripts

# 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:

{
  "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:

{
  "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

# Kill process on port 3000
lsof -ti:3000 | xargs kill -9

# Or use a different port
PORT=3001 pnpm dev

Dependency Installation Issues

# Clear cache and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install

TypeScript Errors

# 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
2. Review the API Reference
3. Check the Security Guide
4. Explore the Testing Guide

Additional Resources

• Next.js Documentation
• TypeScript Documentation
• Chakra UI Documentation
• ethers.js Documentation