WizardConnect/docs/wallet.md

Wallet integration

Wallet integration uses @wizardconnect/wallet. The wallet implements the WalletAdapter interface and hands it to WalletConnectionManager, which handles everything else.

WalletAdapter

interface WalletAdapter {
  walletName: string;   // shown in the dapp's connection UI
  walletIcon: string;   // URL or data-URI, shown in the dapp's connection UI

  /**
   * Return the relay identity private key for this session.
   * May be ephemeral (random per session) or stable (HD-derived) — both work.
   * The dapp learns the wallet's public key from the wallet_ready message,
   * so stability across restarts is not required.
   */
  getRelayPrivateKey(): Uint8Array;

  /** Returns the compressed 33-byte secp256k1 public key at path/index. */
  getPublicKey(path: DerivationPath, index: bigint): Uint8Array;

  /** Returns the BIP32 base58-encoded xpub for the given derivation path.
   *  The dapp derives all addresses from this — no further pubkey requests needed. */
  getXpub(path: DerivationPath): string;

  /** Sign the transaction. May show approval UI to the user.
   *  Called when the wallet has received and validated a sign_transaction_request. */
  signTransaction(request: SignTransactionRequest): Promise<SignTransactionResult>;

  /** Optional: additional paths to include in the session (e.g. stealth_scan). */
  getAdditionalPaths?(): PathXpub[];

  /** Optional: extension data for the session handshake. */
  getExtensions?(): Record<string, unknown>;

  /** Optional: sign a plain message to prove key control. Implementing this is what
   *  advertises the `sign_message` extension to dapps. See § signMessage below. */
  signMessage?(request: SignMessageRequest): Promise<SignMessageResult>;

  /** Optional: key-selection modes signMessage supports. Defaults to [MODE_DAPP_PATH]. */
  signMessageModes?(): MessageSigningMode[];
}

DerivationPath

enum DerivationPath {
  Receive  = 0,  // m/44'/145'/0'/0  — external (receive) addresses
  Change   = 1,  // m/44'/145'/0'/1  — internal (change) addresses
  Cauldron = 7,  // m/44'/145'/0'/7  — DeFi/Cauldron addresses
}

The numeric values are wallet-internal; the protocol uses names (receive, change, defi). childIndexOfPath(path) and pathOfChildIndex(index) convert between them.

SignTransactionResult

interface SignTransactionResult {
  signedTransactionHex: string;
}

SignMessageResult

interface SignMessageResult {
  signature: string;              // base64 — build it with signBitcoinMessage()
  addressPrefix?: CashAddrPrefix; // default "bitcoincash"; set on testnet
  path?: PathName;                // which key was used, when the wallet can say
  addressIndex?: number;
}

Deliberately just the signature. The public key and address are not asked for, because both are recoverable from the signature and WalletConnectionManager derives them that way — so the three values in the response can never disagree, and an adapter cannot accidentally claim a proof about an address it did not prove.

WalletConnectionManager

class WalletConnectionManager extends EventEmitter {
  constructor(adapter: WalletAdapter)

  // Connect to a dapp. Returns a stable connection ID.
  // If a connection for this URI already exists, returns the existing ID.
  connect(uri: string): string

  // Tear down a specific connection, sending a UserDisconnect courtesy message.
  disconnect(connectionId: string): void

  // Tear down all connections.
  disconnectAll(): void

  // Snapshot of all connections for UI rendering.
  getConnections(): Record<string, RelayConnectionState>

  // Send the signed transaction back to the dapp.
  sendSignResponse(connectionId: string, sequence: number, signedTx: string): Promise<void>

  // Send an error back to the dapp (user rejected, signing failed, etc.)
  sendSignError(connectionId: string, sequence: number, errorMessage: string): Promise<void>

  // Send a message signature back to the dapp. Derives the public key and address
  // from the signature; throws if it does not match the requested message and key.
  sendSignMessageResponse(connectionId: string, sequence: number, result: SignMessageResult): Promise<void>

  // Refuse a message-signing request (user rejected, unsupported, etc.)
  sendSignMessageError(connectionId: string, sequence: number, errorMessage: string): Promise<void>

  // Events
  on("connectionStatusChanged", (id: string, status: RelayStatus) => void)
  on("pendingSignRequest", (req: PendingSignRequest) => void)
  on("pendingSignMessageRequest", (req: PendingSignMessageRequest) => void)
  on("connectionsChanged", () => void)
  on("remoteDisconnect", (connectionId: string, reason: DisconnectReason, message: string | undefined) => void)
  on("message", (connectionId: string, message: ProtocolMessage) => void)  // extension messages
}

RelayConnectionState

interface RelayConnectionState {
  id: string;
  uri: string;
  status: RelayStatus;   // { status: "connected" | "reconnecting" | "disconnected" }
  label: string;         // dapp name once known, otherwise "Connecting..."
  dappName: string | null;
  dappIcon: string | null;
  connectedAt: number;   // Unix ms
}

PendingSignRequest

interface PendingSignRequest {
  connectionId: string;
  request: SignTransactionRequest;
}

Connection lifecycle

connect()

1. A unique connectionId is generated.
2. initiateWalletRelay(statusCallback, { uri, walletPrivateKey }) is called.
3. The relay decodes the URI, extracts the dapp's public key and secret, and connects.
4. On the first "connected" status, onConnected() is called.

onConnected()

1. walletReadySentThisCycle is reset to false.
2. A notification processor interval is started (1 second, for retry on send errors).
3. The wallet polls until client.isKeyExchangeComplete() (key exchange with dapp done).
4. pushWalletReady() is called.

pushWalletReady()

Sends wallet_ready with:

• supported_protocols: ["hdwalletv1"]
• wallet_name, wallet_icon from the adapter.
• session["hdwalletv1"]: one { name, xpub } per DerivationPath (receive/change/defi), plus any additional paths from adapter.getAdditionalPaths() and extension data from adapter.getExtensions(). See extensions.md.
• dapp_discovered: whether the dapp was seen in this runtime session.

The message is pushed to a per-connection notificationQueue and flushed immediately. Retry is handled by the interval processor — if relay() throws (e.g. network drop), the message stays in the queue and is retried on the next tick.

Receiving dapp_ready

wallet_discovered=false  → reset walletReadySentThisCycle, call pushWalletReady() again
wallet_discovered=true   → set dappDiscovered=true, no further action

dapp_name and dapp_icon are captured from the first dapp_ready that includes them.

Receiving disconnect

When a disconnect message arrives from the dapp:

1. The remoteDisconnect event is emitted with (connectionId, reason, message).
2. The connection is cleaned up without sending a reply disconnect.

Receiving sign_transaction_request

The wallet emits pendingSignRequest with the connectionId and the full request. The host application is responsible for:

1. Queueing or displaying the request.
2. Getting user approval.
3. Calling sendSignResponse(connectionId, sequence, signedTxHex) or sendSignError(connectionId, sequence, errorMessage).

The wallet library does not auto-sign or auto-reject anything.

Deduplication: The dapp re-sends pending sign requests when the wallet reconnects (see protocol docs). To prevent duplicate approval dialogs, WalletConnectionManager tracks in-flight sequences and silently drops requests whose sequence has already been emitted. The guard is cleared when a response is sent (sendSignResponse / sendSignError) or a sign_cancel is received.

SIGHASH enforcement: The wallet MUST sign every input with SIGHASH_ALL | SIGHASH_FORKID | SIGHASH_UTXOS. See the SIGHASH requirement section in the protocol docs for the security rationale. Because the dapp specifies inputPaths, the wallet trusts the dapp's key selection — SIGHASH_ALL is what makes this safe (a wrong-key signature is simply invalid and cannot be repurposed).

signMessage

Optional. Implementing it advertises the sign_message extension; omitting it leaves the wallet working exactly as before, and a dapp that asks anyway gets an explicit error rather than silence.

import { signBitcoinMessage, MODE_DAPP_PATH, MODE_WALLET_CHOICE } from "@wizardconnect/core";

signMessageModes: () => [MODE_DAPP_PATH, MODE_WALLET_CHOICE],

async signMessage(request) {
  const index = request.addressIndex ?? 0;
  const privateKey = derivePrivateKey(request.path ?? "receive", index);
  return {
    signature: signBitcoinMessage(request.message, privateKey),
    path: request.path ?? "receive",
    addressIndex: index,
  };
},

Then approve it like a transaction:

manager.on("pendingSignMessageRequest", async ({ connectionId, request }) => {
  const approved = await showMessageSigningDialog(request);   // your UI
  if (!approved) {
    await manager.sendSignMessageError(connectionId, request.sequence, "User rejected");
    return;
  }
  const result = await adapter.signMessage!(request);
  await manager.sendSignMessageResponse(connectionId, request.sequence, result);
});

Requirements

Sign the message verbatim. UTF-8, no trimming, no Unicode normalisation. The signature must verify against exactly the text the dapp displayed; re-encoding it produces a signature that verifies against nothing.

Use signBitcoinMessage(). The magic string and both compactSize length prefixes are what third-party verifiers check. This repository tests them against a real Electron Cash install (npm run test:compat --workspace @wizardconnect/core) and against committed vectors Electron Cash generated; a hand-rolled reimplementation in a wallet gets neither.

Choose deterministically under wallet_choice. A dapp treats the returned address as a durable identity. If the wallet picks a different key per connection, a returning user is unrecognisable and login breaks. Only advertise MODE_WALLET_CHOICE if the choice is stable across restarts. Consider a dedicated identity key rather than receive/0, so proving identity does not link it to the user's main address history.

Echo the path used. It is how a dapp learns which key answered under wallet_choice, and it lets sendSignMessageResponse check the signature against the key that should have produced it.

Display requirements

sendSignMessageResponse verifies the cryptography. It cannot verify that the user understood what they signed, which is the wallet's job:

• Show request.message in full, verbatim. Do not truncate it. The user is signing every byte, including trailing whitespace and newlines.
• request.userPrompt is dapp-supplied and unsigned. Render it as clearly subordinate to the message and attribute it to the dapp. Presented as equal, it lets a dapp caption hostile text reassuringly.
• Flag adversarial text. Bidirectional overrides, zero-width characters, control characters and very long messages can all make signed text display as something other than what it is.
• Message signing is safer to approve than a dummy transaction — the magic prefix guarantees the digest can never coincide with a transaction sighash, so no message signature can ever authorise a spend. That is a reason to prefer it over "sign this unspendable transaction" patterns, not a reason to show the user less.

---

Minimal example

import { WalletConnectionManager } from "@wizardconnect/wallet";
import type { WalletAdapter, DerivationPath } from "@wizardconnect/wallet";

class MyAdapter implements WalletAdapter {
  walletName = "My Wallet";
  walletIcon = "";

  getRelayPrivateKey() { return crypto.getRandomValues(new Uint8Array(32)); }
  getPublicKey(path: DerivationPath, index: bigint) { /* ... */ }
  getXpub(path: DerivationPath) { /* ... */ }

  async signTransaction(request) {
    // Show approval UI, sign with SIGHASH_ALL | SIGHASH_FORKID | SIGHASH_UTXOS, return hex.
    // See protocol.md "SIGHASH requirement" — other sighash flags MUST be rejected.
    return { signedTransactionHex: "..." };
  }
}

const manager = new WalletConnectionManager(new MyAdapter());

// When user scans a QR code:
const connId = manager.connect("wiz://?p=...&s=...");

// When a sign request arrives:
manager.on("pendingSignRequest", async ({ connectionId, request }) => {
  try {
    const result = await showApprovalUI(request);
    await manager.sendSignResponse(connectionId, request.sequence, result.signedTransactionHex);
  } catch {
    await manager.sendSignError(connectionId, request.sequence, "User rejected");
  }
});

// When the dapp disconnects:
manager.on("remoteDisconnect", (id, reason, message) => {
  console.log(`Dapp disconnected: ${reason}`, message);
  store.dispatch(setConnections(manager.getConnections()));
});

// For Redux / UI updates:
manager.on("connectionsChanged", () => {
  store.dispatch(setConnections(manager.getConnections()));
});