modernize-move

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: modernize-move

Detect and modernize outdated Move V1 syntax, patterns, and APIs to Move V2+. Preserves correctness through tiered transformations with test verification after each tier.

检测并将过时的Move V1语法、模式和API升级至Move V2+版本。通过分层转换并在每一层转换后进行测试验证，确保代码正确性。

Essential Principles

核心原则

Five non-negotiable rules for every modernization:

Test safety net is mandatory WHY: Modernization must preserve behavior. No tests = no safety net. If no tests exist, invoke
```
generate-tests
```
skill first to create comprehensive tests before making any changes.
Analyze before modifying WHY: The user must see exactly what will change and confirm the scope. Never surprise-edit code. Present the full analysis report and wait for confirmation.
Tiered execution order WHY: Syntax changes (Tier 1) are zero-risk. API migrations (Tier 3) change semantics. Always apply safest changes first so riskier changes build on a clean, verified foundation.
Verify after each tier WHY: If tests break, you know exactly which tier caused it. Revert that tier and investigate before proceeding. Never apply the next tier on a broken baseline.
Preserve error code values WHY: Tests use
```
#[expected_failure(abort_code = N)]
```
. Changing numeric values breaks tests silently. When creating named constants, the numeric value MUST match the original literal.

五条不可妥协的现代化规则：

必须具备测试安全网 原因：现代化必须保留原有代码行为。没有测试就没有安全保障。如果不存在测试，请先调用
```
generate-tests
```
工具创建全面的测试用例，再进行任何修改。
先分析再修改 原因：用户必须清楚了解将要发生的所有变更并确认范围。绝不能擅自修改代码。需提交完整的分析报告并等待用户确认。
按分层顺序执行 原因：语法变更（第1层）零风险。API迁移（第3层）会改变语义。始终优先应用最安全的变更，让风险更高的变更基于已验证的干净代码基础进行。
每一层转换后都要验证 原因：如果测试失败，你能准确知道是哪一层导致的问题。回滚该层的变更并排查问题后再继续。绝不能在测试失败的基础上进行下一层转换。
保留错误代码值 原因：测试用例会使用
```
#[expected_failure(abort_code = N)]
```
。修改数值会导致测试静默失败。创建命名常量时，其数值必须与原字面量完全一致。

When to Use This Skill

适用场景

Upgrading Move V1 contracts to V2 syntax
Migrating
```
public(friend)
```
to
```
package fun
```
Converting
```
vector::borrow
```
to index notation
Converting
```
while
```
loops with counters to
```
for
```
range loops
Replacing manual vector iteration with stdlib inline functions (
```
vector::for_each_ref
```
,
```
vector::map
```
,
```
vector::fold
```
, etc.) and lambdas
Replacing magic abort numbers with named constants
Migrating legacy
```
coin
```
/
```
TokenV1
```
to modern
```
fungible_asset
```
/Digital Assets
Converting
```
EventHandle
```
to
```
#[event]
```
pattern
Upgrading custom signed integer workarounds to native
```
i8
```
-
```
i256
```
types

将Move V1合约升级至V2语法
将
```
public(friend)
```
迁移为
```
package fun
```
将
```
vector::borrow
```
转换为索引表示法
将带计数器的
```
while
```
循环转换为
```
for
```
范围循环
用标准库内联函数（
```
vector::for_each_ref
```
、
```
vector::map
```
、
```
vector::fold
```
等）和lambda表达式替换手动向量迭代
用命名常量替换魔数错误码
将旧版
```
coin
```
/
```
TokenV1
```
迁移为现代
```
fungible_asset
```
/数字资产
将
```
EventHandle
```
转换为
```
#[event]
```
模式
将自定义有符号整数替代方案升级为原生
```
i8
```
-
```
i256
```
类型

When NOT to Use This Skill

不适用场景

Writing new contracts from scratch — use
```
write-contracts
```
Fixing bugs or adding features — modernization is structural, not functional
Optimizing gas usage — use
```
analyze-gas-optimization
```
Auditing security — use
```
security-audit
```
(run AFTER modernization)

从零开始编写新合约 — 请使用
```
write-contracts
```
工具
修复Bug或添加功能 — 现代化仅针对结构优化，不涉及功能修改
优化Gas消耗 — 请使用
```
analyze-gas-optimization
```
工具
安全审计 — 请使用
```
security-audit
```
工具（需在现代化完成后运行）

Workflow

工作流程

Phase 1: Analyze Contract

阶段1：分析合约

Entry: User provides a Move contract or project to modernize.

Actions:

Read all contract source files (
```
.move
```
files in
```
sources/
```
)
Scan for V1 patterns using detection rules from detection-rules.md:
- Grep for Tier 1 patterns (syntax) — highest confidence, most common
- Grep for Tier 2 patterns (visibility, errors, events)
- Grep for Tier 3 patterns (API migrations) — flag for manual review
Cross-reference coupled patterns (T3-09+T3-10)
Categorize each finding: line number, rule ID, pattern name, proposed change, tier, confidence
Build the Analysis Report

Exit: Analysis Report ready for presentation.

进入条件：用户提供需要现代化的Move合约或项目。

执行操作：

读取所有合约源文件（
```
sources/
```
目录下的
```
.move
```
文件）
使用detection-rules.md中的检测规则扫描V1模式：
- 匹配第1层模式（语法）——置信度最高，最常见
- 匹配第2层模式（可见性、错误、事件）
- 匹配第3层模式（API迁移）——标记为需要人工审核
交叉引用关联模式（T3-09+T3-10）
对每个发现进行分类：行号、规则ID、模式名称、建议变更、层级、置信度
生成分析报告

退出条件：分析报告准备完毕，可提交给用户。

Phase 2: Present Analysis (GATE 1)

阶段2：提交分析结果（关卡1）

Entry: Analysis Report complete.

Actions:

Present the full Analysis Report to the user in this format:

undefined

进入条件：分析报告已完成。

执行操作：

按以下格式向用户提交完整的分析报告：

undefined

Modernization Analysis Report

现代化分析报告

Summary

摘要

Tier 1 (Syntax): X findings
Tier 2 (Visibility & Errors): X findings
Tier 3 (API Migrations): X findings

第1层（语法）：X项发现
第2层（可见性与错误）：X项发现
第3层（API迁移）：X项发现

Findings

详细发现

#	File:Line	Rule	Pattern	Proposed Change	Tier	Confidence
1	src/mod.move:15	T1-01	vector::borrow	→ index notation	1	High
...	...	...	...	...	...	...

序号	文件:行号	规则	模式	建议变更	层级	置信度
1	src/mod.move:15	T1-01	vector::borrow	→ 索引表示法	1	高
...	...	...	...	...	...	...

Tier 3 Warnings (if any)

第3层警告（如有）

T3-03: coin → fungible_asset migration is a major rewrite (X locations)


2. Ask the user to choose scope:
   - **`syntax-only`** (Tier 1 only) — zero risk, just cleaner syntax
   - **`standard`** (Tier 1 + Tier 2) — recommended default, syntax + visibility + error constants
   - **`full`** (all tiers) — includes API migrations, higher risk
3. Highlight any Tier 3 items that require major rewrites
4. If scope includes Tier 3, ask the user about deployment context:
   - **Compatible** — Upgrading an already-deployed contract. Breaking changes
     are excluded even if the scope includes them. Rules marked ⚠ Breaking are skipped.
   - **Fresh deploy** — New deployment or willing to redeploy. All changes
     in the selected scope are applied including breaking changes.

**Exit:** User has confirmed scope (and deployment context if Tier 3 is included). Do NOT proceed until confirmed.

T3-03：coin → fungible_asset迁移属于重大重写（涉及X处）


2. 请用户选择现代化范围：
   - **`syntax-only`**（仅第1层）——零风险，仅优化代码语法
   - **`standard`**（第1层 + 第2层）——推荐默认选项，包含语法、可见性和错误常量优化
   - **`full`**（所有层级）——包含API迁移，风险较高
3. 高亮显示任何需要重大重写的第3项内容
4. 如果范围包含第3层，请询问用户部署上下文：
   - **兼容模式**——升级已部署的合约。即使范围包含破坏性变更，也会跳过这些变更。标记为⚠ 破坏性变更的规则将被忽略。
   - **全新部署**——新部署或愿意重新部署。将应用所选范围内的所有变更，包括破坏性变更。

**退出条件**：用户已确认现代化范围（若包含第3层则同时确认部署上下文）。未得到确认前请勿继续。

Phase 3: Establish Test Safety Net

阶段3：建立测试安全网

Entry: User confirmed scope.

Actions:

Search for existing tests:
- ```
#[test_only]
```
  modules within source files
- ```
*_tests.move
```
  files
- ```
tests/
```
  directory
If no tests found: stop and invoke
```
generate-tests
```
skill to create comprehensive tests first, then return here
Run
```
aptos move test
```
to establish a passing baseline
Record baseline: number of tests, all passing status

Exit: All tests pass. Baseline recorded. If tests fail pre-modernization, stop and address test failures first — do not modernize on a broken test suite.

进入条件：用户已确认现代化范围。

执行操作：

查找现有测试：
- 源文件内的
```
#[test_only]
```
  模块
- ```
*_tests.move
```
  文件
- ```
tests/
```
  目录
如果未找到测试：停止当前操作，调用
```
generate-tests
```
工具创建全面的测试用例，完成后再返回此阶段
运行
```
aptos move test
```
以建立测试通过基准
记录基准数据：测试数量、全部通过状态

退出条件：所有测试通过。已记录基准数据。如果现代化前测试失败，请先解决测试问题——绝不能在测试套件失败的基础上进行现代化。

Phase 4: Apply Transformations (with Feedback Loops)

阶段4：应用转换（含反馈循环）

Entry: Test baseline established.

Actions — apply in tier order:

Tier 1 (if scope includes it — always):

Apply all Tier 1 syntax changes per transformation-guide.md
Run
```
aptos move test
```
If tests fail → revert all Tier 1 changes, investigate which specific change caused failure, fix and retry

Tier 2 (if scope is
standard
or
full
): 4. Apply all Tier 2 changes per transformation guide 5. Run

aptos move test

6. If tests fail → revert all Tier 2 changes, investigate and fix

Tier 3 (if scope is
full
only): 7. Apply Tier 3 changes ONE AT A TIME (not all at once)

If deployment context is
```
compatible
```
: skip any rule marked ⚠ Breaking. Add to the skipped list with reason "breaking change, excluded in compatible mode."
If deployment context is
```
fresh deploy
```
: apply all rules in scope normally.

Run
```
aptos move test
```
after EACH individual Tier 3 change
If tests fail → revert that specific change, note it as skipped, proceed to next Tier 3 item

Exit: All approved changes applied, all tests passing.

进入条件：已建立测试基准。

执行操作 — 按层级顺序应用：

第1层（若范围包含——默认必选）：

根据transformation-guide.md应用所有第1层语法变更
运行
```
aptos move test
```
如果测试失败 → 回滚所有第1层变更，排查导致失败的具体变更，修复后重试

第2层（若范围为
standard
或
full
）： 4. 根据转换指南应用所有第2层变更 5. 运行

aptos move test

6. 如果测试失败 → 回滚所有第2层变更，排查并修复问题

第3层（仅当范围为
full
时）： 7. 逐个应用第3层变更（不可批量应用）

如果部署上下文为
```
兼容模式
```
：跳过所有标记为**⚠ 破坏性变更**的规则。将这些规则添加到跳过列表，原因标注为“破坏性变更，兼容模式下已排除”。
如果部署上下文为
```
全新部署
```
：正常应用所选范围内的所有规则。

每完成一个第3层变更后运行
```
aptos move test
```
如果测试失败 → 回滚该具体变更，标记为已跳过，继续下一个第3项内容

退出条件：所有已批准的变更已应用，所有测试通过。

Phase 5: Final Verification

阶段5：最终验证

Entry: All transformations applied.

Actions:

Run
```
aptos move test --coverage
```
Verify test coverage is >= baseline (should be same or better)
Generate Modernization Summary Report:

undefined

进入条件：所有转换已应用。

执行操作：

运行
```
aptos move test --coverage
```
验证测试覆盖率≥基准值（应与基准值相同或更高）
生成现代化总结报告：

undefined

Modernization Summary

现代化总结

Changes Applied

已应用变更

Tier 1: X changes (syntax)
Tier 2: X changes (visibility & errors)
Tier 3: X changes (API migrations)

第1层：X项变更（语法）
第2层：X项变更（可见性与错误）
第3层：X项变更（API迁移）

Changes Skipped

已跳过变更

[List any skipped items with reasons]

[列出所有跳过的项及原因]

Test Results

测试结果

Tests: X passing (baseline: Y)
Coverage: X% (baseline: Y%)

测试：X项通过（基准值：Y）
覆盖率：X%（基准值：Y%）

Files Modified

修改的文件

[List of modified files]


**Exit:** Report presented to user.

[列出所有修改的文件]


**退出条件**：已向用户提交总结报告。

Modernization Scope Quick Reference

现代化范围速查表

Scope	Tiers	Risk	When to Use
`syntax-only`	Tier 1	Zero	Just clean up syntax, no semantic changes
`standard`	Tier 1+2	Low	Default. Syntax + visibility + error constants
`full`	Tier 1+2+3	Medium-High	Full migration including API changes

范围	涉及层级	风险	适用场景
`syntax-only`	第1层	零	仅清理语法，不涉及语义变更
`standard`	第1+2层	低	默认选项。语法 + 可见性 + 错误常量优化
`full`	第1+2+3层	中高	完整迁移，包含API变更

Tier Quick Reference

层级速查表

Tier	What Changes	Risk	Examples
1 — Syntax	Code reads differently, compiles identically	Zero	`vector::borrow(&v, i)` → `v[i]` , `x = x + 1` → `x += 1` , `while (i < n) { ... i += 1 }` → `for (i in 0..n) { ... }`
2 — Visibility & Errors	Same semantics, cleaner declarations	Low	`public(friend)` → `package fun` , magic numbers → `E_*` constants
3 — API Migrations	Different APIs, same intended behavior. Most are breaking changes.	Medium-High	`coin` → `fungible_asset` , `SmartTable` → `BigOrderedMap` , `EventHandle` → `#[event]` , manual loops → stdlib `v.for_each_ref()` / `v.map()` / `v.fold()` with lambdas

See detection-rules.md for the complete rule catalog (22 rules across 3 tiers).

层级	变更内容	风险	示例
1 — 语法	代码写法不同，但编译结果一致	零	`vector::borrow(&v, i)` → `v[i]` ， `x = x + 1` → `x += 1` ， `while (i < n) { ... i += 1 }` → `for (i in 0..n) { ... }`
2 — 可见性与错误	语义相同，声明更简洁	低	`public(friend)` → `package fun` ，魔数 → `E_*` 常量
3 — API迁移	使用不同API，但预期行为一致。大多数为破坏性变更。	中高	`coin` → `fungible_asset` ， `SmartTable` → `BigOrderedMap` ， `EventHandle` → `#[event]` ，手动循环 → 标准库 `v.for_each_ref()` / `v.map()` / `v.fold()` 结合lambda表达式

完整规则目录请查看detection-rules.md（3个层级共22条规则）。

Rationalizations to Reject

需拒绝的错误理由

Rationalization	Why It's Wrong
"Tests pass so the modernization is correct"	Tests verify behavior, not code quality. Review changes manually too.
"This contract is simple, skip the analysis"	Simple contracts can have subtle patterns. Always analyze first.
"Let's do all tiers at once to save time"	If tests break, you can't isolate which change caused it. Always tier.
"The receiver-style call looks right"	Must verify the target function declares `self` . False positives are common.
"Error constants can have new names and values"	Existing tests depend on exact numeric values. Preserve them.
"No tests exist, but the changes are safe"	Without tests there is no safety net. Generate tests first.
"Tier 3 changes are optional, skip the test run"	Every change needs verification. Tier 3 is highest risk — test MORE, not less.

错误理由	错误原因
"测试通过，所以现代化是正确的"	测试仅验证行为，不验证代码质量。还需人工审核变更。
"这个合约很简单，跳过分析"	简单合约也可能存在微妙的模式问题。必须先进行分析。
"一次性完成所有层级以节省时间"	如果测试失败，无法定位具体是哪项变更导致的问题。必须分层执行。
"接收者风格调用看起来是对的"	必须验证目标函数是否声明了 `self` 。误判很常见。
"错误常量可以使用新名称和新值"	现有测试依赖精确的数值。必须保留原数值。
"没有测试，但变更很安全"	没有测试就没有安全保障。必须先生成测试用例。
"第3层变更可选，跳过测试"	每一项变更都需要验证。第3层风险最高——需要更多测试，而不是更少。

Success Criteria

成功标准

Analysis Report presented before any modifications
User confirmed modernization scope
Test baseline established before changes
Tests pass after each tier of changes
All error code numeric values preserved
No Tier 3 changes applied without
```
full
```
scope confirmation
Breaking changes excluded when user selected compatible mode
Modernization Summary Report generated
Test coverage maintained at or above baseline

修改前已提交分析报告
用户已确认现代化范围
变更前已建立测试基准
每一层变更后测试都通过
所有错误代码数值均保留
未在未确认
```
full
```
范围的情况下应用第3层变更
用户选择兼容模式时已排除破坏性变更
已生成现代化总结报告
测试覆盖率维持在基准值或更高

Reference Index

参考索引

File	Content
detection-rules.md	Complete V1 pattern detection catalog (22 rules across 3 tiers)
transformation-guide.md	Before/after code, safety checks, edge cases per rule
MOVE_V2_SYNTAX.md	Full V2 syntax reference
OBJECTS.md	Modern object model patterns
ADVANCED_TYPES.md	Enums, signed integers, phantom types

Related skills:

generate-tests

write-contracts

security-audit

文件	内容
detection-rules.md	完整的V1模式检测规则目录（3个层级共22条规则）
transformation-guide.md	每条规则的代码前后对比、安全检查、边缘情况说明
MOVE_V2_SYNTAX.md	完整的V2语法参考
OBJECTS.md	现代对象模型模式
ADVANCED_TYPES.md	枚举、有符号整数、幻影类型

相关工具：

generate-tests

、

write-contracts

、

security-audit