key-derivation

name	key-derivation
description	This skill should be used when the user asks to "derive keys", "use Type42", "use BRC-42", "derive child keys", "use BIP32", "use HD keys", "create mnemonic", "convert mnemonic to key", "derive BAP identity keys", "derive encryption keys", or mentions key derivation, hierarchical deterministic wallets, invoice numbers, or child key generation on BSV.

BSV Key Derivation

Two primary approaches for deriving keys on BSV, plus mnemonic support.

Quick Reference

Method	Package	Use Case
Type42 (BRC-42)	@bsv/sdk	Modern: privacy-preserving, counterparty derivation
BIP32 (BRC-32)	@bsv/sdk	Legacy: HD wallets, sequential paths
Mnemonic	@bsv/sdk	Seed phrase to master key conversion

1. Type42 Key Derivation (Recommended)

Modern approach using ECDH shared secrets. Provides enhanced privacy and unlimited key derivation.

Basic Usage

import { PrivateKey, PublicKey } from "@bsv/sdk";

const masterKey = PrivateKey.fromWif("L1...");
const counterpartyPubKey = masterKey.toPublicKey(); // or another party's key

// Derive child key using invoice number
const childKey = masterKey.deriveChild(counterpartyPubKey, "invoice-123");
const childAddress = childKey.toPublicKey().toAddress();

Invoice Number Format (BRC-43)

For protocol-specific derivations, use the format: {securityLevel}-{protocol}-{keyId}

// BAP identity signing key
const bapKey = masterKey.deriveChild(masterKey.toPublicKey(), "1-sigma-identity");

// Encryption key
const encKey = masterKey.deriveChild(masterKey.toPublicKey(), "2-encryption-default");

Counterparty Derivation

Type42 enables deriving shared keys between parties without revealing private keys:

// Alice derives key for Bob
const aliceKey = PrivateKey.fromWif("L1...");
const bobPubKey = PublicKey.fromString("02...");
const sharedKey = aliceKey.deriveChild(bobPubKey, "payment-001");

// Bob derives same address using his private key and Alice's public key
const bobKey = PrivateKey.fromWif("K1...");
const alicePubKey = aliceKey.toPublicKey();
const bobDerived = bobKey.deriveChild(alicePubKey, "payment-001");
// bobDerived.toPublicKey().toAddress() === sharedKey.toPublicKey().toAddress()

Key Advantages

• Privacy: ECDH shared secrets prevent address reuse detection
• Flexibility: Any string as invoice number (no 2^31 limit)
• Auditability: Reveal shared secret to specific parties only
• No public derivation: Enhanced security vs BIP32

2. BIP32 HD Key Derivation (Legacy)

Traditional hierarchical deterministic derivation for compatibility.

Basic Usage

import { HD } from "@bsv/sdk";

// From extended private key
const hdKey = HD.fromString("xprv9s21ZrQH143K...");

// Derive child at path
const child = hdKey.derive("m/44'/0'/0'/0/0");
const address = child.pubKey.toAddress();
const privateKey = child.privKey;

Path Format

• m = master key
• Numbers = child index (0 to 2^31-1)
• Apostrophe (') = hardened derivation

// Standard wallet paths
const receiving = hdKey.derive("m/44'/236'/0'/0/0");   // BSV receiving
const change = hdKey.derive("m/44'/236'/0'/1/0");     // BSV change

// BAP identity path
const bapRoot = hdKey.derive("m/424150'/0'/0'");      // 424150 = BAP in decimal

From Mnemonic

import { Mnemonic, HD } from "@bsv/sdk";

const mnemonic = Mnemonic.fromString("word1 word2 word3...");
const seed = mnemonic.toSeed();
const hdKey = HD.fromSeed(seed);

3. Mnemonic to Single Master Key

For Type42, convert mnemonic to a single master key (not extended key):

import { Mnemonic, Hash, PrivateKey, Utils } from "@bsv/sdk";
const { toHex } = Utils;

const mnemonic = Mnemonic.fromString("dial tunnel valid cry exhaust...");
const seed = mnemonic.toSeed();

// SHA256 of seed produces 256-bit private key
const keyBytes = Hash.sha256(seed);
const masterKey = PrivateKey.fromString(toHex(keyBytes), "hex");

// Use with Type42 derivation
const childKey = masterKey.deriveChild(masterKey.toPublicKey(), "bap:0");

This approach:

• Maintains familiar mnemonic backup
• Produces single key for Type42 (not HD extended key)
• Remains compatible with existing BIP39 mnemonics

Choosing Between Methods

Scenario	Recommended
New wallet/identity system	Type42
Privacy-preserving payments	Type42
Counterparty key agreement	Type42
Legacy wallet compatibility	BIP32
Sequential address generation	BIP32
Migration from existing HD wallet	Both (see migration)

BAP Identity Key Derivation

BAP uses a two-level derivation hierarchy:

// Level 1: Member key from path
const memberKey = masterKey.deriveChild(masterKey.toPublicKey(), "bap:0");

// Level 2: Identity signing key using BAP invoice number
const signingKey = memberKey.deriveChild(memberKey.toPublicKey(), "1-sigma-identity");
const signingAddress = signingKey.toPublicKey().toAddress();

For BIP32 legacy:

const memberHD = hdKey.derive("m/424150'/0'/0'/0/0/0");
// Then apply Type42 for signing key
const signingKey = memberHD.privKey.deriveChild(memberHD.pubKey, "1-sigma-identity");

Security Considerations

1. Never expose master keys: Derive child keys for operations
2. Use hardened paths for BIP32 when privacy matters (apostrophe)
3. Type42 prevents public derivation: Cannot derive child public keys from parent public key alone
4. Invoice numbers are not secret: They can be shared

bsv-bap Library

The bsv-bap library implements Type42 with BRC-43 invoice numbers for BAP identities:

import { BAP } from "bsv-bap";
import { PrivateKey } from "@bsv/sdk";

const bap = new BAP({ rootPk: PrivateKey.fromRandom().toWif() });
const identity = bap.newId("Alice");

// Signing key derived with "1-sigma-identity"
const { address, signature } = identity.signMessage(messageBytes);

// Friend encryption key derived with "2-friend-{sha256(friendBapId)}"
const friendPubKey = identity.getEncryptionPublicKeyWithSeed(friendBapId);
const ciphertext = identity.encryptWithSeed("secret", friendBapId);

A CLI is also available: bun add -g bsv-bap (see create-bap-identity skill).

Official Specifications

All BSV key derivation standards are documented at:

https://bsv.brc.dev/key-derivation

Key specifications:

• BRC-42: Type42 key derivation scheme
• BRC-32: BIP32 HD key derivation
• BRC-43: Security levels, protocol IDs, key IDs
• BRC-69: Revealing key linkages
• BRC-72: Protecting key linkage information

Additional Resources

Reference Files

• references/brc-42-type42.md - Complete Type42 specification and advanced patterns
• references/brc-32-bip32.md - BIP32 legacy derivation details
• references/bap-derivation.md - BAP identity key derivation patterns and migration

Examples

• examples/type42-derivation.ts - Type42 counterparty key derivation
• examples/bip32-wallet.ts - BIP32 HD wallet with standard paths
• examples/mnemonic-to-type42.ts - Convert mnemonic to Type42 master key