117 lines
2.6 KiB
Markdown
117 lines
2.6 KiB
Markdown
# 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`
|
|
|