ProtocolCanary-Fixtures

一组版本化的规范兼容性测试数据，用于定义和测试Stellar协议的具体行为。A set of versioned specification compatibility test data used to define and test the specific behaviors of the Stellar protocol.

原始信息汇总

ProtocolCanary-Fixtures 数据集概述

基本信息

• 数据集地址：https://github.com/StellarCanary/ProtocolCanary-Fixtures
• 许可证：Apache-2.0
• 性质：Stellar Protocol Canary 的规范性兼容性夹具（fixtures）集合
• 内容形式：版本化的声明式测试数据语料库，不包含业务逻辑、服务器、数据库或可执行夹具代码

目的

该仓库回答一个问题：Protocol Canary 应该测试哪些确切的 Stellar 协议行为？

流程关系如下：

• 协议规范 / 上游实现 → 规范性夹具 → ProtocolCanary-Fixtures（本仓库）→ Protocol-Canary → 兼容性结果

• ProtocolCanary-Fixtures 定义测试什么

• StellarCanary/Protocol-Canary CLI 定义如何执行测试

• StellarCanary/ProtocolCanary-Action 在 GitHub CI 中对本仓库的夹具运行该 CLI

快速开始

验证器要求 Python 3.11 或更高版本（因其导入仅在 Python 3.11 才加入标准库的 tomllib）。无需安装其他依赖。

• python3 tools/validate/validate.py — 结构性夹具验证
• python3 -m unittest discover tests — 仓库测试套件

仓库关系

• Protocol-Canary 通过 canary_fixtures::load_directory 加载夹具，命令为：stellar-canary check --fixtures-dir <path-to-a-checkout-of-this-repo> --json
• 加载器递归遍历给定目录，将每一个 *.toml 文件解析为一个夹具
• 无 manifest.toml 文件：加载器将每个 .toml 文件视为夹具，单独的发现/枚举文件会被忽略或被误解析为格式错误的夹具
• 目录名仅为装饰性：xdr/、rpc/、soroban/、cap-0083/ 等仅为人类导航而存在；夹具的 surface、protocol、category 字段才是加载器和规划器所依据的
• 可将 --fixtures-dir 指向仓库根目录或单个 protocol-NN/ 目录

协议包（Protocol packs）

协议包	状态	说明
protocol-28/	活跃	CAP-0083、CAP-0085（XDR）；Protocol 28 RPC 身份；一个 Soroban 模拟冒烟夹具。按 surface 的夹具计数：4 xdr，1 rpc，1 soroban（共 6 个）。详见 docs/protocol-28.md
protocol-27/	尚未填充	0 个夹具。夹具仅在上游行为被独立验证后才添加，绝不作为占位符

协议包目录命名为 protocol-<N>，其中 <N> 是该包所针对的 Stellar 协议版本。协议包仅在有已验证的上游行为可记录时才创建。仅顶层的 protocol- 包目录如此命名；包内部目录仅为人类导航，会被加载器忽略。

夹具格式

每个夹具是一个 TOML 文件，包含公共元数据及特定于 surface 的主体：

公共字段：

• id — 必需，全树唯一
• protocol — 必需
• surface — 必需，取值为 "xdr" | "rpc" | "soroban"
• category — 必需，自由文本
• description — 必需
• source_reference — 协议特定夹具必需
• required_capabilities — 可选，kebab-case 能力字符串数组（如 soroban-contract、rpc-client）；缺少某项能力的目标项目会跳过该夹具而非使其失败
• input_file — 可选，相对于夹具文件的路径，指向外部存储的输入；验证器检查文件存在
• expected_file — 可选，相对于夹具文件的路径，指向外部存储的预期输出；同样进行存在性检查

input_file 与 expected_file 目前尚未被本仓库任何夹具使用（值通过 value_base64/expected_base64 内联），但格式支持它们。

当前支持的 RPC 方法：rpc surface 目前仅接受两个方法——get-network 和 get-latest-ledger。命名任何其他方法的夹具会被验证器拒绝。

断言词汇表

每个 surface 通过一小组 kind 值声明其预期结果，其他值在夹具解析时即失败。

Surface	字段	值	断言内容
xdr	kind	decode-success	value_base64 作为命名 type 成功解码
xdr	kind	decode-failure	value_base64 作为命名 type 解码时被拒绝——畸形输入必须失败，绝不静默解码
xdr	kind	roundtrip	解码 value_base64 并重新编码可复现相同字节
xdr	kind	encode-equals	解码 value_base64 并重新编码产生恰好等于 expected_base64 的结果（用于测试规范化）
rpc	[[assert]].kind	field-exists	方法响应包含命名的 field
rpc	[[assert]].kind	field-absent	响应不包含命名的 field
rpc	[[assert]].kind	field-equals	命名的 field 恰好等于 value
rpc	[[assert]].kind	field-type	命名的 field 具有 expected_type 命名的 JSON 类型
soroban	[expect].kind	simulation-success	simulateTransaction 成功且无错误
soroban	[expect].kind	simulation-error	simulateTransaction 失败——可选要求错误消息中出现 message_contains

一个 XDR 夹具携带单个顶层 kind；一个 RPC 夹具携带一个或多个 [[assert]] 表，全部必须通过；一个 Soroban 夹具携带一个 [expect] 表。夹具是声明式数据，绝非代码。

来源（Provenance）

每个协议特定夹具都引用一个 source_reference（CAP 编号、上游 XDR 定义或官方发布/API 参考），并携带头部注释说明已验证的内容、验证方式，以及（涉及实时网络调用者）何时、针对哪个端点验证。没有任何夹具断言无法追溯到权威上游来源的值。

验证

要求 Python 3.11+（验证器使用标准库 tomllib 模块）；CI 固定为 3.11.16。

• python3 tools/validate/validate.py — 验证架构一致性、唯一 ID、协议/surface 枚举、来源引用以及所引用文件的存在性。仅为结构性验证，绝不自行执行兼容性检查
• CI（.github/workflows/validate.yml）在每次推送和拉取请求时运行上述验证，加上 python3 -m unittest discover tests 以及夹具徽章新鲜度检查
• schemas/fixture-v1.schema.json 是本仓库面向编辑器的验证器规则镜像，由 tools/validate/schema_sync.py 保持同步

结构性验证并非实时网络验证：绿色 CI 仅意味着每个夹具格式良好且内部一致，并不意味任何夹具的实时网络断言刚刚针对真实网络重新检查过。protocol-28/ 中的 RPC 和 Soroban 夹具是在特定日期针对实时 soroban-testnet.stellar.org 端点手动验证的，该时间点观测仅记录在每个夹具的头部注释和 docs/protocol-28.md 中。

可用的 Makefile 目标：

命令	作用
make validate	仅结构性夹具验证
make badge	重新生成 README.md 的夹具计数徽章
make badge-check	若徽章过时则失败（CI 所运行）
make test	仅仓库测试套件
make check	按 CI 顺序执行上述全部，遇首个失败即停止

夹具徽章

文件顶部的徽章报告仓库当前夹具总数，其数字是生成的，非手工维护：

• python3 tools/badge/badge.py — 就地重新生成 README.md
• python3 tools/badge/badge.py --check — 若徽章过时则退出非零

tools/badge/badge.py 使用与 tools/validate/validate.py 相同的发现规则统计 protocol-*/ 包下的每个 *.toml 文件，然后仅重写 README.md 中 <!-- fixtures-badge:start --> / <!-- fixtures-badge:end --> 标记之间的区域。

安全

无秘密、无私钥、无可执行夹具代码、无交易提交——夹具文件必须被任何消费者视为不受信任的输入。

维护者与社区

• 维护者：@Hollujay — 可通过本仓库的 GitHub 个人资料联系；本项目未发布其他官方联系渠道
• 社区：尚无专门社区渠道。贡献和讨论通过本仓库的 GitHub issues 和 pull requests 进行
• 贡献：参见 CONTRIBUTING.md
• 安全：参见 SECURITY.md
• 行为准则：参见 CODE_OF_CONDUCT.md

搜集汇总

数据集介绍

构建方式

该数据集以Stellar协议规范及上游实现为权威依据，将经过独立验证的协议行为提炼为声明式测试夹具。每个夹具以TOML文件形式承载，内含唯一标识、协议版本、测试表面（如XDR、RPC、Soroban）及类别等元数据，并附来源引用与验证说明。夹具按协议版本组织于protocol-<N>目录中，目录内可依人类导航需要设置xdr、rpc、soroban等子目录，但加载器仅递归解析全部TOML文件，路径本身不参与语义判断。数据集不包含业务逻辑或可执行代码，仅作为版本化的规范测试语料存在。

特点

该数据集的核心特征在于其声明性与可追溯性。全部夹具均为静态数据，不含任何脚本或可执行指令，消费者须将其视为不可信输入。每个协议相关夹具均标注来源引用，记录验证内容、方式及涉及实时网络调用时的端点与日期，确保断言值可回溯至权威上游。协议包仅在有已验证行为时创建，避免占位性内容。此外，夹具格式通过JSON Schema与验证器常量同步校验，任何规则变更若未镜像至模式定义将导致持续集成失败，从而维持结构一致性。

使用方法

使用该数据集时，需通过Protocol-Canary命令行工具加载夹具目录，例如执行stellar-canary check --fixtures-dir <路径> --json，加载器将递归遍历指定目录并解析所有TOML文件为独立夹具。用户可将路径指向仓库根目录，亦可指向单一protocol-NN目录以限定特定协议包范围，协议过滤机制确保混合协议目录下的加载安全。运行环境要求Python 3.11及以上版本，以支持标准库tomllib模块。结构验证可通过python3 tools/validate/validate.py执行，该步骤仅校验模式合规性、标识唯一性及引用文件存在性，不执行实时网络兼容性检查。

背景与挑战

背景概述

ProtocolCanary-Fixtures诞生于Stellar协议生态对跨版本兼容性进行系统性验证的需求之中。Stellar网络通过协议版本迭代持续引入XDR结构、RPC接口及Soroban智能合约语义的演进，而不同实现方对同一规范的理解偏差可能导致共识分裂或服务异常。该数据集由StellarCanary组织维护，核心研究者包括维护者Hollujay，旨在为Protocol-Canary工具提供权威的声明式测试基准，回答“Stellar协议应测试何种精确行为”这一根本问题。其以协议包形式组织夹具，首个活跃包protocol-28覆盖CAP-0083、CAP-0085等规范，为兼容性回归测试奠定了可追溯、可版本化的数据基础。

当前挑战

该数据集所应对的核心挑战在于，如何将不断演进的Stellar协议规范转化为精确、无歧义且可独立验证的兼容性断言。其领域问题类似于接口兼容性验证：当上游XDR定义或RPC行为发生变更时，测试基准必须同步反映真实语义，而不能沦为占位符或过时断言。构建过程中的挑战包括：确保每条夹具均可追溯至权威来源（CAP编号或上游实现），同时避免引入可执行代码；结构验证通过并不等同于实时网络行为仍成立，因此RPC与Soroban夹具需人工对活体测试网进行时点观测并记录日期；此外，每新增一种XDR类型或RPC方法，均需先变更Protocol-Canary核心库，再更新夹具与模式镜像，形成跨仓库的严格同步约束。

常用场景

经典使用场景

在区块链协议兼容性测试领域，ProtocolCanary-Fixtures作为Stellar协议金丝雀测试的规范化兼容性夹具库，其最经典的使用场景是充当协议行为断言的权威事实来源。该数据集以声明式TOML文件的形式，为XDR编解码、RPC接口响应以及Soroban智能合约模拟等协议表面提供标准化的输入输出预期，供Protocol-Canary命令行工具加载并执行兼容性校验，从而在持续集成流程中自动化地判定目标实现是否与规范一致。

解决学术问题

该数据集着力解决分布式系统与区块链工程研究中的协议一致性验证难题，即如何将抽象的协议规范转化为可复现、可追溯、可版本化的测试事实，从而消除不同实现之间因语义歧义而产生的互操作性障碍。通过为每个夹具标注来源引用与验证日期，它为学术界和工业界提供了一套可审计的基准，使协议演化过程中的兼容性退化能够被及早发现，对推动形式化验证与实证软件工程研究具有积极意义。

衍生相关工作

围绕该数据集已衍生出若干相关经典工作，包括负责定义测试执行方式的Protocol-Canary命令行工具，以及将其集成至GitHub CI环境的ProtocolCanary-Action自动化动作。这些工作与夹具库共同构成从协议规范、规范化夹具、执行引擎到兼容性结果的完整工具链，并推动了面向Stellar协议版本的打包机制，例如protocol-28包对CAP-0083与CAP-0085等变更的系统性覆盖。