DEV Community

yuzurush
yuzurush

Posted on • Edited on

Soroban Quest : Custom Types

#sorobanquest #soroban #stellar #smartcontract

Hi there! Welcome to my "Soroban Quest" blog post series. Soroban Quest is a gamified educational course where you’ll learn Soroban (new smart contract platform by Stellar Foundation) and earn badge rewards!. In this series, i will explain steps to complete every soroban quest and help you understand more about soroban smart contract itself.

The 5th quest is called "Custom Types". This quest will give you lesson how custom types implemented in Soroban.

Joining The Quest

To join the quest and get a Quest Account, use this command:

sq play 5
Enter fullscreen mode Exit fullscreen mode

And dont forget to fund the quest account right away.

Examining README.md

After examining README.md, i found that this quest is very different than all quest before, we will "write" some code ourselves. The tasks for 5th quest is to :

  • Define several custom types with its defined types and its fields in types.rs file

Rectangle struct
Animal enum
User struct
RGB tuple enum
Color tuple enum
Paticipant enum
RoyalCard enum

  • Build the contract
  • Deploy the contract
  • Invoke each of the functions with valid argument for each custom types

Seems like a lot of work, but dont worries i will guide you through this quest!

  • Invoke verify function from dcc02a65c6904c285aca78c456ac30fd66ceb2236c65972177ea60ef9cde3569 contract ID, supply our deployed contract's contractID as --contract_id argument to verify our contract

The Contract Code 

#![no_std]

use soroban_sdk::{contractimpl, Env};
use types::*;

pub struct TypesContract;

#[contractimpl]
impl TypesContract {
    pub fn c_rect(_env: Env, _rect: Rectangle) {}
    pub fn c_animal(_env: Env, _animal: Animal) {}
    pub fn c_user(_env: Env, _user: User) {}
    pub fn c_rgb(_env: Env, _rgb: RGB) {}
    pub fn c_color(_env: Env, _val: Color) {}
    pub fn c_part(_env: Env, _participant: Participant) {}
    pub fn c_card(_env: Env, _card: RoyalCard) {}
}

mod test;
mod types;
Enter fullscreen mode Exit fullscreen mode

The contract is located in lib.rs and contains 7 function that we're gonna invoke later after we defined all the custom types. These functions don't do anything with the arguments passed to them. They are simply placeholders that can be used to test the custom types that defined.

Defining Custom Types

The custom types definition located in types.rs file. We will define each custom types with its defined types and its fields.
There are some example located in types.rs, you can read the comments for the explanation. We will define the rest ourselves with condition that i write before in "Examining README.MD section, Let's go!

  • Rectangle Type

Rectangle struct with two fields, width and height, both in a u32 value

pub struct Rectangle {
    pub width: u32,
    pub height: u32,
}
Enter fullscreen mode Exit fullscreen mode
  • Animal Type

Animal enum with two variations, Cat and Dog.

pub enum Animal {
    Dog,
    Cat
}
Enter fullscreen mode Exit fullscreen mode
  • User Type

User struct with name, age, and pet fields, corresponding to Bytes, u32, and Animal values, respectively.

pub struct User {
    pub name: Bytes,
    pub age: u32,
    pub pet: Animal,
}
Enter fullscreen mode Exit fullscreen mode
  • RGB Type

RGB tuple struct type made with a tuple of 3 u32 values.

pub struct RGB(
    pub u32,
    pub u32,
    pub u32
);
Enter fullscreen mode Exit fullscreen mode
  • Color Type

Color tuple enum type with a variant named "RGB" and an instance of the RGB type.

pub enum Color {
    RGB(RGB)
}
Enter fullscreen mode Exit fullscreen mode
  • Participant Type

Participant enum with single-value tuple variants, including an Account variant with an Address type and a Contract variant with a BytesN<32> type

pub enum Participant {
    Account(Address),
    Contract(BytesN<32>)
}
Enter fullscreen mode Exit fullscreen mode
  • RoyalCard Type

RoyalCard enum containing three u32 integer variations: "Jack" with a value of 11, "Queen" with a value of 12, and "King" with a value of 13

pub enum RoyalCard {
    Jack = 11,
    Queen = 12,
    King = 13
}
Enter fullscreen mode Exit fullscreen mode

Fill types.rs file with above codes and save it.

Testing the Contract

We already defined every custom types by ourselves, to check everything is right, we could test the contract using this command :

cd quests/5-custom-types
cargo test
Enter fullscreen mode Exit fullscreen mode

If everything is right you will see this as result :

running 1 test
test test::test_types ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Enter fullscreen mode Exit fullscreen mode

Building the Contract

To build the contract, use the following command:

cargo build --target wasm32-unknown-unknown --release
Enter fullscreen mode Exit fullscreen mode

This should output a .wasm file in the ../target directory:

../target/wasm32-unknown-unknown/release/soroban_custom_types_contract.wasm
Enter fullscreen mode Exit fullscreen mode

Deploying the Contract

To deploy the contract, use the following command:

soroban contract deploy --wasm /workspace/soroban-quest/target/wasm32-unknown-unknown/release/soroban_custom_types_contract.wasm
Enter fullscreen mode Exit fullscreen mode

From this command you will get a Contract ID, save this for invoking it later.

Invoking the Contract Functions

There is 7 function that we are about to invoke as we can see in "The Contract Code" section before, i will guide you to invoke every function.

  • Invoking c_rect

To invoke c_rect function, use this command format :

soroban contract invoke --id <YourContracID> -- c_rect --_rect '{"width":<widthvalue>,"height":<heightcalue>}'
Enter fullscreen mode Exit fullscreen mode

c_rect

  • Invoking c_animal

To invoke c_animal function, use this command format :

soroban contract invoke --id <YourContracID> -- c_animal --_animal <Dog/Cat>
Enter fullscreen mode Exit fullscreen mode

c_animal

  • Invoking c_user

To invoke c_user function, use this command format :

soroban contract invoke --id <YourContracID> -- c_user --_user '{"name":"<NameInHex>","age":<age>,"pet":"<Cat/Dog>"}'
Enter fullscreen mode Exit fullscreen mode

c_user

  • Invoking c_rgb

To invoke c_rgb function, use this command format :

soroban contract invoke --id <YourContracID> -- c_rgb --_rgb '[<u32-int>,<u32-int>,<u32-int>]'
Enter fullscreen mode Exit fullscreen mode

c_rgb

  • Invoking c_color

To invoke c_color function, use this command format :

soroban contract invoke --id <YourContracID> -- c_color --_val '{"RGB":<RGB-Value>}'
Enter fullscreen mode Exit fullscreen mode

c_color

  • Invoking c_part

You need to invoke c_part twice, first for create an account Participant, use this command format :

soroban contract invoke --id <YourContracID> -- c_part --_participant '{"Account":"<QuestPublicKey>"}'
Enter fullscreen mode Exit fullscreen mode

Account
And one more, invoke c_part function for create an contract Participant, use this command format

soroban contract invoke --id <YourContracID> --fn c_part -- --_participant '{"Contract":"<YourContractID>"}'
Enter fullscreen mode Exit fullscreen mode

Contract

  • Invoking c_card

To invoke c_card function, use this command format :

soroban contract invoke --id <YourContracID> -- c_card --_card <11/12/13>
Enter fullscreen mode Exit fullscreen mode

c_card

Invoke verify Function From Specific ContractID

Last task to complete this quest is to invoke verify function from this specific dcc02a65c6904c285aca78c456ac30fd66ceb2236c65972177ea60ef9cde3569 contract ID, and supply our deployed contract's contractID as --contract_id argument to verify our contract. The command format is :

soroban contract invoke --id dcc02a65c6904c285aca78c456ac30fd66ceb2236c65972177ea60ef9cde3569 -- verify --contract_id <YourContractID>
Enter fullscreen mode Exit fullscreen mode

Checking the Quest

We already completed every step to complete the quest and this is the last thing you need to do. Check your quest and claim your badge reward. To check use the following command :

sq check 5
Enter fullscreen mode Exit fullscreen mode

Congratulations! You have already completed 5 out of 6 quests. You have 1 last more to go.

Top comments (0)