Skip to main content

Module sui::accumulator_metadata

use std::ascii;
use std::bcs;
use std::option;
use std::string;
use std::vector;
use sui::accumulator;
use sui::address;
use sui::bag;
use sui::dynamic_field;
use sui::hex;
use sui::object;
use sui::party;
use sui::transfer;
use sui::tx_context;
use sui::vec_map;

Struct OwnerKey​

=== Accumulator metadata ===

Accumulator metadata is organized as follows:

  • Each address that holds at least one type of accumulator has an owner field attached to the accumulator root.
  • For each type of accumulator held by that address, there is an AccumulatorMetadata field attached to the owner field.
  • When the value of an accumulator drops to zero, the metadata field is removed.
  • If the owner field has no more accumulator metadata field attached to it, it is removed as well.
public struct OwnerKey has copy, drop, store
Click to open
Fields
owner: address

Struct Owner​

An owner field, to which all AccumulatorMetadata fields for the owner are attached.

public struct Owner has store
Click to open
Fields
balances: sui::bag::Bag
The individual balances owned by the owner.
owner: address

Struct MetadataKey​

public struct MetadataKey<phantom T> has copy, drop, store
Click to open
Fields

Struct Metadata​

A metadata field for a balance field with type T.

public struct Metadata<phantom T> has store
Click to open
Fields
fields: sui::bag::Bag
Any per-balance fields we wish to add in the future.

Constants​

const EInvariantViolation: u64 = 0;

Function accumulator_root_owner_exists​

=== Owner functions === Check if there is an owner field attached to the accumulator root.

fun accumulator_root_owner_exists(accumulator_root: &sui::accumulator::AccumulatorRoot, owner: address): bool
Click to open
Implementation
fun accumulator_root_owner_exists(accumulator_root: &AccumulatorRoot, owner: address): bool {
    dynamic_field::exists_with_type<OwnerKey, Owner>(accumulator_root.id(), OwnerKey { owner })
}

Function accumulator_root_borrow_owner_mut​

Borrow an owner field mutably.

fun accumulator_root_borrow_owner_mut(accumulator_root: &mut sui::accumulator::AccumulatorRoot, owner: address): &mut sui::accumulator_metadata::Owner
Click to open
Implementation
fun accumulator_root_borrow_owner_mut(
    accumulator_root: &mut AccumulatorRoot,
    owner: address,
): &mut Owner {
    dynamic_field::borrow_mut(accumulator_root.id_mut(), OwnerKey { owner })
}

Function accumulator_root_attach_owner​

Attach an owner field to the accumulator root.

fun accumulator_root_attach_owner(accumulator_root: &mut sui::accumulator::AccumulatorRoot, owner: sui::accumulator_metadata::Owner)
Click to open
Implementation
fun accumulator_root_attach_owner(accumulator_root: &mut AccumulatorRoot, owner: Owner) {
    dynamic_field::add(accumulator_root.id_mut(), OwnerKey { owner: owner.owner }, owner);
}

Function accumulator_root_detach_owner​

Detach an owner field from the accumulator root.

fun accumulator_root_detach_owner(accumulator_root: &mut sui::accumulator::AccumulatorRoot, owner: address): sui::accumulator_metadata::Owner
Click to open
Implementation
fun accumulator_root_detach_owner(accumulator_root: &mut AccumulatorRoot, owner: address): Owner {
    dynamic_field::remove(accumulator_root.id_mut(), OwnerKey { owner })
}

Function create_accumulator_metadata​

=== Metadata functions === Create a metadata field for a new balance field with type T. The metadata will be attached to the owner field owner. If the owner field does not exist, it will be created.

public(package) fun create_accumulator_metadata<T>(accumulator_root: &mut sui::accumulator::AccumulatorRoot, owner: address, ctx: &mut sui::tx_context::TxContext)
Click to open
Implementation
public(package) fun create_accumulator_metadata<T>(
    accumulator_root: &mut AccumulatorRoot,
    owner: address,
    ctx: &mut TxContext,
) {
    let metadata = Metadata<T> {
        fields: bag::new(ctx),
    };
    if (accumulator_root.owner_exists(owner)) {
        let accumulator_owner = accumulator_root.borrow_owner_mut(owner);
        assert!(accumulator_owner.owner == owner, EInvariantViolation);
        accumulator_owner.attach_metadata(metadata);
    } else {
        let mut accumulator_owner = Owner {
            balances: bag::new(ctx),
            owner,
        };
        accumulator_owner.attach_metadata(metadata);
        accumulator_root.attach_owner(accumulator_owner);
    }
}

Function remove_accumulator_metadata​

Remove the metadata field for a balance field with type T. The metadata will be detached from the owner field owner. If there are no more balance fields attached to the owner field, the owner field will be destroyed.

public(package) fun remove_accumulator_metadata<T>(accumulator_root: &mut sui::accumulator::AccumulatorRoot, owner: address)
Click to open
Implementation
public(package) fun remove_accumulator_metadata<T>(
    accumulator_root: &mut AccumulatorRoot,
    owner: address,
) {
    let is_empty = {
        let accumulator_owner = accumulator_root.borrow_owner_mut(owner);
        let Metadata { fields } = accumulator_owner.detach_metadata<T>();
        fields.destroy_empty();
        accumulator_owner.balances.is_empty()
    };
    if (is_empty) {
        accumulator_root.detach_owner(owner).destroy();
    }
}

Function accumulator_owner_attach_metadata​

Attach a metadata field for type T to the owner field.

fun accumulator_owner_attach_metadata<T>(self: &mut sui::accumulator_metadata::Owner, metadata: sui::accumulator_metadata::Metadata<T>)
Click to open
Implementation
fun accumulator_owner_attach_metadata<T>(self: &mut Owner, metadata: Metadata<T>) {
    self.balances.add(MetadataKey<T>(), metadata);
}

Function accumulator_owner_detach_metadata​

Detach a metadata field for type T from the owner field.

fun accumulator_owner_detach_metadata<T>(self: &mut sui::accumulator_metadata::Owner): sui::accumulator_metadata::Metadata<T>
Click to open
Implementation
fun accumulator_owner_detach_metadata<T>(self: &mut Owner): Metadata<T> {
    self.balances.remove(MetadataKey<T>())
}

Function accumulator_owner_destroy​

Destroy an owner field.

fun accumulator_owner_destroy(this: sui::accumulator_metadata::Owner)
Click to open
Implementation
fun accumulator_owner_destroy(this: Owner) {
    let Owner { balances, .. } = this;
    balances.destroy_empty();
}