WizardConnect/docs/extensions.md

# Extensions

This document covers `hdwalletv1` protocol-level extensions — optional capabilities that extend
the application protocol (extra path names, custom message actions, per-wallet features). For
transport-level capabilities that apply below the application protocol regardless of which
protocol is in use (chunking, future: compression), see
[transport.md § Transport-level extensions](transport.md#transport-level-extensions).

The hdwalletv1 protocol supports optional extensions that let wallets and dapps negotiate
additional capabilities beyond the core sign-transaction flow. Extensions are backward-compatible:
existing wallets and dapps that don't know about extensions continue to work unchanged.

## How extensions work

Extensions use three mechanisms, all of which are optional and additive:

### 1. Session extensions field

Wallets advertise supported extensions in the `wallet_ready` handshake via an `extensions` field
on the `Hdwalletv1Session` object:

```typescript
interface Hdwalletv1Session {
  paths: PathXpub[];
  extensions?: Record<string, unknown>;
}
```

Each key in `extensions` is an extension name. Its **presence** indicates the wallet supports that
extension. The value carries extension-specific handshake data (derivation paths to the hardened
gate where the wallet exports xpubs), or `{}` if no data is needed.

Example:
```json
{
  "paths": [
    { "name": "receive",       "xpub": "xpub6..." },
    { "name": "change",        "xpub": "xpub6..." },
    { "name": "defi",          "xpub": "xpub6..." },
    { "name": "stealth_spend", "xpub": "xpub6..." },
    { "name": "stealth_scan",  "xpub": "xpub6..." },
    { "name": "rpa_spend",     "xpub": "xpub6..." },
    { "name": "rpa_scan",      "xpub": "xpub6..." }
  ],
  "extensions": {
    "bch_stealth_bip352": {
      "spend_path": "m/352'/145'/0'/0'",
      "scan_path":  "m/352'/145'/0'/1'"
    },
    "rpa_bip47": {
      "spend_path": "m/47'/145'/0'/0'",
      "scan_path":  "m/47'/145'/0'/1'"
    },
    "decrypt": { "public_key": "02abc...", "scheme": "ecies" }
  }
}
```

### 2. Additional path names

`PathName` is an open string type. Wallets may include paths beyond the well-known
`receive`/`change`/`defi` set. Extension-defined paths are carried in the standard `paths` array:

```json
{
  "paths": [
    { "name": "receive",       "xpub": "xpub6..." },
    { "name": "change",        "xpub": "xpub6..." },
    { "name": "stealth_spend", "xpub": "xpub6..." },
    { "name": "stealth_scan",  "xpub": "xpub6..." },
    { "name": "rpa_spend",     "xpub": "xpub6..." },
    { "name": "rpa_scan",      "xpub": "xpub6..." }
  ],
  "extensions": {
    "bch_stealth_bip352": {
      "spend_path": "m/352'/145'/0'/0'",
      "scan_path":  "m/352'/145'/0'/1'"
    },
    "rpa_bip47": {
      "spend_path": "m/47'/145'/0'/0'",
      "scan_path":  "m/47'/145'/0'/1'"
    }
  }
}
```

Dapps should ignore path names they do not recognize. The standard pubkey derivation logic
(`DappPubkeyStateManager`) automatically skips unknown paths.

### 3. Custom message actions

Extensions may define new message action strings beyond the well-known set. Custom messages follow
the standard `ProtocolMessage` shape (`action` + `time`) and use the existing relay transport.

Convention for request/response operations:

```typescript
// Request (dapp → wallet):
{ action: "<operation>_request", sequence: number, time: number, ...params }

// Response (wallet → dapp):
{ action: "<operation>_response", sequence: number, time: number, ...result }
```

The `sequence` field ties responses to requests, matching the pattern used by
`sign_transaction_request`/`sign_transaction_response`.

**Wallet side**: custom messages are emitted via the `"message"` event on
`WalletConnectionManager`:

```typescript
manager.on("message", (connectionId, msg) => {
  if (msg.action === "decrypt_request") {
    // handle decrypt request
  }
});
```

**Dapp side**: all messages (including custom ones) are emitted via the `"messagereceived"` event
on `DappConnectionManager`:

```typescript
manager.on("messagereceived", (msg) => {
  if (msg.action === "decrypt_response") {
    // handle decrypt response
  }
});
```

## Implementing an extension (wallet side)

Wallets advertise extensions by implementing optional methods on `WalletAdapter`:

```typescript
interface WalletAdapter {
  // ... core methods ...

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

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

Example:
```typescript
const adapter: WalletAdapter = {
  // ... core implementation ...

  getAdditionalPaths() {
    return [
      { name: "stealth_spend", xpub: deriveXpub("m/352'/145'/0'/0'") },
      { name: "stealth_scan",  xpub: deriveXpub("m/352'/145'/0'/1'") },
      { name: "rpa_spend",     xpub: deriveXpub("m/47'/145'/0'/0'") },
      { name: "rpa_scan",      xpub: deriveXpub("m/47'/145'/0'/1'") },
    ];
  },

  getExtensions() {
    return {
      "bch_stealth_bip352": {
        "spend_path": "m/352'/145'/0'/0'",
        "scan_path":  "m/352'/145'/0'/1'",
      },
      "rpa_bip47": {
        "spend_path": "m/47'/145'/0'/0'",
        "scan_path":  "m/47'/145'/0'/1'",
      },
    };
  },
};
```

Wallets that don't implement these methods produce the same session as before (receive/change/defi
paths only, no extensions field).

## Discovering extensions (dapp side)

Dapps check for extension support after receiving `wallet_ready`:

```typescript
manager.on("walletready", (msg) => {
  const session = msg.session["hdwalletv1"] as Hdwalletv1Session;

  if (session.extensions?.bch_stealth_bip352) {
    const scanPath  = session.paths.find(p => p.name === "stealth_scan");
    const spendPath = session.paths.find(p => p.name === "stealth_spend");
    // enable stealth address features
  } else {
    // show: "Stealth payments require a wallet that supports BCH Stealth (BIP352)"
  }

  if (session.extensions?.rpa_bip47) {
    const rpaSpend = session.paths.find(p => p.name === "rpa_spend");
    const rpaScan  = session.paths.find(p => p.name === "rpa_scan");
    // enable RPA features
  }
});
```

Dapps should degrade gracefully when an extension is absent. If a feature requires an extension the
wallet doesn't support, inform the user rather than failing silently.

## Known extensions

| Extension name | Path names | Hardened gate paths | Purpose | Status |
|---------------|-----------|---------------------|---------|--------|
| `bch_stealth_bip352` | `stealth_spend`, `stealth_scan` | `m/352'/145'/0'/0'`, `m/352'/145'/0'/1'` | BCH stealth addresses (BIP352 structure). Wallet exports xpubs at hardened gates; dapp derives `/0` child locally. | Standard — [BCR post](https://bitcoincashresearch.org/t/ecdh-stealth-addresses-on-bitcoin-cash-implementation-code/1773/5) |
| `rpa_bip47` | `rpa_spend`, `rpa_scan` | `m/47'/145'/0'/0'`, `m/47'/145'/0'/1'` | BIP47 reusable payment addresses. Wallet exports xpubs at hardened gates; dapp derives `/0` child locally. | Standard — [BCR post](https://bitcoincashresearch.org/t/ecdh-stealth-addresses-on-bitcoin-cash-implementation-code/1773/5) |
| `decrypt` | — | — | Dapp-side encrypted storage. Wallet provides a public key; dapp encrypts data for storage and sends `decrypt_request` messages when the data is needed. | Proposed |
| `sign_message` | — | — | Sign a plain message to prove key control, without a transaction. Portable "Bitcoin Signed Message" signature — verifiable in Electron Cash, Electrum and `bitcoin-cli verifymessage`. | Implemented — see below |

See the discussions and specifications for each extension as they are formalized.

---

## First-party extensions

`sign_message` does not follow § 3 above. Its actions live in the `RelayMsgAction` enum and are
handled by `WalletConnectionManager` and `DappConnectionManager` directly, rather than riding the
generic `message` / `messagereceived` events.

That is a **new pattern**, not an existing convention — the only prior enum-plus-advertisement
capability is `chunk`, which is transport-level and so lives outside the hdwalletv1 extension system
entirely. The distinction is about who implements the extension:

- **Third-party extensions** define their own action strings and are handled by the host app through
  the generic message events (§ 3). This library never needs to know they exist.
- **First-party extensions** ship in this library with manager support, verification helpers and
  tests. Routing those through the generic events would force every consumer to hand-roll the
  request/response plumbing for a capability the library already implements.

Support is still advertised through the same `session.extensions` mechanism (§ 1), so discovery is
uniform and a wallet that does not implement the capability is unaffected.

---

## `sign_message`

Advertised under the `sign_message` key:

```json
{
  "extensions": {
    "sign_message": {
      "schemes": ["bitcoin_signed_message"],
      "modes": ["dapp_path", "wallet_choice"]
    }
  }
}
```

`schemes` and `modes` are advertised separately because they are independent capabilities. A wallet
may be able to sign with a dapp-named path but have no notion of a stable identity key, and a dapp
that checked only for the extension's presence would discover that at request time — after the user
had already clicked a login button.

| Mode | Meaning |
|------|---------|
| `dapp_path` | The dapp sends `path` + `addressIndex`. Requires the dapp to hold that path's xpub. |
| `wallet_choice` | The dapp sends neither; the wallet picks the key and returns its address. No xpub needed. |

An older wallet that advertised `"sign_message": {}` before these fields existed is read as
`{schemes: ["bitcoin_signed_message"], modes: ["dapp_path"]}` — the original behaviour.

### Wallet side

Implement `WalletAdapter.signMessage` — that alone is what advertises the extension, so the handshake
cannot claim support an adapter does not have. Declare `signMessageModes()` if the wallet supports
`wallet_choice`. An adapter that returns its own `sign_message` entry from `getExtensions()` wins;
the automatic advertisement never overwrites an explicit one.

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

const adapter: WalletAdapter = {
  // ... core implementation ...

  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,
    };
  },
};
```

Use `signBitcoinMessage()` rather than assembling the construction. The magic string and both
compactSize length prefixes are what third-party verifiers check, and they are covered by this
repository's conformance tests against a real Electron Cash install; a reimplementation is not.

### Dapp side

```typescript
import { MODE_WALLET_CHOICE } from "@wizardconnect/core";

if (!manager.walletSupportsSignMessage(MODE_WALLET_CHOICE)) {
  // Hide the login button rather than offering one that fails.
}

const result = await manager.signMessage({
  // The nonce MUST be single-use and server-issued — see dapp.md § Replay.
  message: `${location.host} wants you to sign in\nnonce=${singleUseNonce}`,
  userPrompt: "Sign in",
});
// result is already verified; result.address is the proven identity.
```

See [protocol.md § sign_message](protocol.md#sign_message) for the wire format,
[wallet.md](wallet.md#signmessage) for the adapter contract and display requirements, and
[dapp.md](dapp.md#signmessage) for what is verified and why replay is the dapp's job.