Sui's Object Model

Sui’s object model is fundamentally different from account-based blockchains. Instead of organizing state around accounts, Sui treats everything as an object - making it the fundamental unit of storage and the primary building block for on-chain assets and logic.

What is a Sui Object?

In Sui, an object is a structured piece of data with the following characteristics:

Globally Unique

Each object has a unique ID derived from its creation transaction

Versioned

Objects have a version number that increments with each mutation

Owned

Every object has an owner - an address, another object, or shared

Typed

Objects are instances of Move structs with the key ability

Object Structure

Every Sui object must have id: UID as its first field. Here’s what an object looks like in Move:

public struct Object has key, store {
    id: UID,
    value: u64,
}

public struct Wrapper has key {
    id: UID,
    o: Object,
}

public fun create(value: u64, recipient: address, ctx: &mut TxContext) {
    transfer::public_transfer(
        Object { id: object::new(ctx), value },
        recipient,
    )
}

The UID type is globally unique and can only be created through object::new(ctx), ensuring no two objects can ever have the same ID.

Object Properties

ID and UID

ID: A copyable, droppable identifier that can be freely duplicated
UID: A unique identifier that cannot be copied or dropped, only deleted

public struct ID has copy, drop, store {
    bytes: address,
}

public struct UID has store {
    id: ID,
}

The UID type enforces uniqueness:

No two UID values are ever equal
Can only be created from TxContext
Must be explicitly deleted with id.delete()

Version Numbers

From the Rust implementation:

pub struct MoveObject {
    /// The type of this object. Immutable
    type_: MoveObjectType,
    /// DEPRECATED this field is no longer used to determine transfer
    has_public_transfer: bool,
    /// Number that increases each time a tx takes this object as a mutable input
    /// This is a lamport timestamp, not a sequentially increasing version
    version: SequenceNumber,
    /// BCS bytes of a Move struct value
    contents: Vec<u8>,
}

Why Lamport Timestamps?

Sui uses Lamport timestamps instead of simple sequential numbers to support causally ordered execution. When an object is used as input to a transaction, its version is updated based on the maximum version of all inputs plus one.

Object Types

Sui supports different types of objects for different use cases:

Owned Objects
Shared Objects
Frozen Objects
Wrapped Objects

Objects owned by a single address. These can be used in transactions without consensus.

public fun create(value: u64, recipient: address, ctx: &mut TxContext) {
    transfer::public_transfer(
        Object { id: object::new(ctx), value },
        recipient,
    )
}

Objects accessible by anyone. These require consensus and have slower transaction processing.

public fun create_shared(value: u64, ctx: &mut TxContext) {
    transfer::public_share_object(
        Object { id: object::new(ctx), value }
    )
}

Immutable objects that can never be modified. Useful for constants and permanent data.

public fun freeze_object(o: Object) {
    transfer::public_freeze_object(o)
}

Objects that exist inside other objects, invisible to external transactions.

public fun wrap(o: Object, ctx: &mut TxContext) {
    transfer::transfer(Wrapper { id: object::new(ctx), o }, ctx.sender());
}

Object Operations

Creating Objects

Objects are created by constructing a Move struct with key ability and a UID:

public fun create(value: u64, recipient: address, ctx: &mut TxContext) {
    transfer::public_transfer(
        Object { id: object::new(ctx), value },
        recipient,
    )
}

Reading Objects

public fun get_value(o: &Object): u64 {
    o.value
}

Updating Objects

public fun set_value(o: &mut Object, value: u64) {
    o.value = value;
}

public fun update(o1: &mut Object, o2: &Object) {
    o1.value = o2.value;
    event::emit(NewValueEvent { new_value: o2.value })
}

Deleting Objects

Objects must be unpacked and their UID explicitly deleted:

public fun delete(o: Object) {
    let Object { id, value: _ } = o;
    id.delete();
}

Forgetting to delete the UID will result in a compilation error, as UID does not have the drop ability.

Special Object Types

Coin Objects

Coins are optimized objects with a known structure:

pub fn new_coin(coin_type: TypeTag, version: SequenceNumber, id: ObjectID, value: u64) -> Self {
    unsafe {
        Self::new_from_execution_with_limit(
            MoveObjectType::coin(coin_type),
            true,
            version,
            Coin::new(id, value).to_bcs_bytes(),
            256,
        )
        .unwrap()
    }
}

/// Return the `value: u64` field of a `Coin<T>` type.
pub fn get_coin_value_unsafe(&self) -> u64 {
    debug_assert!(self.type_.is_coin());
    // 32 bytes for object ID, 8 for balance
    debug_assert!(self.contents.len() == 40);
    u64::from_le_bytes(<[u8; 8]>::try_from(&self.contents[ID_END_INDEX..]).unwrap())
}

System Objects

Sui has several singleton objects with hardcoded IDs:

/// The hardcoded ID for the singleton Sui System State Object.
const SUI_SYSTEM_STATE_OBJECT_ID: address = @0x5;

/// The hardcoded ID for the singleton Clock Object.
const SUI_CLOCK_OBJECT_ID: address = @0x6;

/// The hardcoded ID for the singleton AuthenticatorState Object.
const SUI_AUTHENTICATOR_STATE_ID: address = @0x7;

/// The hardcoded ID for the singleton Random Object.
const SUI_RANDOM_ID: address = @0x8;

Object Size Limits

Objects have size constraints defined in the protocol:

if contents.len() as u64 > max_move_object_size {
    return Err(ExecutionError::from_kind(
        ExecutionErrorKind::MoveObjectTooBig {
            object_size: contents.len() as u64,
            max_object_size: max_move_object_size,
        },
    ));
}

The default maximum object size is configured in the protocol config, with exceptions for system objects when allow_unbounded_system_objects() is enabled.

Best Practices

Always delete UIDs

When destructing an object, always call .delete() on its UID to properly clean up:

let Object { id, value: _ } = o;
id.delete();

Use the right ownership model

Owned objects for user-specific assets (NFTs, tokens)
Shared objects for multi-user protocols (DEX pools)
Frozen objects for immutable data (metadata)

Minimize object size

Smaller objects cost less in storage fees and are more efficient to process:

Use efficient data structures
Avoid storing redundant data
Consider dynamic fields for optional data

Ownership

Learn about ownership types and rules

Dynamic Fields

Extend objects with dynamic fields

Object Storage

Understand how objects are stored

Architecture

Objects & Ownership

Transactions

Move Language

Tokenomics

Sui's Object Model

What is a Sui Object?

Globally Unique

Versioned

Owned

Typed

Object Structure

Object Properties

ID and UID

Version Numbers

Object Types

Object Operations

Creating Objects

Reading Objects

Updating Objects

Deleting Objects

Special Object Types

Coin Objects

System Objects

Object Size Limits

Best Practices

Ownership

Dynamic Fields

Object Storage

Build docs developers (and LLMs) love

Architecture

Objects & Ownership

Transactions

Move Language

Tokenomics

Documentation Index

​What is a Sui Object?

Globally Unique

Versioned

Owned

Typed

​Object Structure

​Object Properties

​ID and UID

​Version Numbers

​Object Types

​Object Operations

​Creating Objects

​Reading Objects

​Updating Objects

​Deleting Objects

​Special Object Types

​Coin Objects

​System Objects

​Object Size Limits

​Best Practices

​Related Topics

Ownership

Dynamic Fields

Object Storage

Build docs developers (and LLMs) love

What is a Sui Object?

Object Structure

Object Properties

ID and UID

Version Numbers

Object Types

Object Operations

Creating Objects

Reading Objects

Updating Objects

Deleting Objects

Special Object Types

Coin Objects

System Objects

Object Size Limits

Best Practices

Related Topics