From 7d6d08481502670aad5d32deb3973e9d4a25369b Mon Sep 17 00:00:00 2001
From: Jeff Emmett <jeffemmett@gmail.com>
Date: Fri, 2 Jan 2026 16:54:59 +0100
Subject: [PATCH] Update task task-007

---
 ...Wallet-Linking-&-Blockchain-Integration.md | 116 ++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 backlog/tasks/task-007 - Web3-Wallet-Linking-&-Blockchain-Integration.md

diff --git a/backlog/tasks/task-007 - Web3-Wallet-Linking-&-Blockchain-Integration.md b/backlog/tasks/task-007 - Web3-Wallet-Linking-&-Blockchain-Integration.md
new file mode 100644
index 0000000..c83efbc
--- /dev/null
+++ b/backlog/tasks/task-007 - Web3-Wallet-Linking-&-Blockchain-Integration.md	
@@ -0,0 +1,116 @@
+---
+id: task-007
+title: Web3 Wallet Linking & Blockchain Integration
+status: To Do
+assignee: []
+created_date: '2025-12-03'
+updated_date: '2026-01-02 15:54'
+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 -->
+- [ ] #1 Install and configure wagmi v2, viem, and @walletconnect/web3modal
+- [ ] #2 Create linked_wallets table in Cloudflare D1 with proper schema
+- [ ] #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 -->