Aptos Move 最弱前置条件(WP)规范推断:move_package_wp 工具契约与诊断处理全指南

原创2026-09-18 19:21:151,412 阅读
文章标签:区块链Web3密码学并发编程

Aptos Move 最弱前置条件(WP)规范推断:move_package_wp 工具契约与诊断处理全指南

导读

本文围绕 Aptos 仓库中 aptos-move/flow 的规范推断(Specification Inference)工作流展开,深入讲解其核心工具 move_package_wp——一个基于最弱前置条件(Weakest Precondition, WP)推理、从 Move 函数实现自动派生形式化规范并写回源码的 MCP 工具。你将掌握该工具的参数与输出模式、五种典型诊断结果的准确含义与修复动作、pragma opaque 与继承式 partial 规则的边界,以及如何区分"规范缺陷"与"工具缺陷"。本文以 wp_tool.md 为骨架,结合 package_spec_infer.rs 源码实现逐条印证。

WP 推理的基本原理

在深入工具之前,先理解其数学内核。wp_concepts.md 给出的定义简洁有力:

最弱前置条件推理从返回(returns)、中止(aborts)、调用(calls)与状态更新(state updates)向后推导,刻画每种行为对应的初始状态集合;循环由其不变量表示,不变量未约束的值在循环之后被视为任意值。

这意味着 move_package_wp 不是"正向模拟执行",而是"反向求解条件":它回答的是"为了满足某个函数的所有可观察行为,调用方必须满足什么前置条件、函数会以何种方式中止、会修改哪些全局状态"。循环之所以需要不变量,是因为向后推理无法机械地穿过任意次迭代,只能依赖一个"进入时成立、每次迭代保持"的断言来抽象整段循环。

move_package_wp 工具概览与调用方式

工具定位

在 core_tools.md 描述的"Move 包检查工具族"(move_package_status、move_package_manifest、move_package_query)之外,move_package_wp 是规范推断专用工具。在 README.md 的工具清单表中,它的定位被描述为:

move_package_wp — Infer and inject specifications with weakest preconditions (hybrid tactics only)

即:仅在后端混合(hybrid)策略下可用,与 agent-only(纯 Agent 直接推理、不含 WP 工具)策略互斥。

参数与默认值

工具的契约在 package_spec_infer.rs 中由 MovePackageSpecInferParams 精确定义:

参数 类型 必填 说明
package_path string 是 Move 包目录路径,即包含 Move.toml 的目录
filter string? 否 作用域过滤:module、module::function 或 address::module::function(支持数字或命名地址;裸模块名必须无歧义)。省略时推断整个包的所有目标模块
spec_output 枚举 否 输出模式,默认 inline

filter 的三级粒度与验证工具 move_package_verify 保持一致。从源码看,filter 会被 resolve_filter 解析为 (VerifiedScope, VerificationScope)(见 package_spec_infer.rs),并且当设置了 filter 时,工具会构建一个全新环境(build_filtered_env),只把匹配 filter 的文件作为 primary target——这与 move_package_verify 的动机一致:避免缓存环境中"所有模块都是 target"导致 prover 的字节码流水线遍历整个包,从而在不打算验证的模块(例如 storage_slot)上 panic。

输出模式:inline 与 file

spec_output 枚举定义在 package_spec_infer.rs:

  • inline(默认):推断出的规范被注入原始源码文件。实现上,prover 先生成 <stem>.enriched.move 富化文件,工具读取其内容、覆盖写回原文件、再删除富化文件(见 package_spec_infer.rs)。
  • file:为每个目标模块生成伴生的 <stem>.spec.move 文件,原始源码保持不动(见 package_spec_infer.rs)。

无论哪种模式,循环不变量永远留在其可执行循环旁边,不随 spec_output 移动到伴生文件。写回后,工具会调用 source_check::check_inferred_output 做格式与 AST 校验,并通过 source_check::format_file 格式化每个被修改文件,最终返回被修改文件的路径清单,以及统计到的 [inferred 标记数量(这是后文"标记纪律"的落点)。

调用示例

# 推断整个包(所有目标模块),默认 inline 注入源码
move_package_wp package_path="sources/"

# 只推断某个模块
move_package_wp package_path="sources/" filter="my_module"

# 只推断某个函数
move_package_wp package_path="sources/" filter="my_module::transfer"

# 推断到伴生 .spec.move 文件,保留原始源码
move_package_wp package_path="sources/" filter="my_module::transfer" spec_output="file"

结果解读:五种情形与对应动作

原文档的核心是"按函数解读结果"的决策树。这是使用 WP 工具最关键的部分——警告不是普通提示,每种警告都对应一种明确的工作项或工具缺陷声明。

情形一:无警告 —— 生成规范按构造正确

没有警告意味着生成的规范在构造上是完整且正确的,包括:

  • 隐式算术中止(如溢出、除零);
  • 边界中止(如越界索引);
  • 资源中止(如访问不存在的资源);
  • 被调用方(callee)的中止传播。

需要特别强调两个边界:

  1. WP 不运行 prover。无警告不代表证明通过——验证可能仍然超时。此时修复方向是"修理证明或改用等价的、对求解器友好的表达式",前提是不削弱契约(不能为了好证而删条件)。
  2. 工具 bug 的判定标准:对未修改的、无警告的 WP 输出,若出现编译错误或反例,这是工具缺陷(tool bug),应报告该失败条件,而不是去改规范。这一点在源码中亦有呼应:无过滤路径会先 clear_diag() 清理历史诊断再运行推断(见 package_spec_infer.rs),确保警告来源干净。

情形二:缺失或不足的循环不变量

这是最常见也最需要动手的情形。动作是添加一个"进入时成立、且被每次迭代保持"的不变量。

关键辅助机制:警告会携带有界循环头观测值(bounded loop-head observations)。源码中对应 LOOP_INVARIANT_EVIDENCE_DEPTH 与 options.inference.loop_invariant_evidence = evidence_depth(见 package_spec_infer.rs)——prover 会展开循环前若干次迭代,报告循环头处的取值,帮助你归纳出不变量。但文档明确警告:

这些观测只是显示的那段执行前缀的描述,不是证明。

正确的迭代流程是:为该函数补齐不变量 → 删除该函数过期的、由 WP 生成的函数子句(保留不变量、helper 和用户手写的子句)→ 重跑 WP。spec_inf_rules.md 还给出了常见的循环不变量形状:累积(accumulation)、搜索(search)、量化遍历(quantified traversal)、有状态遍历(stateful traversal),以及针对内联高阶迭代器的 folds_of 提示。

情形三:部分 opaque / 无体 callee 规范 —— 唯一合法的调用方 partial

这是唯一能让调用方规范"合理地为 partial"的 callee 情形。当被调用方契约自身是 partial 的(aborts_if_is_partial),调用方将没有确切的 abort 条件可以陈述,因此:

  • 保留 pragma aborts_if_is_partial(不要删除它来宣称 totality);
  • 在契约中注明是哪个命名 callee 引入的 partiality;
  • 不要重写调用方,也不要删掉 pragma 去伪装成完备。

配套规则在 spec_inf_rules.md 中被称为"继承式 partiality(Inherited partiality)":它只计入你"发现"的 partiality(推断报告给 callee 的,或你接手时树上已有的);自己写出来的 partiality 不算——把一个 helper 标成 partial 再拿它当挡箭牌,会被候选检查(candidate check)拒绝。在 callee 保持 partial 期间,调用方必须保持 partial,且这个警告不是对调用方的修复义务,不需要反复重跑 WP。

情形四:透明 callee 缺少完整 opaque 契约

当被调用方是**透明(transparent)**的、又没有完整的 opaque 契约时,WP 无法补全调用方。分两种处理路径:

  • callee 在可编辑范围内(例如当前模块内):先为 callee 推断并验证其 opaque 契约,再对调用方重跑 WP;
  • callee 在可编辑范围之外:把该依赖报告为 corpus/package blocker——其所有者必须提供完整且已验证的 opaque 契约。

文档特别强调:绝不能用这种情形来为调用方的 aborts_if_is_partial 辩护。这正是"继承式 partiality"规则的反面教材。

情形五:未建模的 prover intrinsic —— 工具缺陷

pragma intrinsic 函数执行的是 prover 内建语义(builtin),而非其 Move 函数体。因此:

  • 不要为其添加源码级 spec;
  • 不要把它们改成 opaque;
  • WP 工具必须在内部提供该 builtin 的值(value)、中止(abort)与变更(mutation)语义。

遇到此类警告应视为 WP 工具缺陷并上报。spec_inf_rules.md 同步规定:"不要为 pragma intrinsic 函数合成普通契约;prover 提供其语义"。

总则:什么算工具缺陷

文档最后给出收口定义:

条件的意外丢失、畸形输出,或任何其他推断失败,都是工具缺陷,而不是削弱规范的邀请。

也就是说:move_package_wp 的警告体系是"要么修(情形二、四),要么保留并记录(情形三),要么上报(情形一的后半、情形五)",唯一不允许的响应是通过削弱契约让问题消失。

配套工作流:从 WP 输出到候选检查

move_package_wp 不是孤立工具,它嵌在 aptos-move/flow 的完整规范推断闭环中。任务编排定义在 spec_inf_tasks.md,两种混合策略的差异在于 WP 的使用方式:

  • hybrid-guided(默认):按固定顺序执行——先在请求作用域上跑 WP(含循环)→ 按本文第五节的决策树逐个修复诊断、逐函数重跑 → 简化 WP 产物(保持每个 result/abort/frame 义务不变)→ 跑候选检查。README.md 中的调用形式为 /move-inf 与 /move-inf hybrid-flexible sources/x.move。
  • hybrid-flexible:WP 作为可选推断通道,何时用、是否与直接推理和不变式合成搭配,由 Agent 自行决策。

两种策略的终点都是 candidate_check.md 描述的 move_spec_check 候选检查——它是唯一决定"工作是否完成"的裁判,会编译包、验证目标,并拒绝自我削弱的契约(禁用/跳过验证、空洞条件、无 callee 依据的 partial-abort pragma)。它同时取代了收尾时的 move_package_verify 调用:前者重复即将做的验证,后者重复已经做过的证明。

一个值得注意的实现细节:在度量(measured)场景下,uninvariant_loop_is_error 会把"无不变量的循环"从"产出可验证空契约"升级为"必须失败"(见 package_spec_infer.rs 与 EvaluationConfig::uninvariant_loop_is_error 的注释),防止循环被静默抽象成空契约。

输出纪律与工程质量红线

结合 spec_inf_rules.md 与 verification_ref.md,使用 WP 工具时必须遵守以下纪律,这些也是候选检查会强制执行的:

  1. 标记纪律:每个你撰写的条件与不变量标 <a href="https://link.gitcode.com/i/d575a6fe3590d42da0d639319c5ef288" target="_blank">inferred];绝不标记用户既有子句。源码正是通过统计 [inferred 出现次数来计量推断产出的(见 [package_spec_infer.rs)。
  2. opaque 契约的诚实性:对目标函数撰写的规范必须 pragma opaque,并且该契约必须被证明真的成立——"pragma opaque 不会抑制函数自身函数体的验证"。契约缺结果、缺 abort、缺 frame 不只是不完整,而是错误——调用方会基于一个实现不兑现的承诺被验证。同理,不要给检查范围之外的 helper 加 pragma opaque(它会在调用点被假定、却永远不会被验证,检查会拒绝它);透明 helper 不需要契约,prover 直接读其函数体。
  3. 不削弱原则:绝不删减行为条件、绝不添加限制性 requires 来挡反例、绝不启用 partial abort 覆盖、绝不省略 frame、绝不跳过验证。
  4. 诊断分类先行(见 verification_ref.md):编译/规范语言错误先修语法与名字解析;后置条件反例追溯正常路径;abort 反例枚举直接与传递的 abort 来源;frame 失败对照 modifies 子句;超时视为"未解决",既不是假也不是已验证。
  5. 超时策略:先简化 WP 生成或手写的表达式(去冗余、提取公因子、修复 vacuous/sathard 循环输出),用 split_vcs_by_assert 与小 assert 提示切分义务,用等价 frame/有界关系/递归 helper 替换敌意无界量词,偏好加法递推而非非线性闭式,用 apply 显式实例化引理并给 [weight = N],最后才考虑提高 per-condition 超时。

结论:一份可执行的诊断契约

move_package_wp 的价值在于把"规范推断"从黑盒变成了带明确责任边界的流程:WP 引擎负责按构造生成完备条件(含隐式中止与 callee 传播),人类/Agent 负责四件事——补循环不变量、为可编辑范围内的透明 callee 推断 opaque 契约、记录并保留继承的 callee partiality、以及把超时当作证明问题而非规范问题去修。剩下的一切异常(无警告输出上的反例、未建模 intrinsic、条件丢失)都属于工具缺陷,应当上报而非"修掉症状"。这套契约在 wp_tool.md 中被精确定义,并由 package_spec_infer.rs 的实现在工程上落地——理解它,就理解了 Aptos 形式化验证流水线的入口。

登录后查看全文
aptos-core