• 区块链
• 密码学

本指南以仓库内 test/fixtures/core/README.md 为主体，系统解析 bitcoinjs-lib 测试体系中最特殊的一块：直接移植自 Bitcoin Core 官方的数据驱动测试数据（fixtures）。你将了解到这批数据文件各自验证了库的哪些能力、其 JSON 格式如何被测试代码消费，以及 bitcoinjs-lib 刻意排除tx_invalid.json、script*.json、alertTests.raw三类数据的深层原因——这背后是"只做交易/区块的解析与签名，不做脚本虚拟机与网络交互"的架构边界。

一、core 夹具目录的定位：数据驱动的互操作测试

按照 test/fixtures/core/README.md 的说明，test/fixtures/core/目录保存的是"面向 Bitcoin 各个方面的数据驱动测试"（data-driven tests for various aspects of Bitcoin）。所谓数据驱动，指的是测试逻辑与测试数据彻底分离：被测的"输入/期望输出"全部以 JSON 形式存放在数据文件中，测试代码只需加载这些文件、逐条断言即可。

这批数据的来源不是 bitcoinjs-lib 团队自行编造，而是从 Bitcoin Core 官方测试集移植而来，因此它们天然承担着互操作性验证的职责：只要 bitcoinjs-lib 能通过 Bitcoin Core 社区公认的样本数据，就说明其编码/解码行为与比特币主网实际生态保持一致。这也是该目录位于test/fixtures/（而非test/integration/）的原因——它不依赖任何真实节点或网络，属于纯离线、确定性的单元级测试。

二、目录内容总览：7 个数据文件与对应被测能力

目录中除 README 外共有 7 个 JSON 数据文件，它们与测试文件 test/bitcoin.core.spec.ts 中的导入一一对应：

这一对应关系在 test/bitcoin.core.spec.ts 顶部可直观看到：8 行 import 语句恰好对应上述 7 类数据（sig_canonical与sig_noncanonical合并为一组 DER 测试）。

三、逐个解析数据文件格式与对应测试

3.1 base58_encode_decode.json：最朴素的编解码对拍

该文件是纯[hex, base58]二元组数组。以 test/fixtures/core/base58_encode_decode.json 开头几行为例：

[ ["", ""], ["61", "2g"], ["626262", "a3gV"], ["73696d706c792061206c6f6e6720737472696e67", "2cFupjhnEsSn59qHXstmK2ffpLv2"], ["00000000000000000000", "1111111111"] ]

其中既有空串、单字节这样的边界情况，也有0000...这样能验证 Base58 算法"前导零用1字符表示"特性的样本。测试代码（test/bitcoin.core.spec.ts）对每个二元组做双向断言：

• base58.decode(fb58)的十六进制结果必须等于fhex；
• Buffer.from(fhex, 'hex')经base58.encode后必须等于fb58。

注意这里直接使用第三方bs58库而非 bitcoinjs-lib 自身 API，说明该夹具主要用于校验依赖库行为，为上层 Base58Check 提供地基保障。

3.2 base58_keys_valid.json / base58_keys_invalid.json：地址版本字节的验证

合法地址文件采用三元组结构：[Base58Check 地址, 十六进制 payload, 参数对象]。例如 test/fixtures/core/base58_keys_valid.json 中的：

[ "1AGNa15ZQXAZUgFiqJ2i7Z2DPU2J6hW62i", "65a16059864a2fdbc7c99a4723a8395bc6f188eb", { "addrType": "pubkey", "isPrivkey": false, "isTestnet": false } ]

参数对象的三个字段含义：

• addrType："pubkey"（P2PKH）或"script"（P2SH），决定使用网络的哪个版本字节；
• isPrivkey：是否为私钥格式（测试中遇到isPrivkey: true会直接return跳过，因为本库的toBase58Check面向地址哈希）；
• isTestnet：选择bitcoin.networks.testnet还是bitcoin.networks.bitcoin。

测试代码（test/bitcoin.core.spec.ts）先建立映射pubkey → pubKeyHash、script → scriptHash，再按网络取版本字节，最终断言address.toBase58Check(hash, version)与期望地址一致。版本字节的实际取值可在 ts_src/networks.ts 中查到：主网pubKeyHash: 0x00、scriptHash: 0x05，测试网pubKeyHash: 0x6f、scriptHash: 0xc4。

非法地址文件则是纯字符串数组（test/fixtures/core/base58_keys_invalid.json），包含空串、单字符"x"、超长字符串、错误校验和等多种畸形输入。测试断言（test/bitcoin.core.spec.ts）address.fromBase58Check必须抛出匹配/Invalid (checksum|network)|too (short|long)/的错误。与之对应的实现位于 ts_src/address.ts：fromBase58Check内部先做 Base58Check 解码校验，再readUInt8取出版本字节，返回{ version, hash }。

3.3 blocks.json：区块级解析与哈希验证

该文件是对象数组，每个对象含id、transactions（交易数量）与hex（完整区块十六进制）三个字段。例如 test/fixtures/core/blocks.json 中第一个样本：

{ "id": "0000000000013b8ab2cd513b0261a14096412195a72a0c4827d229dcc7e0f7af", "transactions": 9, "hex": "0100000090f0a9f110702f80..." }

测试（test/bitcoin.core.spec.ts）调用bitcoin.Block.fromHex(f.hex)，断言block.getId()等于id、block.transactions!.length等于transactions。getId()的实现位于 ts_src/block.ts，它将区块头做双 SHA-256 后按字节反转得到区块 ID——这正是比特币区块浏览器中区块哈希的展示形式。

3.4 tx_valid.json：只解码、不验证

tx_valid.json是这批数据中"信息密度"最高的文件，其头部注释（test/fixtures/core/tx_valid.json）完整说明了条目格式：

[[[prevout hash, prevout index, prevout scriptPubKey], [input 2], ...], serializedTransaction, verifyFlags]，且只含单个字符串的对象会被忽略（"Objects that are only a single string are ignored"）。

文件中还包含若干真实历史交易样本的注释说明，例如第一个样本对应交易23b397edccd3740a74adb603c9756370fafcde9bcc4483eb271ecad09a94dd63——它包含一个"OpenSSL 能接受的非规范编码签名"，同时是历史上第一笔标准形式的 OP_CHECKMULTISIG 交易。

测试消费逻辑（test/bitcoin.core.spec.ts）：

• if (f.length === 1) return;与数据文件头部注释严格呼应，跳过纯注释条目；
• 用Transaction.fromHex(fhex)解析交易；
• 对每个输入断言：prevOutHash需先将测试数据reverse()再与txIn.hash比较（文件注释明确说明 "test data is reversed"，即测试数据按显示字节序存储，而库内部按内部字节序）；
• 输入索引用txIn.index & 0xffffffff与期望值比较（库以 UInt32 读取，而非 Int32）。

verifyFlags（如"P2SH"、"P2SH,NULLDUMMY"）字段在测试中被刻意忽略（源码中保留了一行 TODO 注释），因为 bitcoinjs-lib 不做脚本验证，这正呼应了下一节的主题。

3.5 sighash.json：签名哈希的黄金样本

sighash.json以一行表头开头（test/fixtures/core/sighash.json）：

["raw_transaction, script, input_index, hashType, signature_hash (result)"]

每条记录为五元组：原始交易 hex、赎回脚本 hex、输入索引、签名哈希类型、期望的签名哈希（注意期望值同样是反转后的显示字节序）。样本中的hashType既有正数也有负数（如-1391424484），这是因为原始数据按有符号 32 位存储，而库内部按无符号处理。

对应测试（test/bitcoin.core.spec.ts）做了四层验证：

1. Transaction.fromHex(txHex)后再toHex()必须原样还原，保证解析无损；
2. 赎回脚本经script.decompile→script.compile往返后字节一致；
3. transaction.hashForSignature(inIndex, script, hashType)的结果反转后与期望哈希相等；
4. 用hashForWitnessV0以hashType < 0 ? 0x100000000 + hashType : hashType转成 UInt32 后调用，确保不抛异常。

其中hashType的语义在 ts_src/transaction.ts 有完整定义：SIGHASH_ALL = 0x01、SIGHASH_NONE = 0x02、SIGHASH_SINGLE = 0x03、SIGHASH_ANYONECANPAY = 0x80，另有SIGHASH_OUTPUT_MASK = 0x03与SIGHASH_INPUT_MASK = 0x80用于位运算提取类型。测试代码还会把 hashType 解析成"SIGHASH_ALL | SIGHASH_ANYONECANPAY"这类可读名字作为用例标题。

3.6 sig_canonical.json / sig_noncanonical.json：DER 签名的严格性测试

sig_canonical.json是规范 DER 签名的十六进制列表（test/fixtures/core/sig_canonical.json），如"300602010002010001"及两条完整的 P2PKH 签名样本。测试（test/bitcoin.core.spec.ts）对每条做decode → encode往返，结果必须与原始 hex 完全一致。

sig_noncanonical.json则采用描述字符串与 hex 交替排列的结构（test/fixtures/core/sig_noncanonical.json），每条非法样本前用一句话说明违规点：

"too short:", "30050201FF020001", "too long:", "30470221005990e0584b2b238e1dfaad8d6ed69ecc1a4a13ac85fc0b31d0df395eb1ba6105022200002d5876262c288beb511d061691bf26777344b702b00f8fe28621fe4e566695ed01", "hashtype:", "304402205990e0584b2b238e1dfaad8d6ed69ecc1a4a13ac85fc0b31d0df395eb1ba610502202d5876262c288beb511d061691bf26777344b702b00f8fe28621fe4e566695ed11", "R padded:", "30450221005990e0584b2b238e1dfaad8d6ed69ecc1a4a13ac85fc0b31d0df395eb1ba610502202d5876262c288beb511d061691bf26777344b702b00f8fe28621fe4e566695ed01"

覆盖的违规类型包括：DER 序列过长/过短、hashType 非法、R/S 长度为零、R/S 为负数、R/S 过度填充（excessively padded）等。测试（test/bitcoin.core.spec.ts）只取奇数索引的 hex（i % 2 !== 0），并断言script.signature.decode抛出匹配Expected DER (integer|sequence)|(R|S) value ...|Invalid hashType的错误。

底层的严格性来自 ts_src/script_signature.ts：decode先读取末字节作为 hashType，用isDefinedHashType校验（仅允许0x01/0x02/0x03/0x81/0x82/0x83），再交给bip66.decode解析 DER 结构；encode则将 64 字节签名拆分 R/S 做 DER 编码后拼接 hashType 字节。整个编解码链路与 Bitcoin Core 的严格 DER 规则保持一致。

四、bitcoinjs-lib notes：哪些 Bitcoin Core 测试被刻意排除，为什么

README 明确声明：该目录并不包含全部 Bitcoin Core 测试，并逐条解释了三个缺失项的取舍理由。这一小节是理解 bitcoinjs-lib 架构边界的关键，也是本文档区别于普通测试说明的核心价值所在。

4.1 alertTests.raw：不直连网络的取舍

alertTests.raw是 Bitcoin Core 用于测试系统警报消息处理的数据。README 给出的理由是：

Bitcoin-js 不直接与比特币网络交互。（"Bitcoin-js does not interact with the Bitcoin network directly."）

bitcoinjs-lib 定位是纯客户端密码学/数据结构库：它只负责在本地构造、解析、签名和编码数据，不实现 P2P 协议、不维护节点状态、不处理网络消息。因此与网络消息层绑定的警报测试对它毫无意义。想要在真实网络上验证行为的用户，可以借助仓库 test/integration/_regtest.ts 中的 regtest 集成测试框架另行搭建环境，但那不属于 core 夹具的职责范围。

4.2 tx_invalid.json：无脚本虚拟机

Bitcoin Core 的tx_invalid.json专门存放应被判定为无效的交易（通常带脚本验证失败原因）。README 的解释分两层：

bitcoinjs-lib 无法执行脚本（cannot evaluate Scripts），因此测试这个没有意义；但它可以解码合法交易，所以保留了tx_valid.json。

这解释了为什么两个文件"一留一删"：tx_valid.json只要求反序列化能力，bitcoinjs-lib 的 Transaction.fromHex 完全可以胜任；而tx_invalid.json的判定核心在于"脚本执行失败"，这需要完整的脚本虚拟机（Script VM）与共识规则引擎，超出了本库范围。同理，tx_valid.json中的verifyFlags字段（如P2SH）在测试中也被显式忽略——验证标志本来就是为脚本解释器准备的。

4.3 script*.json：脚本执行非本库职责

script*.json系列（Bitcoin Core 中的脚本解释器测试）被排除的理由与tx_invalid.json一致：

bitcoinjs-lib 无法执行脚本，使测试失去意义。

需要澄清的是：bitcoinjs-lib 并非完全没有脚本能力——ts_src/script.ts 提供了脚本的反序列化/再序列化（decompile/compile）、操作码定义（ts_src/ops.ts）等工具，并用于构建p2pkh、p2sh、p2wpkh等支付模板（见 ts_src/payments 目录）。它缺少的是"在栈上逐条执行操作码并判定真伪"的解释器。这三条排除项共同勾勒出 bitcoinjs-lib 的能力边界：解码与构造（做得到）、执行与验证（刻意不做）。

五、从文档到测试：bitcoin.core.spec.ts 如何消费这些数据

文档描述的数据与测试代码之间是严丝合缝的契约关系。整个测试文件 test/bitcoin.core.spec.ts 按数据文件组织为 5 个 describe 块：

1. base58：遍历base58_encode_decode.json，做双向编解码断言；
2. address.toBase58Check / address.fromBase58Check：分别消费base58_keys_valid.json与base58_keys_invalid.json，前者验证版本字节映射，后者验证畸形输入抛错；
3. Block.fromHex：消费blocks.json，断言区块 ID 与交易数量；
4. Transaction.fromHex / Transaction：消费tx_valid.json与sighash.json，验证交易反序列化与签名哈希计算（含hashForWitnessV0）；
5. script.signature.decode：消费sig_canonical.json（往返一致）与sig_noncanonical.json（严格抛错）。

运行方式与仓库其他测试一致，例如执行npm test（或针对该文件的npx mocha）即可在本地复现全部断言。整个套件零网络依赖、零节点依赖，这正是数据驱动测试的核心收益：任何一次修改若破坏了与 Bitcoin Core 数据的兼容性，会立刻被这些黄金样本捕获。

六、许可证与引用注意事项

README 的最后一部分明确了这批数据文件的版权归属：

目录中的数据文件版权归The Bitcoin Core developers（2012-2014），按MIT/X11 软件许可证分发（见随附的 COPYING 文件或 opensource.org 的 MIT 许可文本）。

这意味着：虽然数据被嵌入 bitcoinjs-lib 仓库用于测试，但其上游著作权仍归 Bitcoin Core 开发者所有；任何将这批夹具数据二次分发或引入其他项目的行为，都应保留该版权声明并遵循 MIT/X11 条款。这也是在文档中单独开辟 License 小节、而非混入通用项目 LICENSE 的原因——它是对第三方数据来源的诚实标注。

总结

test/fixtures/core/目录是 bitcoinjs-lib 与比特币生态"官方标准"之间的校验锚点：7 个 JSON 数据文件覆盖 Base58、Base58Check 地址、区块解析、交易反序列化、签名哈希与 DER 签名六大能力，全部由 test/bitcoin.core.spec.ts 以数据驱动方式消费；README 则用三条简明结论划清了架构边界——不直连网络（排除alertTests.raw）、不执行脚本（排除tx_invalid.json与script*.json）、只解码合法交易（保留tx_valid.json）。理解这份文档及其背后的取舍，既能帮你快速上手为 bitcoinjs-lib 贡献新测试，也能让你更准确地判断这个库在真实项目中的适用边界。

• 区块链
• 密码学