Core Concepts

WalletPair is a two-party channel protocol. One side is the dApp, the other is the wallet. They communicate through a relay that can only route encrypted bytes — it cannot read, forge, or replay application data.

The core protocol is network-agnostic. It handles pairing, encryption, and message transport without any knowledge of blockchain specifics. All chain-specific logic (signing, transactions, account formats) is delegated to sub-protocols — one per blockchain ecosystem.

Pairing

Pairing establishes the encrypted channel:

1. dApp creates a channel. It generates an ephemeral X25519 keypair and a random channel ID, then sends a create message to the relay.
2. dApp displays a QR code. The pairing URI encodes the channel ID, the dApp's public key, and the relay URL.
3. Wallet scans the QR code. It generates its own ephemeral keypair, derives a shared secret via X25519, and sends a join message with a sealed handshake payload.
4. dApp verifies the handshake. It decrypts the sealed join, derives traffic keys, and auto-accepts.
5. Both sides compute a session fingerprint — a 4-digit code derived from the transcript. Users can compare them out-of-band to detect MITM.

The dApp's public key is delivered via the QR code (a physical out-of-band channel the relay cannot intercept). This is the protocol's trust root.

Encryption

All application data is end-to-end encrypted with:

• Key exchange: X25519 ephemeral keypairs (RFC 7748, with all-zero and low-order point rejection)
• Key derivation: HKDF-SHA256 with channel ID salt and domain-separated info
• Symmetric encryption: ChaCha20-Poly1305 AEAD with type-byte AAD (0x01 request, 0x02 response, 0x03 event — prevents cross-type confusion)
• Replay protection: Per-peer monotonic sequence counters with HMAC-SHA256 nonce derivation
• JSON canonicalization: RFC 8785 (JCS) ensures deterministic serialization

Traffic keys are directional: the dApp-to-wallet key differs from the wallet-to-dApp key. Reflection attacks are impossible by design.

Transports

The protocol is transport-agnostic. The SDK ships with two built-in transports:

• WebSocket (WebSocketTransport) — connect through a relay server. Best for cross-device pairing over the internet.
• Bluetooth LE (WebBleCentralTransport) — direct device-to-device connection. No relay needed. Currently Chrome-only via WebBluetooth API.

Both transports use identical session APIs. You can switch transports without changing application code.

Channel Lifecycle

A session progresses through these phases:

1. idle — session created, not yet started
2. pairing — channel created on relay, waiting for wallet
3. connected — handshake complete, encrypted communication active
4. disconnected — transport lost, reconnection possible
5. closed — session ended, keys erased

Multi-Network (CAIP-2)

WalletPair uses CAIP-2 chain identifiers to support any blockchain network. The core protocol doesn't know or care which chain you're on — it just routes encrypted bytes.

Each network ecosystem has its own CAIP-2 prefix:

The wallet declares supported chains in capabilities.chains. A single session can span multiple chains within the same ecosystem.

Sub-Protocols

WalletPair delegates all chain-specific logic to sub-protocols. The core protocol defines pairing, encryption, and message transport. Sub-protocols define:

• Account and address formats
• Transaction signing methods and parameters
• Message signing standards
• Events (accountsChanged, chainChanged, etc.)
• Data encoding rules

Currently, the EVM sub-protocol is fully specified. Sub-protocols for Solana, Sui, and other ecosystems can be authored following the sub-protocol specification guide.

The Relay

The relay is a stateless message router. It holds channels in memory only — no persistent storage, no breach risk. The relay:

• Cannot read encrypted payloads
• Cannot forge peer messages (it lacks traffic keys)
• Cannot replay messages (sequence counters prevent this)
• Can deny service (drop or delay messages)
• Can observe metadata (timing, message sizes, public keys)

The relay is network-agnostic — it routes bytes for EVM, Solana, Bitcoin, or any future sub-protocol without knowing the difference. You can self-host the relay for full control, or use the public relay for development.