Rooch Object

In Rooch, an Object is akin to a box model. Creating an Object is equivalent to creating a box in the state space, encapsulating an instance of type T within it, with ObjectID serving as the address of this box. Moreover, this box supports the dynamic addition of states, which is the dynamic field feature of an Object.

If we consider the state space of smart contracts as analogous to the heap memory of a program, an Object is similar to a smart pointer, providing references and operations on the state, as well as lifecycle management.

Ownership of Object

The owner field of ObjectEntity signifies which account address owns the Object. Through owner, Objects can be categorized into:

1. SystemOwnedObject: Objects with owner as 0x0. After the creation of the object, it is defaulted to SystemOwnedObject.
2. UserOwnedObject: Objects with owner non-equal to 0x0. Once the Object is transferred to a user, owner will be set as the address of that user.

Object Life Cycle

Creating an Object

An Object of type T can be created by invoking object::new method.

module moveos_std::object {
    #[private_generics(T)]
    public fun new<T: key>(value: T): Object<T>;
}

• This method is protected by private_generics(T), hence, it can only be invoked by the module where T is located. The developer of T module gets to decide whether to provide the methods to encapsulate T into the Object.
• T must has the key ability.
• The ObjectID of this Object is a globally unique ID automatically assigned by the system.

In addition to the above normal Objects, two special Object creation methods are provided that do not automatically assign IDs; instead, they generate IDs through a predetermined algorithm, called Named Object.

module moveos_std::object {
    #[private_generics(T)]
    public fun new_named_object<T: key>(value: T): Object<T>;

    #[private_generics(T)]
    public fun new_account_named_object<T: key>(account: address, value: T): Object<T>;
}

• NamedObject: ObjectID is generated using type name of T. The generation formula is sha3(type_name<T>()). This is generally used for globally unique Objects, like 0x2::timestamp::Timestamp.
• Account NamedObject: ObjectID is generated using both the account address and type name of T. The generating formula is sha3(account + type_name<T>()). It's generally used for Objects of which each user owns only one, like 0x3::coin_store::CoinStore<CoinType>.

Operating an Object

Transferring Ownership

Transfer the Object to new_owner:

module moveos_std::object {
    public fun transfer<T: key + store>(self: Object<T>, new_owner: address);
}

The owner retrieves their Object through object_id:

module moveos_std::object {
    public fun take_object<T: key + store>(owner: &signer, object_id: ObjectID): Object<T>;
}

Note: Once the Object is retrieved, the owner is set to 0x0, at which point the Object becomes a SystemOwnedObject.

For the above methods, T must has key + store ability. Such types of Object are called PublicObject, and the user can transfer the ownership of PublicObject on their own.

If it is the type of Object that only has key ability, we can call it PrivateObject. Users cannot directly transfer the ownership of PrivateObject, and the ownership transfer of PrivateObject must be assisted by the API provided by the module where T is located.

module moveos_std::object {
    #[private_generics(T)]
    public fun take_object_extend<T: key>(object_id: ObjectID): (address, Object<T>);
}

The take_object_extend method is protected by private_generics(T), and can only be invoked by modules where T is located. The developer gets to decide whether to provide the method to transfer PrivateObject to other users.

Object Reference

Object<T> can be referenced in two ways, one is read-only reference &Object<T>, the other one is mutable reference &mut Object<T>.

We can get &T through object::borrow(&Object<T>) method, and &mut T through object::borrow_mut(&mut Object<T>). As for what operations can be performed after obtaining &T and &mut<T>, this is defined by T's module.

There are two ways to get the Object reference:

1. Passed in through the entry method.

entry fun my_entry(obj: &Object<MyStruct>, obj_mut: &mut Object<MyStruct>) {
    // do something 
}

2. Obtained through borrow_object and borrow_mut_object methods.

module moveos_std::object {
    public fun borrow_object<T: key>(object_id: ObjectID): &Object<T>;

    public fun borrow_mut_object<T: key>(owner: &signer, object_id: ObjectID): &mut Object<T>;
}

• Note, all Objects in Rooch are open to read, everyone can get any &Object<T> through ObjectID.
• The owner of the Object can get &mut Object<T> reference through object::borrow_mut_object.

Method extension for developers:

module moveos_std::object {
    #[private_generics(T)]
    public fun borrow_mut_object_extend<T: key>(object_id: ObjectID): &mut Object<T>;
}

• The module where T is located can get any &mut Object<T> reference through ObjectID, except for cases when that Object is frozen.

Shared and Frozen Object

SystemOwnedObject Object<T> has two states, shared and frozen.

• SharedObject: Everyone can directly get the &mut Object<T> reference.
• FrozenObject: No one can get the &mut Object<T> reference, even the module where T is located.

Following method can shift Object<T> to SharedObject.

module moveos_std::object {
    public fun to_shared<T: key>(self: Object<T>);
}

To get the mutable reference of SharedObject, it must be passed through entry parameters or obtained via the method provided by object:

module moveos_std::object {
    public fun borrow_mut_object_shared<T: key>(object_id: ObjectID): &mut Object<T>;
}

Following method can shift Object<T> to FrozenObject.

module moveos_std::object {
    public fun to_frozen<T: key>(self: Object<T>);
}

Note: Once Object becomes frozen or shared, it automatically become SystemOwnedObject; no one can directly get the instance of Object<T>, only the operations on the Object are feasible through the reference.

Nested Object

Given Object<T> itself has store ability, it can be nested in other structures as fields or be saved in containers like vector, Table, etc.

struct Avatar has key {
    head: Object<Head>,
    body: Object<Body>,
}

In the above example, Object<Head> and Object<Body> are fields of the Avatar structure. These two objects belong to the Avatar structure. If the Object<Avatar> is transferred to other user, then the Object<Head> and Object<Body> will be transferred to the other user with the Object<Avatar>.

• Even in a nested state, Objects will still exist in Object Storage and can be accessed through the reference retrieval method described earlier.
• Nested Objects will always be SystemOwnedObject.

Deleting an Object

The following method can be used to delete Object:

module moveos_std::object {
    #[private_generics(T)]
    public fun remove<T: key>(self: Object<T>): T;
}

Deleting an Object will return the encapsulated data in the Object, this method can only be called by the module where T is located.

In summary, different users have different permissions for operations on Objects in different states. The following are the operations that contract developers and normal users can perform on different types of Objects using the methods provided by moveos_std::object:

• Contract developers

• Normal users

Object RPC

ObjectEntity data can be retrieved through rooch_getState RPC interface.

curl -H "Content-Type: application/json" -X POST \
--data '{"jsonrpc":"2.0","method":"rooch_getStates","params":["/object/0x2::timestamp::Timestamp", {"decode":true}],"id":1}' \
https://dev-seed.rooch.network

{
  "jsonrpc": "2.0",
  "result": [
    {
      "value": "0x711ab0301fd517b135b88f57e84f254c94758998a602596be8ae7ba56a0d14b3000000000000000000000000000000000000000000000000000000000000000004002db02e34050600",
      "value_type": "0x2::object::ObjectEntity<0x2::timestamp::Timestamp>",
      "decoded_value": {
        "abilities": 0,
        "type": "0x2::object::ObjectEntity<0x2::timestamp::Timestamp>",
        "value": {
          "flag": 4,
          "id": "0x4e8d2c243339c6e02f8b7dd34436a1b1eb541b0fe4d938f845f4dbb9d9f218a2",
          "owner": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "value": {
            "abilities": 8,
            "type": "0x2::timestamp::Timestamp",
            "value": {
              "milliseconds": "1694571540000000"
            }
          }
        }
      }
    }
  ],
  "id": 1
}

Object-related Method List

The context and object modules provide the following functions that can operate on Object:

In the above functions, if the #[private_generics<T>] column is true, it indicates that only the module where T is located can call the function.

Dynamic Fields of Object in Rooch

Rooch provides the capability to manage dynamic fields for objects. Dynamic fields are Resources or Objects stored within an Object in the form of key-value pairs. Notably, the key can be heterogeneous, meaning it is not restricted by the type of the key. More specifically, an Object can be used as a Table (opens in a new tab) or Bag (opens in a new tab).

Rooch objects offer two types of dynamic fields: normal types and Object types.

Normal dynamic fields are resources with store ability stored under an object; Object type dynamic fields store child Object instances under an object.

List of Methods for Regular Dynamic Fields

List of Methods for Object Type Dynamic Fields

Comparison between Rooch Object, Sui Object, and Aptos Object

Sui Object

• Sui Object is a special kind of struct that requires the struct to has a key ability, and UID must be its first field. An Object is provided by the VM and storage, and there's no Object type in Move. In Rooch, Object is a type defined in Move itself.
• Sui Object is indexed by the external system, and there's no method provided in the contract to retrieve the Object using ID; it can only be passed through parameters. Rooch provides both methods.
• If a Sui Object gets nested or saved into other containers, it will become invisible in the global Object Storage. However, even when nested or saved into other containers, the Rooch Object can still be accessed in the global Object Storage.

Aptos Object

• At the base level, an Aptos Object is a special account, where the address is the ObjectID.
• Object<T> represents the reference to an Object that can be copy,drop, whereas in Rooch, Object<T> is a single instance and cannot be copy, drop.
• Aptos Object uses DeleteRef, ExtendRef, TransferRef to indicate different operation permissions on Object. But Rooch Object differentiates different permissions using read-only reference, mutable reference, and instance.

References

1. Rooch Object API document (opens in a new tab)
2. Rooch Object Source code (opens in a new tab)
3. Sui Object (opens in a new tab)
4. Aptos Object (opens in a new tab)
5. Storage Abstraction
6. Hot Potato (opens in a new tab)