Skip to main content

Configuring objects

At this point, you have an object, but how do you specialize it? Objects must be configured for their capabilities at creation time. If they are not configured with the correct capabilities at creation time, it will be impossible to change later.

Adding Resources​

An object must store data in resources. The signer of the object is required to move resources to the object's storage. Below we'll go through a deletable object example.

When I create my object, I can use the special ConstructorRef to create resources only available at creation time. For example, you can create a signer at creation time to move a resource into the object.

module my_addr::object_playground {
use std::signer;
use aptos_framework::object;

#[resource_group_member(group = aptos_framework::object::ObjectGroup)]
struct MyStruct has key {
num: u8
}

entry fun create_my_object(caller: &signer) {
let caller_address = signer::address_of(caller);

// Creates the object
let constructor_ref = object::create_object(caller_address);

// Retrieves a signer for the object
let object_signer = object::generate_signer(&constructor_ref);

// Moves the MyStruct resource into the object
move_to(&object_signer, MyStruct { num: 0 });

// ...
}
}

Extending the object​

The object was created, but the user decided to add extra data. The ExtendRef provides this functionality to retrieve the object's signer at a later time.

The ExtendRef can be used to generate a signer for the object. Permissions on who can retrieve it must be defined by the contract.

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

/// Caller is not the owner of the object
const E_NOT_OWNER: u64 = 1;
/// Caller is not the publisher of the contract
const E_NOT_PUBLISHER: u64 = 2;

#[resource_group_member(group = aptos_framework::object::ObjectGroup)]
struct MyStruct has key {
num: u8
}

#[resource_group_member(group = aptos_framework::object::ObjectGroup)]
struct Message has key {
message: string::String
}

#[resource_group_member(group = aptos_framework::object::ObjectGroup)]
struct ObjectController has key {
extend_ref: object::ExtendRef,
}

entry fun create_my_object(caller: &signer) {
let caller_address = signer::address_of(caller);

// Creates the object
let constructor_ref = object::create_object(caller_address);

// Retrieves a signer for the object
let object_signer = object::generate_signer(&constructor_ref);

// Moves the MyStruct resource into the object
move_to(&object_signer, MyStruct { num: 0 });

// Creates an extend ref, and moves it to the object
let extend_ref = object::generate_extend_ref(&constructor_ref);
move_to(&object_signer, ObjectController { extend_ref });
// ...
}

entry fun add_message(
caller: &signer,
object: Object<MyStruct>,
message: String
) acquires ObjectController {
let caller_address = signer::address_of(caller);
// There are a couple ways to go about permissions

// Allow only the owner of the object
assert!(object::is_owner(object, caller_address), E_NOT_OWNER);
// Allow only the publisher of the contract
assert!(caller_address == @my_addr, E_NOT_PUBLISHER);
// Or any other permission scheme you can think of, the possibilities are endless!

// Use the extend ref to get a signer
let object_address = object::object_address(object);
let extend_ref = borrow_global<ObjectController>(object_address).extend_ref;
let object_signer = object::generate_signer_for_extending(&extend_ref);

// Extend the object to have a message
move_to(object_signer, Message { message });
}
}

Disabling or re-enabling Transfers​

Objects can be able to be transferred or not. By default, all objects are transferable. However, this functionality can be toggled on and off, or chosen at creation time. It is enabled by the TransferRef, which we'll illustrate below.

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

/// Caller is not the publisher of the contract
const E_NOT_PUBLISHER: u64 = 1;

#[resource_group_member(group = aptos_framework::object::ObjectGroup)]
struct ObjectController has key {
transfer_ref: object::TransferRef,
}

entry fun create_my_object(
caller: &signer,
transferrable: bool,
controllable: bool
) {
let caller_address = signer::address_of(caller);

// Creates the object
let constructor_ref = object::create_object(caller_address);

// Retrieves a signer for the object
let object_signer = object::generate_signer(&constructor_ref);

// Creates a transfer ref for controlling transfers
let transfer_ref = object::generate_transfer_ref(&constructor_ref);

// We now have a choice, we can make it so the object can be transferred
// and we can decide if we want to allow it to change later. By default, it
// is transferrable
if (!transferrable) {
object::disable_ungated_transfer(&transfer_ref);
};

// If we want it to be controllable, we must store the transfer ref for later
if (controllable) {
move_to(&object_signer, ObjectController { transfer_ref });
}
// ...
}

/// In this example, we'll only let the publisher of the contract change the
/// permissions of transferring
entry fun toggle_transfer(
caller: &signer,
object: Object<ObjectController>
) acquires ObjectController {
// Only let the publisher toggle transfers
let caller_address = signer::address_of(caller);
assert!(caller_address == @my_addr, E_NOT_PUBLISHER);

// Retrieve the transfer ref
let object_address = object::object_address(object);
let transfer_ref = borrow_global<ObjectController>(
object_address
).transfer_ref;

// Toggle it based on its current state
if (object::ungated_transfer_allowed(object)) {
object::disable_ungated_transfer(&transfer_ref);
} else {
object::enable_ungated_transfer(&transfer_ref);
}
}
}

Controlled transfers​

Additionally, if the creator wants to control all transfers, a LinearTransferRef can be created from the TransferRef to provide a one time use transfer functionality. The LinearTransferRef has to be used by the owner of the object.

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

/// Caller is not the publisher of the contract
const E_NOT_PUBLISHER: u64 = 1;

#[resource_group_member(group = aptos_framework::object::ObjectGroup)]
struct ObjectController has key {
transfer_ref: object::TransferRef,
linear_transfer_ref: option::Option<object::LinearTransferRef>,
}

entry fun create_my_object(
caller: &signer,
transferrable: bool,
controllable: bool
) {
let caller_address = signer::address_of(caller);

// Creates the object
let constructor_ref = object::create_object(caller_address);

// Retrieves a signer for the object
let object_signer = object::generate_signer(&constructor_ref);

// Creates a transfer ref for controlling transfers
let transfer_ref = object::generate_transfer_ref(&constructor_ref);

// Disable ungated transfer
object::disable_ungated_transfer(&transfer_ref);
move_to(&object_signer, ObjectController {
transfer_ref,
linear_transfer_ref: option::none(),
});
// ...
}

/// In this example, we'll only let the publisher of the contract change the
/// permissions of transferring
entry fun allow_single_transfer(
caller: &signer,
object: Object<ObjectController>
) acquires ObjectController {
// Only let the publisher toggle transfers
let caller_address = signer::address_of(caller);
assert!(caller_address == @my_addr, E_NOT_PUBLISHER);

let object_address = object::object_address(object);

// Retrieve the transfer ref
let transfer_ref = borrow_global<ObjectController>(
object_address
).transfer_ref;

// Generate a one time use `LinearTransferRef`
let linear_transfer_ref = object::generate_linear_transfer_ref(
&transfer_ref
);

// Store it for later usage
let object_controller = borrow_global_mut<ObjectController>(
object_address
);
option::fill(
&mut object_controller.linear_transfer_ref,
linear_transfer_ref
)
}

/// Now only owner can transfer exactly once
entry fun transfer(
caller: &signer,
object: Object<ObjectController>,
new_owner: address
) acquires ObjectController {
let object_address = object::object_address(object);

// Retrieve the linear_transfer ref, it is consumed so it must be extracted
// from the resource
let object_controller = borrow_global_mut<ObjectController>(
object_address
);
let linear_transfer_ref = option::extract(
&mut object_controller.linear_transfer_ref
);

object::transfer_with_ref(linear_transfer_ref, new_owner);
}
}

Allowing deletion of an Object​

Deleting an object can be useful to get rid of clutter, as well as retrieve back storage refunds. Deletion can be done with a DeleteRef, which must be created at object creation time.

Note that you cannot create a DeleteRef for a non-deletable object.

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

/// Caller is not the owner of the object
const E_NOT_OWNER: u64 = 1;

#[resource_group_member(group = aptos_framework::object::ObjectGroup)]
struct ObjectController has key {
delete_ref: object::DeleteRef,
}

entry fun create_my_object(
caller: &signer,
transferrable: bool,
controllable: bool
) {
let caller_address = signer::address_of(caller);

// Creates the object
let constructor_ref = object::create_object(caller_address);

// Retrieves a signer for the object
let object_signer = object::generate_signer(&constructor_ref);

// Creates and store the delete ref
let delete_ref = object::generate_delete_ref(&constructor_ref);
move_to(&object_signer, ObjectController {
delete_ref
});
// ...
}

/// Now only let the owner delete the object
entry fun delete(
caller: &signer,
object: Object<ObjectController>,
) {
// Only let caller delete
let caller_address = signer::address_of(caller);
assert!(object::is_owner(&object, caller_address), E_NOT_OWNER);

let object_address = object::object_address(object);

// Retrieve the delete ref, it is consumed so it must be extracted
// from the resource
let ObjectController {
delete_ref
} = move_from<ObjectController>(
object_address
);

// Delete the object forever!
object::delete(delete_ref);
}
}

Immutability​

An object can be made immutable by making the contract associated immutable, and removing any ability to extend or mutate the object. By default, contracts are not immutable, and objects can be extended with an ExtendRef, and resources can be mutated if the contract allows for it.