nautilus_trader Derive 适配器：EIP-712 自托管签名管线的第三方材料引用与字节级等价性验证

nautilus_trader Derive 适配器EIP-712 自托管签名管线的第三方材料引用与字节级等价性验证【免费下载链接】nautilus_traderProduction-grade Rust-native trading engine with deterministic event-driven architecture项目地址: https://gitcode.com/GitHub_Trending/na/nautilus_trader本篇技术指南聚焦于 nautilus_trader 的 Derive 适配器如何以第三方材料的方式引用 Derive.xyz 官方 Python 签名 SDKv2-action-signing-python并以该 SDK 为行为基准构建 Rust 端 EIP-712 签名管线的字节级等价性测试oracle 向量验证。读完本文你将掌握这份第三方许可声明的完整含义、oracle 向量夹具fixture的生成与重放机制、签名管线的底层实现细节以及未来上游版本升级时的再固定 再生成流程。一、文档定位一份有技术内涵的第三方许可证声明仓库中的 THIRD_PARTY_LICENSES.md 虽然以许可证声明命名但它的技术分量远超普通合规文件。它回答了一个关键工程问题nautilus_trader 的 Rust 版 Derive 自托管签名协议实现其行为正确性以什么为基准来验证答案是该文档与源码共同揭示的Rust 端src/signing/目录下的 EIP-712 签名管线是原始实现original implementation并非对上游代码的移植或封装上游 Python SDK 仅作为行为参考behavioral reference用于生成 oracle 向量并记录在 signing_trade_action_vectors.json 中向量由 generate_oracle.py 生成向量元数据中记录固定的上游修订版本。这种独立实现 官方参考实现做等价性对拍的做法让适配器在完全自研的同时又能与 Derive 官方生态保持字节级一致。二、第三方材料清单原文档核心内容原文档声明的第三方材料如下这是整个验证体系的依据项目值上游项目Derive.xyz -v2-action-signing-python用途作为 Rust EIP-712 签名管线的行为参考生成 oracle 向量固定修订版本d1914d61985e33559244da242892c7255b6fd0ca固定版本号0.0.132025-08-21 提交归属作者Derive.xyzjoshuaderive.xyz、8baller8ballerstation.codes声明于上游pyproject.toml许可证MIT经 pyproject classifier 声明固定修订版本的上游仓库未附带 LICENSE 文件向量生成脚本generate_oracle.py向量输出文件signing_trade_action_vectors.json两点需要特别留意许可证信息以 pyproject classifier 为准上游仓库在固定修订版本上没有 LICENSE 文件因此 MIT 判定来自pyproject.toml中的声明。这一细节同时被写进了 oracle 向量的元数据见下文。上游来源项目地址为github.com/derivexyz/v2-action-signing-python仓库源码中 signing/mod.rs 的文档注释亦注明了该来源。三、为什么需要第三方参考Derive 自托管签名协议Derive 是构建在 Derive Chain 上的去中心化衍生品交易协议。其安全模型中每一个改变状态的请求都必须携带一个 EIP-712 typed-data 签名由会话密钥session key对 secp256k1 私钥签名并由智能合约钱包验证。这意味着交易、改单、撤单等动作的签名格式是协议级约定容不得半点字节偏差——任何编码顺序、填充方式或哈希组合的错误都会导致合约端验签失败或签名被拒绝。这正是引入官方 SDK 作为 oracle 的原因Rust 实现必须与官方 Python 实现产生完全相同的字节序列才能确信协议兼容。协议常量协议常量来自 Derive 官方 Protocol Constants 参考文档并固化在 consts.rs 中Domain separatormainnet 为0xd96e5f90...c60441btestnet 为0x9bcf4dc0...e3dd1105Action typehash0x4d7a9f27c403ff9c0f19bce61d76d82f9aa29f8d6d4b0c5474607d9770d1af17跨网络一致Trade module 合约地址mainnet0xB8D20c2B...5b5e7btestnet0x87F28638...3f2be最小签名 TTLMIN_SIGNATURE_TTL 5 分钟v2 文档要求signature_expiry_sec至少在未来 5 分钟触发单签名 TTLTRIGGER_ORDER_SIGNATURE_TTL 31 天mainnet 要求触发单的过期时间在 3090 天区间一天缓冲规避时钟漂移小数定标所有链上十进制字段以 1e18 定点整数表示DECIMAL_SCALE。这些常量既用于生产配置的默认值也作为 oracle 测试的比对基准——见下文第五节。四、oracle 向量字节级等价性的证据链4.1 向量夹具的结构signing_trade_action_vectors.json 是验证的核心夹具结构为metadata vectorsmetadata记录了来源github.com/derivexyz/v2-action-signing-python、上游版本0.0.13、固定修订版本d1914d...、生成脚本路径、许可证声明MIT含上游无 LICENSE 文件的说明以及一条重要注释签名使用 RFC 6979 确定性随机数因此每个值都是字节级相等目标byte-equality targetvectors是 5 组测试向量对应 5 个行为分支见下节。每组向量完整记录了从输入到签名的全链路中间值domain_separator / action_typehash / module_address / subaccount_id nonce / signature_expiry_sec / owner / session_key / signer tradeasset_address、sub_id、limit_price、amount、max_fee、recipient_id、is_bid module_dataABI 编码后的完整字节 module_data_hash / action_hash / typed_data_hash / signature以第一组向量limit_buy_round_mainnet为例节选{ case: limit_buy_round_mainnet, environment: mainnet, domain_separator: 0xd96e5f90797da7ec8dc4e276260c7f3f87fedf68775fbe1ef116e996fc60441b, action_typehash: 0x4d7a9f27c403ff9c0f19bce61d76d82f9aa29f8d6d4b0c5474607d9770d1af17, module_address: 0xB8D20c2B7a1Ad2EE33Bc50eF10876eD3035b5e7b, subaccount_id: 30769, nonce: 1695836058725001, signature_expiry_sec: 2147483647, trade: { asset_address: 0x000000000000000000000000000000000000abcd, sub_id: 42, limit_price: 100, amount: 1, max_fee: 1000, recipient_id: 30769, is_bid: true }, module_data_hash: 0xc9adef7e1b0648c010e846ee4a30ad72a3320279ab75b986e296dd9b9cb39c10, signature: 0x9f28ed4e5b014e5214143d4060ea7758e4c8f837a3287841909b046caf43a6fd18a7707f30241f6fafff7ba53f839381390e13354264d984ea648de6c20369d31c }注意向量中的会话密钥0x2ae8be44...a4816bbd和所有者地址0x8772185a...5d698来自上游 SDK 自带的测试套件不控制任何真实资金。4.2 五个行为分支的覆盖设计generate_oracle.py 中的CASES数组精心选择了 5 组输入覆盖交易编码器和 action-hash 组合的各个行为分支用例覆盖点limit_buy_round_mainnetmainnet 环境、整数价格、买单bidlimit_sell_fractional_testnettestnet 环境、小数价格与数量3500.01 / 1.25、卖单sell_negative_amount_testnet负数 amount-0.75的 ABI 编码int256 补码option_buy_large_sub_id_mainnet超出 64 位范围的期权 sub_id2^95 量级的 uint256 编码limit_buy_zero_max_fee_testnetmax_fee为零的边界情形由于private/order、private/trigger_order、private/replace都通过同一条 EIP-712 管线对TradeModuleData签名一组 trade 模块向量即可覆盖全部签名面signing surface。4.3 为什么字节相等是有效的验证oracle 成立的关键前提是RFC 6979 确定性随机数相同输入在任何实现、任何时间运行都产生相同签名。这意味着 Rust 实现与 Python SDK 对相同输入产出的module_data、module_data_hash、action_hash、typed_data_hash乃至最终 65 字节签名都必须与夹具逐字节相等byte equality而不是语义等价。五、Rust 签名管线的源码级实现5.1 三步哈希管线signing/mod.rs 的模块文档给出了完整管线action_hash keccak256(abi.encode( [bytes32, uint, uint, address, bytes32, uint, address, address], [ACTION_TYPEHASH, subaccount_id, nonce, module_address, keccak256(module_data_abi_encoded), signature_expiry_sec, owner, signer], )) typed_data_hash keccak256(0x1901 || DOMAIN_SEPARATOR || action_hash) signature secp256k1_sign(typed_data_hash, signer_key)对应实现分布在 eip712.rs 中compute_action_hash将 8 字段 ABI 元组typehash、subaccount、nonce、module、module_data_hash、expiry、owner、signer编码后取 keccak256。元组字段的顺序是承载字节等价性的协议约定——测试test_compute_action_hash_pins_byte_layout用固定期望值0x509b526a...锁死布局任何字段交换、删除或重排都会立刻被检测compute_typed_data_hash拼接0x19 0x01前缀 domain separator action_hash 后取 keccak256测试test_compute_typed_data_hash_includes_19_01_prefix专门验证前缀参与哈希SignedAction::sign先校验过期时间见 5.3再走完模块编码 → 模块哈希 → action 哈希 → typed-data 哈希 → secp256k1 签名全流程签名结果以 65 字节原始形式保存并通过signature_hex()输出0x前缀的 130 字符十六进制串。5.2 Trade 模块的 ABI 编码modules/trade.rs 实现TradeModuleData其 ABI 元组为(address, uint256, int256, int256, uint256, uint256, bool)对应(asset_address, sub_id, limit_price, amount, max_fee, recipient_id, is_bid)全部为静态类型编码结果是7 个 32 字节字测试test_encode_produces_seven_static_words断言长度恰为 224 字节limit_price与amount在 ABI 层是有符号 int256即使价格通常非负max_fee是无符号 uint256 且拒绝负数十进制字段乘以DECIMAL_SCALE1e18转为定点整数负数amount编码为 int256 补码测试test_encode_negative_amount_is_two_complement断言符号扩展字节为0xff地址左填充 12 字节零、sub_id大端 uint256、is_bid布尔打包为0x01/0x00均有对应单元测试逐一锁定编码指纹测试test_keccak_of_encoded_payload_is_stable将编码结果的 keccak256 锁死为0xc9adef7e...9cb39c10——这恰好与 oracle 向量中的module_data_hash一致形成测试与夹具的交叉印证。5.3 过期时间与随机数管理签名安全还依赖两个支撑模块过期校验SignedAction::sign会先以MIN_SIGNATURE_TTL5 分钟校验signature_expiry_sec不足则返回TypedDataError::ExpiryTooSoon测试test_sign_rejects_expiry_that_is_too_soon以 1 分钟过期验证拒绝路径系统时钟早于 UNIX 纪元则返回ClockBeforeEpoch。nonce 管理nonce.rs 实现进程级(wallet, subaccount)随机数分配器。Derive 的 venue schema 定义唯一 nonce 为 UTC 毫秒 至多 3 位后缀分配器采用utc_ms * 1000 suffix格式保证同毫秒内单调递增、时钟回拨时在最后逻辑毫秒上继续推进而非倒退、按(wallet, subaccount)独立跟踪钱包地址统一转小写避免 checksum 形式产生重复 nonce、DashMap分片 compare_exchange循环保证并发安全。5.4 签名上下文解析signing/context.rs 的resolve_signing_context将凭据钱包地址、会话密钥、子账户 ID与 DeriveExecutionClientConfig 结合解析出完整的SigningContextdomain separator、typehash、trade module 地址等协议常量优先取配置覆盖值未配置时回落为consts.rs中的环境默认值max_fee_per_contract为必填项。六、等价性测试如何在 Rust 中重放oracle 测试直接内嵌在 eip712.rs 的#[cfg(test)]模块中通过include_str!(../../test_data/common/signing_trade_action_vectors.json)将夹具编译进测试二进制。核心测试链包括test_oracle_fixture_records_upstream_provenance仅强制校验元数据四要素source、version、revision、generator非空——刻意不锁定具体值这样未来换用新上游版本重新生成夹具时无需改动测试结构test_oracle_vectors_use_production_protocol_constants逐一断言夹具中每个向量的 domain separator、typehash、module 地址与common::consts中生产的常量一致防止夹具自洽但脱离线上配置的陷阱test_signing_matches_upstream_sdk_oracle_vectors真正的对拍测试——对每个向量用 Rust 实现重新编码module_data、计算module_data_hash、action_hash、typed_data_hash并签名逐字节断言与上游夹具相等。此外还有签名可恢复性测试test_sign_produces_recoverable_signature从 65 字节签名恢复地址并与会话密钥比对模拟合约端反向验签和签名在 Debug 输出中脱敏REDACTED测试。七、版本固定策略与未来升级路径固定修订版本是 oracle 有效性的前提。当前钉在d1914d61985e33559244da242892c7255b6fd0ca0.0.13。文档明确给出了升级流程1. 更换上游版本例如未来的 V3 signer重新固定修订版本 2. 重新运行 generate_oracle.py 生成新夹具元数据记录新 revision 3. Rust 测试结构保持不变也就是说换版本只是一次re-pin 再生成不涉及 Rust 测试逻辑的任何改动——这正是元数据校验测试刻意不锁定具体版本值的原因。重新生成夹具的操作步骤记录在 generate_oracle.py 的模块文档中git clone https://github.com/derivexyz/v2-action-signing-python cd v2-action-signing-python git checkout upstream_revision # UPSTREAM_REVISION in this script python3 -m venv .venv .venv/bin/pip install . .venv/bin/python nautilus_trader 仓库根目录/crates/adapters/derive/tests/oracle-py/generate_oracle.py生成器按自身所在位置解析默认输出路径因此无论从哪个工作目录运行都会把夹具写入test_data/common/signing_trade_action_vectors.json也可用--out参数覆盖。值得注意的工程细节生成器在记录 SDK 私有计算的action_hash、typed_data_hash时会独立重算typed-data hashkeccak256(0x1901 || domain || action_hash)并与之比对不一致即报错——这为夹具本身提供了防篡改护栏避免以错误实现为基准。八、许可证合规要点从合规角度看该声明明确了上游v2-action-signing-python以MIT许可证使用依据 pyproject classifier 声明由于固定修订版本上游仓库未附带 LICENSE 文件归属与许可信息需以官方元数据为准归属作者为 Derive.xyzjoshuaderive.xyz与 8baller8ballerstation.codes。这一信息同时被冗余记录在 oracle 夹具的metadata.license字段中形成文档与数据的双重留痕便于审计与追溯。九、相关文件索引第三方许可证声明crates/adapters/derive/licenses/THIRD_PARTY_LICENSES.md签名模块总览crates/adapters/derive/src/signing/mod.rsEIP-712 实现与 oracle 测试crates/adapters/derive/src/signing/eip712.rsTrade 模块 ABI 编码器crates/adapters/derive/src/signing/modules/trade.rsNonce 分配器crates/adapters/derive/src/signing/nonce.rs签名上下文解析crates/adapters/derive/src/signing/context.rs协议常量crates/adapters/derive/src/common/consts.rs适配器配置crates/adapters/derive/src/config.rsOracle 生成器crates/adapters/derive/tests/oracle-py/generate_oracle.pyOracle 向量夹具crates/adapters/derive/test_data/common/signing_trade_action_vectors.jsonDerive 适配器集成测试crates/adapters/derive/tests/integration/十、小结这份第三方许可证声明揭示的其实是 nautilus_trader Derive 适配器在加密签名领域的一种高置信度工程实践独立实现协议、以官方 SDK 生成字节级 oracle、在 CI 测试中逐字节对拍、以固定版本保证可复现。它既满足了第三方材料的归属与许可合规要求又为自托管签名这种错一个字节就失败的协议提供了可验证的正确性保证。理解这套机制无论是审查适配器代码、排查签名问题还是规划上游升级都能事半功倍。【免费下载链接】nautilus_traderProduction-grade Rust-native trading engine with deterministic event-driven architecture项目地址: https://gitcode.com/GitHub_Trending/na/nautilus_trader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考