sui-object-model

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sui Object Model

Sui对象模型

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 two sources. Do not use third-party blogs, tutorials, or unofficial documentation.

Objects are the fundamental unit of storage on Sui. Every resource, asset, and piece of data onchain is an object. Unlike account-based blockchains where state lives in shared mappings inside contracts, Sui gives each piece of state its own identity, version, and owner. Transactions consume objects as inputs and produce modified versions as outputs.

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。扩展或更新本技能时，仅可从这两个来源获取内容，请勿使用第三方博客、教程或非官方文档。

对象是Sui上存储的基本单元。链上的每个资源、资产和数据都是一个对象。与基于账户的区块链（状态存储在合约内的共享映射中）不同，Sui为每个状态赋予自己的标识、版本和所有者。交易将对象作为输入消耗，并生成修改后的版本作为输出。

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

Reference files

参考文件

ownership — Ownership Types and Versioning

ownership — 所有权类型与版本控制

Path:

ownership.md

Load when: asking about ownership types (address-owned, consensus-address-owned, shared, immutable, wrapped), choosing between shared and owned, parallel execution, consensus, Mysticeti, fastpath, object versioning, Lamport timestamps, or frontend access to shared objects. Covers: all five ownership types with consensus implications, consensus-address-owned objects, shared object access mode optimization, frontend PTB access pattern, wrapped object behavior, Lamport timestamp versioning, fastpath vs consensus versioning.

路径：

ownership.md

加载场景： 询问所有权类型（地址所有、共识地址所有、共享、不可变、包装）、选择共享与自有对象、并行执行、共识、Mysticeti、快速路径、对象版本控制、Lamport时间戳，或前端访问共享对象时。 涵盖内容： 五种所有权类型及其对共识的影响、共识地址所有对象、共享对象访问模式优化、前端PTB访问模式、包装对象行为、Lamport时间戳版本控制、快速路径与共识版本控制对比。

transfers — Transferring and Deleting Objects

transfers — 对象转移与删除

Path:

transfers.md

Load when: transferring objects, choosing between

transfer

and

public_transfer

, implementing custom transfer rules, using

Receiving<T>

, transfer-to-object, or deleting/destroying objects. Covers: six core transfer functions (module-restricted vs public), custom transfer rules, transfer-to-object with

Receiving<T>

receive

public_receive

, object deletion/unpacking pattern, dynamic field cleanup warning.

路径：

transfers.md

加载场景： 转移对象、选择

transfer

与

public_transfer

、实现自定义转移规则、使用

Receiving<T>

、向对象转移，或删除/销毁对象时。 涵盖内容： 六种核心转移函数（模块限制型 vs 公开型）、自定义转移规则、借助

Receiving<T>

向对象转移、

receive

与

public_receive

对比、对象删除/解包模式、动态字段清理警告。

dynamic-fields-and-collections — Dynamic Fields and Collections

dynamic-fields-and-collections — 动态字段与集合

Path:

dynamic-fields-and-collections.md

Load when: using dynamic fields, choosing between

dynamic_field

and

dynamic_object_field

, working with collections (

Table

Bag

VecMap

LinkedTable

), or designing storage for large datasets. Covers: dynamic field vs dynamic object field visibility, field naming, core API (add/borrow/remove/exists_), all collection types with decision table, cleanup requirements, system limits (256 KB object size, 2048 objects/txn).

路径：

dynamic-fields-and-collections.md

加载场景： 使用动态字段、选择

dynamic_field

与

dynamic_object_field

、处理集合（

Table

、

Bag

、

VecMap

、

LinkedTable

），或设计大型数据集存储时。 涵盖内容： 动态字段与动态对象字段的可见性对比、字段命名、核心API（add/borrow/remove/exists_）、所有集合类型及决策表、清理要求、系统限制（256 KB对象大小、每交易2048个对象）。

patterns — Common Patterns and Derived Objects

patterns — 常见模式与派生对象

Path:

patterns.md

Load when: implementing hot potato, capability, soulbound, inventory, or borrow patterns, or working with derived objects. Covers: hot potato pattern (no-ability structs), capability pattern (AdminCap/TreasuryCap), borrow pattern with

sui::borrow

module, soulbound objects, inventory pattern (ObjectBag), derived objects with deterministic IDs, derived objects vs dynamic fields comparison.

路径：

patterns.md

加载场景： 实现烫手山芋、能力、灵魂绑定、库存或借用模式，或处理派生对象时。 涵盖内容： 烫手山芋模式（无能力结构体）、能力模式（AdminCap/TreasuryCap）、借助

sui::borrow

模块的借用模式、灵魂绑定对象、库存模式（ObjectBag）、带确定性ID的派生对象、派生对象与动态字段对比。

display — Object Display (V2)

display — Object Display（V2）

Path:

display.md

Load when: setting up how objects render in wallets, explorers, or apps, working with Display templates, configuring NFT metadata, or migrating from Display V1. Covers: V2

Display<T>

creation via

display_registry::new_with_publisher

DisplayCap<T>

for updates,

set

unset

clear

share

API,

{field_name}

template syntax with nested field access, common display properties, V1 to V2 migration.

路径：

display.md

加载场景： 设置对象在钱包、浏览器或应用中的渲染方式、处理Display模板、配置NFT元数据，或从Display V1迁移时。 涵盖内容： 通过

display_registry::new_with_publisher

创建V2

Display<T>

、用于更新的

DisplayCap<T>

、

set

unset

clear

share

API、支持嵌套字段访问的

{field_name}

模板语法、常见显示属性、V1到V2的迁移方法。

Routing guide

路由指南

Task	Load
What is an object / object structure	SKILL.md only
Abilities: key, store, copy, drop	SKILL.md only
Ownership types, shared vs owned vs consensus-address-owned	ownership
Parallel execution, consensus, fastpath	ownership
Object versioning, Lamport timestamps	ownership
Wrapped objects and accessibility	ownership
Frontend access to shared objects	ownership
Transferring objects, transfer vs public_transfer	transfers
Custom transfer rules	transfers + patterns
Transfer to object, Receiving	transfers
Deleting / destroying objects	transfers
Dynamic fields, dynamic object fields	dynamic-fields-and-collections
Collections: Table, Bag, VecMap, LinkedTable	dynamic-fields-and-collections
Scalability, large collection design	dynamic-fields-and-collections
Hot potato pattern	patterns
Capability pattern, AdminCap	patterns
Borrow pattern, cap inside object	patterns
Soulbound / non-transferable objects	transfers + patterns
Inventory for arbitrary objects	patterns + dynamic-fields-and-collections
Derived objects	patterns
Object Display, NFT rendering	display
Full project / code review	all reference files

任务	加载文件
对象定义/对象结构	仅SKILL.md
能力：key、store、copy、drop	仅SKILL.md
所有权类型、共享 vs 自有 vs 共识地址所有	ownership
并行执行、共识、快速路径	ownership
对象版本控制、Lamport时间戳	ownership
包装对象及可访问性	ownership
前端访问共享对象	ownership
对象转移、transfer vs public_transfer	transfers
自定义转移规则	transfers + patterns
向对象转移、Receiving	transfers
删除/销毁对象	transfers
动态字段、动态对象字段	dynamic-fields-and-collections
集合：Table、Bag、VecMap、LinkedTable	dynamic-fields-and-collections
可扩展性、大型集合设计	dynamic-fields-and-collections
烫手山芋模式	patterns
能力模式、AdminCap	patterns
借用模式、对象内的权限	patterns
灵魂绑定/不可转移对象	transfers + patterns
任意对象的库存	patterns + dynamic-fields-and-collections
派生对象	patterns
Object Display、NFT渲染	display
完整项目/代码审查	所有参考文件

Object structure

对象结构

Every Sui object contains four components:

Globally unique ID: A 32-byte identifier derived from the creation transaction digest plus a generation counter. The ID never changes across the object's lifetime.
Version number: An 8-byte integer that increments with each modification. Uses Lamport timestamps: the new version for all objects a transaction touches is
```
1 + max(version of all input objects)
```
.
Owner field: A 32-byte value designating access control (an address, another object's ID, or a sentinel for shared/immutable).
Transaction digest: A 32-byte hash referencing the last transaction that modified the object.

Objects can be referenced three ways: by ID alone (query current state), by versioned ID (read historical state), or by full object reference containing ID + version + digest (transaction inputs, authenticated snapshot).

每个Sui对象包含四个组件：

全局唯一ID： 32字节标识符，由创建交易摘要加上生成计数器派生而来。ID在对象生命周期内永不改变。
版本号： 8字节整数，每次修改时递增。使用Lamport时间戳：交易所触及的所有对象的新版本为
```
1 + max(所有输入对象的版本)
```
。
所有者字段： 32字节值，指定访问控制（地址、另一个对象的ID，或共享/不可变的标记值）。
交易摘要： 32字节哈希，引用最后修改该对象的交易。

对象有三种引用方式：仅通过ID（查询当前状态）、通过版本化ID（读取历史状态），或通过包含ID+版本+摘要的完整对象引用（交易输入、已认证快照）。

Defining objects in Move

在Move中定义对象

A Sui object is a Move struct with the

key

ability and an

id: UID

as the first field:

move

public struct Sword has key, store {
    id: UID,
    damage: u64,
    element: String,
}

object::new(ctx)

is the only way to create a

UID

. You cannot call

ctx.new()

directly.

Sui对象是带有

key

能力且第一个字段为

id: UID

的Move结构体：

move

public struct Sword has key, store {
    id: UID,
    damage: u64,
    element: String,
}

object::new(ctx)

是创建

UID

的唯一方式。不能直接调用

ctx.new()

。

Move abilities and objects

Move能力与对象

Ability	What it controls
`key`	The struct is a Sui object. Must have `id: UID` as first field. Required for all onchain objects.
`store`	The struct can be stored inside other objects, and transferred by any module using `public_transfer` . Without it, only the defining module can transfer the object. Adding `store` permanently removes the ability to enforce custom transfer rules.
`copy`	The struct can be duplicated. Cannot be used on objects — `UID` lacks `copy` , so any struct with `key` cannot have `copy` . Used only on non-object structs (configs, event data, read-only values).
`drop`	The struct can be silently discarded at end of scope. Cannot be used on objects — `UID` lacks `drop` , so any struct with `key` cannot have `drop` . Used only on non-object structs (ephemeral receipts, events). Objects must always be explicitly unpacked to destroy.

能力	控制内容
`key`	该结构体是Sui对象。必须将 `id: UID` 作为第一个字段。所有链上对象都需要此能力。
`store`	该结构体可存储在其他对象内部，且任何模块都可使用 `public_transfer` 进行转移。如果没有此能力，只有定义该结构体的模块可以转移对象。添加 `store` 后将永久失去执行自定义转移规则的能力。
`copy`	该结构体可被复制。不能用于对象—— `UID` 不具备 `copy` 能力，因此任何带有 `key` 的结构体都不能拥有 `copy` 能力。仅用于非对象结构体（配置、事件数据、只读值）。
`drop`	该结构体可在作用域结束时被静默丢弃。不能用于对象—— `UID` 不具备 `drop` 能力，因此任何带有 `key` 的结构体都不能拥有 `drop` 能力。仅用于非对象结构体（临时收据、事件）。对象必须始终被显式解包才能销毁。

Object ability combinations

对象能力组合

Because

UID

has neither

copy

nor

drop

, objects (structs with

key

) can only combine

key

and

store

has key
: Only the defining module can transfer, share, or freeze. Use for custom transfer rules.
has key, store
: Any module can transfer, share, freeze, or wrap. Use for freely composable assets. Once
```
store
```
is granted, you cannot re-add custom transfer restrictions.

由于

UID

既没有

copy

也没有

drop

能力，对象（带有

key

的结构体）只能组合

key

和

store

：

has key
：只有定义模块可以转移、共享或冻结对象。用于自定义转移规则。
has key, store
：任何模块都可以转移、共享、冻结或包装对象。用于可自由组合的资产。一旦授予
```
store
```
能力，就无法重新添加自定义转移限制。

Non-object struct combinations (no

key

)

非对象结构体组合（无

key

）

has store
: Can be stored as a field inside an object. Cannot exist independently.
has copy, drop
: A plain data struct for events, intermediate values, and configs.
has copy, drop, store
: Can be used as dynamic field names.
No abilities: A hot potato. Must be consumed in the same transaction. See patterns reference file.

has store
：可作为字段存储在对象内部。不能独立存在。
has copy, drop
：用于事件、中间值和配置的纯数据结构体。
has copy, drop, store
：可作为动态字段名称使用。
无能力： 烫手山芋结构体。必须在同一交易中被消耗。请查看patterns参考文件。

Rules

规则

```
object::new(ctx)
```
is the only way to create a UID. The
```
id: UID
```
field must be first.
Once
```
store
```
is added to a type, custom transfer rules are permanently disabled.
Once an object is shared, it cannot be converted back to address-owned.
Always remove all dynamic fields before deleting a parent object — orphaned fields become permanently inaccessible.
Accessing a nonexistent dynamic field (via
```
borrow
```
,
```
borrow_mut
```
, or
```
remove
```
) aborts the transaction. Use
```
exists_
```
to check first.
Wrapping and unwrapping can happen within the same transaction — a PTB can wrap an object and later unwrap it atomically.
Common capabilities:
```
AdminCap
```
,
```
TreasuryCap
```
,
```
UpgradeCap
```
. Always mention all three when discussing the capability pattern.
Each
```
Table
```
entry is a separate storage operation — gas cost scales linearly with entries accessed per transaction.
Prefer immutable references (
```
&
```
) on shared objects to maximize parallel execution.
Do not use
```
VecMap
```
for collections larger than ~100 entries. Use
```
Table
```
instead.

```
object::new(ctx)
```
是创建UID的唯一方式。
```
id: UID
```
字段必须是第一个字段。
一旦为类型添加
```
store
```
能力，自定义转移规则将永久失效。
对象一旦被共享，就无法转换回地址所有。
删除父对象前必须移除所有动态字段——孤立字段将永久无法访问。
访问不存在的动态字段（通过
```
borrow
```
、
```
borrow_mut
```
或
```
remove
```
）会终止交易。请先使用
```
exists_
```
进行检查。
包装与解包可在同一交易中完成——PTB可以原子性地包装对象然后解包。
常见能力：
```
AdminCap
```
、
```
TreasuryCap
```
、
```
UpgradeCap
```
。讨论能力模式时请务必提及这三种。
每个
```
Table
```
条目都是单独的存储操作——每个交易访问的条目数量会线性影响gas成本。
在共享对象上优先使用不可变引用（
```
&
```
）以最大化并行执行效率。
不要将
```
VecMap
```
用于超过约100条目的集合。请改用
```
Table
```
。

Common mistakes

常见错误

Adding
store
when you need custom transfer rules. Once granted, any module can call
```
public_transfer
```
and your enforcement logic is bypassed permanently.
Using
VecMap
for large collections. It has O(n) lookup and is stored inline, hitting the 256 KB object size limit quickly.
Confusing
dynamic_field
with
dynamic_object_field
. Use
```
dynamic_object_field
```
when the child must remain queryable by ID in explorers. Use
```
dynamic_field
```
for plain values.
Deleting an object without removing its dynamic fields first. Those fields become permanently inaccessible.
Using the legacy
sui::display
module for new code. Use
```
sui::display_registry
```
(Display V2). V1 is deprecated and will be decommissioned.
Forgetting to
display_registry::share(display)
after setting fields. The display must be shared to be discoverable.

需要自定义转移规则时添加
store
能力：一旦授予该能力，任何模块都可以调用
```
public_transfer
```
，你的执行逻辑将被永久绕过。
将
VecMap
用于大型集合：它的查找复杂度为O(n)且是内联存储，会很快达到256 KB的对象大小限制。
混淆
dynamic_field
与
dynamic_object_field
：当子对象需要通过ID在浏览器中可查询时，使用
```
dynamic_object_field
```
。纯值请使用
```
dynamic_field
```
。
删除对象前未移除其动态字段： 这些字段将永久无法访问。
在新代码中使用旧版
sui::display
模块：请使用
```
sui::display_registry
```
（Display V2）。V1已被弃用并将被停用。
设置字段后忘记调用
display_registry::share(display)
： Display必须被共享才能被发现。

sui-object-model

Original

Translation

Sui Object Model

Sui对象模型

Reference files

参考文件

ownership — Ownership Types and Versioning

ownership — 所有权类型与版本控制

transfers — Transferring and Deleting Objects

transfers — 对象转移与删除

dynamic-fields-and-collections — Dynamic Fields and Collections

dynamic-fields-and-collections — 动态字段与集合

patterns — Common Patterns and Derived Objects

patterns — 常见模式与派生对象

display — Object Display (V2)

display — Object Display（V2）

Routing guide

路由指南

Object structure

对象结构

Defining objects in Move

在Move中定义对象

Move abilities and objects

Move能力与对象

Object ability combinations

对象能力组合

Non-object struct combinations (no
`key`
)

非对象结构体组合（无
`key`
）

Rules

规则

Common mistakes

常见错误

sui-object-model

Original

Translation

Sui Object Model

Sui对象模型

Reference files

参考文件

ownership — Ownership Types and Versioning

ownership — 所有权类型与版本控制

transfers — Transferring and Deleting Objects

transfers — 对象转移与删除

dynamic-fields-and-collections — Dynamic Fields and Collections

dynamic-fields-and-collections — 动态字段与集合

patterns — Common Patterns and Derived Objects

patterns — 常见模式与派生对象

display — Object Display (V2)

display — Object Display（V2）

Routing guide

路由指南

Object structure

对象结构

Defining objects in Move

在Move中定义对象

Move abilities and objects

Move能力与对象

Object ability combinations

对象能力组合

Non-object struct combinations (no key)

非对象结构体组合（无key）

Rules

规则

Common mistakes

常见错误

Non-object struct combinations (no
`key`
)

非对象结构体组合（无
`key`
）