Working with Sui Objects

Introduction

Sui Move is a fully object-centric language. Transactions on Sui are expressed as operations where the inputs and outputs are both objects. As we briefly touched on this concept in this lecture, Sui objects are the basic unit of storage in Sui. It all starts from the struct keyword.

Here is an example

struct Transcript {
    history: u8,
    math: u8,
    literature: u8,
}

The above definition is a regular Move struct, but it is not a Sui object. In order to make a custom Move type instantiate a Sui object in global storage, we need to add the key ability, and a globally unique id: UID field inside the struct definition.

Create a Sui Object

Creating a Sui object requires a unique ID, we use the sui::object::new function to create a new ID passing in the current TxContext.

In Sui, every object must have an owner, which can be either an address, another object, or "shared". In our examples, we decided to make our new transcriptObject owned by the transaction sender, it is done using the transfer function of Sui framework and using tx_context::sender function to get the current entry call's sender's address.

public entry fun create(ctx: &mut TxContext) {
        let object = CounterObject {
            id: object::new(ctx),
            value:0
        };
        transfer::public_transfer(object, tx_context::sender(ctx));
    }

We will discuss object ownership more in-depth in the next section.

💡Note: Move supports field punning, which allows us to skip the field values if the field name happens to be the same as the name of the value variable it is bound to.

Ownership of Sui Objects

Each object in Sui has an owner field that indicates how this object is being owned. In Sui Move, there are total of four types of ownership.

• Owned

  • Owned by an address

  • Owned by another object

• Shared

  • Shared immutable

  • Shared mutable

Owned Object

The first two types of ownership fall under the Owned Objects category. Owned objects in Sui are processed differently from shared objects and do not require global ordering.

Owned by an address

Let's continue using our transcript example here. This type of ownership is pretty straightforward as the object is owned by an address to which the object is transferred to upon object creation, such as in the above example at this line:

    transfer::transfer(transcriptObject, tx_context::sender(ctx)) // where tx_context::sender(ctx) is the recipient

where the transcriptObject is transferred to the address of the transaction sender upon creation.

Owned by an object

In order for an object to be owned by another object, it is done using dynamic_object_field, which we will explore in a future section. Basically, when an object is owned by another object, we will call it a child object. A child object is able to be looked up in global storage using its object ID.

module sui::dynamic_field {

public fun add<Name: copy + drop + store, Value: store>(
  object: &mut UID,
  name: Name,
  value: Value,
);

Shared Objects

Shared Immutable Objects

Certain objects in Sui cannot be mutated by anyone, and because of this, these objects do not have an exclusive owner. All published packages and modules in Sui are immutable objects.

To make an object immutable manually, one can call the following special function:

    transfer::freeze_object(obj);

Shared Mutable Objects

Shared objects in Sui can be read or mutated by anyone. Shared object transactions require global ordering through a consensus layer protocol, unliked owned objects.

To create a shared object, one can call this method:

    transfer::share_object(obj);

Once an object is shared, it stays mutable and can be accessed by anyone to send a transaction to mutate the object.

Coming up: Parameter Passing and Object Deletion