b9a0e16893
The sign_message extension leaves replay to the dapp, because a signature proves key control over an exact string and carries no freshness or audience. The previous commit said so in three places in the docs. That is exactly the failure this repository should not ship: a login built on a bare signMessage call works in every manual test and is a password that never expires, so documenting the requirement mostly relocates the blame. So the two failures that matter are structural here rather than advisory: verifyLoginChallenge cannot be called without `domain` and `consumeNonce`. There is no overload that omits them. Verifying a login without single-use enforcement and audience binding is not something this API can express — if you want plain signature verification, verifyMessageSignatureForAddress is right there and is honestly named. createLoginChallenge refuses a nonce under MIN_NONCE_LENGTH and refuses a line break in any field, so neither a guessable nonce nor an injected `Nonce:` line can reach a signed message. Check order is deliberate: parse, domain, expiry, signature, THEN consume the nonce. Consuming earlier would let anyone who sniffs a nonce burn it with a garbage signature before the real user finishes signing; there is a test asserting the nonce survives a bad signature and the genuine login still completes. consumeNonce is a caller-supplied callback rather than a store this module owns, because single-use enforcement is a property of the caller's database — two replays arriving together both reach that point and only one may be told true. The docstring says it must be atomic. createInMemoryNonceStore exists for development and says plainly that it is per-process, so two servers behind a load balancer would each honour the same signature once. parseLoginChallenge is strict: unknown fields, duplicate fields, out-of-order fields and stray lines are rejected rather than skipped, so exactly one byte sequence parses to a given challenge. A lenient parser is where field injection lives. Address is optional in the message because under wallet_choice the dapp does not yet know which key will answer. When present the proof is self-describing — a third party reading the message alone sees which address was claimed — and verification then requires the recovered address to match it. NOT SIWE. The layout is deliberately similar to Sign-In With Ethereum so it reads familiarly, but it does not claim EIP-4361 or CAIP-122 compatibility: there is no agreed SIWX profile for Bitcoin Cash to conform to. If one lands it belongs beside this as a second format, not as a silent change to this one. Also adds addressesEqual() to message-signing, which compares decoded public key hashes so prefixed CashAddr, bare CashAddr, the token-aware form and legacy base58 all compare equal for the same key. 27 tests, mostly about what must be refused: the replay, the wrong site, the stale and future-dated challenge, four field-injection attempts, the nonce-burning attack, the wrong key, and a cross-encoding address match. test-cli now builds its challenge with these helpers rather than hand-rolled text, since that is what integrators copy, and verifies the response twice — once as a third party would and once as the server would, printing proof that replaying the identical signature is rejected. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|---|---|---|
| contrib | ||
| docs | ||
| linters | ||
| packages | ||
| .gitignore | ||
| .gitlab-ci.yml | ||
| CLAUDE.md | ||
| eslint.config.cjs | ||
| LICENSE.txt | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| tsconfig.base.json | ||
| zensical.toml | ||
WizardConnect
A dapp-to-wallet protocol built for Bitcoin Cash.
WizardConnect lets a dapp scan a wallet's QR code and immediately start deriving addresses, constructing transactions, and requesting signatures — no seed phrases, no trusted servers, no round trips.
Why not WalletConnect?
WalletConnect was built for Ethereum, where a wallet is a single address. BCH wallets are HD wallets with thousands of addresses for privacy. Forcing an Ethereum protocol onto BCH means:
- One address per session. WalletConnect gives the dapp a single address. That breaks the HD wallet model and destroys the privacy that multiple addresses provide.
- Unreliable on BCH. BCH support in WalletConnect is a second-class citizen — a bridge on top of an Ethereum-native protocol. Connections drop, sessions fail to restore, and there's no community maintaining it for BCH.
WizardConnect replaces all of this with a protocol designed from the ground up for UTXO chains and HD wallets.
How it works
Wallet Relay Dapp
│ │ │
│ ◄───── QR code scan ────── │ ◄──── shows QR (wiz://...) │
│ │ │
│ wallet_ready ──────────────►│──────────────────────────────►│
│ (xpubs + key exchange) │ │
│ │ derive addresses │
│ │ locally from xpubs │
│ │ (no more round trips)│
│ │ │
│ ◄──────────────────────────│◄──── sign_transaction_request │
│ user approves on wallet │ │
│ sign_transaction_response──►│──────────────────────────────►│
│ │ broadcast │
- The dapp generates a
wiz://URI and displays it as a QR code. - The wallet scans the QR, connects to the relay, and sends its xpubs.
- The dapp derives all addresses locally — no further contact with the wallet needed for address generation.
- When the dapp needs a signature, it sends a request. The user approves on the wallet. The signed transaction comes back.
All communication is end-to-end encrypted via Nostr NIP-17 gift wrap. The relay sees only ciphertext.
Key features
Full HD wallet support. The wallet shares BIP32 xpubs for specific derivation paths (receive, change, DeFi). The dapp derives unlimited addresses locally. No more single-address sessions.
Zero round trips for addresses. After the initial handshake, the dapp never needs to ask the wallet for a public key. It derives them on demand from the xpubs, in microseconds.
Decentralized transport. Built on Nostr — an open protocol with hundreds of public relays. No proprietary bridge server. Users can point to any relay for additional privacy or self-host their own.
Reconnection-proof. Both sides can disconnect and reconnect independently (app switch, browser refresh, network drop) and converge back to a live session without user action.
Extensible. The protocol negotiates capabilities during the handshake.
hdwalletv1 is the first protocol; future protocols (multisig, post-quantum,
token-aware) can be added without breaking existing connections.
Open source (LGPL-3.0). Free to use in commercial and non-commercial applications. Modifications to the library itself must be shared back.
Packages
npm install @wizardconnect/core # transport, protocol types, key exchange
npm install @wizardconnect/dapp # dapp-side session + address derivation
npm install @wizardconnect/wallet # wallet-side connection + signing
| Package | Description |
|---|---|
@wizardconnect/core |
Relay client, NIP-17 encryption, URI encoding, protocol message types |
@wizardconnect/dapp |
DappConnectionManager, DappPubkeyStateManager — session management and on-demand pubkey derivation |
@wizardconnect/wallet |
WalletConnectionManager, WalletAdapter interface — multi-connection management and sign request dispatch |
Quick start: dapp
import { initiateDappRelay } from "@wizardconnect/core";
import { DappConnectionManager } from "@wizardconnect/dapp";
const dapp = new DappConnectionManager("My Dapp", "https://example.com/icon.png");
const relay = initiateDappRelay(
(payload) => dapp.updateConnection(payload.client, payload.status),
{ explicitRelayUrls: ["wss://relay.riften.net:443"] },
);
// Display relay.uri as a QR code for the wallet to scan
dapp.on("walletready", () => {
// Connected! Derive addresses locally:
const receivePubkey = dapp.getPubkey(0, 0n); // receive path, index 0
const changePubkey = dapp.getPubkey(1, 0n); // change path, index 0
});
Quick start: wallet
import { WalletConnectionManager } from "@wizardconnect/wallet";
const manager = new WalletConnectionManager(myWalletAdapter);
// When the user scans a dapp's QR code:
const connectionId = manager.connect("wiz://?p=...&s=...");
// When a sign request arrives, show it to the user:
manager.on("pendingSignRequest", async ({ connectionId, request }) => {
const approved = await showApprovalUI(request);
if (approved) {
await manager.sendSignResponse(connectionId, request.sequence, signedTxHex);
} else {
await manager.sendSignError(connectionId, request.sequence, "User rejected");
}
});
See wallet integration guide for WalletAdapter implementation details.
Privacy model
WizardConnect shares xpubs at the chain level, not the account level. A dapp receiving the receive xpub can derive receive addresses but cannot derive change addresses or any other internal wallet activity. This is the same level of key material used by watch-only wallets.
For wallets that want stronger isolation, the protocol supports per-session xpub rotation — the dapp sees only the xpub node, never the derivation path.
See xpub sharing: why it's safe for a full discussion.
Security
- Private keys never leave the wallet. Signing happens on-device.
- All relay traffic is end-to-end encrypted (NIP-17 gift wrap). The relay cannot read messages.
- Key exchange includes an 8-byte shared secret (embedded in the QR code) for MITM prevention.
- No trusted intermediary. The relay is a dumb message broker — compromise it and you get ciphertext.
Documentation
| Topic | Link |
|---|---|
| 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 derivation | pubkey-derivation.md |
| xpub sharing: why it's safe | xpub-sharing.md |
Building
npm install
npm run build # builds all packages in dependency order
npm run test # unit tests (fast, no network)
Integration tests hit a live relay:
cd packages/wallet && npm run test:integration
License
LGPL-3.0-or-later. Free for commercial and non-commercial use. Modifications to the library must be released under the same license.
Built by Riften Labs.