python-hdwallet Electrum V1/V2助记词体系实战：standard/segwit/2fa全模式支持

python-hdwallet 是一个 Python 层实现的层次确定性（HD）钱包生成库，内置 Electrum 官方两套助记词标准：Electrum-V1（128 位旧版）与Electrum-V2（132/264 位新版）。本文带你用最少代码跑通 V1/V2 助记词的生成、校验、种子推导，以及 standard、segwit、standard-2fa、segwit-2fa 四种模式下的比特币地址生成。

一、先看懂：V1 与 V2 助记词有何不同？

Electrum 客户端在 3.x 版本后把助记词从自研词表升级为基于 BIP39 词表的 V2 体系。两代体系的差异一览：

💡 V2 的类型（type）不是靠"最后一个词"之类的标记来区分，而是对整句助记词计算HMAC-SHA512（密钥为Seed version），再看十六进制结果的前缀：01= standard，100= segwit，101= standard-2fa，102= segwit-2fa。这个设计保证了同类型助记词在海量组合中几乎必然唯一命中，逻辑实现见 hdwallet/mnemonics/electrum/v2/mnemonic.py。

两种类型的常量定义在 hdwallet/mnemonics/electrum/v2/mnemonic.py，四种类型的十六进制前缀映射在 mnemonic_types 字典。

二、快速安装与验证

hdwallet已在 PyPI 发布，一行命令即可安装（含 CLI 支持）：

pip install "hdwallet[cli]"

也可以从源码安装（仓库地址：https://gitcode.com/gh_mirrors/pyth/python-hdwallet）：

git clone https://gitcode.com/gh_mirrors/pyth/python-hdwallet cd python-hdwallet && pip install .

验证安装是否成功：

hdwallet -v

三、一行命令生成 Electrum V2 助记词（CLI 方式）

库自带hdwallet命令行工具（入口定义于 hdwallet/cli/generate/mnemonic.py），--mnemonic-type（简写-mt）就是用来选择四种模式的：

# standard 模式（默认，生成 12 词英语助记词） hdwallet generate mnemonic -c Electrum-V2 -w 12 -mt standard # segwit 模式，西班牙语 hdwallet generate mnemonic -c Electrum-V2 -l spanish -w 12 -mt segwit # 24 词的 segwit-2fa 模式 hdwallet generate mnemonic -c Electrum-V2 -w 24 -mt segwit-2fa

生成种子同样一行搞定（-m传助记词，-mt必须与助记词类型一致）：

hdwallet generate seed -c Electrum-V2 -m "your mnemonic words..." -mt segwit

四、Python 实战：standard 模式完整流程

standard 模式对应传统 P2PKH 地址（1...开头），派生路径为m/{change}/{address}。核心代码：

from hdwallet import HDWallet from hdwallet.mnemonics import ( ElectrumV2Mnemonic, ELECTRUM_V2_MNEMONIC_LANGUAGES, ELECTRUM_V2_MNEMONIC_TYPES, ELECTRUM_V2_MNEMONIC_WORDS, ) from hdwallet.derivations import ElectrumDerivation from hdwallet.cryptocurrencies import Bitcoin from hdwallet.consts import MODES, PUBLIC_KEY_TYPES from hdwallet.hds import ElectrumV2HD hdwallet = HDWallet( cryptocurrency=Bitcoin, hd=ElectrumV2HD, network=Bitcoin.NETWORKS.MAINNET, language=ELECTRUM_V2_MNEMONIC_LANGUAGES.ENGLISH, mnemonic_type=ELECTRUM_V2_MNEMONIC_TYPES.STANDARD, mode=MODES.STANDARD, ).from_mnemonic( mnemonic=ElectrumV2Mnemonic( mnemonic=ElectrumV2Mnemonic.from_words( words=ELECTRUM_V2_MNEMONIC_WORDS.TWELVE, language=ELECTRUM_V2_MNEMONIC_LANGUAGES.ENGLISH, mnemonic_type=ELECTRUM_V2_MNEMONIC_TYPES.STANDARD, ), mnemonic_type=ELECTRUM_V2_MNEMONIC_TYPES.STANDARD, ) ).from_derivation( derivation=ElectrumDerivation(change=0, address=0) ) print(hdwallet.address()) # 1... 开头的 P2PKH 地址

四个关键参数必须自洽：

1. mnemonic_type：决定助记词按哪种类型生成/校验（见 HDWallet 主流程的校验逻辑）；
2. mode：决定派生路径与地址格式，常量定义在 hdwallet/consts.py；
3. language：生成与解析的语言必须一致；
4. change/address：对应 Electrum 的"接收/找零"两级索引。

五、segwit 模式：一键推导 bc1 原生 SegWit 地址

segwit 模式是 V2 体系的亮点：助记词类型前缀100，且派生路径自动在根节点插入硬派生段m/0'，最终输出bc1...原生 SegWit（P2WPKH）地址。

这条路径规则就写在 ElectrumV2HD.drive() 中：

• mode = "standard"→ 路径m/{change}/{address}→1...地址
• mode = "segwit"→ 路径m/0'/{change}/{address}→bc1...地址

把上面示例中两处STANDARD换成SEGWIT，并加上mode=MODES.SEGWIT，地址立刻变为bc1开头：

hdwallet = HDWallet( cryptocurrency=Bitcoin, hd=ElectrumV2HD, network=Bitcoin.NETWORKS.MAINNET, language=ELECTRUM_V2_MNEMONIC_LANGUAGES.ENGLISH, mnemonic_type=ELECTRUM_V2_MNEMONIC_TYPES.SEGWIT, mode=MODES.SEGWIT, public_key_type=PUBLIC_KEY_TYPES.UNCOMPRESSED, ).from_mnemonic( mnemonic=ElectrumV2Mnemonic( mnemonic=ElectrumV2Mnemonic.from_words( words=ELECTRUM_V2_MNEMONIC_WORDS.TWELVE, language=ELECTRUM_V2_MNEMONIC_LANGUAGES.ENGLISH, mnemonic_type=ELECTRUM_V2_MNEMONIC_TYPES.SEGWIT, ), mnemonic_type=ELECTRUM_V2_MNEMONIC_TYPES.SEGWIT, ) ).from_derivation(derivation=ElectrumDerivation(change=0, address=0)) print(hdwallet.address()) # bc1... 原生 SegWit 地址

完整可运行版本可直接参考官方示例 examples/hdwallet/electrum/v2/from_mnemonic.py，V1 的对应示例在 examples/hdwallet/electrum/v1/from_mnemonic.py。

六、2fa 模式：standard-2fa 与 segwit-2fa

2fa（Two-Factor Authentication）类型是为双因子场景设计的助记词变体，其密钥派生方式与对应的基础模式完全相同，区别只在"类型指纹"：

用法与标准模式完全一致，只需替换类型参数。测试数据中就有一条真实的 segwit-2fa 用例（12 词葡萄牙语助记词推导出bc1qwrjjrlw8p92dq8atuwv6nfvscxq8zvhsnvd9a6），可对照 tests/hdwallet/hdwallet/electrum/v2/segwit_2fa/test_segwit_2fa_from_entropy.py 复现。

# 仅示例：segwit-2fa 类型的关键参数 HDWallet( hd=ElectrumV2HD, mnemonic_type=ELECTRUM_V2_MNEMONIC_TYPES.SEGWIT_2FA, # "102" 前缀 mode=MODES.SEGWIT, ... )

⚠️ 注意：mnemonic_type必须与助记词实际类型一致，否则会在 is_valid 校验 阶段抛出MnemonicError。校验还会自动排除"恰好是合法 BIP39 或 V1 助记词"的边界情况，避免误判。

七、V1 旧版助记词：128 位 + 1626 词表

如果你手里是 Electrum 3.x 之前生成的 12 词助记词，用 V1 体系处理。其特点：

• 熵为 128 bit，按 4 字节一组、每组映射 3 个单词（模 1626 的进位算法），编解码实现在 ElectrumV1Mnemonic；
• 种子 = 对解码后的熵做SHA256 迭代 100,000 次，得到 64 位十六进制（32 字节），见 hdwallet/seeds/electrum/v1.py；
• V2 种子则是PBKDF2-HMAC-SHA512（2048 轮，盐值electrum，可附加助记密码），得到 128 位十六进制（64 字节），见 hdwallet/seeds/electrum/v2.py。

V1 钱包实例化与 V2 同构，只是hd=ElectrumV1HD且没有mode和mnemonic_type参数，输出固定为1...地址。

八、核心文件路径速查

九、常见问题 FAQ

Q1：segwit 助记词能生成 standard 地址吗？可以。mnemonic_type只负责类型校验，mode才决定路径与地址格式。把mode设为standard即可得到1...地址，反之亦然——这与 Electrum 官方客户端的行为保持一致。

Q2：12 词和 24 词怎么选？12 词提供 132 bit 熵，日常使用足够；24 词提供 264 bit 熵，适合多币种、多账户或安全要求更高的场景。

Q3：助记词语言可以混用吗？生成、解码必须使用同一语言（简体中文、英语、葡萄牙语、西班牙语四选一），词表文件位于 hdwallet/mnemonics/electrum/v2/wordlist/。

Q4：V2 助记词支持助记密码（passphrase）吗？支持。V2 种子推导时盐值为electrum + passphrase，只需在种子生成环节传入passphrase参数，助记词本身不变，钱包会完全不同。

Q5：如何判断我手里的助记词属于哪种类型？调用ElectrumV2Mnemonic.is_type(mnemonic, mnemonic_type)逐一比对四种前缀即可，或直接用 CLI 生成同类做交叉验证。

💪 小结：python-hdwallet 用统一的HDWallet门面把 Electrum 两代助记词体系、四种模式封装成了"传参即用"的体验——V1 处理存量老钱包，V2 覆盖 standard/segwit/2fa 全场景，配合 CLI 一行命令即可完成助记词到比特币地址的完整推导。