# Wallet Connectivity Specification

## Overview

This document specifies wallet connectivity options including WalletConnect v2, hardware wallet support, and embedded wallet architecture.

## WalletConnect v2 Integration

### Implementation

**Library**: `@walletconnect/web3wallet` or `@web3modal/wagmi`

**Features**:
- Multi-wallet support
- Session management
- Chain switching
- Transaction signing
- Message signing

### Connection Flow

1. User initiates connection
2. QR code displayed or deep link generated
3. User approves in wallet app
4. Session established
5. Ready for transactions

### Session Management

**Storage**: Persist sessions in localStorage
**Expiration**: Handle session expiration gracefully
**Reconnection**: Auto-reconnect on page reload

## Hardware Wallet Support

### Supported Wallets

**Ledger**: Via Ledger Live or browser extension
**Trezor**: Via Trezor Connect
**Other**: Via Web3 provider standard

### Integration

**Method**: Use Web3 provider interface
**Security**: Never expose private keys
**UX**: Clear instructions for hardware wallet usage

## Embedded Wallet

### Architecture

**Options**:
1. **Non-Custodial**: User controls keys (Web3Auth, Magic)
2. **Custodial**: Platform manages keys (Fireblocks, Circle)

**Recommendation**: Start with non-custodial, add custodial for banking features

### Non-Custodial Embedded Wallet

**Technology**: Web3Auth or similar
**Features**:
- Social login (Google, Twitter, etc.)
- Passwordless authentication
- Key management via MPC or smart contract wallets
- Recovery options

### Custodial Embedded Wallet

**Use Cases**: Banking features requiring custody
**Requirements**:
- Regulatory compliance
- Secure key storage (HSM)
- Insurance
- Audit trails

**Policy Gating**: Only enable for users meeting compliance requirements

## Key Management

### Non-Custodial Keys

**Storage**: User's device or MPC network
**Recovery**: Social recovery or seed phrase
**Security**: Never transmitted to server

### Custodial Keys

**Storage**: Hardware Security Module (HSM)
**Access**: Multi-signature approval
**Audit**: All key operations logged

## API Integration

### Wallet Connection

**Methods**:
- `connect()`: Initiate connection
- `disconnect()`: Close connection
- `getAccount()`: Get connected account
- `switchChain()`: Switch to different chain

### Transaction Signing

**Flow**:
1. Build transaction
2. Request user approval
3. Sign transaction
4. Broadcast transaction
5. Monitor confirmation

## References

- Swap Engine: See `swap-engine.md`
- Bridge Engine: See `bridge-engine.md`
- Security: See `../security/security-architecture.md`