explorer-monorepo/docs/specs/actions/wallet-connectivity.md

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