NBitcoin Skill

NBitcoin provides HD wallet operations in Sorcha through the Sorcha.Wallet.Core project. The codebase wraps NBitcoin types in domain value objects (Mnemonic, DerivationPath) and uses them exclusively for BIP32/39/44 key derivation—NOT for transaction building. Actual signing uses Sorcha.Cryptography (ED25519, P-256, RSA-4096).

Quick Start

Generate a Mnemonic

// src/Common/Sorcha.Wallet.Core/Domain/ValueObjects/Mnemonic.cs
var mnemonic = Mnemonic.Generate(12);  // or 24 for higher security
// NEVER log mnemonic.Phrase - use mnemonic.ToString() which returns "Mnemonic(12 words)"

Derive Keys at BIP44 Path

// src/Common/Sorcha.Wallet.Core/Services/Implementation/KeyManagementService.cs:62-111
var masterKey = await _keyManagement.DeriveMasterKeyAsync(mnemonic, passphrase);
var path = DerivationPath.CreateBip44(coinType: 0, account: 0, change: 0, addressIndex: 0);
var (privateKey, publicKey) = await _keyManagement.DeriveKeyAtPathAsync(masterKey, path, "ED25519");

Validate a Mnemonic

if (Mnemonic.IsValid(userProvidedPhrase))
{
    var mnemonic = new Mnemonic(userProvidedPhrase);
}

Key Concepts

Concept	Usage	Example
Mnemonic	Wraps NBitcoin.Mnemonic	Mnemonic.Generate(12)
DerivationPath	Wraps NBitcoin.KeyPath	DerivationPath.CreateBip44(0, 0, 0, 0)
ExtKey	Extended private key	ExtKey.CreateFromSeed(masterKey)
System Paths	Sorcha-specific aliases	"sorcha:register-attestation" → "m/44'/0'/0'/0/100"
Gap Limit	BIP44: max 20 unused addresses	Enforced in WalletManager.cs:493-508

Common Patterns

Wallet Creation Flow

When: User creates a new wallet.

// 1. Generate mnemonic (NEVER store on server)
var mnemonic = Mnemonic.Generate(12);

// 2. Derive master key with optional passphrase
var masterKey = await _keyManagement.DeriveMasterKeyAsync(mnemonic, passphrase);

// 3. Derive first key at m/44'/0'/0'/0/0
var path = DerivationPath.CreateBip44(0, 0, 0, 0);
var (privateKey, publicKey) = await _keyManagement.DeriveKeyAtPathAsync(masterKey, path, algorithm);

// 4. Encrypt private key before storage
var (encryptedKey, keyId) = await _keyManagement.EncryptPrivateKeyAsync(privateKey, string.Empty);

System Path Resolution

When: Using Sorcha-specific derivation purposes.

// src/Common/Sorcha.Wallet.Core/Constants/SorchaDerivationPaths.cs
var resolvedPath = SorchaDerivationPaths.IsSystemPath(derivationPath)
    ? SorchaDerivationPaths.ResolvePath(derivationPath)  // "sorcha:register-attestation" → "m/44'/0'/0'/0/100"
    : derivationPath;

See Also

• patterns - Value objects, key derivation, security patterns
• workflows - Wallet creation, recovery, address management

Related Skills

• See the cryptography skill for signing operations (ED25519, P-256, RSA-4096)
• See the dotnet skill for .NET 10 patterns and DI configuration
• See the xunit skill and fluent-assertions skill for testing HD wallet operations

Documentation Resources

Fetch latest NBitcoin documentation with Context7.

How to use Context7:

1. Use mcp__context7__resolve-library-id to search for "nbitcoin"
2. Query with mcp__context7__query-docs using the resolved library ID

Library ID: /metacosa/nbitcoin

Recommended Queries:

• "NBitcoin BIP32 BIP39 BIP44 key derivation"
• "NBitcoin ExtKey master key child derivation"
• "NBitcoin Mnemonic passphrase seed"