Wallet Integration

A wallet implements the pairing URI parser, relay client, encryption layer, and EIP-1193 request handler directly. There is no WalletPair SDK or capability negotiation message in the protocol.

Prepare and verify the pairing

  1. Require exactly one each of ch, pubkey, relay, name, url, and icon.
  2. Reject invalid percent encoding, non-canonical channel IDs or base64url keys, and invalid metadata.
  3. Calculate the dApp pairing code using the decoded URI values and show it to the user.
  4. Only after the user confirms the matching code, generate a fresh X25519 key pair and join the relay.
  5. Pin the public key from the QR URI; it is the wallet's authenticated dApp identity.

Validate every request

Decrypt only strictly increasing frames under the dApp-to-wallet key. Validate the EIP-1193 method, parameters, account authorization, selected chain, and all transaction or typed-data details before showing approval UI. Do not trust dApp-provided summaries.

Respond with EIP-1193 errors

json 
{
  "id": "req-1",
  "error": {
    "code": 4001,
    "message": "User rejected the request"
  }
}

Use 4001 for a user rejection, 4100 for unauthorized access, 4200 for unsupported methods, and 4900/4901 for disconnection. Malformed requests use -32600; invalid parameters use -32602.

Preserve secrets and counters

Erase ephemeral private, shared-secret, and root-key material as soon as the key schedule permits. Persist traffic-key and counter state atomically before reuse across a reconnect. Otherwise abandon the channel and require a new QR pairing.