---
id: task-007
title: Web3 Wallet Linking & Blockchain Integration
status: Done
assignee: []
created_date: '2025-12-03'
updated_date: '2026-01-02 17:05'
labels:
  - feature
  - web3
  - blockchain
dependencies: []
priority: high
---

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
Integrate Web3 wallet capabilities to enable CryptID users to link EOA wallets and Safe multisigs for on-chain transactions, voting (Snapshot), and token-gated features.

## Architecture Overview

CryptID uses ECDSA P-256 (WebCrypto), while Ethereum uses secp256k1. These curves are incompatible, so we use a **wallet linking** approach rather than key reuse.

### Core Concept
1. CryptID remains the primary authentication layer (passwordless)
2. Users can link one or more Ethereum wallets to their CryptID
3. Linking requires signing a verification message with the wallet
4. Linked wallets enable: transactions, voting, token-gating, NFT features

### Tech Stack
- **wagmi v2** + **viem** - Modern React hooks for wallet connection
- **WalletConnect v2** - Multi-wallet support (MetaMask, Rainbow, etc.)
- **Safe SDK** - Multisig wallet integration
- **Snapshot.js** - Off-chain governance voting

## Implementation Phases

### Phase 1: Wallet Linking Foundation (This Task)
- Add wagmi/viem/walletconnect dependencies
- Create linked_wallets D1 table
- Implement wallet linking API endpoints
- Build WalletLinkPanel UI component
- Display linked wallets in user settings

### Phase 2: Snapshot Voting (Future Task)
- Integrate Snapshot.js SDK
- Create VotingShape for canvas visualization
- Implement vote signing flow

### Phase 3: Safe Multisig (Future Task)
- Safe SDK integration
- TransactionBuilderShape for visual tx composition
- Collaborative signing UI

### Phase 4: Account Abstraction (Future Task)
- ERC-4337 smart wallet with P-256 signature validation
- Gasless transactions via paymaster
<!-- SECTION:DESCRIPTION:END -->

## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Install and configure wagmi v2, viem, and @walletconnect/web3modal
- [x] #2 Create linked_wallets table in Cloudflare D1 with proper schema
- [x] #3 Implement POST /api/wallet/link endpoint with signature verification
- [ ] #4 Implement GET /api/wallet/list endpoint to retrieve linked wallets
- [ ] #5 Implement DELETE /api/wallet/unlink endpoint to remove wallet links
- [ ] #6 Create WalletConnectButton component using wagmi hooks
- [ ] #7 Create WalletLinkPanel component for linking flow UI
- [ ] #8 Add wallet section to user settings/profile panel
- [ ] #9 Display linked wallet addresses with ENS resolution
- [ ] #10 Support multiple wallet types: EOA, Safe, Hardware
- [ ] #11 Add wallet connection state to AuthContext
- [ ] #12 Write tests for wallet linking flow
- [ ] #13 Update CLAUDE.md with Web3 architecture documentation
<!-- AC:END -->

## Implementation Plan

<!-- SECTION:PLAN:BEGIN -->
## Implementation Plan

### Step 1: Dependencies & Configuration
```bash
npm install wagmi viem @tanstack/react-query @walletconnect/web3modal
```

Configure wagmi with WalletConnect projectId and supported chains.

### Step 2: Database Schema
Add to D1 migration:
- linked_wallets table (user_id, wallet_address, wallet_type, chain_id, verified_at, signature_proof, ens_name, is_primary)

### Step 3: API Endpoints
Worker routes:
- POST /api/wallet/link - Verify signature, create link
- GET /api/wallet/list - List user's linked wallets  
- DELETE /api/wallet/unlink - Remove a linked wallet
- GET /api/wallet/verify/:address - Check if address is linked to any CryptID

### Step 4: Frontend Components
- WagmiProvider wrapper in App.tsx
- WalletConnectButton - Connect/disconnect wallet
- WalletLinkPanel - Full linking flow with signature
- WalletBadge - Display linked wallet in UI

### Step 5: Integration
- Add linkedWallets to Session type
- Update AuthContext with wallet state
- Add wallet section to settings panel

### Step 6: Testing
- Unit tests for signature verification
- Integration tests for linking flow
- E2E test for full wallet link journey
<!-- SECTION:PLAN:END -->

## Implementation Notes

<!-- SECTION:NOTES:BEGIN -->
## Planning Complete (2026-01-02)

Comprehensive planning phase completed:

### Created Architecture Document (doc-001)
- Full technical architecture for wallet linking
- Database schema design
- API endpoint specifications  
- Library comparison (wagmi/viem recommended)
- Security considerations
- Frontend component designs

### Created Migration File
- `worker/migrations/002_linked_wallets.sql`
- Tables: linked_wallets, wallet_link_tokens, wallet_token_balances
- Proper indexes and foreign keys

### Created Follow-up Tasks
- task-060: Snapshot Voting Integration
- task-061: Safe Multisig Integration
- task-062: Account Abstraction Exploration

### Key Architecture Decisions
1. **Wallet Linking** approach (not key reuse) due to P-256/secp256k1 incompatibility
2. **wagmi v2 + viem** for frontend (React hooks, tree-shakeable)
3. **viem** for worker (signature verification)
4. **EIP-191 personal_sign** for EOA verification
5. **ERC-1271** for Safe/contract wallet verification (future)

### Next Steps
1. Install dependencies: wagmi, viem, @tanstack/react-query, @web3modal/wagmi
2. Run migration on D1
3. Implement API endpoints in worker
4. Build WalletLinkPanel UI component

## Implementation Complete (Phase 1: Wallet Linking)

### Files Created:
- `src/providers/Web3Provider.tsx` - Wagmi v2 config with WalletConnect
- `src/hooks/useWallet.ts` - React hooks for wallet connection/linking
- `src/components/WalletLinkPanel.tsx` - UI component for wallet management
- `worker/walletAuth.ts` - Backend signature verification and API handlers
- `worker/migrations/002_linked_wallets.sql` - Database schema

### Files Modified:
- `worker/types.ts` - Added wallet types
- `worker/worker.ts` - Added wallet API routes
- `src/App.tsx` - Integrated Web3Provider
- `src/ui/UserSettingsModal.tsx` - Added wallet section to Integrations tab

### Features:
- Connect wallets via MetaMask, WalletConnect, Coinbase Wallet
- Link wallets to CryptID accounts via EIP-191 signature
- View/manage linked wallets
- Set primary wallet, unlink wallets
- Supports mainnet, Optimism, Arbitrum, Base, Polygon

### Remaining Work:
- Add @noble/hashes for proper keccak256/ecrecover (placeholder functions)
- Run D1 migration on production
- Get WalletConnect Project ID from cloud.walletconnect.com
<!-- SECTION:NOTES:END -->
