Skip to main content

Using objects

Using an object as an entry function argument​

0x1::object::Object<T> can be used as an input argument to an entry function. It's encoded as the address of the object, and type checked to the value in T.

For more generic functions, this can be handled as providing a generic T for typing the input:

module my_addr::object_playground {
  use aptos_framework::object::Object;

  /// This will fail of the object doesn't have the generic `T` stored
  entry fun do_something<T>(object: Object<T>) {
    // ...
  }
}

Additionally, the individual resources that are at the object can be used. The resource will be checked for existence before the function executes.

module my_addr::object_playground {
  use aptos_framework::object::Object;

  struct MyAwesomeStruct has key {}

  /// This will fail if the object doesn't have MyAwesomeStruct stored
  entry fun do_something(object: Object<MyAwesomeStruct>) {
    // ...
  }
}

The resource 0x1::object::ObjectCore is available for all objects

module my_addr::object_playground {
  use aptos_framework::object::{Object, ObjectCore};

  /// This will only fail of the address is not an object
  entry fun do_something(object: Object<ObjectCore>) {
    // ...
  }
}

Object Types

Objects can store multiple resources at their address, and you can refer to an Object by any of those types. You can convert an address to an object, or convert an object between types as long as the resource is available.

module my_addr::object_playground {
  use aptos_framework::object::{self, Object, ObjectCore};

  struct MyAwesomeStruct has key {}

  fun convert_type(object: Object<ObjectCore>): Object<MyAwesomeStruct> {
    object::convert<MyAwesomeStruct>(object)
  }

  fun address_to_type(object_address: address): Object<MyAwesomeStruct> {
    object::address_to_object<MyAwesomeStruct>(object)
  }
}

Object ownership

Objects can be owned by any address, this includes Objects, Accounts, and Resource accounts. This allows composability between objects, as well as complex relationships between objects.

Looking up ownership​

Ownership can be found by a few methods:

module my_addr::object_playground {
  use std::signer;
  use aptos_framework::object::{self, Object};

  // Not authorized!
  const E_NOT_AUTHORIZED: u64 = 1;

  fun check_owner_is_caller<T>(caller: &signer, object: Object<T>) {
    assert!(
      object::is_owner(object, signer::address_of(caller)),
      E_NOT_AUTHORIZED
    );
  }

  fun check_is_owner_of_object<T>(addr: address, object: Object<T>) {
    assert!(object::owner(object) == addr, E_NOT_AUTHORIZED);
  }

  fun check_is_nested_owner_of_object<T, U>(
    caller: &signer,
    outside_object: Object<T>,
    inside_object: Object<U>
  ) {
    // Ownership expected
    // Caller account -> Outside object -> inside object

    // Check outside object owns inside object
    let outside_address = object::object_address(outside_object);
    assert!(object::owns(inside_object, outside_address), E_NOT_AUTHORIZED);

    // Check that the caller owns the outside object
    let caller_address = signer::address_of(caller);
    assert!(object::owns(outside_object, caller_address), E_NOT_AUTHORIZED);

    // Check that the caller owns the inside object (via the outside object)
    // This can skip the first two calls (and even more nested)
    assert!(object::owns(inside_object, caller_address), E_NOT_AUTHORIZED);
  }
}

Transfer of ownership​

An object can be transferred as long as ungated transfer has not been disabled.
See disabling transfer of an object.

If the ungated transfer is disabled, only transfers can be done with a TransferRef or a LinearTransferRef. When ungated transfers are enabled, objects can be transferred as follows:

module my_addr::object_playground {
  use aptos_framework::object::{self, Object};

  /// Transfer to another address, this can be an object or account
  fun transfer<T>(owner: &signer, object: Object<T>, destination: address) {
    object::transfer(owner, object, destination);
  }

  /// Transfer to another object
  fun transfer_to_object<T, U>(
    owner: &signer,
    object: Object<T>,
    destination: Object<U>
  ) {
    object::transfer_to_object(owner, object, destination);
  }
}

Deleting or Burning objects

There are two ways to remove an object:

  • Delete
  • Burn

Deleting​

To delete an object, the user must have a DeleteRef see allowing deletion of an object.

Burning​

However, if the object is not deletable, you can tombstone and burn the unwanted object.

module my_addr::object_playground {
  use aptos_framework::object::{self, Object};

  fun burn_object<T>(owner: &signer, object: Object<T>) {
    object::burn(owner, object);
    assert!(object::is_burnt(object) == true, 1);
  }
}

If a user decided that they did not want to burn it, they can un-burn it

module my_addr::object_playground {
  use aptos_framework::object::{self, Object};

  fun unburn_object<T>(owner: &signer, object: object::Object<T>) {
    object::unburn(owner, object);
    assert!(object::is_burnt(object) == false, 1);
  }
}

Example contracts​