key-derivation（密钥派生）

BSV Key Derivation

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

Quick Reference

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

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