Objects
The Sui object model is the foundation of how Sui stores and manages onchain state. Objects have unique IDs, owners, and types. Transactions consume and produce objects, and Sui records every object change onchain.
What is a Sui object?
On Sui, the base unit of storage is an object. Unlike account-based blockchains where state lives in a single global store keyed by address, Sui organizes state around individual objects. Each object has:
- A globally unique ID
- An ownership type: owned by an address or another object, shared, immutable, or party (consensus-address owned)
- A type defined by a Move package
- A version that increments with each mutation
Move packages are also objects. When you publish a Move package to Sui, the package becomes an immutable object stored onchain. The functions and types defined in that package are then available to other transactions.
Transactions on Sui take objects as inputs and produce objects as outputs. When a transaction runs, it can read, mutate, transfer, or delete its input objects. The resulting objects become available for future transactions.
Object ownership determines how a transaction can use an object. Only transactions signed by the owner can use an address-owned object. Any transaction can use a shared object, but a shared object requires consensus to order concurrent access. Another object can also own an object, and some objects, such as published Move packages, are immutable.
To see how these concepts appear in code, the following example shows a basic Move struct that defines a custom object type:
public struct TodoList has key {
id: UID,
items: vector<String>,
}
The key ability marks this struct as a Sui object. The id field of type UID gives each instance a unique onchain identifier. When you create a value of this type and transfer it to an address, it becomes an owned object on Sui.
The pages in this section cover the object model, how to use objects, and the different object ownership methods in more detail.
Types of Object Ownership
Derived Objects
Derived objects on Sui have deterministic addresses computed from a parent object and key, enabling Transfer-to-Object compatibility, guaranteed one-per-key uniqueness, and native parallelization for composable systems.
Dynamic Fields
Dynamic fields and dynamic object fields on Sui are added and removed dynamically, affect gas only when accessed, and store heterogeneous values.
Versioning
Sui versions every onchain object by (ID, version) pair using Lamport timestamps, with objects versioned either through the fastpath or through consensus depending on their ownership type.
Owned Compared With Shared
The same trustless swap service implemented 2 ways, once with address-owned objects and a custodian and once with a shared object, to show the trade-offs between the 2 ownership models.
Object Display
Transferring Objects
What is party object ownership?
A party object combines properties of address-owned and shared objects. When you call party_transfer, only the members of the Party can use the object as a transaction input, as with an address-owned object. As with a shared object, the default permissions of the Party value can let anyone use the object. The object must go through consensus.
The object model has 2 related owner types:
ConsensusAddressOwner: A single address exclusively owns the object, and Sui sequences it through consensus.Party: Sui sequences the object through consensus with per-address permissions. Each listed address receives a subset of permission flags, and addresses not explicitly listed fall back to the default permissions.
The party_transfer function asserts that the Party value has a single owner.