666 lines
16 KiB
Markdown
666 lines
16 KiB
Markdown
---
|
|
id: doc-001
|
|
title: Web3 Wallet Integration Architecture
|
|
type: other
|
|
created_date: '2026-01-02 16:07'
|
|
---
|
|
# Web3 Wallet Integration Architecture
|
|
|
|
**Status:** Planning
|
|
**Created:** 2026-01-02
|
|
**Related Task:** task-007
|
|
|
|
---
|
|
|
|
## 1. Overview
|
|
|
|
This document outlines the architecture for integrating Web3 wallet capabilities into the canvas-website, enabling CryptID users to link Ethereum wallets for on-chain transactions, voting, and token-gated features.
|
|
|
|
### Key Constraint: Cryptographic Curve Mismatch
|
|
|
|
| System | Curve | Usage |
|
|
|--------|-------|-------|
|
|
| **CryptID (WebCrypto)** | ECDSA P-256 (NIST) | Authentication, passwordless login |
|
|
| **Ethereum** | ECDSA secp256k1 | Transactions, message signing |
|
|
|
|
These curves are **incompatible**. A CryptID key cannot sign Ethereum transactions. Therefore, we use a **wallet linking** approach where:
|
|
1. CryptID handles authentication (who you are)
|
|
2. Linked wallet handles on-chain actions (what you can do)
|
|
|
|
---
|
|
|
|
## 2. Database Schema
|
|
|
|
### Migration: `002_linked_wallets.sql`
|
|
|
|
```sql
|
|
-- Migration: Add Linked Wallets for Web3 Integration
|
|
-- Date: 2026-01-02
|
|
-- Description: Enables CryptID users to link Ethereum wallets for
|
|
-- on-chain transactions, voting, and token-gated features.
|
|
|
|
-- =============================================================================
|
|
-- LINKED WALLETS TABLE
|
|
-- =============================================================================
|
|
-- Each CryptID user can link multiple Ethereum wallets (EOA, Safe, hardware)
|
|
-- Linking requires signature verification to prove wallet ownership
|
|
|
|
CREATE TABLE IF NOT EXISTS linked_wallets (
|
|
id TEXT PRIMARY KEY, -- UUID for the link record
|
|
user_id TEXT NOT NULL, -- References users.id (CryptID account)
|
|
wallet_address TEXT NOT NULL, -- Ethereum address (checksummed, 0x-prefixed)
|
|
|
|
-- Wallet metadata
|
|
wallet_type TEXT DEFAULT 'eoa' CHECK (wallet_type IN ('eoa', 'safe', 'hardware', 'contract')),
|
|
chain_id INTEGER DEFAULT 1, -- Primary chain (1 = Ethereum mainnet)
|
|
label TEXT, -- User-provided label (e.g., "Main Wallet")
|
|
|
|
-- Verification proof
|
|
signature_message TEXT NOT NULL, -- The message that was signed
|
|
signature TEXT NOT NULL, -- EIP-191 personal_sign signature
|
|
verified_at TEXT NOT NULL, -- When signature was verified
|
|
|
|
-- ENS integration
|
|
ens_name TEXT, -- Resolved ENS name (if any)
|
|
ens_avatar TEXT, -- ENS avatar URL (if any)
|
|
ens_resolved_at TEXT, -- When ENS was last resolved
|
|
|
|
-- Flags
|
|
is_primary INTEGER DEFAULT 0, -- 1 = primary wallet for this user
|
|
is_active INTEGER DEFAULT 1, -- 0 = soft-deleted
|
|
|
|
-- Timestamps
|
|
created_at TEXT DEFAULT (datetime('now')),
|
|
updated_at TEXT DEFAULT (datetime('now')),
|
|
last_used_at TEXT, -- Last time wallet was used for action
|
|
|
|
-- Constraints
|
|
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
|
|
UNIQUE(user_id, wallet_address) -- Can't link same wallet twice
|
|
);
|
|
|
|
-- Indexes for efficient lookups
|
|
CREATE INDEX IF NOT EXISTS idx_linked_wallets_user ON linked_wallets(user_id);
|
|
CREATE INDEX IF NOT EXISTS idx_linked_wallets_address ON linked_wallets(wallet_address);
|
|
CREATE INDEX IF NOT EXISTS idx_linked_wallets_active ON linked_wallets(is_active);
|
|
CREATE INDEX IF NOT EXISTS idx_linked_wallets_primary ON linked_wallets(user_id, is_primary);
|
|
|
|
-- =============================================================================
|
|
-- WALLET LINKING TOKENS TABLE (for Safe/multisig delayed verification)
|
|
-- =============================================================================
|
|
-- For contract wallets that require on-chain signature verification
|
|
|
|
CREATE TABLE IF NOT EXISTS wallet_link_tokens (
|
|
id TEXT PRIMARY KEY,
|
|
user_id TEXT NOT NULL,
|
|
wallet_address TEXT NOT NULL,
|
|
nonce TEXT NOT NULL, -- Random nonce for signature message
|
|
token TEXT NOT NULL UNIQUE, -- Secret token for verification callback
|
|
expires_at TEXT NOT NULL,
|
|
used INTEGER DEFAULT 0,
|
|
created_at TEXT DEFAULT (datetime('now')),
|
|
|
|
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
|
|
);
|
|
|
|
CREATE INDEX IF NOT EXISTS idx_wallet_link_tokens_token ON wallet_link_tokens(token);
|
|
|
|
-- =============================================================================
|
|
-- TOKEN BALANCES CACHE (optional, for token-gating)
|
|
-- =============================================================================
|
|
-- Cache of token balances for faster permission checks
|
|
|
|
CREATE TABLE IF NOT EXISTS wallet_token_balances (
|
|
id TEXT PRIMARY KEY,
|
|
wallet_address TEXT NOT NULL,
|
|
token_address TEXT NOT NULL, -- ERC-20/721/1155 contract address
|
|
token_type TEXT CHECK (token_type IN ('erc20', 'erc721', 'erc1155')),
|
|
chain_id INTEGER NOT NULL,
|
|
balance TEXT NOT NULL, -- String to handle big numbers
|
|
last_updated TEXT DEFAULT (datetime('now')),
|
|
|
|
UNIQUE(wallet_address, token_address, chain_id)
|
|
);
|
|
|
|
CREATE INDEX IF NOT EXISTS idx_token_balances_wallet ON wallet_token_balances(wallet_address);
|
|
CREATE INDEX IF NOT EXISTS idx_token_balances_token ON wallet_token_balances(token_address);
|
|
```
|
|
|
|
### TypeScript Types
|
|
|
|
Add to `worker/types.ts`:
|
|
|
|
```typescript
|
|
// =============================================================================
|
|
// Linked Wallet Types
|
|
// =============================================================================
|
|
|
|
export type WalletType = 'eoa' | 'safe' | 'hardware' | 'contract';
|
|
|
|
export interface LinkedWallet {
|
|
id: string;
|
|
user_id: string;
|
|
wallet_address: string;
|
|
wallet_type: WalletType;
|
|
chain_id: number;
|
|
label: string | null;
|
|
signature_message: string;
|
|
signature: string;
|
|
verified_at: string;
|
|
ens_name: string | null;
|
|
ens_avatar: string | null;
|
|
ens_resolved_at: string | null;
|
|
is_primary: number; // SQLite boolean
|
|
is_active: number; // SQLite boolean
|
|
created_at: string;
|
|
updated_at: string;
|
|
last_used_at: string | null;
|
|
}
|
|
|
|
export interface WalletLinkToken {
|
|
id: string;
|
|
user_id: string;
|
|
wallet_address: string;
|
|
nonce: string;
|
|
token: string;
|
|
expires_at: string;
|
|
used: number;
|
|
created_at: string;
|
|
}
|
|
|
|
export interface WalletTokenBalance {
|
|
id: string;
|
|
wallet_address: string;
|
|
token_address: string;
|
|
token_type: 'erc20' | 'erc721' | 'erc1155';
|
|
chain_id: number;
|
|
balance: string;
|
|
last_updated: string;
|
|
}
|
|
|
|
// API Response types
|
|
export interface LinkedWalletResponse {
|
|
id: string;
|
|
address: string;
|
|
type: WalletType;
|
|
chainId: number;
|
|
label: string | null;
|
|
ensName: string | null;
|
|
ensAvatar: string | null;
|
|
isPrimary: boolean;
|
|
linkedAt: string;
|
|
lastUsedAt: string | null;
|
|
}
|
|
|
|
export interface WalletLinkRequest {
|
|
walletAddress: string;
|
|
signature: string;
|
|
message: string;
|
|
walletType?: WalletType;
|
|
chainId?: number;
|
|
label?: string;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. API Endpoints
|
|
|
|
### Base Path: `/api/wallet`
|
|
|
|
All endpoints require CryptID authentication via `X-CryptID-PublicKey` header.
|
|
|
|
---
|
|
|
|
### `POST /api/wallet/link`
|
|
|
|
Link a new wallet to the authenticated CryptID account.
|
|
|
|
**Request:**
|
|
```typescript
|
|
{
|
|
walletAddress: string; // 0x-prefixed Ethereum address
|
|
signature: string; // EIP-191 signature of the message
|
|
message: string; // Must match server-generated format
|
|
walletType?: 'eoa' | 'safe' | 'hardware' | 'contract';
|
|
chainId?: number; // Default: 1 (mainnet)
|
|
label?: string; // Optional user label
|
|
}
|
|
```
|
|
|
|
**Message Format (must be signed):**
|
|
```
|
|
Link wallet to CryptID
|
|
|
|
Account: ${cryptidUsername}
|
|
Wallet: ${walletAddress}
|
|
Timestamp: ${isoTimestamp}
|
|
Nonce: ${randomNonce}
|
|
|
|
This signature proves you own this wallet.
|
|
```
|
|
|
|
**Response (201 Created):**
|
|
```typescript
|
|
{
|
|
success: true;
|
|
wallet: LinkedWalletResponse;
|
|
}
|
|
```
|
|
|
|
**Errors:**
|
|
- `400` - Invalid request body or signature
|
|
- `401` - Not authenticated
|
|
- `409` - Wallet already linked to this account
|
|
- `422` - Signature verification failed
|
|
|
|
---
|
|
|
|
### `GET /api/wallet/list`
|
|
|
|
Get all wallets linked to the authenticated user.
|
|
|
|
**Response:**
|
|
```typescript
|
|
{
|
|
wallets: LinkedWalletResponse[];
|
|
count: number;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `GET /api/wallet/:address`
|
|
|
|
Get details for a specific linked wallet.
|
|
|
|
**Response:**
|
|
```typescript
|
|
{
|
|
wallet: LinkedWalletResponse;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `PATCH /api/wallet/:address`
|
|
|
|
Update a linked wallet (label, primary status).
|
|
|
|
**Request:**
|
|
```typescript
|
|
{
|
|
label?: string;
|
|
isPrimary?: boolean;
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```typescript
|
|
{
|
|
success: true;
|
|
wallet: LinkedWalletResponse;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `DELETE /api/wallet/:address`
|
|
|
|
Unlink a wallet from the account.
|
|
|
|
**Response:**
|
|
```typescript
|
|
{
|
|
success: true;
|
|
message: 'Wallet unlinked';
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `GET /api/wallet/verify/:address`
|
|
|
|
Check if a wallet address is linked to any CryptID account.
|
|
(Public endpoint - no auth required)
|
|
|
|
**Response:**
|
|
```typescript
|
|
{
|
|
linked: boolean;
|
|
cryptidUsername?: string; // Only if user allows public display
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `POST /api/wallet/refresh-ens`
|
|
|
|
Refresh ENS name resolution for a linked wallet.
|
|
|
|
**Request:**
|
|
```typescript
|
|
{
|
|
walletAddress: string;
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```typescript
|
|
{
|
|
ensName: string | null;
|
|
ensAvatar: string | null;
|
|
resolvedAt: string;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Signature Verification Implementation
|
|
|
|
```typescript
|
|
// worker/walletAuth.ts
|
|
|
|
import { verifyMessage, getAddress } from 'viem';
|
|
|
|
export function generateLinkMessage(
|
|
username: string,
|
|
address: string,
|
|
timestamp: string,
|
|
nonce: string
|
|
): string {
|
|
return `Link wallet to CryptID
|
|
|
|
Account: ${username}
|
|
Wallet: ${address}
|
|
Timestamp: ${timestamp}
|
|
Nonce: ${nonce}
|
|
|
|
This signature proves you own this wallet.`;
|
|
}
|
|
|
|
export async function verifyWalletSignature(
|
|
address: string,
|
|
message: string,
|
|
signature: `0x${string}`
|
|
): Promise<boolean> {
|
|
try {
|
|
// Normalize address
|
|
const checksumAddress = getAddress(address);
|
|
|
|
// Verify EIP-191 personal_sign signature
|
|
const valid = await verifyMessage({
|
|
address: checksumAddress,
|
|
message,
|
|
signature,
|
|
});
|
|
|
|
return valid;
|
|
} catch (error) {
|
|
console.error('Signature verification error:', error);
|
|
return false;
|
|
}
|
|
}
|
|
|
|
// For ERC-1271 contract wallet verification (Safe, etc.)
|
|
export async function verifyContractSignature(
|
|
address: string,
|
|
message: string,
|
|
signature: string,
|
|
rpcUrl: string
|
|
): Promise<boolean> {
|
|
// ERC-1271 magic value: 0x1626ba7e
|
|
// Implementation needed for Safe/contract wallet support
|
|
// Uses eth_call to isValidSignature(bytes32,bytes)
|
|
throw new Error('Contract signature verification not yet implemented');
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Library Comparison
|
|
|
|
### Recommendation: **wagmi v2 + viem**
|
|
|
|
| Library | Bundle Size | Type Safety | React Hooks | Maintenance | Recommendation |
|
|
|---------|-------------|-------------|-------------|-------------|----------------|
|
|
| **wagmi v2** | ~40KB | Excellent | Native | Active (wevm team) | ✅ **Best for React** |
|
|
| **viem** | ~25KB | Excellent | N/A | Active (wevm team) | ✅ **Best for worker** |
|
|
| **ethers v6** | ~120KB | Good | None | Active | ⚠️ Larger bundle |
|
|
| **web3.js** | ~400KB | Poor | None | Declining | ❌ Avoid |
|
|
|
|
### Why wagmi + viem?
|
|
|
|
1. **Same team** - wagmi and viem are both from wevm, designed to work together
|
|
2. **Tree-shakeable** - Only import what you use
|
|
3. **TypeScript-first** - Excellent type inference and autocomplete
|
|
4. **Modern React** - Hooks-based, works with React 18+ and Suspense
|
|
5. **WalletConnect v2** - Built-in support via Web3Modal
|
|
6. **No ethers dependency** - Pure viem underneath
|
|
|
|
### Package Configuration
|
|
|
|
```json
|
|
{
|
|
"dependencies": {
|
|
"wagmi": "^2.12.0",
|
|
"viem": "^2.19.0",
|
|
"@tanstack/react-query": "^5.45.0",
|
|
"@web3modal/wagmi": "^5.0.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Supported Wallets (via Web3Modal)
|
|
|
|
- MetaMask (injected)
|
|
- WalletConnect v2 (mobile wallets)
|
|
- Coinbase Wallet
|
|
- Rainbow
|
|
- Safe (via WalletConnect)
|
|
- Hardware wallets (via MetaMask bridge)
|
|
|
|
---
|
|
|
|
## 6. Frontend Architecture
|
|
|
|
### Provider Setup (`src/providers/Web3Provider.tsx`)
|
|
|
|
```typescript
|
|
import { WagmiProvider, createConfig, http } from 'wagmi';
|
|
import { mainnet, optimism, arbitrum, base } from 'wagmi/chains';
|
|
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
|
|
import { createWeb3Modal } from '@web3modal/wagmi/react';
|
|
|
|
// Configure chains
|
|
const chains = [mainnet, optimism, arbitrum, base] as const;
|
|
|
|
// Create wagmi config
|
|
const config = createConfig({
|
|
chains,
|
|
transports: {
|
|
[mainnet.id]: http(),
|
|
[optimism.id]: http(),
|
|
[arbitrum.id]: http(),
|
|
[base.id]: http(),
|
|
},
|
|
});
|
|
|
|
// Create Web3Modal
|
|
const projectId = process.env.WALLETCONNECT_PROJECT_ID!;
|
|
|
|
createWeb3Modal({
|
|
wagmiConfig: config,
|
|
projectId,
|
|
chains,
|
|
themeMode: 'dark',
|
|
});
|
|
|
|
const queryClient = new QueryClient();
|
|
|
|
export function Web3Provider({ children }: { children: React.ReactNode }) {
|
|
return (
|
|
<WagmiProvider config={config}>
|
|
<QueryClientProvider client={queryClient}>
|
|
{children}
|
|
</QueryClientProvider>
|
|
</WagmiProvider>
|
|
);
|
|
}
|
|
```
|
|
|
|
### Wallet Link Hook (`src/hooks/useWalletLink.ts`)
|
|
|
|
```typescript
|
|
import { useAccount, useSignMessage, useDisconnect } from 'wagmi';
|
|
import { useAuth } from '../context/AuthContext';
|
|
import { useState } from 'react';
|
|
|
|
export function useWalletLink() {
|
|
const { address, isConnected } = useAccount();
|
|
const { signMessageAsync } = useSignMessage();
|
|
const { disconnect } = useDisconnect();
|
|
const { session } = useAuth();
|
|
const [isLinking, setIsLinking] = useState(false);
|
|
|
|
const linkWallet = async (label?: string) => {
|
|
if (!address || !session.username) return;
|
|
|
|
setIsLinking(true);
|
|
try {
|
|
// Generate link message
|
|
const timestamp = new Date().toISOString();
|
|
const nonce = crypto.randomUUID();
|
|
const message = generateLinkMessage(
|
|
session.username,
|
|
address,
|
|
timestamp,
|
|
nonce
|
|
);
|
|
|
|
// Request signature from wallet
|
|
const signature = await signMessageAsync({ message });
|
|
|
|
// Send to backend for verification
|
|
const response = await fetch('/api/wallet/link', {
|
|
method: 'POST',
|
|
headers: {
|
|
'Content-Type': 'application/json',
|
|
'X-CryptID-PublicKey': session.publicKey,
|
|
},
|
|
body: JSON.stringify({
|
|
walletAddress: address,
|
|
signature,
|
|
message,
|
|
label,
|
|
}),
|
|
});
|
|
|
|
if (!response.ok) {
|
|
throw new Error('Failed to link wallet');
|
|
}
|
|
|
|
return await response.json();
|
|
} finally {
|
|
setIsLinking(false);
|
|
}
|
|
};
|
|
|
|
return {
|
|
address,
|
|
isConnected,
|
|
isLinking,
|
|
linkWallet,
|
|
disconnect,
|
|
};
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Integration Points
|
|
|
|
### A. AuthContext Extension
|
|
|
|
Add to `Session` type:
|
|
```typescript
|
|
interface Session {
|
|
// ... existing fields
|
|
linkedWallets?: LinkedWalletResponse[];
|
|
primaryWallet?: LinkedWalletResponse;
|
|
}
|
|
```
|
|
|
|
### B. Token-Gated Features
|
|
|
|
```typescript
|
|
// Check if user holds specific tokens
|
|
async function checkTokenGate(
|
|
walletAddress: string,
|
|
requirement: {
|
|
tokenAddress: string;
|
|
minBalance: string;
|
|
chainId: number;
|
|
}
|
|
): Promise<boolean> {
|
|
// Query on-chain balance or use cached value
|
|
}
|
|
```
|
|
|
|
### C. Snapshot Voting (Future)
|
|
|
|
```typescript
|
|
// Vote on Snapshot proposal
|
|
async function voteOnProposal(
|
|
space: string,
|
|
proposal: string,
|
|
choice: number,
|
|
walletAddress: string
|
|
): Promise<void> {
|
|
// Use Snapshot.js SDK with linked wallet
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Security Considerations
|
|
|
|
1. **Signature Replay Prevention**
|
|
- Include timestamp and nonce in message
|
|
- Server validates timestamp is recent (within 5 minutes)
|
|
- Nonces are single-use
|
|
|
|
2. **Address Validation**
|
|
- Always checksum addresses before storing/comparing
|
|
- Validate address format (0x + 40 hex chars)
|
|
|
|
3. **Rate Limiting**
|
|
- Limit link attempts per user (e.g., 5/hour)
|
|
- Limit total wallets per user (e.g., 10)
|
|
|
|
4. **Wallet Verification**
|
|
- EOA: EIP-191 personal_sign
|
|
- Safe: ERC-1271 isValidSignature
|
|
- Hardware: Same as EOA (via MetaMask bridge)
|
|
|
|
---
|
|
|
|
## 9. Next Steps
|
|
|
|
1. **Phase 1 (This Sprint)**
|
|
- [ ] Add migration file
|
|
- [ ] Install wagmi/viem dependencies
|
|
- [ ] Implement link/list/unlink endpoints
|
|
- [ ] Create WalletLinkPanel UI
|
|
- [ ] Add wallet section to settings
|
|
|
|
2. **Phase 2 (Next Sprint)**
|
|
- [ ] Snapshot.js integration
|
|
- [ ] VotingShape for canvas
|
|
- [ ] Token balance caching
|
|
|
|
3. **Phase 3 (Future)**
|
|
- [ ] Safe SDK integration
|
|
- [ ] TransactionBuilderShape
|
|
- [ ] Account Abstraction exploration
|