Forem: Altuğ Bakan

Soroban Quest - Asset Interop

Altuğ Bakan — Sun, 04 Dec 2022 06:00:00 +0000

So, we have tackled Custom Types on the last post on Soroban and learned a lot. Now, on this last quest, we will use our knowledge from all of the previous quests to dive into Asset Interop!

Understanding `README.md`

For the last time, let's check out the README.md file.

It is quite the quest! We will use Stellar's "Classic" Assets, Soroban Tokens, and even import some Lumens from Stellar network to Soroban network!

Setting Up Our Quest Account

At this point, you should be able to start playing pretty easy! If you need a reminder, we should use sq play 6, and fund our account to start playing the 6^th and last quest.

Token Interface

On Soroban, tokens should implement the Token Interface if they want to interoperate between other contracts and protocols. Having a common interface for contracts help developers to support all types of tokens implementing the same interface without knowing their implementations.

The Token Interface is defined as

// The metadata used to initialize token (doesn't apply to contracts representing 
// 'classic' Stellar assets).
pub struct TokenMetadata {
    pub name: Bytes,
    pub symbol: Bytes,
    pub decimals: u32,
}

// Initializes a 'smart-only' token by setting its admin and metadata.
// Tokens that represent 'classic' Stellar assets don't need to call this, as
// their metadata is inherited from the existing assets.
fn init(env: Env, admin: Identifier, metadata: TokenMetadata);

// Functions that apply on for tokens representing classic assets.

// Moves the `amount` from classic asset balance to the token balance of `id`
// user.
// `id` must be a classic Stellar account (i.e. an account invoker or signature 
// signed by an account).
fn import(env: Env, id: Signature, nonce: BigInt, amount: i64);

// Moves the `amount` from token balance to the classic asset balance of `id`
// user.
// `id` must be a classic Stellar account (i.e. an account invoker or signature 
// signed by an account).
fn export(env: Env, id: Signature, nonce: BigInt, amount: i64);

// Admin interface -- these functions are privileged

// If "admin" is the administrator, burn "amount" from "from"
fn burn(e: Env, admin: Signature, nonce: BigInt, from: Identifier, amount: BigInt);

// If "admin" is the administrator, mint "amount" to "to"
fn mint(e: Env, admin: Signature, nonce: BigInt, to: Identifier, amount: BigInt);

// If "admin" is the administrator, set the administrator to "id"
fn set_admin(e: Env, admin: Signature, nonce: BigInt, new_admin: Identifier);

// If "admin" is the administrator, freeze "id"
fn freeze(e: Env, admin: Signature, nonce: BigInt, id: Identifier);

// If "admin" is the administrator, unfreeze "id"
fn unfreeze(e: Env, admin: Signature, nonce: BigInt, id: Identifier);

// Token Interface

// Get the allowance for "spender" to transfer from "from"
fn allowance(e: Env, from: Identifier, spender: Identifier) -> BigInt;

// Set the allowance to "amount" for "spender" to transfer from "from"
fn approve(e: Env, from: Signature, nonce: BigInt, spender: Identifier, amount: BigInt);

// Get the balance of "id"
fn balance(e: Env, id: Identifier) -> BigInt;

// Transfer "amount" from "from" to "to"
fn xfer(e: Env, from: Signature, nonce: BigInt, to: Identifier, amount: BigInt);

// Transfer "amount" from "from" to "to", consuming the allowance of "spender"
fn xfer_from(
    e: Env,
    spender: Signature,
    nonce: BigInt,
    from: Identifier,
    to: Identifier,
    amount: BigInt,
);

// Returns true if "id" is frozen
fn is_frozen(e: Env, id: Identifier) -> bool;

// Returns the current nonce for "id"
fn nonce(e: Env, id: Identifier) -> BigInt;

// Descriptive Interface

// Get the number of decimals used to represent amounts of this token
fn decimals(e: Env) -> u32;

// Get the name for this token
fn name(e: Env) -> Bytes;

// Get the symbol for this token
fn symbol(e: Env) -> Bytes;

on the Soroban SDK. It uses some cryptographic tools and some helpful interfaces from the soroban-auth crate, which is a crate that contain libraries for user authentication on the Soroban network.

The token interface is quite large but it is not hard to understand, so I urge you to check it out yourself and see if you can make sense of it. We will inspect the parts we will use on the token interface in quite the detail when we need them.

Examining the Contract

Once again, let's check out the lib.rs file. The source code for this contract is quite large, and pretty complex. Let's check out some important parts of the source file.

use soroban_auth::{Identifier, Signature};

On this contract, we are dealing with user authentication, so we need the soroban_auth crate to add this functionality to our contract. This crate helps us get more details about the input arguments of some functions that the Token Interface use.

mod token {
    soroban_sdk::contractimport!(file = "./soroban_token_spec.wasm");
}

This mod statement imports the soroban_token_spec.wasm file to make the compiler infer the types and structs from the Token Interface. This is useful as we did not have to copy and paste the source code of the token interface of the contract to a new file and import it.

Allowance Trait

We have a trait in our code, which defines the AllowanceTrait interface. The contracts implementing the AllowanceTrait should implement two functions, init and withdraw, to successfully compile.

pub trait AllowanceTrait {
    fn init(
        e: Env,
        child: AccountId,
        token_id: BytesN<32>,
        amount: BigInt,
        step: u64,
    ) -> Result<(), Error>;

    fn withdraw(e: Env) -> Result<(), Error>;
}

The init function has four external arguments. The child argument sets the "Child" account that can withdraw some money from the "Parent" account. token_id arguments is the ID of the token that the Child account can withdraw, amount is how much of the said token that Child account withdraw for a year, and step is how frequent the child account can withdraw, in seconds.

The withdraw function does not have an external argument and returns success or a custom Error if the the withdrawal fails.

We can see that our AllowanceContract implements the AllowanceTrait trait, so it should implement those two functions in addition to whatever it might implement. Let's check out the implementations of the init and withdraw functions so that we have a good understanding about what each of them do.

`init` Function

The init function is defined as

fn init(
        e: Env,
        child: AccountId,
        token_id: BytesN<32>,
        amount: BigInt,
        step: u64,
    ) -> Result<(), Error> {
        let token_key = DataKey::TokenId;
        if e.data().has(token_key.clone()) {
            return Err(Error::ContractAlreadyInitialized);
        }

        if step == 0 {
            return Err(Error::InvalidArguments);
        }

        if (&amount * step) / SECONDS_IN_YEAR == 0 {
            return Err(Error::InvalidArguments);
        }

        e.data().set(token_key, token_id);
        e.data()
            .set(DataKey::Parent, to_account(e.invoker()).unwrap());
        e.data().set(DataKey::Child, child);
        e.data().set(DataKey::Amount, amount);
        e.data().set(DataKey::Step, step);

        Ok(())
    }

The contract has to be initialized only once. The first thing that the init function does is checking this case. If the environment already has a TokenId defined, which can be only done on the init function, it means that the contract has already been initialized, and the init function returns an Error.

After a sanity check, the contract validates the numerical arguments. It first checks if the step value is not 0, as division by 0 on calculations would give an error, and you can't really withdraw every 0 seconds. After that, it checks if (&amount * step) / SECONDS_IN_YEAR is not zero. Since we are supplying an amount that is for a whole year, we can calculate how much the child account can withdraw at a time using the calculation given.

Then, the function sets up some data on the environment for later use. Lastly, the contract sets up the time of the initial withdraw to a value in the past, so that the Child can withdraw at any time starting now.

Ledger Data

We have utilized the contract data quite much, but how about some network-wide values that do not depend on any contract? We can read the values from the Stellar Ledger using the ledger method of the environment.

The Ledger has information about the protocol_version, sequence, timestamp of the closing time, and the network_passphrase available for all contracts to read. This information is useful as we can create a contract that unlocks at a future time, which is implemented using the timestamp value of the Ledger. Check out the docs on soroban_sdk for more information.

`withdraw` Function

The withdraw function is implemented as

fn withdraw(e: Env) -> Result<(), Error> {
        let key = DataKey::TokenId;
        if !e.data().has(key.clone()) {
            return Err(Error::ContractNotInitialized);
        }

        let token_id: BytesN<32> = e.data().get(key).unwrap().unwrap();
        let client = token::Client::new(&e, token_id);

        match e.invoker() {
            Address::Account(id) => id,
            _ => return Err(Error::InvalidInvoker),
        };

        let step: u64 = e.data().get(DataKey::Step).unwrap().unwrap();
        let iterations = SECONDS_IN_YEAR / step;
        let amount: BigInt = e.data().get(DataKey::Amount).unwrap().unwrap();
        let withdraw_amount = amount / iterations;

        let latest: u64 = e.data().get(DataKey::Latest).unwrap().unwrap();
        if latest + step > e.ledger().timestamp() {
            return Err(Error::ChildAlreadyWithdrawn);
        }

        client.xfer_from(
            &Signature::Invoker,
            &BigInt::zero(&e),
            &Identifier::Account(e.data().get(DataKey::Parent).unwrap().unwrap()),
            &Identifier::Account(child),
            &withdraw_amount,
        );

        let new_latest = latest + step;
        e.data().set(DataKey::Latest, new_latest);

        Ok(())
    }

The withdraw function also starts with a sanity check, this time it requires the contract to be initialized, as it needs to know the parameters on what will it work on.

After the check, it creates a client which, if you remember, is an interface for the function to interact with another contract. This time, the interface is any contract that implements the Token Interface.

After that, it checks the caller is an EOA and not another contract. This is not required, but used for our purposes.

Next, it does some calculations like how much to withdraw at a time, who is the Child account, and such using the stored data on the environment. It also checks if the latest withdraw is before the allowed interval, and returns an error otherwise.

Finally, it sends the required amount to the Child account using the xfer_from function of the token contract. This function transfers tokens from the Parent account to the Child account. To accomplish this task, the Parent account should allow the use of its tokens by this contract. We will accomplish that task later on the quest.

Examining the Test

The test.rs file has a test using the USD Coin contract to create an allowance for the Child account, approving the contract and so on. Please inspect the test functions to see if you can make sense of them. One thing to note here is the use of

env.ledger().set(LedgerInfo {
        timestamp: 1669726145,
        protocol_version: 1,
        sequence_number: 10,
        network_passphrase: Default::default(),
        base_reserve: 10,
    });

function to set the state of the Soroban Ledger for testing purposes. Since the functions depend on the timestamps of the Ledger, we need a way of testing instead of waiting the required amount of time!

Again, we can use cargo test to test the validity of the tests.

Python Scripts

You will see a folder named py-scripts on the quest folder that contains some Python scripts. These scripts are supplied by overcat, and are ways to interact with the Soroban network using the Stellar Python SDK. We won't be using these scripts, but feel free to check them out if you are interested with interacting with Soroban using Python.

Solving the Quest

So, our tasks for the quest are

Deploy the AllowanceContract as the Parent_Account
Invoke the init function of the AllowanceContract
import some XLM into the Parent_Account from their "Classic" Stellar account
approve the AllowanceContract to make proxy transfers from the Parent_Account to the Child_Account
Invoke the withdraw function of the AllowanceContract with either the Child_Account or Parent_Account
export some XLM from the Child_Account to their "Classic" Stellar account

Let's start with them.

Deploying the Contract

As usual, we can build and deploy the contract using

cargo build --target wasm32-unknown-unknown --release
soroban deploy --wasm target/wasm32-unknown-unknown/release/soroban_asset_interop_contract.wasm

Note your contract ID somewhere, as we will need it for the next steps of the quest.

Invoking the `init` Function

At this point, we are used to the custom types that we have to supply to the soroban CLI, so invoking the init function shouldn't be that hard. The init function has the arguments of type AccountId, BytesN<32>, BigInt, and u64.

We have worked with the all those types except BigInt, which is not any different than supplying a u64 variable. The only difference is that the BigInt type can be a quite large number, even larger than the u64 variable.

We need to create a Child account before invoking the init function, as we need to supply the value as an argument.

The stellar_sdk on Python has all the functionality we need to create an account and view its public key in hexadecimal. Note that for this Quest, we need some additional Soroban compatibility on stellar_sdk, so we need to install a specific version of the stellar_sdk. We might already have a version of stellar_sdk, so use the following command to change your version of the stellar_sdk to a Soroban enabled one.

pip install git+https://github.com/StellarCN/py-stellar-base.git@soroban --upgrade --force-reinstall

To create the Child account and get its public key in hexadecimal, we will use

from stellar_sdk import Keypair

child = Keypair.random()

print(f"Public Key: {child.public_key}")
print(f"Private Key: {child.secret}")
print(f"Public Key in Hex: {child.raw_public_key().hex()}")

Note these values somewhere to not forget them as we will need those later.

We also need to find the contract ID of the native Stellar token on Soroban network. Since the contract IDs of imported tokens are deterministic, we can use the same calculation to determine the address. We will use

import hashlib
from stellar_sdk import Asset, xdr

asset = Asset.native()

data = xdr.HashIDPreimage(
    xdr.EnvelopeType.ENVELOPE_TYPE_CONTRACT_ID_FROM_ASSET,
    from_asset=asset.to_xdr_object(),
)

print(f"Native Token ID: {hashlib.sha256(data.to_xdr_bytes()).hexdigest()}")

Note the XLM token's contract ID, which should be 71c670db8b9d9dd3fa17d83bd98e4a9814f926121972774bd419fa402fe01dc7, somewhere since we will use it later.

Now that we have all the information we need, Let's invoke the init function of our contract.

soroban invoke \
--id [your contract id] \
--fn init \
--arg '{"object":{"accountId":{"publicKeyTypeEd25519":"[public key of your child account in hexadecimal]"}}}' \
--arg [the XLM token contract address] \
--arg [the allowance that you would like to give in stroops] \
--arg [the withdrawal rate in seconds]

We should get a success reply if our arguments are correct. Note that the allowance is in stroops, and a stroop is a 10 millionth of a Lumen.

I allowed the Child account to withdraw 500 Lumens yearly, once every week (60 * 60 * 24 * 7 = 604800).

`import`ing XLM to Parent Account

Now, we have to import some "Classic" Lumens from the Stellar network to Soroban network, so that the Child account can withdraw them. We will use the import function of the token contract, as it implements the Token Interface that we discussed above. As a reminder, the definition of the import function is

fn import(env: Env, id: Signature, nonce: BigInt, amount: i64);

We have a new Signature type that we need to construct as an argument. The Signature type is a proof indicating the signer is giving permission to the function invoker the required permissions. Since we will import for ourselves, we can use the "Invoker" argument to tell the contract that we are doing it for ourselves. Since we are the invoker of this function, the contract knows that we possess the control of the account's secret key, and allows us to accomplish whatever we would like to do.

The nonce parameter is used for signature validation. Since we are not supplying a signature, we can just pass 0.

Signature nonces

Let's say we have approved a third party to take 100 tokens from us by giving them a signature indicating the approval. What keeps them from just using the signature again and again to take 100s of tokens from us? This is called a "Signature Replay Attack", and should be migitated with making signatures "one use only".

Adding a nonce parameter to the message we are signing, assuming the contract has the correct implementation, will prevent Signature Replay Attacks, as now the contract will check if the supplied nonce is one higher than the previous.

So, we can call the import function on the XLM Token Contract using

soroban invoke \
--id 71c670db8b9d9dd3fa17d83bd98e4a9814f926121972774bd419fa402fe01dc7 \
--fn import \
--arg '{"object":{"vec":[{"symbol":"Invoker"}]}}' \
--arg 0 \
--arg [amount in stroops]

Note that the amount is again in stroops, meaning that we have to add seven 0s to convert them to Lumens.

We can go a step further and check out the amount of Lumens we have using the balance function on the XLM Token Contract. The definition of the balance function is

fn balance(e: Env, id: Identifier) -> BigInt;

The Identifier type is a type that indicates if the ID argument is from an EOA or a Contract. Since we are an EOA with a Public and Private key pair, we should use the Account identifier on our argument. If you forgot how to calculate your account ID in hexadecimal using Python, here's a reminder:

from stellar_sdk import Keypair

print(Keypair.from_public_key("[your public key]").raw_public_key().hex())

Let's invoke the balance function of the XLM Token Contract using

soroban invoke \
--id 71c670db8b9d9dd3fa17d83bd98e4a9814f926121972774bd419fa402fe01dc7 \
--fn balance \
--arg '{"object":{"vec":[{"symbol":"Account"},{"object":{"accountId":{"publicKeyTypeEd25519":"[your public key in hexadecimal]"}}}]}}'

We will get a reply indicating our balance in stroops.

`approve`ing the `AllowanceContract`

We now should permit the AllowanceContract to use our Lumens. Note that we should not permit the Child account instead, as they should only be able to withdraw using our contract.

The approve function's definition is

fn approve(e: Env, from: Signature, nonce: BigInt, spender: Identifier, amount: BigInt);

This time the Identifier will be of type contract, which will have the contract ID of our deployed contract as an input. Since we already know how to construct the other arguments, we can call the approve function using

soroban invoke \
--id 71c670db8b9d9dd3fa17d83bd98e4a9814f926121972774bd419fa402fe01dc7 \
--fn approve \
--arg '{"object":{"vec":[{"symbol":"Invoker"}]}}' \
--arg 0 \
--arg '{"object":{"vec":[{"symbol":"Contract"},{"object":{"bytes":"[your contract id]"}}]}}' \
--arg [amount to approve]

If you approve less than a withdraw function would take at a time, it will fail. We can approve the same amount of tokens we have allowed.

`withdraw`ing to the Child Account

After setting up the contract and giving out permissions, we now can invoke the withdraw function in our contract using either the child account or our account. Note that anyone can call the withdraw function, but the funds will only go to the Child account. For a difference, let's invoke the contract from the Child account. We just need to supply the Child account's Secret Key to soroban CLI to invoke it from the Child account.

soroban invoke \
--id [your contract id] \
--fn withdraw \
--secret-key [child account's secret key]

We should see a success denoting the withdrawal has succeeded.

Now, let's check out the balance of the child account to see if the withdrawal actually worked.

soroban invoke \
--id 71c670db8b9d9dd3fa17d83bd98e4a9814f926121972774bd419fa402fe01dc7 \
--fn balance \
--arg '{"object":{"vec":[{"symbol":"Account"},{"object":{"accountId":{"publicKeyTypeEd25519":"[child account's public key in hexadecimal]"}}}]}}'

We should see a non-zero value for the Child account's balance! This value is also in stroops and will change with the arguments you have supplied to the init function.

`export`ing Lumens Back

Since the Child account has some Lumens now, we can export them back to the Stellar network using the export command of the XLM Token Contract. The export function is defined as

fn export(env: Env, id: Signature, nonce: BigInt, amount: i64);

Similar to the import function, we will build these arguments as JSON objects, and invoke the export function from the Child account.

soroban invoke \
--id 71c670db8b9d9dd3fa17d83bd98e4a9814f926121972774bd419fa402fe01dc7 \
--fn export \
--arg '{"object":{"vec":[{"symbol":"Invoker"}]}}' \
--arg 0 \
--arg 100000 \
--secret-key [child account's secret key]

Note that we can only export a maximum of the amount of Lumens that we have.

Success! Use sq check 6 to claim your reward 🎉!

Finishing Up

This was the last quest of this series, and definitely was the hardest one to finish. You should be proud of yourself! We have accomplished many feats using the Soroban network, and learned a lot about blockchain design, cryptography primitives, and programming in general.

I hope that you have enjoyed these posts, and learned some new information. The Stellar Quest series is always an incredible place to learn, so keep going on! Solve the Learn Quests, the Side Quests, and read the documentation.

I hope to see you again for the next quest. See you around!

Soroban Quest - Custom Types

Altuğ Bakan — Thu, 01 Dec 2022 06:00:00 +0000

After successfully completing the complicated Cross Contract quest on last post, we are ready for the Custom Types quest. Beware though, this quest is quite long and challenging, just what we like!

If you haven’t checked out the discussion on custom Soroban types, please take a look at the Using get to Retrieve Data section on the Auth Store tutorial.

Understanding `README.md`

Let's once again check out the README.md file for this quest.

Setting Up Our Quest Account

Use the usual commands, sq login if required, and sq play 5 to start your adventure.

Examining the Contract

Let's start with checking out the lib.rs file.

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) {}
}

It has some empty functions! The arguments of the functions are different types, which are seemingly imported from the types.rs file, as there is the use types::*; import up top.

We won't add any functionality to this file, so let's check out the types.rs file.

Filling Out `types.rs`

The types.rs file already has two examples: a struct and an enum.

#[contracttype]
pub struct Cylinder {
    pub radius: u32,
    pub height: u32,
}


#[contracttype]
pub enum Car {
    Chevrolet,
    Ford,
    Mercedes,
    Porsche,
    Honda,
    Toyota
}

Using Custom Types

The structs are used for creating objects that have multiple different values. These values can consist of basic types like u32 and Bytes, another structs, enums, arrays, and so on. The structs allow us to carry all properties of an object together on a single variable. Well, it is useful to pass a Car struct to a insert_to_garage function instead of tires, engine, color, fuel_type, license_plate, total_kilometers...

The enums are used for creating numeric types with names for a limited list. It is mostly useful for programmers, as trying to remember the ID of a student in a classroom might not be helpful, but you would know who Bob is. The compiler is not interested in those names, and will happily use their numeric values in your code.

We have a lot of empty structs and enums, waiting for us to implement them. Before starting out, please check out the Custom Types section from the Soroban Docs to learn more about the type system of Soroban.

Implementing `Rectangle`

Let's start with implementing the Rectangle struct.

#[contracttype]
pub struct Rectangle {
    // TODO: create your fields here for your `Rectangle` type
}

From README.md, we can see that

The Rectangle type must be a struct, with two fields: width and height which both must be a u32 value.

So, we can implement Rectangle as follows:

pub struct Rectangle {
    pub width: u32,
    pub height: u32,
}

Implementing `Animal`

Next, let's check out the Animal enum. From README.md, we can see that

The Animal type must be an enum, with at least two variations: Cat and Dog.

So, we can implement Animal as:

pub enum Animal {
    Dog,
    Cat,
    Bear,
    Wolf,
    Gorilla /* and many more */
}

Implementing `User`

Let's move on to the User struct. Again, from README.md, we see that

The User type must be a struct with name, age, and pet fields, corresponding to Bytes, u32, and Animal values, respectively.

Let's implement the User type. It consists of another struct, but that's nothing hard to implement.

pub struct User {
    pub name: Bytes,
    pub age: u32,
    pub pet: Animal,
}

Implementing `RGB`

We are almost halfway done! Let's now implement the RGB struct.

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

Since it should be defined using unnamed u32 types, we can define it as a tuple using the following definition.

#[contracttype]
pub struct RGB(pub u32, pub u32, pub u32);

Implementing `Color`

More than halfway done! Now, we must implement the Color enum, using the following definiton.

The Color type will combine the RGB custom type nested within a tuple enum type. Construct your RGB struct type as described bove, Then, your Color enum type must be defined as a variant with a name of "RGB" and an instance of your RGB type.

An enums type definitions can be of any type, including custom structs.

pub enum Color {
    RGB(RGB)
}

Implementing `Participant`

Almost done! We now need to implement the Participant enum type. The definition is

The Participant type must be an enum with single-value tuple variants as follows:

An "Account" variant with an AccountId type

A "Contract" variant with a BytesN<32> type

So, Participant should be composed from two different Soroban types: AccountId, and BytesN<32>. Since we know how to implement custom types on enums, let's go ahead and define the Participant enum.

pub enum Participant {
    Contract(BytesN<32>),
    Account(AccountId),
}

Implementing `RoyalCard`

Only one left! We now just need to implement the RoyalCard enum.

The RoyalCard type must be an enum containing three u32 integer variations as follows:

A "Jack" variant, with a value of 11

A "Queen" variant, with a value of 12

A "King" variant, with a value of 13

It is quite simple to define an enum with given values, so we can implement it as follows.

#[repr(u32)]
pub enum RoyalCard {
    Jack = 11,
    Queen = 12,
    King = 13
}

The #[repr(u32)] attribute tells the compiler to pack each enum element into an 32 bit memory slot, which is the size of an u32 variable.

We have accomplished quite much! But the quest isn't over, since we still have to invoke the "empty" functions successfully using soroban CLI. To learn more about how we can invoke those functions, let's check out the test.rs file.

Examining the Test

The test has only one function, test_types, which tests the types of all of the custom structs and enums we have created by constructing the corresponding type, and calling the corresponding function. Let's check if our implementations of the custom types are correct using

cargo test -p soroban-custom-types-contract

Success!

Solving the Quest

Now, we can try to solve the quest by creating the arguments to invoke each function on the implementation of our Soroban contract.

Deploying the Contract

Before we start invoking, let's deploy our contract using

cargo build --target wasm32-unknown-unknown --release
soroban deploy --wasm target/wasm32-unknown-unknown/release/soroban_custom_types_contract.wasm

Invoking `c_rect`

First, we have to call the c_rect function, which has the argument _rect of type Rectangle. If we check out the README.md file, we see that we can

Invoke the c_rect function to create a Rectangle using something like:

soroban invoke \
    --id <contract-id> \
    --fn c_rect \
    --arg '{"object":{"map":[{"key":{"symbol":"width"},"val":{"u32":<a-u32-integer>}},{"key":{"symbol":"height"},"val":{"u32":<a-u32-integer>}}]}}'

We can see that we should change the values for the sections marked with <a-u32-integer> to an actual u32 integer, and <contract-id> to our contract ID. You can choose any height or width for your rectangle. After you are happy with your choices, invoke the contract.

soroban invoke \
    --id <contract-id> \
    --fn c_rect \
    --arg '{"object":{"map":[{"key":{"symbol":"width"},"val":{"u32":<a-u32-integer>}},{"key":{"symbol":"height"},"val":{"u32":<a-u32-integer>}}]}}'

Invoking `c_animal`

After successfully invoking the c_rect function, we now will move on to the c_animal function. From README.md, we can

Invoke the c_animal function to create an Animal using something like:

soroban invoke \
    --id <contract-id> \
    --fn c_animal \
    --arg '{"object":{"vec":[{"symbol":"<a-relevant-animal-symbol>"}]}}'

Again, we should change the <contract-id> to our contract ID, and <a-relevant-animal-symbol> to an animal enum we have created. Since the Animal struct is a custom type we have created, we should create the corresponding object as a JSON.

Invoking `c_user`

Now, it's c_user function's turn. Again, checking out README.md, we see that we could

Invoke the c_user function to create a User using something like:

soroban invoke \
    --id <contract-id> \
    --fn c_user \
    --arg '{"object":{"map":[{"key":{"symbol":"name"},"val":{"object":{"bytes":"<a-hex-encoded-string>"}}},{"key":{"symbol":"age"},"val":{"u32":<a-u32-integer>}},{"key":> {"symbol":"pet"},"val":<an-animal-object>}]}}'

That's quite the prompt! We should find the hexadecimal encoded string of a name, change the <a-u32-integer> to an age, and <an-animal-object> to the JSON representation of an animal object.

Remember that we could use the same Dog object that we used for the c_animal invocation, but feel free to use any animal you'd like.

Invoking `c_rgb`

That one was the hardest! Now, we can invoke the c_rgb function. Again, if we check out README.md, we will see that we can

Invoke the c_rgb function to create a RGB value using something like:

soroban invoke \
    --id <contract-id> \
    --fn c_rgb \
    --arg '{"object":{"vec":[{"u32":<a-u32-integer>},{"u32":<a-u32-integer>},{"u32":<a-u32-integer>}]}}'

We again have to change the <a-u32-integer> values to any integer values that we'd like.

Invoking `c_color`

Keep going! Now, we can try invoking the c_color function. The README.md file states that we should

Invoke the c_color function to create a Color using something like:

soroban invoke \
    --id <contract-id> \
    --fn c_color \
    --arg '{"object":{"vec":[{"symbol":"RGB"},<a-rgb-object>]}}'

where <a-rgb-object> should be a JSON object representation of the RGB struct. Try to construct the object without looking below!

Invoking `c_part`

You are close! Now it's time to call the c_part function. Let's check out the README.md file once more.

Invoke the c_part function to create an account Participant using something like:

soroban invoke \
    --id <contract-id> \
    --fn c_part \
    --arg '{"object":{"vec":[{"symbol":"Account"},{"object":{"accountId":{"publicKeyTypeEd25519":"<hex-encoded-account-id>"}}}]}}'

Also invoke the c_part function to create a contract Participant using something like:

soroban invoke \
    --id <contract-id> \
    --fn c_part \
    --arg '{"object":{"vec":[{"symbol":"Contract"},{"object":{"bytes":"<contract-id>"}}]}}'

Do you remember how to obtain your hexadecimal encoded public key? (Hint: using Python!). Try to find out what to put into <hex-encoded-account-id>. The <contract-id> parameter is pretty simple, as we have been using that one for all function invocations that we have done.

Invoking `c_card`

Last one! You should be pretty tired at this point, but bear with me. Luckily, the last invocation is quite simple, as we only have to

Invoke the c_card function using something like:

soroban invoke \
    --id <contract-id> \
    --fn c_foo \
    --arg '{"u32":<a-u32-integer>}'

Remember that the u32 argument should be one of 11, 12, or 13, as we only defined those values. And c_foo should be c_card, if that wasn't clear.

`verify`ing Our Implementation

That was a lot of invocations! Finally, we must invoke the verify function of the verification contract 40d12b03a08f5dde4e0068aa752fa65eddf905e82a18f522efe350e0cd268b8a to make the verification contract verify the correctness of our deployed contract. Can you guess which argument we should supply? If you guessed the contract ID of the contract we have deployed, you are right! We can use

soroban invoke \
--id 40d12b03a08f5dde4e0068aa752fa65eddf905e82a18f522efe350e0cd268b8a \
--fn verify \
--arg [your-contract-id]

We should get a reply indicating that all of our custom implementations have succeeded, and none of them have failed.

Nicely done! You have definitely earned your reward! Use sq check 5 to claim your reward 🎉!

Soroban Quest - Cross Contract

Altuğ Bakan — Sat, 26 Nov 2022 16:41:21 +0000

We have tackled the Reverse Engineer quest on the last post, and are ready for the next quest, Cross Contract.

Understanding `README.md`

As always, let's check out the README.md file on the quest folder.

On this quest, we are tasked with deploying the CrossContractCall contract, and use it to interact with the DataStore contract we worked on the Auth Store quest.

Setting Up Our Quest Account

You should be pretty familiar with this concept by now. Use sq login if you haven't, and sq play 4 to start this quest.

Examining the Contract

Let's check out the contract's source code on lib.rs to learn more about this quest.

mod storage_contract {
    soroban_sdk::contractimport!(
        file = "../../target/wasm32-unknown-unknown/release/soroban_auth_store_contract.wasm"
    );
}

pub trait StorageCallTrait {
    fn inv_get(env: Env, store_id: BytesN<32>, owner: AccountId) -> Bytes;
}

pub struct CrossContractCallContract;

#[contractimpl]
impl StorageCallTrait for CrossContractCallContract {
    fn inv_get(env: Env, store_id: BytesN<32>, owner: AccountId) -> Bytes {
        let storage_client = storage_contract::Client::new(&env, store_id);
        storage_client.get(&owner)
    }
}

There are some new concepts on the source code. Let's examine them one by one.

Contract Import

Previously, we used the mod keyword to include the test.rs file, or the error.rs contract into our code. These files had their source code ready for importing, and we used them for developing our contract.

Using soroban_sdk::contractimport! macro is quite different, as we are now importing a precompiled contract. The soroban_sdk can use the imported contract's types, interface, and the client in the imported source code this way.

Contract Traits

We can define traits for contracts using the trait keyword. This can be thought as an abstract class, meaning that it has the interface but not the source code of its subclasses. On the source code of the CrossContractCallContract, we have

pub trait StorageCallTrait {
    fn inv_get(env: Env, store_id: BytesN<32>, owner: AccountId) -> Bytes;
}

which means that every contract that implements the StorageCallTrait should implement a function, inv_get, which has the parameters env, store_id, owner, and returns a Bytes result.

Why Do We Need Traits?

Since interoperability is a basic feature of smart contract blockchains, there are some standards that people use for easier interoperability. Let's say we have a token trait, which implements the send, recv_from, and balance_of traits. If we have such a standard, we can develop a token marketplace for all tokens that use this standard. Actually, most of the tokens you see everywhere implements the ERC-20 Token Standard created by Ethereum developers!

If we didn't have such standards exist, the exchange developers would have to support every implementation that exist on a smart contract blockchain, which would be harmful for anyone's time, and would raise various security concerns.

After creating a trait, we can import it to our contract using

impl StorageCallTrait for CrossContractCallContract {
    // code implementing inv_get here
}

If we fail to implement the inv_get function, the Rust compiler would give an error such as

Very handy for developing contracts!

Overall View

After getting to know about the new concepts on the contract, we can start checking out what the contract does.

There is only one function on the contract implementation, which is inv_get

fn inv_get(env: Env, store_id: BytesN<32>, owner: AccountId) -> Bytes {
        let storage_client = storage_contract::Client::new(&env, store_id);
        storage_client.get(&owner)
    }

It simply uses the imported StorageContract's get function to return the data that exists on that contract for an address.

Examining the Test

The test.rs file has one test function, get_cross_call.

use crate::{storage_contract, CrossContractCallContract, CrossContractCallContractClient};

#[test]
fn get_cross_call() {
    let env = Env::default();
    let storage_contract_id = env.register_contract_wasm(None, storage_contract::WASM);
    let storage_contract_client = storage_contract::Client::new(&env, storage_contract_id.clone());

    let cross_call_contract_id = env.register_contract(None, CrossContractCallContract);
    let cross_call_contract_client =
        CrossContractCallContractClient::new(&env, cross_call_contract_id);

    let u1 = env.accounts().generate();
    env.set_source_account(&u1);
    storage_contract_client.put(&bytes![&env, 0x48656c6c6f20536f726f62616e21]);

    assert_eq!(
        cross_call_contract_client.inv_get(&storage_contract_id, &u1),
        bytes![&env, 0x48656c6c6f20536f726f62616e21]
    );
}

We have an interesting line here, use crate::{storage_contract, CrossContractCallContract, CrossContractCallContractClient};, which imports the types from the lib.rs file. Since Rust modules are called crates, we import the crates from the contract implementation to use them in tests. Or, we could just use use super::* as previous tests did.

Using Specific Classes vs All Classes

Using use super::* instead of importing the crates used one by one might look easier, but later could cause some serious headache when the code grows in complexity. If we import everything from the parent implementation, we would have to use the names, types, and anything implemented on that contract only. For example, we could have problems if we tried to import another implementation of the storage_contract with additional functionality for testing.

Since we have examined lots of tests until now, I think you now understand what this test does. It first deploys the storage_contract and the cross_call_contract into the testing sandbox we use, then, creates a test user to put a value into the storage_contract. After putting a value, we can now assert that our cross_call_contract returns the same result that was put into the storage_contract.

Solving the Quest

Since we are tasked with deploying the DataStoreContract again, let's use the commands we used on the Auth Store quest to deploy them using current quest's account.

cargo build --target wasm32-unknown-unknown --release
soroban deploy --wasm target/wasm32-unknown-unknown/release/soroban_auth_store_contract.wasm

After we deploy the DataStoreContract, let's invoke the put function to put some data into the contract.

soroban invoke \
--id [the ID of your DataStoreContract] \
--fn put \
--arg [hexadecimal value longer than 10 bytes]

The first part of the quest is done! For the second part, we should first deploy the CrossContractCallContract to Soroban Futurenet.

soroban deploy --wasm target/wasm32-unknown-unknown/release/soroban_cross_contract_call_contract.wasm

Then, we need to find what the required function arguments are. The first argument we need to supply is store_id, which is of type BytesN<32>. This corresponds to the DataStoreContract's ID, which consists of 32 bytes, represented in hexadecimal values. The second argument is owner, of type AccountId. Recall that we used the AccountId type when solving the second quest using the get function. The idea is the same, we should create the JSON representation of the complex type AccountId. We can use the same Python script to find out our raw public key in hexadecimal format.

soroban invoke \
--id [the ID of your CrossContractCallContract] \
--fn inv_get \
--arg [the ID of your DataStoreContract] \
--arg '{"object": { "accountId": { "publicKeyTypeEd25519": "[your raw public key in hexadecimal format]" } } }'

Success! That was quite hard, and you should be proud of yourself. This quest combined almost all of the concepts of previous quests, so your success is well deserved! Use sq check 4 to claim your reward 🎉!

Soroban Quest - Reverse Engineer

Altuğ Bakan — Sat, 26 Nov 2022 12:31:02 +0000

The Auth Store Quest we solved on the last post was quite the feat! We will now tackle the next quest: Reverse Engineer.

Understanding `README.md`

As always, let's open the README.md file in the 3-reverse-engineer folder and take a look.

This quest is quite different! We are tasked with finding the contract ID of the already deployed contract. We have an important tip though, we are given the deployer account's public key, which is GAC7HE4PQWI7H34JQN6QLQ7Y7NTAUZDWJZ4SJ6GXVC4K2DN7N65K5NLI.

The Concept of Public Ledgers

Since we are transacting on a blockchain, all of our transactions are fully inspectable by anyone! Aside from privacy chains (Monero, Zcash, etc.), all of the transactions, meaning contract deployments, coin transfers, account creations are all easily inspectable! This is the case, as the validators should check the integrity of all the data that the blockchain has processed to achieve consensus between all nodes. Of course, there are some other ways such as zk-proofs, which hide the details of the transactions while making them still verifiable!

The so called "privacy" components of the blockchains comes from the idea that we do not know who the public key's owner is. This can be quite handy for privacy, but is also not the exact solution to the privacy problem as the transactions of a user can be mapped to a person with enough information, such as IP addresses, their social media sharings and so on.

Setting Up Our Stellar Quest Account

As always, use sq login if you haven't, and use sq play 2 to start questing. Don't forget to fund your account!

Examining the Contract

Let's check out the lib.rs file in the src folder. The contract is quite short, but has some different concepts than previous contracts. Let's check it out.

pub struct ReverseEngineerContract;

const SECRET : Symbol = symbol!("dancinRaph");

#[contractimpl]
impl ReverseEngineerContract {
    pub fn submit(_: Env, secret: Symbol) -> bool{
        secret == SECRET
    }
}

We see that there is only one function, submit, which takes the argument secret of type Symbol. If you remember, the Symbol type can be thought as a string with a maximum length of 10.

Focus on the following line:

const SECRET : Symbol = symbol!("dancinRaph");

We can see that a constant value is defined here, which is not modifiable by any means using any functions in the contract, or elsewhere. The SECRET constant is also of type Symbol, and has the value of "dancinRaph".

Constants and Secrets in Blockchains

Since the blockchain ledgers are actually public, we can't have secret values by just naming them "SECRET" and not telling anyone. Having the source code of course makes guessing the value trivial, but anyone can reverse engineer any contract's source code, and with some simple bytecode translations, view all of your values.

There are some ways of putting actual secret data on blockchains, such as hashing the values off-chain, and then submitting them. We can also check if another supplied value is correct, we can hash them on-chain, and compare the results. The wonders of cryptography!

Examining the Test

We only have one test function for this quest.

#[test]
fn test_q3() {
    let env = Env::default();
    let contract_id = env.register_contract(None, ReverseEngineerContract);
    let client = ReverseEngineerContractClient::new(&env, &contract_id);

    assert_eq!(client.submit(&symbol!("wrong")), false);
    assert_eq!(client.submit(&SECRET), true);
}

What this test does is quite simple. It checks the output value by giving it a false input, and checks it again by giving it the correct input. We did not expect the contract to panic when we supply an invalid value, as it just simply returns the false value.

Solving the Quest

To even attempt solving the quest, we should first find the contract ID of the quest contract. After finding the contract ID, we should supply the secret keyword that we found as the secret argument of the submit function, and solve the quest.

Stellar Laboratory

The Stellar Laboratory is a place for everything Stellar! You can check out all the endpoints of any Stellar network, even custom ones, and Build, Sign, and Decode transactions!

The Laboratory is definitely a very helpful place, but since we are programmers, and programmers are lazy, we don't want to leave our cozy terminal to solve the quests! Jokes aside, do check out the Stellar Laboratory to learn more about the Horizon API and other Stellar concepts.

Finding the Contract ID

Since the only information we have about the contract is the deployer account, let's check what the deployer account has done on the Futurenet. Let's communicate with the Horizon API from our terminal. Use

curl https://horizon-futurenet.stellar.org/accounts/GAC7HE4PQWI7H34JQN6QLQ7Y7NTAUZDWJZ4SJ6GXVC4K2DN7N65K5NLI/operations

To get some information about the deployer account. The output is quite large, but the interesting part of the JSON response is as follows.

{
  --snip--

  "transaction_successful": true,
  "source_account": "GAC7HE4PQWI7H34JQN6QLQ7Y7NTAUZDWJZ4SJ6GXVC4K2DN7N65K5NLI",

  --snip--

  "transaction_hash": "b4ead070088ad86a32c341907d9944a4f3def6c7f1e42cd6e1789d10ca344c38",

  --snip--

  "function": "HostFunctionHostFnCreateContractWithSourceAccount",
  "footprint": "AAAAAAAAAAEAAAAGTNbD4mfKK1nhwm9oUMF+GpFYPmEFgv/ujOvINx6UVzoAAAADAAAAAw=="
}

We see that the account GAC7HE4PQWI7H34JQN6QLQ7Y7NTAUZDWJZ4SJ6GXVC4K2DN7N65K5NLI has used the function HostFunctionHostFnCreateContractWithSourceAccount, which means that they successfully deployed a contract on the Soroban network. If we inspect the footprint using the soroban CLI, we can get more information about the transaction.

soroban xdr dec \
--type LedgerFootprint \
--xdr AAAAAAAAAAEAAAAGTNbD4mfKK1nhwm9oUMF+GpFYPmEFgv/ujOvINx6UVzoAAAADAAAAAw== \
--output json | grep contractId

We got the contract ID!

XDR Types

eXternal Data Representation (XDR) is a format that is quite compact, reliable, and rich. Stellar ledger uses XDR formatted data to communicate with clients and store all kinds of data. They are shown base64 encoded, which compresses the data even more when communicating with clients. Check out Stellar Docs on XDR for more information.

Invoking the `submit` Function

Now that we have found the contract ID, we can call the submit function on the ReverseEngineerContract.

soroban invoke \
--id 4cd6c3e267ca2b59e1c26f6850c17e1a91583e610582ffee8cebc8371e94573a \
--fn submit --arg dancinRaph

Success! Since we got true as the response, we know that we supplied the correct parameter as an argument. Use sq check 3 to claim your reward 🎉!

Soroban Quest - Auth Store

Altuğ Bakan — Fri, 25 Nov 2022 11:29:54 +0000

After completing the Hello World quest on the last post, you should feel more comfortable about solving a more advanced quest.

Understanding `README.md`

As before, let's open our quests folder, then, open the 2-auth-store folder to start tackling the second quest.

On the README.md file, we can see that we are tasked with using the put function of the Soroban contract to save some data onto the Stellar ledger. Then, we should use get or get_self functions to retrieve the data we saved.

Setting Up Our Stellar Quest Account

As usual, use sq login to login to your Stellar Quest account if you haven't, and use sq play 2 to start solving the second quest. Don't forget to fund your account with sq fund to succesfully transact on the Futurenet.

Examining the Contract

As usual, open up the src/lib.rs file to view the contract's source code. In addition to test.rs, you will also see error.rs for this quest. Let's start by checking out the functions of the DataStoreContract.

`put` Function

The put function allows us to store arbitrary data mapped to our account address.

pub fn put(env: Env, value: Bytes) -> Result<(), ContractError> {
        let key = match env.invoker() {
            Address::Account(account_id) => account_id,
            Address::Contract(_) => {
                panic_with_error!(&env, ContractError::CrossContractCallProhibited)
            }
        };

        if value.len() <= 10 {
            panic_with_error!(&env, ContractError::InputValueTooShort)
        }

        env.data().set(key, value);

        Ok(())
}

The put function has two arguments, one of them being the environment variable env, and the other one is the value argument of type Bytes. The Bytes type can be thought as a string, as each character of a string consists of one byte. The difference between the Symbol and the Bytes type is that the Symbol type can only have a maximum of 10 characters. The function returns either the Ok value or a ContractError.

Understanding Contract Errors

Custom errors are enums, which is a number type that is mapped to labels. The use of numbers are efficient for computers, and labels are helpful for programmers to understand what they mean.

Using custom contract errors is useful when negative testing the contract. Negative tests make sure that the implementations support unexpected input, while positive tests ensures that the implementations are working as expected. Since our Soroban contracts will be immutable, testing against harmful behavior helps with preventing some attack patterns.

Using custom contract errors are also useful for User Experience, as the users usually get these errors before calling a contract function. Giving helpful names to errors help users fix their input arguments easily.

First, the put function finds the key of the contract invoker. The invoker can be one of two things: an Externally Owned Account (EOA), which will be us, an user with a private and public key pair, or another contract using cross-contract calls. This implementation blocks the use of cross-contract calls, which we can see by inspecting the match statement. if env.invoker() matches a contract address, the program panics and exits with the custom contract error, CrossContractCallProhibited. The implementation of these errors can be found in the error.rs file.

Next, the put function checks if the length of the supplied value is shorter or equal to 10 bytes, and panics with the custom InputValueTooShort error if it is the case. This is to highlight the difference between a Symbol variable and a Bytes variable, and is not required when implementing a function.

If all the checks are correct, the contract stores the supplied value variable mapped to the invoker's address to persist between function invocations.

Persisting Data vs Temporary Data

If you are familiar with any programming language, you would remember that there are global variables, which are accessible anywhere from the code, and local variables, that are scoped to their blocks.

Variables declared in the functions are lost after the execution has ended, and not stored permanently onto the chain. By storing the variables into the environment however, we make permanent records on the Soroban network. Due to this, storage is usually very expensive compared to the other methods on smart contract chains.

`get` Function

The get function allows us to retrieve data set by a given account.

pub fn get(env: Env, owner: AccountId) -> Bytes {
        env.data()
            .get(owner)
            .unwrap_or_else(|| Ok(bytes!(&env)))
            .unwrap()
}

The get function looks pretty simple, but has some hidden functionality behind it. Excluding the env argument, the get function has the owner parameter of type AccountId, which can be tricky to supply from the soroban CLI as an argument. First, the function uses env.data.get(owner) to get the value set by the given account. If this value does not exist, the function returns Ok with env converted to bytes using the bytes! macro. If this value does exist, it returns the value set by the account.

Note that the cross-contract calls are allowed for this function, meaning that we can use another contract to call this function to get any user's set data from our contract. Pretty handy!

`get_self` Function

If you check out the get_self function at first, it looks a little off.

pub fn get_self(/* env: Env */) -> Result<Bytes, ContractError> {
        unimplemented!("not implemented")
        // let key = match env.invoker() {
        //     Address::Account(account_id) => account_id,
        //     Address::Contract(_) => {
        //         panic_with_error!(&env, ContractError::CrossContractCallProhibited)
        //     }
        // };
        // Ok(env
        //     .data()
        //     .get(key)
        //     .unwrap_or_else(|| Ok(bytes!(&env)))
        //     .unwrap())
    }

The implementation of the contract is commented out, meaning the compiler ignores those lines. Comments are shown with the double forward slashes, //, or can be done inline using /* */ in Rust. To "unlock" the functionality of the get_self function, remove or comment the line starting with the unimplemented! macro, and uncomment the other lines, including the input parameter, env.

pub fn get_self(env: Env) -> Result<Bytes, ContractError> {
        // unimplemented!("not implemented")
        let key = match env.invoker() {
            Address::Account(account_id) => account_id,
            Address::Contract(_) => {
                panic_with_error!(&env, ContractError::CrossContractCallProhibited)
            }
        };
        Ok(env
            .data()
            .get(key)
            .unwrap_or_else(|| Ok(bytes!(&env)))
            .unwrap())
    }

Comments on Codes

On any code file, you will usually see some comments, explaining the code, disabling some lines, or drawing some awesome ASCII art. The comments are an important part of programming, and they are not even for computers (mostly)!

The comments are a helpful way for programmers, who generally work on a codebase on a different time than each other, to give out details, explain the cryptic parts, and even leave themselves some reminders. The Doom inverse square root code is a great example on comments:

Well maybe not. The code is still cryptic, but the programmer also thinks that it is, which we can understand from the comment that they left for us. They also commented out the 2^nd iteration as they think that it is not required. Be kind to other programmers and try to explain your code if you think commenting is required!

The get_self function allows us to retrieve data that we set ourselves. It first checks if the caller is an EOA and not an external contract as before, and returns the data set by the caller, as before. This function is easier to use for our quest, as we don't need to supply an account to retrieve a data. We will use both solutions to solve this quest.

Examining the Tests

The test.rs file containing the tests is pretty hefty! Usually, tests take more time to write than the contract to ensure the safety of the contract. Since the tests are extremely well commented, I encourage you to understand them yourselves! I will explain some key features of these tests that do not exists on the HelloContract tests.

`#[ignore]` Modifier

The #[ignore] modifier is used on tests which should be, well, ignored. The main reason for this can be unimplemented source code, or unfinished tests. Since we have removed the comments on the get_self file, we can remove the #[ignore] modifier for its test.

#[test]
#[should_panic(expected = "Status(ContractError(1))")]
fn test_contract_get_self() {
    /* the test code as usual */
}

Now, we can also test the functionality of the get_self function when we use cargo test to test our contract.

`should_panic` Keyword

#[test]
#[should_panic(expected = "Status(ContractError(2))")]
fn test_store_value_too_short() {
    let env = Env::default();
    let contract_id = env.register_contract(None, DataStoreContract);
    let client = DataStoreContractClient::new(&env, &contract_id);

    let u1 = env.accounts().generate();
        .with_source_account(&u1)
        .put(&bytes![&env, 0x007]);
}

The should_panic keyword, supplied with a custom contract error makes sure that the contract returns the expected error when supplied with an invalid input argument. On this test, we are calling the put function with a value that is two bytes long, and expecting it to fail with the InputValueTooShort error, which has the value 2.

Contract Implementation in `test.rs`

We can implement contracts just for testing on the test.rs file. this is helpful to test the cross contract calls, and many other methods that require another contract.

pub struct CallerContract;

#[contractimpl]
impl CallerContract {
    pub fn try_put(env: Env, contract_id: BytesN<32>, data: Bytes) {
        let cli = DataStoreContractClient::new(&env, contract_id);
        cli.put(&data);
    }

    pub fn try_get_s(env: Env, contract_id: BytesN<32>) -> Bytes {
        let cli = DataStoreContractClient::new(&env, contract_id);
        cli.get_self()
    }

    pub fn try_get(env: Env, contract_id: BytesN<32>, owner: AccountId) -> Bytes {
        let cli = DataStoreContractClient::new(&env, contract_id);
        cli.get(&owner)
    }
}

The CallerContract implements three functions. The first one is the try_put function, which tries to use the put function on the DataStoreContract using a cross-contract call. This invocation is expected to fail, but it is important to test the failing cases too! Next, it has the try_get_s function, which is used for trying to invoke the get_self function via a cross-contract call. This is also expected to fail with the custom CrossContractCallProhibited error. Lastly, it has the try_get function, which should successfully call the get function of the DataStoreContract.

Why are Function Names Too Short?

The functions are implemented as Symbols, which are at most 10 characters long. Storing function names as Symbols is helpful due to execution efficiency and storage cost. Since the efficiency is important on blockchains, and this issue does not really cause a bad user experience, this implementation is chosen.

Generating a Test Account and Using Test Contracts

We can generate accounts for testing our contracts using env.accounts().generate(). This is helpful for testing the implementation using multiple accounts.

fn test_contract_get() {
    let env = Env::default();
    let contract_id_data_store = env.register_contract(None, DataStoreContract);
    let client_data_store = DataStoreContractClient::new(&env, &contract_id_data_store);

    let contract_id_caller = env.register_contract(None, CallerContract);
    let caller_client = CallerContractClient::new(&env, contract_id_caller);

    let u1 = env.accounts().generate();
    client_data_store
        .with_source_account(&u1)
        .put(&bytes!(&env, 0x48656c6c6f20536f726f62616e21));

    let value = caller_client.try_get(&contract_id_data_store, &u1);
    assert_eq!(value, bytes!(&env, 0x48656c6c6f20536f726f62616e21));
}

This test uses a test account to invoke the put function on the DataStoreContract, in order to test the get function using a cross-contract call, as it is not possible to put data to the contract environment using a contract.

We can use let u1 = env.accounts().generate() to create an EOA, then, use client_data_store.with_source_account(&u1).put(&bytes!(&env, 0x48656c6c6f20536f726f62616e21)); to test invoking the put function using the generated account. with_source_account method is what accomplishes our task.

We can use let contract_id_caller = env.register_contract(None, CallerContract); to register the contract implementation into our testing environment, and use let caller_client = CallerContractClient::new(&env, contract_id_caller); to create the client used for testing cross-contract calls.

Solving the Quest

Now that we fully understand the Quest, we can attempt solving it. We will use both get and get_self to solve this Quest.

Deploying the Soroban Contract

As usual, we will use cargo build --target wasm32-unknown-unknown --release to build the contract, and cargo test to see if everything works before publishing our contract. cargo build will create the target/wasm32-unknown-unknown/release/soroban_auth_store_contract.wasm file, which we will deploy to the Soroban network.

We will use

soroban deploy --wasm target/wasm32-unknown-unknown/release/soroban_auth_store_contract.wasm

to deploy our contract. If it succeeds, we will see a success message, followed by the contract id of our contract.

If your local RPC does not work, use sq rpc -c to change your RPC endpoint to an official one.

Why Use My Own RPC Endpoint?

The Remote Procedural Call (RPC) endpoint is a server that can execute custom RPC commands on the server. The Soroban blockchain is interacted using the RPC procedure to deploy contracts, invoke functions, and check data on-chain. The soroban CLI acts as the middleware which uses the RPC calls underneath to interact with the Soroban network.

Using your own RPC endpoint helps with privacy, as other RPC servers might collect your IP address, log your calls, and so on to identify who you are. Running a local Soroban node helps with hiding this information from third-party actors, and helps with the decentralization of the Soroban network.

`put`ting Data to Our Contract

After deploying the contract, if everything works well, we can use

soroban invoke --id [your contract id] --fn put --arg [value]

to save data to your contract environment. If we recall that the type of value was Bytes, we know that we need to supply the hexadecimal value of the "string" we are looking to save. We can convert the string value we need to hexadecimal without even leaving our terminal! Type

echo "Hello Soroban!" | xxd -p

to convert the string "Hello Soroban!" to its hexadecimal representation. Note that you should select a value that is longer than 10 characters.

What Does xxd Do?

The xxd program creates a hexdump of the input given. A hexdump is the hexadecimal representation of a given file, string, or anything digital, which is actually how the computer stores given data. The x character represents the heXadecimal word, and the d character represents the dumping process.

The -p option prints the output plainly into the standard output, which is without grouping and without the string representation. Remove the -p flag to test it!

As with almost all Linux commands, you can use man xxd to learn more about the xxd command by reading the manual page. Getting to know more about Linux commands makes you a more efficient programmer!

After we obtain the hexadecimal value of our message, let's put the value into our contract data.

Using `get_self` to Retrieve Data

Using get_self to retrieve data is simple, as we don't need to supply any arguments. Simply call

soroban invoke --id [your contract id] --fn get_self

to retrieve the data you saved using the put function. You should receive a success message, followed by an array of bytes in decimal representation.

How to Check if the Returned Value is Correct

The returned value consists of some decimal values, which makes it hard to check if the received value is the same with the supplied value. Luckily, we can use Python to easily check if that is the case.
import re

for i in re.findall("[0-9]+", "[72,101,108,108,111,32,83,111,114,111,98,97,110,33]"):
    print(chr(int(i)), end="")
That is one cryptic code, but what it does is replacing all the decimals in the returned array, that is [72,101,108,108,111,32,83,111,114,111,98,97,110,33], with their ASCII representations. We should see the original string we converted into its hexadecimal representation.

Success!

Using `get` to Retrieve Data

Using get to retrieve the data we supplied with our account is harder than the first method, but nothing impossible. We will use

soroban invoke --id [your contract id] --fn get --arg '{"object": { "accountId": { "publicKeyTypeEd25519": "[your raw public key in hexadecimal format]" } } }'

As you see, the hard part is constructing the AccountId type from the CLI, and finding the hexadecimal format of our public key. Since Soroban uses the JSON-RPC spec to communicate with clients, the complex types derive from the object class. Please check out the wonderful guide from Smephite for more information about Soroban types.

JSON-RPC Types

JSON stands for JavaScript Object Notation, which is a data interchange format which is derived from the JavaScript types. The reason complex types derive from the "object" class is due to JSON supporting only a handful types, which are strings, numbers, booleans, null, object, and array. All other classes are composed using these 6 classes.

Soroban has 8 default JSON-RPC classes, where u63 and u32 are unsigned integer types, i32 is the signed integer type, static is an enum type that can take the values void, true, false, and ledgerKeyContractCode, object is the same object type from JSON, symbol is a value that is limited by 10 bytes of length, bitset is a type that consists of at most 60 bits, and status is also an enum type that denotes errors.

Since we have access to Python on our workspace, we can use the stellar_sdk Python package, which has some great utility tools we can use. Since it is not preinstalled, we can use

pip install stellar_sdk

to install it to our workspace. Note that the package will cease to exist after your workspace becomes inactive. After installing stellar_sdk, we can enter Python and find our public key's hexadecimal representation using

from stellar_sdk import Keypair

print(Keypair.from_public_key("[your public key]").raw_public_key().hex())

Great! After calling the get function, we should get a success message, followed by the data we saved using the put function into the contract.

Success! Use sq check 2 to claim your reward 🎉!

Soroban Quest - Hello World

Altuğ Bakan — Thu, 24 Nov 2022 19:13:05 +0000

On the last post, we booted up our GitPod environment and now are ready to tackle the first Soroban Quest: Hello World!

Understanding `README.md`

Let's begin questing by opening the quests folder in our Explorer. We can see multiple quests existing here. Since we will tackle the first quest right now, let's open the 1-hello-world folder by clicking on it. Then, select README.md for more information about what to do on this quest.

We can see that we have to use our Stellar Quest account to deploy and invoke the 1 Hello World contract on the Stellar Futurenet. What does any of these words mean? Let's check them out.

Setting Up Our Stellar Quest Account

If we missed it, or are using another workspace, we should use sq login to login to our Stellar Quest account. This way, our progress can be saved to our account, and we can get sweet NFTs to our connected wallet. If the 1-hello-world folder is missing, we can use sq pull to get the newest copy of the repository from GitHub.

Pull? From where?

sq pull uses git underneath to "pull" the newest changes from the soroban quest repository to our local workspace. git is a version control program with excellent remote and local repository synchronization support, so that's what is happening here. sq pull accomplishes it in three steps:

Uses git stash to save our changes into a stash, so that collisions between the remote repository and our repository do not occur.

Uses git pull to pull the changes from the soroban quest repository.

Uses git stash pop to reapply the saved changes to our workspace.

It is pretty useful for saving our work on the workspace, while having the ability to add new stuff!

After setting up our account and everything, we can use sq play 1 to start questing! We should accept the funding by the prompt, as we will need some Futurenet Lumens for transacting. If you accidentally pressed no, you can use sq fund [account], with account being the public key given to you for the quest. Don't forget to remove the brackets!

Examining the Contract

On the src folder, we can see two files: lib.rs and test.rs. lib.rs contains the source code of the Soroban contract given on this quest. Let's begin checking out the code.

// We don't include the standard library to minimize compiled
// size. We also import a few macros and types we need from the
// `soroban_sdk`.
#![no_std]
use soroban_sdk::{contractimpl, symbol, vec, Env, Symbol, Vec};

pub struct HelloContract;

// Our `HelloContract` implementation contains only one function,
// `hello()`. This function will receive a `to` argument, and
// return a Vec made up of "Hello" and the supplied `to` value.
#[contractimpl]
impl HelloContract {
    pub fn hello(env: Env, to: Symbol) -> Vec<Symbol> {
        vec![&env, symbol!("Hello"), to]
    }
}

// This `mod` declaration inserts the contents of `test.rs` into
// this file.
mod test;

The Soroban contracts are written in Rust, which is the hottest programming language at the moment. If you are not familiar with Rust, no worries! The contracts are extremely well commented, and it is quite understandable if you are experienced with another programming language. Let's dive deeper into the contract's code.

What is Rust and Why is it Everywhere?

Rust is a systems programming language, which is known by it's memory safety. In addition to being memory safe, it is also blazingly fast, which makes it a popular programming language amongst programmers. The memory safety aspect is important, since 70% of the CVEs are caused by memory safety issues. So, to write a fast and secure code, a different approach than C and C++, must be employed. That's why Rust is everywhere!

#![no_std]
use soroban_sdk::{contractimpl, symbol, vec, Env, Symbol, Vec};

pub struct HelloContract;

The #![no_std] line tells the Rust compiler to not include the standard library, as it is quite large and is not fully supported by the Soroban environment. The useful components are already implemented in the soroban_sdk, so we don't need to include the standard library! The second line tells the compiler to use the implementations of contractimpl, symbol, vec, Env, Symbol, and Vec from the soroban_sdk library. We will use these lines almost every time when we are developing a Soroban contract. The next line tells the Soroban Runtime that our contract's name is HelloContract. After these definitions, we can check the implementation of the contract.

#[contractimpl]
impl HelloContract {
    pub fn hello(env: Env, to: Symbol) -> Vec<Symbol> {
        vec![&env, symbol!("Hello"), to]
    }
}

The implementations of Soroban contracts are marked with #[contractimpl] to tell the compiler to do the right thing. In our contract implementation of the HelloContract, we can see that we have a public function, denoted with pub fn. Public functions are functions on a contract which are invokable by everyone using the Soroban network. The hello function has two arguments, and returns a Vector of Symbols. A Symbol is a string-like value, which consists of at most 10 characters. A Vector can be defined as an array with the capacity to grow indefinitely.

The first input argument is env of type Env. This parameter can be found on every functiion that deals with the state of the Soroban network. It is generally used in each function, as it supplies some additional functionality. The env argument is not supplied by the invoker of the function, and is added automatically on function invocation.

The second input argument is to of type Symbol. Symbols can be assumed as strings of a maximum length of 10. They provide cost and space efficiency, and are widely used for small data.

The function returns a Vector, using the macro vec!. It returns a vector with three elements, which are &env, the symbol "Hello", and the symbol to, which is supplied by the invoker of the function. The &env parameter is the reference of the Soroban environment, and is not explicitly returned to the user.

mod test;

The last line inserts the code content of the test.rs file to the lib.rs file.

Examining the Test

Now, let's examine the test.rs file. Examining the tests are important to see how the contract operates. A well tested contract is more secure than a non-tested contract, and security is one of the most important concerns when dealing with contracts on a blockchain.

#![cfg(test)]

use super::*;
use soroban_sdk::{symbol, vec, Env};

// The purpose of this file is to run automated tests on the 
// contract code we've written in `lib.rs`. Writing tests can be
// quite a big topic, and we'll dive in further in a future quest. 
// Just you wait!
#[test]
fn test() {
    // we register the contract in a Soroban environment, and
    // build a client we can use to invoke the contract
    let env = Env::default();
    let contract_id = env.register_contract(None, HelloContract);
    let client = HelloContractClient::new(&env, &contract_id);

    // Next, we call `client.hello()`, supplying "Dev" as our `to`
    // argument.
    let words = client.hello(&symbol!("Dev"));

    // We assert the contract must return a Vec that matches what 
    // we would expect to receive from our contract: 
    // [Symbol("Hello"), Symbol("Dev")]
    assert_eq!(words, vec![&env, symbol!("Hello"), symbol!("Dev"),]);
}

The test is also written in Rust, and is used to test the functionality of the HelloContract on a local environment.

#![cfg(test)]

use super::*;
use soroban_sdk::{symbol, vec, Env};

The first line configures the file as a test environment. The second line, use super::*;, imports everything from the parent module, which is the HelloContract file here. As before, the third line imports some implementations from the soroban_sdk.

#[test]
fn test() {
    let env = Env::default();
    let contract_id = env.register_contract(None, HelloContract);
    let client = HelloContractClient::new(&env, &contract_id);

    let words = client.hello(&symbol!("Dev"));

    assert_eq!(words, vec![&env, symbol!("Hello"), symbol!("Dev"),]);
}

The test implementations are marked with #[test], and allows the Rust compiler to understand that these are testing functions. We start with creating a constant, env, and initializing with the default value. Next, we are registering our HelloContract to the environment. Now, we have a local Soroban sandbox with only HelloContract existing. We then create a client to interact with the contract of ours for testing.

We invoke the function hello on our HelloContract by using the hello method of our client using the "Dev" argument. See that we are not supplying the env parameter, as it is implicitly included already. We then set the reply of the function to the words constant.

After doing our invocation, we assert the contract must return a Vec, which consists of the elements &env, "Hello", and our input argument, "Dev". If that is the case, the test ends without an error, which means that our implementation is correct.

Testing Tips

When testing software, we use the AAA (Arrange, Act, and Assert) principle. First, we "Arrange" the environment, which we did here using the first three lines. Then, we "Act" on our source code, which corresponds to invoking our hello function on our contract. Finally, we "Assert" that everything is correct by comparing the actual result to the expected result. This way, testing software can be done systematically.

Compiling, Testing, Deploying

We can compile our code using cargo build to compile our rust codes into .wasm files. If we want to build only a specific quest's contract, the usage is

cargo build --package [package-name] --target wasm32-unknown-unknown --release

where the package name of a quest can be found in the Cargo.toml file on the quest's folder. For example, the Hello World quest's package name is soroban-hello-world-contract, so we can build it using

cargo build --package soroban-hello-world-contract --target wasm32-unknown-unknown --release

The created object can be found in target/wasm32-unknown-unknown/release/soroban_hello_world_contract.wasm file. We can also use cargo test, to see if our implementations contains any error.

Everything looks great! We now can deploy our Soroban contract to the Futurenet using soroban deploy command. Please be careful that you are using the CLI - Futurenet: bash terminal to successfully accomplish this task. The full command is

soroban deploy --wasm target/wasm32-unknown-unknown/release/soroban_hello_world_contract.wasm

We should see a success message with the contract's ID. If you are getting errors when deploying, wait for the Soroban client to synchronize to the Futurenet, which can take some time. If you are still getting errors, try using the handy command sq rpc -c to change the default RPC endpoint to an official one.

Great! We will need to supply this ID to interact with our deployed contract. We can use a different contract ID to interact with another contract. The possibilities are endless!

We can now invoke the hello function using soroban invoke to get a reply from our contract. We should again use the Futurenet CLI for this purpose.

soroban invoke --id [your contract id] --fn hello --arg [any string argument shorter than 10 characters]

The invocation should return a success and the Vector that contains the "Hello" word followed by the argument we supplied.

Everything works perfectly, and we have completed the first quest! Well done! Use sq check 1 to claim your reward 🎉.

How Long Will My Contract Live?

Forever! That's the beauty of the blockchains. The immutability and the censorship resistance are what makes blockchains great. This power is a double edged sword though, if we make any mistakes, or have any vulnerabilities in our contract, there's nothing we can do! That's why testing and auditing smart contracts are an important business.

Note that this is the Futurenet, which is a test server for Soroban contracts. It often gets reset, so your Soroban contract will cease to exist. This will not happen when Soroban hits the mainnet!

Soroban Quest - Getting Familiar with the Workspace

Altuğ Bakan — Wed, 23 Nov 2022 17:23:32 +0000

So, you have found yourself in the new paradigm that is the blockchain, and would like to jump into the newest hot topic on Stellar ecosystem: Smart Contracts with Soroban.

The Stellar Quest has been an ongoing system which awards developers knowledge about the Stellar ecosystem. The first four Stellar Quests have been about the Horizon, Stellar's API for interacting with the network. Horizon allows you to accomplish most of the stuff on the Stellar ecosystem such as Path Payments, Trade Offers, and Asset Creation.

Enter Soroban, a new smart contract framework on Stellar, which allows developers to accomplish everything Horizon can and much more. The new Stellar Quest is about getting familiar with Soroban's development environment, which is what we will jump right into.

GitPod Environment

GitPod is a development environment which supports Docker, Node.js, and much more to generate a previously configured development environment, ready to go. The GitPod is a virtual Linux machine, and is presented with a much loved VSCode environment. To get started, go to soroban-quest repository and press the "Open in GitPod" button.

The environment will open within a VSCode web context.

This might look overwhelming at first, but let's check out the parts of the environment. At left, we see the explorer, which includes the quests and some configuration files. The most interesting part here is the "quests" directory.

We see the currently available quests, and new quests in the future. Next, we have our main panel, in which we can see the README.md file open by default.

Next, our favorite place: the terminal. At right, we can see that there are actually four different terminal pages open. Starting from the top, we see:

Futurenet: docker - Allows us to interact with the Soroban network on Futurenet.
Albedo Signer: npm run start - Allows us to earn the rewards from the quests!
CLI - Futurenet: bash - Allows us to send transactions and deploy contracts to the Futurenet Soroban network. This is where we will mostly work.
CLI - Sandbox: bash - Allows us to work on a local Soroban network for testing. No one else is allowed here!

Now that we are kind of familiar with the environment, let's start questing!

Squirtle CLI

There are two main programs we will use. The first one is sq, which stands for Squirtle (yes, actually!). sq is a CLI program created just for Stellar Quest. How handy!

Type

sq help

to your terminal to get to know more about the commands.

`sq login`

We should first use sq login to login to our Stellar Quest account. We should see four ✅s on our terminal to know that we're good to go!

After logging in, we don't need to login again if we continue to use the same GitPod workspace.

`sq pull`

sq pull is one of the main commands we will use before every quest. It "pulls" the new code from the soroban-quest repository so we can jump into solving quests.

`sq play [index]`

sq play [index] is another main command we will use on every quest. It creates an account on Futurenet, which we will use to solve the quests. Index is 1 for the first quest, 2 for the second and so on. After creating a new account, it asks if we would like to fund the account. The answer is almost always yes as creating Soroban contracts and invoking them require some Lumens.

`sq fund [key]`

sq fund [key] is useful when we forget to fund our account on the sq play command. The key parameter is our quest public key, which is in the form of something like GACS6G2UW226A5VJECJLJB5O772ZF47G6AOJVZ33VWHYTSJLUA6TUYQI.

`sq check [index]`

sq check [index] is used for checking if our solution is correct. If it is, we might get some rewards!

Soroban CLI

Soroban CLI is the heart of the Soroban Quest, and does everything required for developing Soroban smart contracts.

Type

soroban --help

to your terminal to get to know more about the commands.

`soroban deploy`

Allows us to deploy a Soroban contract to the Futurenet. The usage is

soroban deploy \
    --wasm <WASM> \
    --secret-key <SECRET_KEY> \
    --network-passphrase <NETWORK_PASSPHRASE> \
    --rpc-url <RPC_URL>

but since this development environment is automatically created, we only need to supply the WASM path using --wasm <WASM>. Doesn't make any sense? No worries, as it will soon enough!

Tips for interested peeps

I will try to include tidbits of information for advanced or curious developers to make use of. These stuff are definitely not required to know, but makes it easy to understand the whole concept.

The SECRET_KEY, NETWORK_PASSPHRASE, and RPC_URL parameters are already set! Try using echo $SOROBAN_SECRET_KEY, echo $SOROBAN_RPC_URL, and $SOROBAN_NETWORK_PASSPHRASE to see their values!

`soroban invoke`

Allows us to interact with contracts deployed on the Soroban network. The usage is

soroban invoke \
    --id <CONTRACT_ID> \
    --fn <FUNCTION> \
    --secret-key <SECRET_KEY> \
    --network-passphrase <NETWORK_PASSPHRASE> \
    --rpc-url <RPC_URL>

As before, we don't need to supply the --secret-key <SECRET_KEY>, --network-passphrase <NETWORK_PASSPHRASE>, and the --rpc-url <RPC_URL> arguments as they already exist. The id parameter is the address of a Soroban contract, fn is the function we would like to invoke on the Soroban contract, and arg is the arguments required for the function. We can use multiple arguments with multiple arg flags.

Other Useful Programs

We also have cargo available on the workspace, which is used for compiling the Soroban contracts. Python is also present, so we can make use of some helpful scripts for calculations and conversions.

`cargo`

cargo is the package manager of the Rust, like npm, and is also used for development as it has the ability to compile the contracts. We will use cargo to compile the contract codes, so that we can deploy them on Soroban.

We will use

cargo build --target wasm32-unknown-unknown --release

to compile our contracts and create the .wasm files required so that we can deploy them to the Soroban network.

Python

Since our workspace is a Linux environment, we will have access to Python and pip to install some packages. Using Python will be crucial to achieve success fast in a quest, as some conversions and tests can easily be done using Python. You can access it using

python

from your terminal.

After finishing your work with Python, you can use

quit()

to return to your Bash terminal.

Explorer

The main folder on the explorer will be the quests folder. Inside we can see all the quest files, which include README.md for the quest's purpose, STORY.md for the story of the quest, and the quest contract's source files on src.

lib.rs includes the source code of our Soroban contracts, and test.rs includes the tests for the said contract. The contracts are always correct as they are already built, but test files might contain some hints for the quests! Checking out test files is always helpful for checking out how the contract is used, so do check them out!

Finishing Thoughts

Now that we are pretty familiar with our development workspace, we can start working on some quests! Do check out my next post on how to understand and get to the solution of the "Hello World" quest, and understand even more about working with Soroban!

Forem: Altuğ Bakan

Soroban Quest - Asset Interop

Understanding README.md

Setting Up Our Quest Account

Token Interface

Examining the Contract

Allowance Trait

init Function

Ledger Data

withdraw Function

Examining the Test

Python Scripts

Solving the Quest

Deploying the Contract

Invoking the init Function

importing XLM to Parent Account

Signature nonces

approveing the AllowanceContract

withdrawing to the Child Account

exporting Lumens Back

Finishing Up

Soroban Quest - Custom Types

Understanding README.md

Setting Up Our Quest Account

Examining the Contract

Filling Out types.rs

Using Custom Types

Implementing Rectangle

Implementing Animal

Implementing User

Implementing RGB

Implementing Color

Implementing Participant

Implementing RoyalCard

Examining the Test

Solving the Quest

Deploying the Contract

Invoking c_rect

Invoking c_animal

Invoking c_user

Invoking c_rgb

Invoking c_color

Invoking c_part

Invoking c_card

verifying Our Implementation

Soroban Quest - Cross Contract

Understanding README.md

Setting Up Our Quest Account

Examining the Contract

Contract Import

Contract Traits

Why Do We Need Traits?

Overall View

Examining the Test

Using Specific Classes vs All Classes

Solving the Quest

Soroban Quest - Reverse Engineer

Understanding README.md

The Concept of Public Ledgers

Setting Up Our Stellar Quest Account

Examining the Contract

Constants and Secrets in Blockchains

Examining the Test

Solving the Quest

Stellar Laboratory

Finding the Contract ID

XDR Types

Invoking the submit Function

Soroban Quest - Auth Store

Understanding README.md

Setting Up Our Stellar Quest Account

Examining the Contract

put Function

Understanding Contract Errors

Persisting Data vs Temporary Data

get Function

get_self Function

Comments on Codes

Examining the Tests

#[ignore] Modifier

Understanding `README.md`

`init` Function

`withdraw` Function

Invoking the `init` Function

`import`ing XLM to Parent Account

Signature `nonce`s

`approve`ing the `AllowanceContract`

`withdraw`ing to the Child Account

`export`ing Lumens Back

Understanding `README.md`

Filling Out `types.rs`

Implementing `Rectangle`

Implementing `Animal`

Implementing `User`

Implementing `RGB`

Implementing `Color`

Implementing `Participant`

Implementing `RoyalCard`

Invoking `c_rect`

Invoking `c_animal`

Invoking `c_user`

Invoking `c_rgb`

Invoking `c_color`

Invoking `c_part`

Invoking `c_card`

`verify`ing Our Implementation

Understanding `README.md`

Understanding `README.md`

Invoking the `submit` Function

Understanding `README.md`

`put` Function

`get` Function

`get_self` Function

`#[ignore]` Modifier

`should_panic` Keyword

Contract Implementation in `test.rs`

`put`ting Data to Our Contract

What Does `xxd` Do?

Using `get_self` to Retrieve Data

Using `get` to Retrieve Data

Understanding `README.md`

`sq login`

`sq pull`

`sq play [index]`

`sq fund [key]`

`sq check [index]`

`soroban deploy`

`soroban invoke`

`cargo`