DEV Community: truong

Sui basic - Managed coin

truong — Fri, 24 Nov 2023 16:34:25 +0000

Now we have peeked under the hood of the sui::coin module, we can look at a simple but complete example of creating a type of custom fungible token where there is a trusted manager that has the capability to mint and burn, similar to many ERC-20 implementations.

Smart Contract

You can find the complete Managed Coin example contract under the example project folder.

Given what we have covered so far, this contract should be fairly easy to understand. It follows the One Time Witness pattern exactly, where the witness resource is named MANAGED, and automatically created by the module init function.

The init function then calls coin::create_currency to get the TreasuryCap and CoinMetadata resources. The parameters passed into this function are the fields of the CoinMetadata object, so include the token name, symbol, icon URL, etc.

The CoinMetadata is immediately frozen after creation via the transfer::freeze_object method, so that it becomes a shared immutable object that can be read by any address.

The TreasuryCap Capability object is used as a way to control access to the mint and burn methods that create or destroy Coin<MANAGED> objects respectively.

Publishing and CLI Testing

Publish the Module

Under the fungible_tokens project folder, run:

    sui client publish --gas-budget 10000000

You should see console output similar to:

The two immutable objects created are respectively the package itself and the CoinMetadata object of Managed Coin. And the owned object passed to the transaction sender is the TreasuryCap object of Managed Coin.

Export the object IDs of the package object and the TreasuryCap object to environmental variables:

export PACKAGE_ID=<package object ID from previous output>
export TREASURYCAP_ID=<treasury cap object ID from previous output>

Minting Tokens

To mint some MNG tokens, we can use the following CLI command:

    sui client call --function mint --module managed --package $PACKAGE_ID --args $TREASURYCAP_ID \"<amount to mint>\" <recipient address> --gas-budget 10000000

💡Note: as of Sui binary version 0.21.0, u64 inputs must be escaped as strings, thus the above CLI command format. This might change in a future version.

Export the object ID of the newly minted COIN<MANAGED> object to a bash variable:

export COIN_ID=<coin object ID from previous output>

Verify that the Supply field under the TreasuryCap<MANAGED> object should be increased by the amount minted.

Burning Tokens

To burn an existing COIN<MANAGED> object, we use the following CLI command:

    sui client call --function burn --module managed --package $PACKAGE_ID --args $TREASURYCAP_ID $COIN_ID --gas-budget 10000000

Verify that the Supply field under the TreasuryCap<MANAGED> object should be back to 0.

Exercise: What other commonly used functions do fungible tokens need? You should know enough about programming in Move now to try to implement some of these functions.

Referent

Part 7: Generics

Sui basic - Generics

truong — Fri, 24 Nov 2023 16:27:11 +0000

Intro to Generics

Generics are abstract stand-ins for concrete types or other properties. They work similarly to generics in Rust, and can be used to allow greater flexibility and avoid logic duplication while writing Sui Move code.

Generics are a key concept in Sui Move, and it's important to understand and have an intuition for how they work, so take your time with this section and understand every part fully.

Generics Usage

Using Generics in Structs

Let's look at a basic example of how to use generics to create a container Box that can hold any type in Sui Move.

First, without generics, we can define a Box that holds a u64 type as the following:

module  generics::storage {
    struct Box {
        value: u64
    }
}

However, this type will only be able to hold a value of type u64. To make our Box able to hold any generic type, we will need to use generics. The code would be modified as follows:

module  generics::storage {
    struct Box<T> {
        value: T
    }
}

Ability Constraints

We can add conditions to enforce that the type passed into the generic must have certain abilities. The syntax looks like the following:

module  generics::storage {
    // T must be copyable and droppable 
    struct Box<T: store + drop> has key, store {
        value: T
    }
}

💡It's important to note here that the inner type T in the above example must meet certain ability constraints due to the outer container type. In this example, T must have store, as Box has store and key. However, T can also have abilities that the container doesn't have, such as drop in this example.

The intuition is that if the container is allowed to contain a type that does not follow the same rules that it does, the container would violate its own ability. How can a box be storeable if its content isn't also storeable?

We will see in the next section that there is a way to get around this rule in certain cases using a special keyword, called phantom.

💡See the generics project under example_projects for some examples of generic types.

Using Generics in Functions

To write a function that returns an instance of Box that can accept a parameter of any type for the value field, we also have to use generics in the function definition. The function can be defined as the following:

public fun create_box<T>(value: T): Box<T> {
        Box<T> { value }
    }

If we want to restrict the function to only accept a specific type for value, we simply specify that type in the function signature as follows:

public fun create_box(value: u64): Box<u64> {
        Box<u64>{ value }
    }

This will only accept inputs of the type u64 for the create_box method, while still using the same generic Box struct.

Calling Functions with Generics

To call a function with a signature that contains generics, we must specify the type in angle brackets, as in the following syntax:

// value will be of type storage::Box<bool>
    let bool_box = storage::create_box<bool>(true);
// value will be of the type storage::Box<u64>
    let u64_box = storage::create_box<u64>(1000000);

Calling Functions with Generics using Sui CLI

To call a function with generics in its signature from the Sui CLI, you must define the argument's type using the flag --type-args.

The following is an example that calls the create_box function to create a box that contains a coin of the type 0x2::sui::SUI:

sui client call --package 0xbff5d0f3202e3b19e622b13819f269ae9aad904436cc557bace358266938e2ec --module generics --function create_box --args $OBJECT_ID --type-args 0x2::sui::SUI --gas-budget 10000000

Note: tạo 1 object simple_box then put it into a box

Advanced Generics Syntax

For more advanced syntax involving the use of generics in Sui Move, such as multiple generic types, please refer to the excellent section on generics in the Move Book.

But for our current lesson on fungible tokens, you already know enough about how generics work to proceed.

Here is example code

Referent

Part 6: Events

Sui basic - events

truong — Thu, 23 Nov 2023 03:36:25 +0000

Events

Events are important for Sui Move smart contracts, as it is the main way for indexers to track actions on-chain. You can understand it as logging on server backends, and indexers as parsers.

Events on Sui are also represented as objects. There are several types of system level events in Sui, including Move event, Publish event, Transfer object event, and so on. For the full list of system event types, please refer to the Sui Events API page here.

The event details of a transaction can be viewed on the Sui Explorer under the Events tab:

Custom Events

Developers can also define custom events on Sui. We can define a custom event marking when a transcript has been requested in the following way.

    /// Event marking when a transcript has been requested
    struct TranscriptRequestEvent has copy, drop {
        // The Object ID of the transcript wrapper
        wrapper_id: ID,
        // The requester of the transcript
        requester: address,
        // The intended address of the transcript
        intended_address: address,
    }

The type representing an event has the abilities copy and drop. Event objects aren't representing assets, and we are only interested in the data contained within, so they can be duplicated, and dropped at the end of scopes.

To emit an event in Sui, you just need to use the sui::event::emit method.

Let's modify our request_transcript method to emit this event:

    public fun request_transcript(transcript: WrappableTranscript, intended_address: address, ctx: &mut TxContext){
        let folderObject = Folder {
            id: object::new(ctx),
            transcript,
            intended_address
        };
        event::emit(TranscriptRequestEvent {
            wrapper_id: object::uid_to_inner(&folderObject.id),
            requester: tx_context::sender(ctx),
            intended_address,
        });
        //We transfer the wrapped transcript object directly to the intended address
        transfer::transfer(folderObject, intended_address);
    }

On the Sui explorer, we can see the event emitted displayed as the following, showing the three data fields that we defined in the TranscriptRequestEvent event:

Here is example code: sui and js

Try out creating, requesting and unpacking transcripts using the Sui CLI client and the Sui explorer to check the result.

That's the end of basic example, great job!

Referent

Part 5: Capability Design Pattern
Part 7: Generics

Sui basic - Capability Design Pattern

truong — Thu, 23 Nov 2023 03:26:51 +0000

Capability Design Pattern

Now we have the basics of a transcript publishing system, we want to add some access control to our smart contract.

Capability is a commonly used pattern in Move that allows fine-tuned access control using an object-centric model. Let's take a look at how we can define this capability object:

  // Type that marks the capability to create, update, and delete transcripts
  struct TeacherCap has key {
    id: UID
  }

We define a new struct TeacherCap that marks the capability to perform privileged actions on transcripts. If we want the capability to be non-transferrable, we simply do not add the storage ability to the struct.

*💡Note: This is also how the equivalent of soulbound tokens (SBT) can be easily implemented in Move. You simply define a struct that has the key ability, but not the store ability.

Passing and Consuming Capability Objects

Next, we need to modify the methods which should be callable by someone with the TeacherCap capability object to take in the capability as an extra parameter and consume it immediately.

For example, for the create_wrappable_transcript_object method, we can modify it as the follows:

    public fun create_wrappable_transcript_object(_: &TeacherCap, history: u8, math: u8, literature: u8, ctx: &mut TxContext) {
        let wrappableTranscript = WrappableTranscript {
            id: object::new(ctx),
            history,
            math,
            literature,
        };
        transfer::transfer(wrappableTranscript, tx_context::sender(ctx))
    }

We pass in a reference to TeacherCap capability object and consume it immediately with the _ notation for unused variables and parameters. Note that because we are only passing in a reference to the object, consuming the reference has no effect on the original object.

Quiz: What happens if try to pass in TeacherCap by value?

This means only an address that has a TeacherCap object can call this method, effectively implementing access control on this method.

We make similar modifications to all other methods in the contract that perform privileged actions on transcripts.

Initializer Function

A module's initializer function is called once upon publishing the module. This is useful for initializing the state of the smart contract, and is used often to send out the initial set of capability objects.

In our example, we can define the init method as the following:

    /// Module initializer is called only once on module publish.
    fun init(ctx: &mut TxContext) {
        transfer::transfer(TeacherCap {
            id: object::new(ctx)
        }, tx_context::sender(ctx))
    }

This will create one copy of the TeacherCap object and send it to the publisher's address when the module is first published.

We can see the publish transaction's effects on the Sui Explorer as below:

The second object created from the above transaction is an instance of the TeacherCap object, and sent to the publisher address:

Quiz: What was the first object created?

Add Additional Teachers or Admins

In order to give additional addresses admin access, we can simply define a method to create and send additional TeacherCap objects as the following:

    public fun add_additional_teacher(_: &TeacherCap, new_teacher_address: address, ctx: &mut TxContext){
        transfer::transfer(
            TeacherCap {
                id: object::new(ctx)
            },
        new_teacher_address
        )
    }

This method re-uses the TeacherCap to control access, but if needed, you can also define a new capability struct indicating sudo access.

💡Note: You can find some example in here.

Referent

Part 4: object wrapping
Part 6: Event

Sui basic - object wrapping

truong — Thu, 23 Nov 2023 03:16:08 +0000

Object Wrapping

There are multiple ways of nesting an object inside of another object in Sui Move. The first way we will introduce is called object wrapping.

Let's continue our transcript example. We define a new WrappableTranscript type, and the associated wrapper type Folder.

struct WrappableTranscript has store {
    history: u8,
    math: u8,
    literature: u8,
}

struct Folder has key {
    id: UID,
    transcript: WrappableTranscript,
}

In the above example, Folder wraps WrappableTranscript, and Folder is addressable through its id as it has the key ability.

Object Wrapping Properties

For a struct type to be capable of being embedded in a Sui object struct, which will generally have the key ability, the embedded struct type must have the store ability.

When an object is wrapped, the wrapped object is no longer accessible independently via object ID. Instead it would just be parts of the wrapper object itself. More importantly, the wrapped object can no longer be passed as an argument in Move calls, and the only access point is through the wrapper object.

Because of this property, object wrapping can be used as a way to make an object inaccessible outside of specific contract calls. For further info about Object wrapping, go check out here.

Object Wrapping Example

We will implement an example of object wrapping to our transcript example, so that WrappableTranscript is wrapped by a Folder object, and so that the Folder object can only be unpacked by, and thus the transcript inside only accessible by an intended address/viewer.

Modify `WrappableTranscript` and `Folder`

First, we need to make some adjustments to our two custom types WrappableTranscript and Folder from the previous section

We need to add the key ability to our type definitions for WrappableTranscript, so that they become assets and are transferrable.

Remember that custom types with the abilities key and store are considered to be assets in Sui Move.

struct WrappableTranscript has key, store {
        id: UID,
        history: u8,
        math: u8,
        literature: u8,
}

We need to add an additional field intended_address to the Folder struct that indicates the address of the intended viewer of the wrapped transcript.

struct Folder has key {
    id: UID,
    transcript: WrappableTranscript,
    intended_address: address
}

Request Transcript Method

public fun request_transcript(transcript: WrappableTranscript, intended_address: address, ctx: &mut TxContext){
    let folderObject = Folder {
        id: object::new(ctx),
        transcript,
        intended_address
    };
    //We transfer the wrapped transcript object directly to the intended address
    transfer::transfer(folderObject, intended_address)
}

This method simply takes in a WrappableTranscript object and wraps it in a Folder object, and transfers the wrapped transcript to the intended address of the transcript.

Unwrap Transcript Method

public fun unpack_wrapped_transcript(folder: Folder, ctx: &mut TxContext){
    // Check that the person unpacking the transcript is the intended viewer
    assert!(folder.intended_address == tx_context::sender(ctx), 0);
    let Folder {
        id,
        transcript,
        intended_address:_,
    } = folder;
    transfer::transfer(transcript, tx_context::sender(ctx));
    // Deletes the wrapper Folder object
    object::delete(id)
    }

This method unwraps the WrappableTranscript object from the Folder wrapper object if the method caller is the intended viewer of the transcript, and sends it to the method caller.

Quiz: Why do we need to delete the wrapper object here manually? What happens if we don't delete it?

Assert

We used the assert! syntax to verify that the address sending the transaction to unpack the transcript is the same as the intended_address field of the Folder wrapper object.

the assert! macro takes in two parameters of the format:

assert!(<bool expression>, <code>)

where the boolean expression must evaluate to true, otherwise it will abort with error code <code>.

Custom Errors

We are using a default 0 for our error code above, but we can also define a custom error constant in the following way:

    const ENotIntendedAddress: u64 = 1;

This error code then can be consumed at the application level and handled appropriately.

You can find detail code here

Referent

Part 3: parameters
Part 5: Capability Design Pattern

Sui basic - parameter

truong — Tue, 21 Nov 2023 16:15:56 +0000

Parameter Passing and Object Deletion

Parameter Passing (by `value`, `ref` and `mut ref`)

If you are familiar with rustlang, then you are probably familiar with the Rust ownership system. One advantage of movelang compared to Solidity is that you can get a sense of what a function call might do to the asset that you used for the function interaction. Here are some examples:

use sui::object::{Self};

// You are allowed to retrieve the score but cannot modify it
public fun view_score(transcriptObject: &TranscriptObject): u8{
    transcriptObject.literature
}

// You are allowed to view and edit the score but not allowed to delete it
public fun update_score(transcriptObject: &mut TranscriptObject, score: u8){
    transcriptObject.literature = score
}

// You are allowed to do anything with the score, including view, edit, or delete the entire transcript itself.
public fun delete_transcript(transcriptObject: TranscriptObject){
    let TranscriptObject {id, history: _, math: _, literature: _ } = transcriptObject;
    object::delete(id);
}

Object Deletion and Struct Unpacking

The delete_transcript method from the example above illustrates how to delete an object on Sui.

In order to delete an object, you must first unpack the object and retrieve its object ID. Unpacking can only be done inside the module that defines the object due to Move's privileged struct operation rules:

Struct types can only be created ("packed"), destroyed ("unpacked") inside the module that defines the struct
The fields of a struct are only accessible inside the module that defines the struct

Following these rules, if you want to modify your struct outside its defining module, you will need to provide public methods for these operations.

After unpacking the struct and retrieving its ID, the object can be deleted by simply calling the object::delete framework method on its object ID.

💡Note: the, _, underscore in the above method denotes unused variables or parameters. This will consume the variable or parameter immediately.

💡Note: You can find some example in [here](https://github.com/truonggau/sui-tutorial/blob/main/basic_example/basic_example/build/basic_example/sources/transcript_3.move.

Referent

Part 2: ownership
Part 4: object wrapping

Sui basic - ownership

truong — Tue, 21 Nov 2023 16:00:39 +0000

Introduction

Each object in Sui has an owner field that indicates how this object is being owned. In Sui Move, there are a total of four types of ownership.

Owned
- Owned by an address
- Owned by another object
Shared
- Shared immutable
- Shared mutable

Owned Objects

The first two types of ownership fall under the Owned Objects category. Owned objects in Sui are processed differently from shared objects and do not require global ordering.

Owned by an Address

Let's continue using our transcript example here. This type of ownership is pretty straightforward as the object is owned by an address to which the object is transferred upon object creation, such as in the above example at this line:

    transfer::transfer(transcriptObject, tx_context::sender(ctx)) // where tx_context::sender(ctx) is the recipient

where the transcriptObject is transferred to the address of the transaction sender upon creation.

Owned by an Object

In order for an object to be owned by another object, it is done using dynamic_object_field, which we will explore in a future section. Basically, when an object is owned by another object, we will call it a child object. A child object is able to be looked up in global storage using its object ID.

Shared Objects

A shared object is an object that is shared using the sui::transfer::share_object function and is accessible to everyone. Unlike owned objects, anyone can access shared ones on the network. Extended functionality and accessibility of this kind of objects requires additional effort by securing access, if needed.
Shared objects require the key ability.

Shared Immutable Objects

Certain objects in Sui cannot be mutated by anyone, and because of this, these objects do not have an exclusive owner. All published packages and modules in Sui are immutable objects.

To make an object immutable manually, one can call the following special function:

    transfer::freeze_object(obj);

Shared Mutable Objects

Shared objects in Sui can be read or mutated by anyone. Shared object transactions require global ordering through a consensus layer protocol, unliked owned objects.

To create a shared object, one can call this method:

    transfer::share_object(obj);

Once an object is shared, it stays mutable and can be accessed by anyone to send a transaction to mutate the object.

💡Note: You can find some example in here.

Referent

Part 1: object
Part 3: parameters

Sui basic - Object

truong — Tue, 21 Nov 2023 10:21:56 +0000

Introduction

Sui Move is a fully object-centric language. Transactions on Sui are expressed as operations where the inputs and outputs are both objects. Sui objects are the basic unit of storage in Sui. It all starts from the struct keyword.

Let's first start with an example that represents a transcript recording a student's grades:

struct Transcript {
    history: u8,
    math: u8,
    literature: u8,
}

The above definition is a regular Move struct, but it is not a Sui object. In order to make a custom Move type instantiate a Sui object in global storage, we need to add the key ability, and a globally unique id: UID field inside the struct definition.

use sui::object::{UID};

struct TranscriptObject has key {
    id: UID,
    history: u8,
    math: u8,
    literature: u8,
}

Create a Sui Object

Creating a Sui object requires a unique ID. We use the sui::object::new function to create a new ID passing in the current TxContext.

In Sui, every object must have an owner, which can be either an address, another object, or "shared". In our examples, we decided to make our new transcriptObject owned by the transaction sender. It is done using the transfer function of the Sui framework and using tx_context::sender function to get the current entry call's sender's address.

We will discuss object ownership more in-depth in the next section.

use sui::object::{Self};
use sui::tx_context::{Self, TxContext};
use sui::transfer;

public fun create_transcript_object(history: u8, math: u8, literature: u8, ctx: &mut TxContext) {
  let transcriptObject = TranscriptObject {
    id: object::new(ctx),
    history,
    math,
    literature,
  };
  transfer::transfer(transcriptObject, tx_context::sender(ctx))
}

💡Note: Move supports field punning, which allows us to skip the field values if the field name happens to be the same as the name of the value variable it is bound to.

💡Note: You can find some example in here.

Referent

Part 2: ownership

DEV Community: truong

Sui basic - Managed coin

Smart Contract

Publishing and CLI Testing

Publish the Module

Minting Tokens

Burning Tokens

Referent

Sui basic - Generics

Intro to Generics

Generics Usage

Using Generics in Structs

Ability Constraints

Using Generics in Functions

Calling Functions with Generics

Calling Functions with Generics using Sui CLI

Advanced Generics Syntax

Referent

Sui basic - events

Events

Custom Events

Referent

Sui basic - Capability Design Pattern

Capability Design Pattern

Passing and Consuming Capability Objects

Initializer Function

Add Additional Teachers or Admins

Referent

Sui basic - object wrapping

Object Wrapping

Object Wrapping Properties

Object Wrapping Example

Modify WrappableTranscript and Folder

Request Transcript Method

Unwrap Transcript Method

Assert

Custom Errors

Referent

Sui basic - parameter

Parameter Passing and Object Deletion

Parameter Passing (by value, ref and mut ref)

Object Deletion and Struct Unpacking

Referent

Sui basic - ownership

Introduction

Owned Objects

Owned by an Address

Owned by an Object

Shared Objects

Shared Immutable Objects

Shared Mutable Objects

Referent

Sui basic - Object

Introduction

Create a Sui Object

Referent

Modify `WrappableTranscript` and `Folder`

Parameter Passing (by `value`, `ref` and `mut ref`)