Object Ownership

OBJECT_OWNERSHIP Skill

Trigger Pattern: Always required for Sui Move audits -- object lifecycle and ownership model Inject Into: Breadth agents, depth-state-trace, depth-token-flow Finding prefix: [OO-N] Rules referenced: R4, R5, R9, R10, R13

Sui's object-centric model is fundamentally different from account-based chains. Every struct with the key ability is an on-chain object with a globally unique ID, and its ownership model (owned/shared/frozen/wrapped) determines who can access and mutate it. Incorrect ownership choices, missing transfer restrictions, orphaned UIDs, and uncontrolled dynamic fields are the primary Sui-specific vulnerability classes.

---

1. Object Inventory

For EVERY struct with key ability in the codebase, build this table:

Ability rules:

• key alone: Object can exist on-chain but CANNOT be transferred by generic transfer::public_transfer (requires module-defined transfer logic).
• key + store: Object CAN be transferred by anyone via transfer::public_transfer. This is a permissive choice -- verify it is intentional.
• key + store + copy: Object can be duplicated -- extremely rare for value-bearing objects. FLAG if found on any object holding balances.
• key + store + drop: Object can be silently discarded without calling a destructor. FLAG if the object holds Balance<T> or other value -- tokens can be lost.

Ownership model classification:

• OWNED: Created and transferred to a specific address via transfer::transfer or transfer::public_transfer. Only the owner can pass it as a transaction argument.
• SHARED: Made accessible to all via transfer::public_share_object. Any transaction can read/write it. CRITICAL access control implications.
• FROZEN: Made immutable via transfer::public_freeze_object. Anyone can read, no one can mutate.
• WRAPPED: Stored as a field inside another object (not directly addressable on-chain). Accessible only through the parent.
• MIXED: Object starts as one type and transitions to another (e.g., created as owned, then shared). Document the transition path.

---

2. Ownership Model Analysis

2a. Owned Object Audit

For each OWNED object:

Check patterns:

• Should this be shared? If multiple unrelated parties need to mutate the object in the same epoch, owned model creates bottlenecks or requires trust delegation. Common mistake: config objects that should be shared are kept owned, forcing single-admin bottleneck.
• Ownership change undermines assumptions? If code assumes "only admin holds AdminCap", but AdminCap has store ability, it can be transferred to anyone. Verify that transfer does not break invariants downstream.
• Phantom ownership: Object is "owned" but the owner address is a PDA-like derived address that nobody controls (e.g., @0x0). The object is effectively inaccessible -- equivalent to locked funds if it holds value.

2b. Shared Object Audit

For each SHARED object:

CRITICAL checks:

• Access control on mutation: Shared objects can be passed as arguments by ANY transaction. If a function takes &mut SharedObj without verifying the caller has authority (e.g., checking a capability object), anyone can mutate it. This is the #1 Sui vulnerability pattern.
• Public mutable reference getters: A public function that returns &mut internal state, calls borrow_mut, or exposes dynamic-field mutable access is externally callable by attacker packages. It must be public(package) or require a capability unless external mutation is explicitly safe.
• Helper visibility: Internal helpers that mutate state or expose sensitive references should not be public only because another module in the same package needs them. Use public(package) for same-package helpers.
• Consensus ordering: Transactions touching the same shared object are ordered by Sui's consensus. If the protocol relies on specific transaction ordering (e.g., "admin sets fee before user trades"), front-running is possible because consensus ordering is non-deterministic from the user's perspective.
• Race conditions: Two transactions that both mutate the same shared object field can produce different final states depending on execution order. If the protocol assumes sequential access, this is a bug.
• Gas-based DoS: An attacker can submit many transactions touching a shared object to increase contention and gas costs for legitimate users.

2c. Frozen Object Audit

For each FROZEN object:

Check: If frozen object holds configuration that may need updating (fee rates, oracle addresses, admin keys), freezing is likely wrong -- should be shared with access control instead.

2d. Wrapped Object Audit

For each WRAPPED object:

Check patterns:

• No unwrap path: If a wrapped object holds value (Balance, Coin) but there is no function to extract it, funds are permanently locked inside the parent. Apply Rule 9: stranded asset = minimum MEDIUM.
• Parent destruction without unwrap: If the parent object can be destroyed (has drop ability or explicit destructor) without first unwrapping/extracting the inner object, the inner object's value is lost.
• Dynamic fields on wrapped objects: Dynamic fields added to a wrapped object's UID are NOT accessible when the object is wrapped. They become orphaned until unwrap. If the protocol adds dynamic fields and then wraps, those fields are inaccessible.

---

3. Object Transfer Analysis

For each transfer::transfer, transfer::public_transfer, transfer::share_object, transfer::public_share_object, transfer::freeze_object, transfer::public_freeze_object call:

Check patterns:

• store ability gate: transfer::public_transfer requires store. transfer::transfer does not -- it is module-restricted. If an object should NOT be freely transferable by holders, it should NOT have store.
• Recipient validation: If an object is transferred to an arbitrary address and that address does not have the matching module to use it, the object is stranded. This is especially dangerous for capability objects (AdminCap sent to a contract that cannot invoke admin functions).
• Transfer to self: Transferring an object to the transaction sender is sometimes used as a "commit" pattern. Verify this does not bypass any state transitions.
• Conditional transfer: If transfer happens inside a conditional branch, check the else branch -- does the object leak (neither transferred, shared, frozen, wrapped, nor destroyed)?

---

4. Shared Object Mutation Safety

For each shared object, build the mutation map:

Sui-specific re-entrancy note: Move's borrow checker prevents re-entrancy within a single module (you cannot pass &mut Obj to a function that also borrows &mut Obj). However, cross-module re-entrancy is possible if Object A's mutation calls a function in Module B that calls back to Module A with a different entry point that accesses a DIFFERENT shared object whose state is coupled with Object A.

Concurrent mutation checklist:

• Can two independent transactions mutate the same field to conflicting values?
• Does the protocol rely on reading a value from the shared object and then writing back a derived value? (TOCTOU with consensus ordering)
• Can an attacker observe a pending transaction on a shared object and submit a competing transaction that front-runs it?
• Are balance operations on shared objects atomic? (Balance::split + Balance::join should not be interruptible across objects)

---