Problem this solves: Teams struggle to map complex app state (permissions, collections, indices) to Sui’s object model without slipping into a single shared mega-object.

What you’ll learn:

How to structure app state with owned, shared, and immutable objects

Use of capabilities for permissions and admin tasks

Dynamic fields to scale collections without huge monolithic objects

Versioning and upgrade patterns

1. Capability-driven design A capability is an object proving you’re allowed to do something (e.g., mint, admin, pause). Pattern:

On init, create an immutable AdminCap owned by the project’s cold address (or a multi-sig).

Functions that require admin rights take &AdminCap as a parameter.

Rotations: transfer the AdminCap if admins change; no need to rewrite storage.

Benefits: Clear, auditable permissions with least privilege.

2. Owned first, shared sparingly Example: A game with player inventories and a public leaderboard.

Inventory (owned by player): items, counters, achievements → high parallelism.

Leaderboard (shared): append only minimal score entries; heavy analysis off-chain or periodic roll-ups.

Migration tip: If a shared object is growing too hot, split it by shard key (e.g., season, region) or use dynamic fields to distribute load.

3. Dynamic fields for scalable maps Dynamic fields let an object act like a dictionary without storing a massive list inline.

Pattern:

Collection object (owned/shared) + dynamic fields keyed by item IDs.

Fetch by key when needed; you avoid ballooning a single on-chain struct.

Use cases: NFT collections, per-user settings, sparse indexes.

4. Versioning and upgrades Every mutation bumps an object’s version.

To “upgrade” a structure layout, you can migrate: create a new object type, transform data, deprecate old.

Keep immutable objects for schema descriptors or constants; reference them from mutable objects.

Safe rollout steps:

Introduce new types side-by-side.

Add migration functions gated by AdminCap.

Offer per-user opt-in migrations first, then a full sweep.

Freeze old paths after a sunset period.

5. Step-by-step: Rebuilding a subscription app Problem: Your subscription service has one shared Subscriptions map; writes conflict; fees spike.

Solution path:

Create a Plan object (immutable) describing price/duration.

For each user, create an owned Subscription object with plan_id, start, expires.

Maintain a shared Directory with just (user, subscription_id) pairs for discovery.

Renewals mutate only the user’s Subscription (owned) → parallel.

Admin price changes update Plan (immutable v2) + migration function gated by AdminCap.

Analytics happen off-chain using emitted events.

Result: Massive contention drop; predictable fees; clean permission boundaries.

6. Quick checklist Minimal shared, maximal owned.

Capabilities for authority.

Dynamic fields for scalable indexing.

Clear migration paths with immutable descriptors.