Safe Wallet Extension

A Chrome browser extension for managing Safe (Gnosis Safe) wallets on Sepolia testnet.

NOTE: THIS IS AN EXPERIMENTAL PROJECT. USE AT YOUR OWN RISK!

Overview

This extension provides a simple interface to interact with Safe smart contract wallets, allowing users to:

• Import Safe accounts by address
• Manage owner keys for transaction signing
• Send ETH transactions from Safe wallets
• View Safe account details and balances

Features

• Safe Account Management: Import and manage Safe wallets on Sepolia testnet
• Owner Key Support: Securely import private keys for transaction signing
• Transaction Interface: Send ETH transactions with Safe's multi-signature security
• Modern UI: Built with React, TypeScript, and Tailwind CSS
• Security First: Follows security best practices for wallet extensions

Technology Stack

• Frontend: React 19 with TypeScript
• Styling: Tailwind CSS v4 + Shadcn UI components
• Build System: Vite with Chrome extension optimization
• Web3: Viem for blockchain interactions
• Safe Integration: Safe Protocol Kit from Safe{Core} SDK
• Configuration: Cross-environment variables with validation
• Testing: Jest with React Testing Library (279 tests)
• Code Quality: ESLint, Prettier, and pre-commit hooks

Quick Start

Prerequisites

• Node.js 18+ (use nvm use for exact version)
• Chrome browser
• Git

Installation & Development

1. Clone and setup

   git clone https://github.com/rahulrumalla/safe-extension.git
   cd safe-extension
   nvm use  # Uses .nvmrc for Node version consistency
   npm install

2. Configure environment (optional)

   # Copy environment template
   cp .env.example .env.local
   
   # Customize as needed (all variables have sensible defaults)
   # See "Environment Configuration" section below for details

3. Start developing

   npm run dev:extension
   # Builds extension and shows load instructions

4. Load in Chrome

   • Go to chrome://extensions/
   • Enable "Developer mode"
   • Click "Load unpacked" → select dist/ folder
   • Pin extension for easy access

5. Development workflow

   # Make changes to src/ files
   npm run dev:extension  # Rebuild
   # Go to chrome://extensions/ and hit reload button

Chrome Extension Development Tips

Loading & Reloading:

• After building (npm run dev:extension), load the dist/ folder in Chrome extensions
• Click the refresh button in chrome://extensions/ after each rebuild
• Hot reload was intentionally removed to avoid Chrome extension compatibility issues

Troubleshooting:

• Extension not loading: Ensure dist/ folder contains all files, check Chrome console, verify manifest.json
• Development issues: Restart dev server, reload extension, check Chrome's developer console

Development

Essential Commands

# 🚀 Development (most used)
npm run dev:extension    # Build + instructions for Chrome reload
npm run dev:watch        # Auto-rebuild on file changes

# ✅ Quality Assurance
npm run check            # Full validation (lint + security + build + test)
npm run fix-conflicts    # Fix any formatting conflicts

# 🔒 Security & Performance
npm run security:check   # Validate dependencies & lockfile
npm run build:analyze    # Bundle size analysis + stats.html

# 🧪 Testing
npm run test             # Run all tests
npm run test:watch       # Watch mode
npm run test:coverage    # Coverage report

VS Code Debugging

• F5 → Launch Chrome with extension loaded
• Ctrl+Shift+P → "Tasks: Run Task" → "Extension: Reload"
• Breakpoints work in popup, background, and content scripts

Development Tips

• Bundle analysis: Run npm run build:analyze to see what's making bundles large
• Auto-format: Files format on save (configured for AI-generated code)
• Security: Pre-commit hooks prevent commits with vulnerabilities
• Performance: Build warns if chunks exceed 1MB (configurable)

Project Structure

src/
├── components/          # React components
│   ├── ui/             # Reusable UI components
│   └── ErrorBoundary.tsx
├── config/             # Configuration files
├── lib/                # Utility functions
├── types/              # TypeScript type definitions
├── __tests__/          # Test files
├── App.tsx             # Main application component
├── main.tsx            # Entry point
└── index.css           # Global styles

Environment Configuration

The extension uses environment variables for configuration with sensible defaults. All variables are optional and have fallback values.

Available Environment Variables

Copy .env.example to .env.local and customize as needed:

# Network Configuration (Optional)
VITE_NETWORK=sepolia                                    # Target network: sepolia, mainnet, goerli
VITE_RPC_URL=https://ethereum-sepolia-rpc.publicnode.com  # Ethereum RPC endpoint

# Safe Configuration (Optional)  
VITE_SAFE_TRANSACTION_SERVICE_URL=https://safe-transaction-sepolia.safe.global  # Safe API endpoint

# Development Settings (Optional)
VITE_DEV_MODE=true     # Enable development features: true, false
VITE_LOG_LEVEL=debug   # Logging level: debug, info, warn, error

Default Configuration

The extension is configured for Sepolia testnet by default:

• Network: Sepolia testnet
• RPC URL: https://ethereum-sepolia-rpc.publicnode.com
• Safe Transaction Service: https://safe-transaction-sepolia.safe.global
• Explorer: https://sepolia.etherscan.io
• Log Level: info (production), debug (development)

Environment Validation

The extension automatically validates environment variables at startup:

• URL Validation: Ensures RPC and service URLs are properly formatted
• Enum Validation: Validates network, log level, and dev mode values
• Startup Logging: Displays validation results in development mode

// Environment validation is built-in and automatic
// Check browser console for validation results in development

Security Considerations

• Private Key Handling: Keys are stored securely using Chrome's storage API
• Input Validation: All user inputs are validated before processing
• Network Security: HTTPS-only connections to RPC endpoints
• Minimal Permissions: Extension requests only necessary Chrome permissions
• Error Boundaries: Robust error handling throughout the application

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Quality check: npm run check (includes security validation)
5. Commit your changes (pre-commit hooks will run automatically)
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Project Status

✅ Complete - All core functionality implemented:

• Safe Account Management: Import Safe wallets and view account details
• Owner Key Management: Secure private key import with validation
• Transaction System: Send ETH transactions with confirmation dialogs
• Security Features: XOR encryption, input validation, error handling
• Professional UI/UX: Responsive design with smooth animations
• Quality Assurance: 279 tests, automated linting, and security checks

Future Enhancements: Multi-network support, transaction history, advanced Safe features

License

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

Support

For questions, issues, or contributions, please visit the GitHub repository.

Acknowledgments

• Safe Global for the Safe Protocol Kit
• Viem for Web3 functionality
• Shadcn UI for beautiful components
• Tailwind CSS for styling