使用助记词与派生路径创建钱包：Fuel SDK 助记词钱包完整指南

使用助记词与派生路径创建钱包Fuel SDK 助记词钱包完整指南【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-ts本文以 Fuel 官方文档 mnemonic-wallet.md 为骨架讲解 Fuel TypeScript SDKfuels-ts中从助记词mnemonic phrase派生钱包的核心概念与两种用法使用默认派生路径与自定义派生路径。读者将理解助记词→种子→HD 钱包→私钥的完整链路掌握Wallet.fromMnemonic的完整签名、BIP-44 派生路径各段含义以及对应源码在packages/account中的具体实现可直接在自己的 dApp 或脚本中落地使用。助记词可读、可备份的私钥载体钱包本质上是一对公私钥私钥是 32 字节的随机数难以记忆与抄写。BIP-39 提出的助记词方案用一组人类可读的单词来编码熵entropy从而让你可以用一句话保管一个钱包。助记词短语mnemonic phrase是一串由密码学算法生成的单词序列用于派生私钥。Fuel SDK 官方指南给出了这样一个例子助记词oblige salon price punch saddle immune slogan rare snap desert retire surprise将派生配合 Fuel 默认派生路径出地址0xdf9d0e6c6c5f5da6e82e5e1a77974af6642bdb450a10c43f0c6910a212600185值得注意的是该示例助记词共 12 个单词恰好落在 Fuel SDK 支持的最小助记词长度上——从 mnemonic.ts 源码中的MNEMONIC_SIZES [12, 15, 18, 21, 24]可以看到SDK 校验助记词只接受 12、15、18、21、24 五种长度对应 BIP-39 的 128256 bit 熵 校验和。任何其他长度的助记词都会被assertMnemonic拒绝并抛出错误。在真正上手前请务必理解助记词就是钱包的主密钥载体谁掌握助记词谁就掌握资产请务必通过离线或加密渠道妥善保存。不止一个钱包HD 分层确定性钱包与派生路径仅仅从助记词生成一个私钥并不稀奇。Fuel SDK 更进一步完整实现了Hierarchical Deterministic (HD) 分层确定性钱包与派生路径derivation path机制允许从同一个根助记词派生出一整棵树的钱包地址——这正是各大加密钱包一套助记词、多链多账户多地址的底层原理。你很可能在钱包产品中见过这样的路径m/44/1179993420/0/0/0SDK 文档明确指出该结构的价值在于同一个助记词短语可以创建出多个钱包地址。只需改变路径最后几段的下标即可得到互不相同、且可随时重现的地址序列只要备份了助记词任意路径下的钱包都能被重新还原。解析 Fuel 的默认派生路径Fuel SDK 的默认派生路径定义在 base-wallet-unlocked.tsstatic defaultPath m/44/1179993420/0/0/0;按照 BIP-44由 BIP-32 派生规则演化而来的分层约定可以把这段路径自左向右拆解如下路径段层级含义说明mmaster主节点由助记词生成的种子经 HMAC-SHA512 得到的根密钥44purpose用途固定为44声明使用 BIP-44 的多币种分层规范1179993420coin type币种Fuel 网络专属的币种编号0account账户第 0 号账户0change找零/外部链BIP-44 中0通常表示外部收款地址链0address index地址索引该链上的第 0 个地址其中1179993420这个数字值得玩味将其换算为十六进制是0x4655454C而这串字节恰好是 ASCII 编码的字符串FUEL——据此可以推断Fuel 选择了把FUEL的 ASCII 值直接作为其 BIP-44 coin type便于在生态内统一识别与记忆。路径中带如44、1179993420、0的段称为硬化索引hardened index。在 hdwallet.ts 的源码实现中const HARDENED_INDEX 0x80000000;parsePath会把解析为在原索引上加0x80000000即 2147483648。硬化派生只允许由父私钥推导子密钥可防止子公钥泄露导致整棵树被攻破因此 BIP-44 规定目的、币种、账户三层必须硬化。若尝试用不含私钥的扩展公钥去派生硬化索引deriveIndex会抛出Cannot derive a hardened index without a private Key.见 hdwallet.ts。两种实例化方式默认路径 vs 自定义路径SDK 通过同一个入口Wallet.fromMnemonic对外暴露两种用法——这也是官方文档 mnemonic-wallet.md 给出的两条主线不传派生路径自动使用默认路径m/44/1179993420/0/0/0显式传入自定义派生路径适合需要多账户、复用通用路径如以太坊风格的m/44/60/...或与既有钱包同步的场景。这两种用法对应的可运行示例位于文档同级目录下from-mnemonic-phrases-1.ts默认路径from-mnemonic-phrases-2.ts自定义路径方式一使用默认派生路径如果你不需要或不关心派生路径的具体配置只需一行Wallet.fromMnemonic(mnemonic)import { Wallet } from fuels; const mnemonic oblige salon price punch saddle immune slogan rare snap desert retire surprise; const wallet Wallet.fromMnemonic(mnemonic);此时的内部行为等价于Wallet.fromMnemonic(mnemonic, Wallet.defaultPath)即路径取默认值m/44/1179993420/0/0/0。wallet是一个已解锁的WalletUnlocked实例wallet.address即前文所示地址也可以进一步拿到wallet.privateKey、wallet.publicKey。方式二使用自定义派生路径当你想从同一助记词管理多个账户或想让 Fuel 钱包与某个既有的 HD 钱包路径对齐时把路径作为第二个参数传入即可import { Wallet } from fuels; const mnemonic oblige salon price punch saddle immune slogan rare snap desert retire surprise; const path m/44/60/1/0/0; // 注意这是以太坊常用的路径形式仅作示例 const wallet Wallet.fromMnemonic(mnemonic, path);示例中的m/44/60/1/0/0与默认路径的唯一区别是 coin type 由1179993420Fuel换成了60以太坊的 BIP-44 编号并且账户号从0变成了1——这会导致派生出完全不同的私钥与地址。要点如下派生路径是确定性的相同的助记词, 路径必然还原出相同的私钥与地址这是 HD 钱包可用于备份恢复的根本原因路径段须为合法的非负整数且遵循 BIP-32 语法非法路径如空段、异常层级会在 hdwallet.ts 的parsePath中直接抛错若要接入真实网络一般应优先使用 Fuel 生态约定的默认路径自定义路径适合需要一套助记词多钱包或兼容既有导入流程的场景。Wallet.fromMnemonic完整签名不止两个参数虽然文档只演示了两个参数但从源码看该 API 实际支持四个参数wallets.ts 中的完整定义如下static fromMnemonic( mnemonic: string, path?: string, passphrase?: BytesLike, provider?: Provider ): WalletUnlocked { const seed Mnemonic.mnemonicToSeed(mnemonic, passphrase); const hdWallet HDWallet.fromSeed(seed); const childWallet hdWallet.derivePath(path || WalletUnlocked.defaultPath); return new WalletUnlocked(stringchildWallet.privateKey, provider); }参数类型必填作用mnemonicstring是由 12/15/18/21/24 个单词组成的助记词短语pathstring否BIP-32/44 派生路径缺省为m/44/1179993420/0/0/0passphraseBytesLike否BIP-39 附加口令见下文进阶一节providerProvider否燃料提供者实例传入后钱包可立即执行链上操作另外类Wallet上的入口只是一个静态转发见 wallet.tsstatic fromMnemonic WalletUnlocked.fromMnemonic;也就是说真正实现位于WalletUnlockedWallet是其便捷门面你也可以绕过门面直接使用WalletUnlocked.fromMnemonic(...)。底层原理从助记词到私钥的三步调用链fromMnemonic内部虽只有三行却串起了packages/account中 BIP-39 与 BIP-32/44 两套完整实现。梳理调用链有助于你判断何时需要更底层的 API。第 1 步助记词 → BIP-39 种子PBKDF2-SHA512Mnemonic.mnemonicToSeed(phrase, passphrase)的实现见 mnemonic.tsconst phraseBytes toUtf8Bytes(getPhrase(phrase)); const salt toUtf8Bytes(mnemonic${passphrase}); return pbkdf2(phraseBytes, salt, 2048, 64, sha512);它严格遵循 BIP-39 规范将单词短语 UTF-8 化拼上盐mnemonic passphrase经PBKDF22048 轮、HMAC-SHA512派生出 64 字节种子。调用前还会通过assertMnemonic校验单词数量是否落在MNEMONIC_SIZES中。若想在不真正生成钱包的情况下预检助记词是否合法可调用 mnemonic.ts 中的Mnemonic.isMnemonicValid(phrase)——它会逐词在 2048 词的英文词表中做二分查找校验词表即english导入的 BIP-39 标准词表见 mnemonic.ts。第 2 步种子 → 主 HD 节点HDWallet.fromSeed(seed)见 hdwallet.ts其本质是对种子做一次以Bitcoin seed为 HMAC key 的 HMAC-SHA512static fromSeed(seed: string) { const masterKey Mnemonic.masterKeysFromSeed(seed); return new HDWallet({ chainCode: arrayify(masterKey.slice(32)), privateKey: arrayify(masterKey.slice(0, 32)), }); }得到的 64 字节主密钥中前 32 字节作为根私钥、后 32 字节作为链码chain code二者共同构成 HD 树的根节点。第 3 步沿派生路径逐级下钻hdWallet.derivePath(path)hdwallet.ts先把路径按/拆成若干段并经parsePath处理硬化标记然后逐级调用deriveIndexderivePath(path: string) { const paths parsePath(path, this.depth); return paths.reduce((hdwallet, index) hdwallet.deriveIndex(index), HDWalletthis); }每一级子密钥都通过父密钥 链码 索引做 HMAC-SHA512Key 链码Data 0x00‖父私钥 或 父压缩公钥 4 字节索引计算出子私钥与子链码对应 BIP-32 的 CKDChild Key Derivation流程细节见 hdwallet.ts。走到路径终点得到的子私钥被封装进new WalletUnlocked(privateKey, provider)即返回给你的已解锁钱包。进阶口令、Provider 与兄弟 API给助记词加一层口令passphrasefromMnemonic的第三个参数passphrase是 BIP-39 的可选第 25 个单词。它不参与助记词本身的编码而是混入 PBKDF2 的盐中用于改变最终派生的种子。源码注释特别警示见 mnemonic.ts口令一旦遗忘所有由该助记词派生的钱包都将永久丢失——备份时必须连同口令一同保存。传入 Provider一步到位可上链默认创建的WalletUnlocked是离线实例。若你后续要转账、调用合约等链上操作有两种选择创建后连接wallet.connect(provider)或在实例化时直接传入第四参数provider更推荐的Create a Wallet Unlocked from a mnemonic链路使返回的钱包立即可用。关于 Provider 连接的完整做法可参见 instantiating-wallets.md。同族兄弟 API种子 / 扩展密钥理解了fromMnemonic的三步链路后你会发现同文件中的另两个静态方法只是入口不同、链路相同WalletUnlocked.fromSeed(seed, path?, provider?)wallets.ts跳过第 1 步直接由现成的 64 字节种子走 HD 派生WalletUnlocked.fromExtendedKey(extendedKey, provider?)wallets.ts从 BIP-32 扩展密钥含 base58check 校验与主/测试网前缀识别直接恢复钱包。它们与助记词方式共享同一套HDWallet派生实现适合只拿到种子或 xprv、而非助记词的导入场景。工程质量测试与钱包管理器中的实际使用这套助记词能力并非孤立实现而是被全仓库充分验证与复用的单元测试助记词 BIP-39 相关行为有 mnemonic.test.tsHD 派生有 hdwallet.test.ts而WalletUnlocked.fromMnemonic的实例化与签名、交易能力在 wallet-unlocked.test.ts 中覆盖钱包管理器集成在需要助记词管理多个钱包的wallet-manager中助记词被封装为一种 vault 类型mnemonic-vault.ts其测试 mnemonic-vault.test.ts 也验证了一套助记词 派生路径树在真实账户管理场景下的可用性。若你的需求演化为多账户、多钱包统一管理、加密持久化可以进一步阅读 wallet-manager.md 了解在此基础上构建的管理器方案。小结本文基于官方指南 mnemonic-wallet.md 展开了从概念到源码的完整梳理核心结论可归纳为助记词BIP-39是私钥的可读载体Fuel SDK 支持 1224 词HD 钱包机制让你可以用一个助记词派生无数地址Fuel 默认路径为m/44/1179993420/0/0/0coin type1179993420的十六进制0x4655454C正是 ASCIIFUELWallet.fromMnemonic(mnemonic)走默认路径Wallet.fromMnemonic(mnemonic, path)走自定义路径二者分别对应文档示例 from-mnemonic-phrases-1.ts 与 from-mnemonic-phrases-2.ts方法实际还支持passphrase与provider参数其底层依次经历mnemonicToSeedPBKDF2-SHA512、HDWallet.fromSeedHMAC-SHA512 主密钥、derivePathBIP-32 逐级下钻三步。对多数应用而言直接使用默认路径即可安全、简单地落地只有当你需要一套助记词支撑多账户 / 多链路径对齐时才需要显式传入自定义派生路径。【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-ts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考