WizardConnect/docs/index.md

# 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/react   — @wizardconnect/react
│                      React components and hooks for dapp integration.
│                      QR dialog, useWizardConnect hook.
│
└── 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](https://www.gnu.org/licenses/lgpl-3.0.html) (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:

```ts
// 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](protocol.md) |
| Protocol extensions | [extensions.md](extensions.md) |
| Connection URI and key exchange | [connection-uri.md](connection-uri.md) |
| Relay transport and encryption | [transport.md](transport.md) |
| Wallet integration guide | [wallet.md](wallet.md) |
| Dapp integration guide | [dapp.md](dapp.md) |
| React components and hooks | [react.md](react.md) |
| xpub delivery and pubkey derivation | [pubkey-derivation.md](pubkey-derivation.md) |
| xpub sharing: why it's safe | [xpub-sharing.md](xpub-sharing.md) |