fuels-ts 钱包实例化完全指南从私钥、助记词到 Provider 连接【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-ts导读Wallet是 Fuel 官方 TypeScript SDKfuels-ts中创建与管理钱包的核心入口类位于fuel-ts/account包内。本指南以 instantiating-wallets.md 为主体系统讲解在 SDK 中实例化钱包的全部途径随机生成新钱包、从私钥/助记词/种子/HD 派生密钥/加密 JSON 文件还原已解锁钱包、仅凭地址创建锁定钱包以及如何为钱包挂载Provider以便发起链上交易。阅读完成后你将能够在任何 fuels-ts 项目中熟练选用合适的实例化方式并理解WalletLocked与WalletUnlocked两种状态背后的设计动机。说明fuels-ts 中所谓钱包本质是围绕一组 Fuel 密钥公私钥对与地址的封装对象它与常见 EOA 钱包交互模型类似但实现针对 Fuel 网络地址格式做了专门适配。先理解两个核心概念WalletLocked与WalletUnlocked在进入具体代码之前必须先厘清 fuels-ts 的钱包对象模型因为文档中所有实例化方式都围绕这两个类展开WalletUnlocked已解锁钱包持有私钥可直接用于签名交易与消息。凡是从私钥、助记词、种子、HD 扩展密钥、加密 JSON 还原出来的钱包默认都处于该状态。WalletLocked锁定钱包仅持有地址不暴露私钥只能用于只读查询如查询余额、构建不含签名的交易无法直接签名。一般通过Wallet.fromAddress(address)创建。Wallet门面类把两者的静态工厂方法统一收口在一起方便开发者只从fuels包导入一个类即可完成所有实例化。其源码可在 packages/account/src/wallet/wallet.ts 中查看例如fromAddress直接返回new WalletLocked(address, provider)fromPrivateKey返回new WalletUnlocked(privateKey, provider)而generate、fromSeed、fromMnemonic、fromExtendedKey、fromEncryptedJson则全部委托给WalletUnlocked的同名静态方法见 packages/account/src/wallet/wallets.ts。生成新钱包当应用需要为新用户创建一套全新的、随机的密钥时直接调用Wallet.generate()即可。该方法在底层生成一个随机密钥对并返回一个立即可用的WalletUnlocked实例——无需任何额外的解锁或导入步骤。// #region instantiating-wallets-1 import { Wallet } from fuels; import type { WalletUnlocked } from fuels; const wallet: WalletUnlocked Wallet.generate(); // #endregion instantiating-wallets-1从源码看Wallet.generate就是WalletUnlocked.generate的静态别名见 packages/account/src/wallet/wallet.ts#L40其实际实现在 packages/account/src/wallet/wallets.ts#L59并且接受可选的GenerateOptions参数。需要特别提醒的是generate()产生的是全新随机密钥SDK 不会替你保存它。上线前必须把私钥或助记词妥善备份例如转为加密 JSON 存档否则一旦丢失就无法再恢复资产。与之配套的备份方案如WalletUnlocked.encrypt可以参阅同一目录下的 encrypting-and-decrypting.md。实例化已解锁钱包WalletUnlocked还原已有钱包的核心思路是用密钥材料重建WalletUnlocked。fuels-ts 一共提供了五种互不相同的密钥材料入口适用场景各不相同下面逐一展开。方式一通过私钥导入当你手上直接持有私钥如从自己的数据库或环境变量读取时用Wallet.fromPrivateKey(privateKey)。私钥是燃料量形式的十六进制字符串也可作为BytesLike传入见 wallet.ts#L30。// #region instantiating-wallets-2 import type { WalletUnlocked } from fuels; import { Wallet } from fuels; const privateKey 0x36ca81ba70f3e04b7cc8780bff42d907ebca508097d4ae3df5147c93fd217f7c; const wallet: WalletUnlocked Wallet.fromPrivateKey(privateKey); // #endregion instantiating-wallets-2⚠️ 安全提示私钥即资产所有权。切勿将其硬编码在源码、提交进版本库或写入前端可见位置生产环境应放入受保护的环境变量或密钥管理服务。方式二通过助记词导入用户用钱包应用导出的一串 12/24 个英文单词即为助记词BIP-39 mnemonic。Wallet.fromMnemonic(mnemonic)会按默认派生路径从助记词推导出私钥并创建已解锁钱包。// #region instantiating-wallets-3 import type { WalletUnlocked } from fuels; import { Wallet } from fuels; const mnemonic section gospel lady april mouse huge prosper boy urge fox tackle orient; const wallet: WalletUnlocked Wallet.fromMnemonic(mnemonic); // #endregion instantiating-wallets-3对应方法签名在 wallets.ts#L89fromMnemonic(mnemonic, provider?, path?, passphrase?)。其中path用于自定义 HD 派生路径passphrase用于传入额外的 BIP-39 口令。fuels-ts 使用的默认派生路径与 Fuel 生态约定保持一致通常无需改动。方式三通过种子导入某些场景如从硬件钱包或自建密钥库直接拿到的是熵种子seed。此时用Wallet.fromSeed(seed)// #region instantiating-wallets-4 import type { WalletUnlocked } from fuels; import { Wallet } from fuels; const seed 0xa5d42fd0cf8825fc846b2f257887a515573ee5b779e99f060dc945b3d5504bca; const wallet: WalletUnlocked Wallet.fromSeed(seed); // #endregion instantiating-wallets-4方式四通过 HD 派生扩展密钥导入WalletUnlocked还支持直接传入由 BIP-32 风格推导出的扩展密钥extended key。典型组合是先用HDWallet.fromSeed(seed).toExtendedKey()得到扩展密钥再交给Wallet.fromExtendedKey实例化// #region instantiating-wallets-5 import type { WalletUnlocked } from fuels; import { HDWallet, Wallet } from fuels; const seed 0xa5d42fd0cf8825fc846b2f257887a515573ee5b779e99f060dc945b3d5504bca; const extendedKey HDWallet.fromSeed(seed).toExtendedKey(); const wallet: WalletUnlocked Wallet.fromExtendedKey(extendedKey); // #endregion instantiating-wallets-5HDWallet同样由fuels统一导出它实现了 Fuel 网络的层级确定性密钥派生逻辑。若你的应用需要实现 HD 钱包多账户体系一个种子派生多个子私钥建议深入阅读 mnemonic-wallet.md 与 packages/account/src/hdwallet 目录。方式五通过加密 JSONkeystore导入当钱包此前以加密 JSON 文件keystore遵循 Web3 Secret Storage 格式默认使用 scrypt KDF AES-128-CTR 加密的形式备份时需要密码配合解密才能还原因此该方法是异步的使用await// #region instantiating-wallets-6 import type { WalletUnlocked } from fuels; import { Wallet } from fuels; const jsonWallet {id:83d1792f-3230-496a-92af-3b44a1524fd6,version:3,address:ada436e1b80f855f94d678771c384504e46335f571aa244f11b5a70fe3e61644,crypto:{cipher:aes-128-ctr,mac:6911499ec31a6a6d240220971730374396efd666bd34123d4e3ce85e4cf248c6,cipherparams:{iv:40576cbd4f7c84e88b0532320e23b425},ciphertext:3e5e77f23444aa86b397dbc62e14d8b7d3fd7c7fe209e066bb7df17eca398129,kdf:scrypt,kdfparams:{dklen:32,n:8192,p:1,r:8,salt:b046520d85090ee2abd6285174f37bc01e28846b6bb5edc03ae5f7c13aec03d2}}}; const password password; const wallet: WalletUnlocked await Wallet.fromEncryptedJson( jsonWallet, password ); // #endregion instantiating-wallets-6从上面 JSON 可以看到 keystore 的关键字段crypto.cipher加密算法、crypto.kdf与kdfparams密钥派生函数及其参数、crypto.ciphertext密文以及crypto.mac完整性校验。fuels-ts 对这类文件加密/解密的完整流程含生产环境生成方式见 encrypting-and-decrypting.md。方式六从锁定钱包解锁还有一种常见形态你手里只有一个仅含地址的WalletLocked但随后又拿到了对应私钥。此时无需重新fromPrivateKey直接对锁定钱包调用.unlock(privateKey)即可原地升级为已解锁钱包// #region instantiating-wallets-7 import type { WalletLocked, WalletUnlocked } from fuels; import { Wallet } from fuels; const address 0x4cb2b5d2bdbcc8dbdbf91cd00be3e2deedb0ea0f34c969c0ed741a1925111a87; const privateKey 0x9deba03f08676716e3a4247797672d8008a5198d183048be65415ef89447b890; const lockedWallet: WalletLocked Wallet.fromAddress(address); const wallet: WalletUnlocked lockedWallet.unlock(privateKey); // #endregion instantiating-wallets-7unlock返回一个新的WalletUnlocked其中的私钥可通过wallet.privateKey访问。反向操作把已解锁钱包降级为仅地址的锁定钱包以及加解密、锁定的生命周期管理可参见 locking-and-unlocking.md。实例化锁定钱包WalletLocked只读场景如监控某个地址的余额、读取该地址相关的链上状态不需要私钥仅用 Fuel 的 b256 地址即可创建WalletLocked。Wallet.fromAddress接受形如0x 64 位十六进制的B256Address字符串也支持Address对象见 wallet.ts#L19// #region instantiating-wallets-8 import type { B256Address, WalletLocked } from fuels; import { Wallet } from fuels; const address: B256Address 0x6d309766c0f1c6f103d147b287fabecaedd31beb180d45cf1bf7d88397aecc6f; const wallet: WalletLocked Wallet.fromAddress(address); // #endregion instantiating-wallets-8在 fuels-ts 的默认导出之外WalletLocked、WalletUnlocked与HDWallet等类型与类均会一并从fuels入口导出因此import type { WalletLocked } from fuels即可获得完整的类型提示。连接 Provider让钱包具备链上能力钱包本身可以作为纯离线密钥容器独立存在但任何需要与区块链交互的操作——查询余额、估算手续费、提交交易、读取合约——都必须让钱包关联一个Provider。Provider负责与 Fuel 节点的 GraphQL/HTTP 接口通信是钱包访问链上世界的通道。场景 A为已有钱包补挂 Provider先创建 Provider再用wallet.connect(provider)动态绑定// #region instantiating-wallets-9 import type { WalletLocked } from fuels; import { Provider, Wallet } from fuels; import { LOCAL_NETWORK_URL, WALLET_ADDRESS } from ../../../../env; const provider new Provider(LOCAL_NETWORK_URL); const wallet: WalletLocked Wallet.fromAddress(WALLET_ADDRESS); wallet.connect(provider); // #endregion instantiating-wallets-9connect会就地给该钱包实例关联 Provider之后便可调用余额查询、交易构建等接口。示例中的LOCAL_NETWORK_URL、WALLET_ADDRESS来自文档环境的 env.ts实际开发时通常指向本地fuel-core节点的 URL 与某个测试地址。场景 B实例化时直接注入 Provider多数情况下更推荐这种写法——把provider作为第二个可选参数直接传给工厂方法一步到位// #region instantiating-wallets-10 import type { WalletLocked } from fuels; import { Provider, Wallet } from fuels; import { LOCAL_NETWORK_URL, WALLET_ADDRESS } from ../../../../env; const provider new Provider(LOCAL_NETWORK_URL); const wallet: WalletLocked Wallet.fromAddress(WALLET_ADDRESS, provider); // #endregion instantiating-wallets-10这一可选参数模式贯穿全部工厂方法fromPrivateKey、fromMnemonic、fromSeed、fromExtendedKey等都将provider?作为可选参数参见 wallet.ts#L19-L80即在导入密钥的同时完成链连接。因此你完全可以把第 3~6 小节的代码改写为Wallet.fromMnemonic(mnemonic, provider)等形态获得可直接交易的钱包。关于 Provider 的创建细节如链上配置读取、本地节点 URL、网络切换可进一步查阅 provider/index.md。如何选择正确的实例化方式目标状态现有材料推荐 API备注新账户无Wallet.generate()生成随机密钥需自行安全备份已解锁私钥Wallet.fromPrivateKey(pk)最常见的恢复方式已解锁助记词Wallet.fromMnemonic(mnemonic)支持自定义 path/passphrase已解锁种子Wallet.fromSeed(seed)直接输入熵种子已解锁HD 扩展密钥Wallet.fromExtendedKey(xkey)常配合HDWallet使用已解锁加密 JSON 密码await Wallet.fromEncryptedJson(json, password)唯一异步路径已解锁WalletLocked 私钥lockedWallet.unlock(pk)就地升级为已解锁钱包锁定只读b256 地址Wallet.fromAddress(addr)也可传入Address对象任意钱包已有 Providerwallet.connect(provider)实例化后补绑链连接任意钱包密钥材料 ProviderWallet.fromXxx(mat, provider)实例化时直接绑定选择依据可归纳为三条需要签名吗需要则用已解锁钱包持有私钥只读查询则用fromAddress创建锁定钱包更安全。手头有什么密钥材料按私钥 / 助记词 / 种子 / 扩展密钥 / 加密 JSON五选一对应五条fromXxx路径。要不要立即上链需要则顺手传入provider参数或用connect补挂。底层原理与验证所有工厂方法都收敛于 packages/account/src/wallet/wallets.ts 中WalletUnlocked/WalletLocked的实现generatewallets.ts#L59内部生成随机密钥对返回WalletUnlocked即已解锁钱包。fromSeed/fromMnemonic/fromExtendedKeywallets.ts#L73-L109负责将不同格式的种子/短语/扩展密钥统一转换为私钥再装配为WalletUnlocked。从源码结构可以推断助记词路径内部必然经过 BIP-39 校验与 HD 派生两步最后落到与fromSeed相同的私钥装配逻辑。Wallet门面类wallet.ts只是这些静态方法的薄封装提供统一的导入入口。仓库中也配套了针对钱包实例化行为的基础测试如 wallet.test.ts 与 wallet-unlocked.test.ts它们验证了生成、导入、解锁等关键路径的行为可作为理解 API 契约的补充素材。延伸阅读钱包生命周期不止于实例化。在同一guide/wallets目录下还有与本文直接相关的进阶主题locking-and-unlocking.mdWalletLocked/WalletUnlocked双向转换与加解锁机制encrypting-and-decrypting.mdkeystore JSON 的加密/解密配合fromEncryptedJson使用mnemonic-wallet.mdHD 助记词钱包的派生与管理配合fromMnemonic/fromExtendedKeyprivate-keys.md私钥的安全存储与使用建议checking-balances.md实例化完成后如何查询余额等链上数据signing.md使用WalletUnlocked签名交易与消息。【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-ts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
