Back to Details

nbitcoin

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

NBitcoin Skill

NBitcoin 技能

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).
NBitcoin 通过
Sorcha.Wallet.Core
项目在Sorcha中提供HD钱包操作。代码库将NBitcoin类型封装到领域值对象（
Mnemonic
、
DerivationPath
）中，仅用于BIP32/39/44密钥推导——不用于交易构建。实际签名操作使用
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)"
csharp
// src/Common/Sorcha.Wallet.Core/Domain/ValueObjects/Mnemonic.cs
var mnemonic = Mnemonic.Generate(12);  // 或生成24词以提升安全性
// 切勿记录mnemonic.Phrase - 请使用mnemonic.ToString()，该方法返回"Mnemonic(12 words)"

Derive Keys at BIP44 Path

在BIP44路径下推导密钥

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");
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);
}
csharp
if (Mnemonic.IsValid(userProvidedPhrase))
{
    var mnemonic = new Mnemonic(userProvidedPhrase);
}

Key Concepts

核心概念

ConceptUsageExample
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 PathsSorcha-specific aliases
"sorcha:register-attestation"
→ 
"m/44'/0'/0'/0/100"
Gap LimitBIP44: max 20 unused addressesEnforced in 
WalletManager.cs:493-508
概念用途示例
Mnemonic
封装
NBitcoin.Mnemonic
Mnemonic.Generate(12)
DerivationPath
封装
NBitcoin.KeyPath
DerivationPath.CreateBip44(0, 0, 0, 0)
ExtKey
扩展私钥
ExtKey.CreateFromSeed(masterKey)
系统路径Sorcha专属别名
"sorcha:register-attestation"
→ 
"m/44'/0'/0'/0/100"
间隔限制BIP44：最多20个未使用地址在
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);
适用场景： 用户创建新钱包时。
csharp
// 1. 生成助记词（切勿存储在服务器上）
var mnemonic = Mnemonic.Generate(12);

// 2. 使用可选密码推导主密钥
var masterKey = await _keyManagement.DeriveMasterKeyAsync(mnemonic, passphrase);

// 3. 在m/44'/0'/0'/0/0路径下推导首个密钥
var path = DerivationPath.CreateBip44(0, 0, 0, 0);
var (privateKey, publicKey) = await _keyManagement.DeriveKeyAtPathAsync(masterKey, path, algorithm);

// 4. 存储前加密私钥
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;
适用场景： 使用Sorcha专属推导用途时。
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 - Value objects, key derivation, security patterns
  • workflows - Wallet creation, recovery, address management
  • patterns - 值对象、密钥推导、安全模式
  • workflows - 钱包创建、恢复、地址管理

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
  • 签名操作（ED25519、P-256、RSA-4096）请查看cryptography技能
  • .NET 10模式与DI配置请查看dotnet技能
  • HD钱包操作测试请查看xunit技能与fluent-assertions技能

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"
使用Context7获取最新的NBitcoin文档。
如何使用Context7：
  1. 使用
    mcp__context7__resolve-library-id
    搜索"nbitcoin"
  2. 使用解析后的库ID，通过
    mcp__context7__query-docs
    进行查询
库ID： 
/metacosa/nbitcoin
推荐查询语句：
  • "NBitcoin BIP32 BIP39 BIP44 key derivation"
  • "NBitcoin ExtKey master key child derivation"
  • "NBitcoin Mnemonic passphrase seed"