playbooks

home / skills / stuartf303 / sorcha / nbitcoin

nbitcoin skill

/.claude/skills/nbitcoin

This skill enables HD wallet key derivation using NBitcoin for BIP32/39/44, deriving keys from mnemonics and paths without transaction signing.

npx playbooks add skill stuartf303/sorcha --skill nbitcoin

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
3.9 KB
---
name: nbitcoin
description: |
  Utilizes NBitcoin for HD wallet operations (BIP32/39/44).
  Use when: Creating wallets, deriving keys from mnemonics, working with BIP44 derivation paths, or implementing hierarchical deterministic wallet features.
allowed-tools: Read, Edit, Write, Glob, Grep, Bash, mcp__context7__resolve-library-id, mcp__context7__query-docs
---

# 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

```csharp
// 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

```csharp
// 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

```csharp
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.

```csharp
// 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.

```csharp
// 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](references/patterns.md) - Value objects, key derivation, security patterns
- [workflows](references/workflows.md) - 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"

Overview

This skill integrates NBitcoin to provide hierarchical deterministic (HD) wallet operations following BIP32, BIP39, and BIP44. It exposes mnemonic generation and validation, BIP44 derivation path creation, and deterministic key derivation while delegating actual signing to the project cryptography stack. Use it to create wallets, derive keys from mnemonics, and resolve application-specific system paths for deterministic addresses.

How this skill works

The skill wraps NBitcoin types in domain-safe value objects (Mnemonic, DerivationPath) and uses them to generate seeds and derive ExtKey/child keys at BIP44 paths. It supports generating 12- or 24-word mnemonics, validating user-provided phrases, deriving a master key with an optional passphrase, and deriving keys at resolved BIP44 paths. System-level aliases (e.g., sorcha:register-attestation) are translated into concrete BIP44 paths before derivation. Private keys are expected to be encrypted before long-term storage.

When to use it

  • When creating a new HD wallet and issuing a recovery mnemonic.
  • When deriving account, change, or address keys using BIP44 paths.
  • When validating or restoring a wallet from a user-provided mnemonic.
  • When mapping application-specific system paths to concrete BIP44 derivation paths.
  • When enforcing gap-limit checks for address discovery and management.

Best practices

  • Never log raw mnemonic phrases; expose only safe diagnostics (e.g., Mnemonic(12 words)).
  • Use an optional passphrase when deriving the master seed for higher security and better recovery control.
  • Always encrypt private keys before persisting them to storage or sending them to other services.
  • Resolve and validate Sorcha-specific system paths to concrete BIP44 paths before derivation.
  • Enforce the BIP44 gap limit (commonly 20) when scanning for unused addresses to avoid keyspace gaps.

Example use cases

  • Generate a 12-word mnemonic for a new user wallet and derive the first address at m/44'/0'/0'/0/0.
  • Recover a wallet from a user-supplied mnemonic and derive account-level keys for balance reconciliation.
  • Derive ED25519 keys at a BIP44 path for use with the project’s signature algorithms (signing is handled by the cryptography layer).
  • Resolve a system alias like sorcha:register-attestation to its hard-coded BIP44 path and derive the corresponding key.
  • Implement address discovery with gap-limit enforcement when restoring wallets or scanning accounts.

FAQ

Can this skill be used for transaction building and signing?

No. Key derivation uses NBitcoin, but transaction building and signing are performed by the project cryptography modules (ED25519, P-256, RSA-4096).

How should mnemonics be stored or logged?

Never store or log raw mnemonic phrases. Treat the mnemonic as sensitive secret material, encrypt private keys, and only display non-sensitive debug summaries like "Mnemonic(12 words)".