sui-object-model

Guide Sui Move object modeling with ownership, storage, and transfer patterns.

10|5|Updated Mar 13, 2026
One-click install
npx skills add https://github.com/MystenLabs/skills --skill sui-object-model
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: sui-object-model
Source: https://github.com/MystenLabs/skills/tree/main/object-model
Command: npx skills add https://github.com/MystenLabs/skills --skill sui-object-model

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

It solves confusion and costly mistakes when modeling onchain data in Sui by explaining how objects work (structure, versioning, ownership) and how to choose the right storage, transfer, and access patterns.

Core Features & Use Cases

  • Object fundamentals: Clarifies the four components of a Sui object (ID, version, owner, transaction digest) and how transactions consume/produce object versions.
  • Ownership decision-making: Covers address-owned, shared, immutable (frozen), party/consensus-address-owned, and wrapped objects, including consensus and parallelism implications.
  • Transfer, sharing, and deletion: Explains module-restricted vs public transfer functions, custom transfer rules, Receiving<T> patterns for transfer-to-object, and the correct way to delete/unpack objects (especially those without drop).
  • Dynamic fields and collection storage: Differentiates dynamic_field vs dynamic_object_field and compares Table, Bag, VecMap, VecSet, and LinkedTable (including scalability and cleanup requirements).
  • Modeling patterns for real systems: Provides guidance for hot potato workflows, capability-based permissions (AdminCap/TreasuryCap), soulbound/non-transferable objects, inventories, and derived objects vs dynamic fields.
  • Object Display (V2): Shows how to configure wallet/explorer rendering using DisplayRegistry, templates, publisher/cap mechanics, and migration expectations.

Quick Start

Use the sui-object-model skill to answer: “How should I model an inventory that holds arbitrary NFTs and keep them transferable according to my rules, including the right ownership and storage pattern?”

Frequently Asked Questions about sui-object-model

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I choose between dynamic fields and dynamic object fields when modeling collections in Sui Move?

Dynamic fields store values by hashable names, while dynamic object fields preserve object structure for direct access. Choosing dynamic object fields keeps nested objects transferable and independently owned within Sui Move collections.

What is the best way to model capabilities and permissions in Sui Move?

Model capabilities as objects like AdminCap or TreasuryCap to manage permissions in Sui Move. Transfer the capability object to an address, requiring the caller to pass it into functions to prove authorization for restricted operations.

How does object ownership affect transaction execution and parallelism in Sui Move?

Object ownership affects parallelism in Sui Move because address-owned objects allow transactions to execute concurrently without consensus. Shared objects require global sequencing, reducing parallel throughput for operations touching them.

How do I delete or unpack a Sui Move object that does not have the drop ability?

To delete a Sui Move object without drop, explicitly call delete_obj in a module function and pass the object by value. Unpack the object's fields first, ensuring inner objects are transferred or deleted individually.

When should I use a Table vs a Bag for storing dynamic data in Sui Move?

Use Table for typed key-value storage in Sui Move when keys and values share specific types. Use Bag for heterogeneous collections holding diverse types, though both require manual cleanup of dynamic fields upon deletion.

How do I implement custom transfer rules for non-transferable soulbound objects in Sui Move?

Implement custom transfer rules in Sui Move by restricting transfer functions to internal module logic and omitting public transfer. Use Receiving<T> patterns or keep objects address-owned to enforce non-transferable soulbound behavior.