Skip to content

WizardConnect

WizardConnect is a protocol and library for connecting dapps to HD cryptocurrency wallets over an encrypted relay. A wallet shows a QR code; the dapp scans it. After that, the dapp can derive any number of the wallet's public keys locally and request transaction signatures — no seed phrase exposure, no trusted intermediary, minimal round-trips.

Design goals

  • Private: all relay messages are end-to-end encrypted (Nostr NIP-17 gift wrap). The relay sees only ciphertext addressed to the recipient's Nostr public key.
  • Reconnection-proof: both sides can disconnect and reconnect independently (mobile app switch, browser refresh, relay drop) and converge back to a live session without user action.
  • Low-latency pubkey delivery: the wallet sends BIP32 xpubs in the handshake; the dapp derives all addresses locally with no further round-trips.
  • Protocol-agnostic paths: the protocol identifies derivation paths by name (receive, change, defi) rather than numeric child indices. The wallet chooses how it actually derives those xpubs.

Package structure

libwizardconnect/
├── packages/core    — @wizardconnect/core
│                      Transport (Nostr relay, key exchange, encryption),
│                      protocol message types and type guards.
│
├── packages/wallet  — @wizardconnect/wallet
│                      WalletConnectionManager, WalletAdapter interface.
│                      Multi-connection management, sign-request queuing.
│
├── packages/dapp    — @wizardconnect/dapp
│                      DappConnectionManager, DappPubkeyStateManager.
│                      Single-session dapp helper, on-demand xpub derivation.
│
└── packages/test-cli — @wizardconnect/test-cli  (private)
                        CLI for manual and exploratory testing.

The dependency graph is strictly one-directional:

test-cli → wallet, dapp → core

core has no knowledge of wallets or dapps; wallet and dapp have no knowledge of each other.

License

WizardConnect is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0-or-later).

You may use, link against, and distribute WizardConnect in both open-source and proprietary applications. Modifications to the library itself must be released under the same license.

Every source file must carry the copyright header:

// Copyright (C) 2026 Whiterun LLC,
// This software is licensed under the GNU Lesser General Public License (LGPL), version 3.0 or later.
// A copy of the license can be found in the LICENSE file or at https://www.gnu.org/licenses/lgpl-3.0.html

A linter enforces this: npm run lint:copyright.

Contributing

All contributors must sign a Contributor License Agreement (CLA) before their contributions can be accepted. The CLA assigns copyright to Whiterun LLC so that the project can be relicensed in the future if needed. You will be prompted to sign the CLA when you open your first pull request.

Quick navigation

Topic File
Protocol messages and handshake protocol.md
Connection URI and key exchange connection-uri.md
Relay transport and encryption transport.md
Wallet integration guide wallet.md
Dapp integration guide dapp.md
xpub delivery and pubkey derivation pubkey-derivation.md