sui-move

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sui Move

MCP tool: When available in your environment, also query the Sui documentation MCP server (
https://sui.mcp.kapa.ai
) for up-to-date answers. Use it for verification and for details not covered by these reference files.

Source constraint: All information in this skill is sourced exclusively from docs.sui.io and move-book.com. When extending or updating this skill, only pull from these sources. Do not use third-party blogs, tutorials, or unofficial documentation.

Move is Sui's smart contract language, designed around resource safety and an object-centric data model. This skill covers the core Move language: the type system, abilities, resource safety, events, and coins.

This skill routes to focused reference files. Load only the ones relevant to the current task.

MCP工具： 当你的环境中可用时，也可查询Sui文档MCP服务器（
https://sui.mcp.kapa.ai
）获取最新答案。用它来验证信息，以及获取这些参考文件未涵盖的细节。

来源限制： 本技能中的所有信息均独家来源于docs.sui.io和move-book.com。扩展或更新本技能时，仅可从这些来源获取内容，请勿使用第三方博客、教程或非官方文档。

Move是Sui的智能合约语言，围绕资源安全和以对象为中心的数据模型设计。本技能涵盖Move核心语言：类型系统、能力、资源安全、事件以及代币。

本技能会导向聚焦的参考文件。仅加载与当前任务相关的文件。

Reference files (this skill)

参考文件（本技能）

move — Move Language Fundamentals

move — Move语言基础

Path:

move.md

Load when: writing Move code, working with abilities, TxContext, time/Clock, init functions, One-Time Witness,

internal::Permit<T>

type_name

deprecations, packages, modules, structs, resource safety, access control patterns, admin rotation, deny lists, security review, or advanced design patterns (ability dosing, phantom events, shared-object concurrency, receiver syntax, error attributes,

transfer::receive

, field privacy, macros). Covers: the four abilities and common combinations, TxContext methods, Clock object, init functions, OTW pattern,

internal::Permit<T>

type-level authorization,

type_name

deprecations, packages and upgrades, modules, structs, resource safety and object destruction, a worked Greeting example, admin rotation (two-step transfer), regulated coins and deny lists, security review checklist, advanced design patterns (ability dosing, phantom-type events, event denormalization, shared-object

&mut

, receiver-syntax ordering,

#[error]

constants,

transfer::receive

privacy, field privacy, macro gotchas).

路径：

move.md

加载时机： 编写Move代码、处理能力、TxContext、时间/Clock、初始化函数、One-Time Witness、

internal::Permit<T>

、

type_name

弃用、包、模块、结构体、资源安全、访问控制模式、管理员轮换、拒绝列表、安全审查或高级设计模式（能力剂量、幻影事件、共享对象并发、接收者语法、错误属性、

transfer::receive

、字段隐私、宏）时。 涵盖内容： 四种能力及其常见组合、TxContext方法、Clock对象、初始化函数、OTW模式、

internal::Permit<T>

类型级授权、

type_name

弃用、包与升级、模块、结构体、资源安全与对象销毁、一个完整的Greeting示例、管理员轮换（两步转移）、受监管代币与拒绝列表、安全审查清单、高级设计模式（能力剂量、幻影类型事件、事件反规范化、共享对象

与

&mut

对比、接收者语法排序、

#[error]

常量、

transfer::receive

隐私、字段隐私、宏陷阱）。

events-coins — Events and Coins

events-coins — 事件与代币

Path:

events-coins.md

Load when: emitting events, subscribing to events offchain, creating fungible tokens, or working with coin operations (mint, burn, split, join). Covers: event emission, event struct requirements, coin::create_currency, TreasuryCap, CoinMetadata, standard coin operations.

路径：

events-coins.md

加载时机： 触发事件、链下订阅事件、创建可替代代币或处理代币操作（铸造、销毁、拆分、合并）时。 涵盖内容： 事件触发、事件结构体要求、coin::create_currency、TreasuryCap、CoinMetadata、标准代币操作。

Related skills (load from separate skill directories)

相关技能（从独立技能目录加载）

Topic	Skill	Load when
Object model, ownership, dynamic fields, collections, Display, transfer patterns	`object-model/`	Designing data models, choosing ownership types, using dynamic fields or collections, setting up Object Display
Programmable transaction blocks, commands, equivocation	`ptbs/`	Building PTBs, composing transactions, sponsored transactions, troubleshooting transaction errors
Frontend dApp development, dApp Kit, wallet connection	`frontend-apps/`	Building React/Vue frontends, wallet integration, querying onchain state from the browser
Project setup, Move.toml, dependencies, publishing	`sui-move-project/`	Creating a Move project, configuring Move.toml, resolving build errors, publishing packages
Move 2024 syntax, method syntax, macros	`modern-move-syntax/`	Using Move 2024 edition features like method syntax, vector literals, option/loop macros
Composable function design	`composable-move-functions/`	Designing functions for PTB composability, parameter ordering, return patterns
Unit testing conventions	`move-unit-testing/`	Writing Move unit tests, test patterns, expected_failure, cleanup
Naming conventions	`naming-conventions/`	Naming errors, constants, capabilities, events, getters, dynamic field keys

主题	技能	加载时机
对象模型、所有权、动态字段、集合、Display、转移模式	`object-model/`	设计数据模型、选择所有权类型、使用动态字段或集合、设置Object Display时
可编程交易块、命令、双花	`ptbs/`	构建PTB、组合交易、赞助交易、排查交易错误时
前端dApp开发、dApp Kit、钱包连接	`frontend-apps/`	构建React/Vue前端、钱包集成、从浏览器查询链上状态时
项目设置、Move.toml、依赖、发布	`sui-move-project/`	创建Move项目、配置Move.toml、解决构建错误、发布包时
Move 2024语法、方法语法、宏	`modern-move-syntax/`	使用Move 2024版本特性如方法语法、向量字面量、option/loop宏时
可组合函数设计	`composable-move-functions/`	设计适用于PTB组合性的函数、参数排序、返回模式时
单元测试约定	`move-unit-testing/`	编写Move单元测试、测试模式、expected_failure、清理时
命名约定	`naming-conventions/`	错误、常量、权限、事件、获取器、动态字段键的命名时

Routing guide

路由指南

Task	Load
Writing a Move struct with abilities	move
Using TxContext or the Clock object	move
Writing an init function or OTW	move
Using `type_name` functions	move
Proving module authority with `internal::Permit<T>`	move
Publishing or upgrading a package	move
Destroying an object without drop	move
Emitting or subscribing to events	events-coins
Creating a fungible token	move + events-coins
Designing an object data model	`object-model/` skill
Choosing shared vs owned objects	`object-model/` skill
Using dynamic fields or collections	`object-model/` skill
Setting up Object Display	`object-model/` skill
Building a PTB	`ptbs/` skill
Implementing sponsored transactions	`ptbs/` skill
Building a frontend	`frontend-apps/` skill
Setting up Move.toml	`sui-move-project/` skill
Writing a complete smart contract	move + events-coins + `object-model/` + `naming-conventions/` + `modern-move-syntax/`
Code review	move + events-coins + `composable-move-functions/` + `naming-conventions/` + `modern-move-syntax/`
Security review / access control audit	move + `object-model/` (patterns) + events-coins
Advanced design patterns / performance tuning	move

任务	加载内容
编写带能力的Move结构体	move
使用TxContext或Clock对象	move
编写初始化函数或OTW	move
使用 `type_name` 函数	move
用 `internal::Permit<T>` 证明模块权限	move
发布或升级包	move
销毁无drop能力的对象	move
触发或订阅事件	events-coins
创建可替代代币	move + events-coins
设计对象数据模型	`object-model/` 技能
选择共享对象 vs 自有对象	`object-model/` 技能
使用动态字段或集合	`object-model/` 技能
设置Object Display	`object-model/` 技能
构建PTB	`ptbs/` 技能
实现赞助交易	`ptbs/` 技能
构建前端	`frontend-apps/` 技能
设置Move.toml	`sui-move-project/` 技能
编写完整智能合约	move + events-coins + `object-model/` + `naming-conventions/` + `modern-move-syntax/`
代码审查	move + events-coins + `composable-move-functions/` + `naming-conventions/` + `modern-move-syntax/`
安全审查 / 访问控制审计	move + `object-model/` （模式） + events-coins
高级设计模式 / 性能调优	move

Rules

规则

Always use
```
object::new(ctx)
```
to create UIDs. There is no other way.
Use
```
public_transfer
```
(not
```
transfer
```
) when the object has
```
store
```
and the call originates outside the defining module.
Event structs must have
```
copy
```
and
```
drop
```
abilities.
No
```
as
```
casts on numeric types. Use
```
from
```
/
```
into
```
or
```
try_from
```
/
```
try_into
```
.
To destroy an object without
```
drop
```
, unpack the struct and call
```
object::delete(id)
```
on the UID.

必须使用
```
object::new(ctx)
```
创建UID，没有其他方法。
当对象具有
```
store
```
能力且调用来自定义模块外部时，使用
```
public_transfer
```
（而非
```
transfer
```
）。
事件结构体必须具备
```
copy
```
和
```
drop
```
能力。
数值类型禁止使用
```
as
```
强制转换，使用
```
from
```
/
```
into
```
或
```
try_from
```
/
```
try_into
```
。
要销毁无
```
drop
```
能力的对象，需解包结构体并对UID调用
```
object::delete(id)
```
。

Common mistakes

常见错误

Confusing
transfer
with
public_transfer
. The non-public variant only works within the defining module. Calling it from another module is a compile error.
Forgetting to delete the UID. When destroying an object, you must call
```
object::delete(id)
```
on the UID field.
Assuming
ctx.epoch_timestamp_ms()
is precise. It returns the epoch start time. Use the Clock object (
```
0x6
```
) for real-time timestamps.

混淆
transfer
与
public_transfer
：非公开变体仅在定义模块内有效，从其他模块调用会导致编译错误。
忘记删除UID：销毁对象时，必须对UID字段调用
```
object::delete(id)
```
。
假设
ctx.epoch_timestamp_ms()
是精确的：它返回的是纪元开始时间，如需实时时间戳，请使用Clock对象（
```
0x6
```
）。