Module sui::derived_object

Enables the creation of objects with deterministic addresses derived from a parent object's UID.
This module provides a way to generate objects with predictable addresses based on a parent UID and a key, creating a namespace that ensures uniqueness for each parent-key combination, which is usually how registries are built.

Key features:

• Deterministic address generation based on parent object UID and key
• Derived objects can exist and operate independently of their parent

The derived UIDs, once created, are independent and do not require sequencing on the parent object. They can be used without affecting the parent. The parent only maintains a record of which derived addresses have been claimed to prevent duplicates. Releasing a derived UID removes its record, so the same address can be claimed again.

use std::ascii;
use std::bcs;
use std::option;
use std::string;
use std::vector;
use sui::address;
use sui::dynamic_field;
use sui::hex;
use sui::object;
use sui::tx_context;

Struct Claimed

Added as a DF to the parent's UID, to mark an ID as claimed.

public struct Claimed has copy, drop, store

Click to open

Fields

0: sui::object::ID

Struct DerivedObjectKey

An internal key to protect from generating the same UID twice (e.g. collide with DFs)

public struct DerivedObjectKey<K: copy, drop, store> has copy, drop, store

Click to open

Fields

0: K

Enum ClaimedStatus

The possible values of a claimed UID.
We make it an enum to make upgradeability easier in the future.

public enum ClaimedStatus has store

Click to open

Variants

Variant Reserved

The UID has been claimed. It may be in use or deleted with object::delete. release removes the marker.

Constants

Tries to create an object twice with the same parent-key combination.

#[error]
const EObjectAlreadyExists: vector<u8> = b"Derived object is already claimed.";

Tries to release a UID that is not claimed under the given parent.

#[error]
const EObjectNotClaimed: vector<u8> = b"Derived object is not claimed by this parent.";

Tries to release the UID of a shared object.

#[error]
const ESharedObjectRelease: vector<u8> = b"Shared objects cannot be released.";

Function claim

Claim a deterministic UID, using the parent's UID & any key.

public fun claim<K: copy, drop, store>(parent: &mut sui::object::UID, key: K): sui::object::UID

Function release

Deletes id, claimed under parent, so that its address can be claimed again.
Dynamic fields of id, objects sent to its address, and its address balances persist and are reachable again once it is re-claimed.

public fun release(parent: &mut sui::object::UID, id: sui::object::UID)

Function exists

Checks if a provided key has been claimed for the given parent.
Note: If the UID has been deleted through object::delete rather than release, this will always return true.

public fun exists<K: copy, drop, store>(parent: &sui::object::UID, key: K): bool

Function derive_address

Given an ID and a Key, it calculates the derived address.

public fun derive_address<K: copy, drop, store>(parent: sui::object::ID, key: K): address