DEV Community: yuzurush

Soroban Contracts 101 : Liquidity Pool

yuzurush — Mon, 27 Mar 2023 14:04:07 +0000

Hi there! Welcome to last post of my series called "Soroban Contracts 101", where I'll be explaining the basics of Soroban contracts, such as data storage, authentication, custom types, and more. All the code that we're gonna explain throughout this series will mostly come from soroban-contracts-101 github repository.

In this post, i will explain Soroban Liquidity Pool example contract. This contract enables decentralized exchange functionality between two token types by maintaining a constant product invariant. It accomplishes this through the use of a third token type, called pool shares, which represent ownership in the liquidity pool.

The Contract Code

#![no_std]

mod test;
mod token;

use num_integer::Roots;
use soroban_sdk::{contractimpl, Address, Bytes, BytesN, ConversionError, Env, RawVal, TryFromVal};
use token::create_contract;

#[derive(Clone, Copy)]
#[repr(u32)]
pub enum DataKey {
    TokenA = 0,
    TokenB = 1,
    TokenShare = 2,
    TotalShares = 3,
    ReserveA = 4,
    ReserveB = 5,
}

impl TryFromVal<Env, DataKey> for RawVal {
    type Error = ConversionError;

    fn try_from_val(_env: &Env, v: &DataKey) -> Result<Self, Self::Error> {
        Ok((*v as u32).into())
    }
}

fn get_token_a(e: &Env) -> BytesN<32> {
    e.storage().get_unchecked(&DataKey::TokenA).unwrap()
}

fn get_token_b(e: &Env) -> BytesN<32> {
    e.storage().get_unchecked(&DataKey::TokenB).unwrap()
}

fn get_token_share(e: &Env) -> BytesN<32> {
    e.storage().get_unchecked(&DataKey::TokenShare).unwrap()
}

fn get_total_shares(e: &Env) -> i128 {
    e.storage().get_unchecked(&DataKey::TotalShares).unwrap()
}

fn get_reserve_a(e: &Env) -> i128 {
    e.storage().get_unchecked(&DataKey::ReserveA).unwrap()
}

fn get_reserve_b(e: &Env) -> i128 {
    e.storage().get_unchecked(&DataKey::ReserveB).unwrap()
}

fn get_balance(e: &Env, contract_id: BytesN<32>) -> i128 {
    token::Client::new(e, &contract_id).balance(&e.current_contract_address())
}

fn get_balance_a(e: &Env) -> i128 {
    get_balance(e, get_token_a(e))
}

fn get_balance_b(e: &Env) -> i128 {
    get_balance(e, get_token_b(e))
}

fn get_balance_shares(e: &Env) -> i128 {
    get_balance(e, get_token_share(e))
}

fn put_token_a(e: &Env, contract_id: BytesN<32>) {
    e.storage().set(&DataKey::TokenA, &contract_id);
}

fn put_token_b(e: &Env, contract_id: BytesN<32>) {
    e.storage().set(&DataKey::TokenB, &contract_id);
}

fn put_token_share(e: &Env, contract_id: BytesN<32>) {
    e.storage().set(&DataKey::TokenShare, &contract_id);
}

fn put_total_shares(e: &Env, amount: i128) {
    e.storage().set(&DataKey::TotalShares, &amount)
}

fn put_reserve_a(e: &Env, amount: i128) {
    e.storage().set(&DataKey::ReserveA, &amount)
}

fn put_reserve_b(e: &Env, amount: i128) {
    e.storage().set(&DataKey::ReserveB, &amount)
}

fn burn_shares(e: &Env, amount: i128) {
    let total = get_total_shares(e);
    let share_contract_id = get_token_share(e);

    token::Client::new(e, &share_contract_id).burn(&e.current_contract_address(), &amount);
    put_total_shares(e, total - amount);
}

fn mint_shares(e: &Env, to: Address, amount: i128) {
    let total = get_total_shares(e);
    let share_contract_id = get_token_share(e);

    token::Client::new(e, &share_contract_id).mint(&to, &amount);

    put_total_shares(e, total + amount);
}

fn transfer(e: &Env, contract_id: BytesN<32>, to: Address, amount: i128) {
    token::Client::new(e, &contract_id).transfer(&e.current_contract_address(), &to, &amount);
}

fn transfer_a(e: &Env, to: Address, amount: i128) {
    transfer(e, get_token_a(e), to, amount);
}

fn transfer_b(e: &Env, to: Address, amount: i128) {
    transfer(e, get_token_b(e), to, amount);
}

fn get_deposit_amounts(
    desired_a: i128,
    min_a: i128,
    desired_b: i128,
    min_b: i128,
    reserve_a: i128,
    reserve_b: i128,
) -> (i128, i128) {
    if reserve_a == 0 && reserve_b == 0 {
        return (desired_a, desired_b);
    }

    let amount_b = desired_a * reserve_b / reserve_a;
    if amount_b <= desired_b {
        if amount_b < min_b {
            panic!("amount_b less than min")
        }
        (desired_a, amount_b)
    } else {
        let amount_a = desired_b * reserve_a / reserve_b;
        if amount_a > desired_a || desired_a < min_a {
            panic!("amount_a invalid")
        }
        (amount_a, desired_b)
    }
}

pub trait LiquidityPoolTrait {
    // Sets the token contract addresses for this pool
    fn initialize(e: Env, token_wasm_hash: BytesN<32>, token_a: BytesN<32>, token_b: BytesN<32>);

    // Returns the token contract address for the pool share token
    fn share_id(e: Env) -> BytesN<32>;

    // Deposits token_a and token_b. Also mints pool shares for the "to" Identifier. The amount minted
    // is determined based on the difference between the reserves stored by this contract, and
    // the actual balance of token_a and token_b for this contract.
    fn deposit(e: Env, to: Address, desired_a: i128, min_a: i128, desired_b: i128, min_b: i128);

    // If "buy_a" is true, the swap will buy token_a and sell token_b. This is flipped if "buy_a" is false.
    // "out" is the amount being bought, with in_max being a safety to make sure you receive at least that amount.
    // swap will transfer the selling token "to" to this contract, and then the contract will transfer the buying token to "to".
    fn swap(e: Env, to: Address, buy_a: bool, out: i128, in_max: i128);

    // transfers share_amount of pool share tokens to this contract, burns all pools share tokens in this contracts, and sends the
    // corresponding amount of token_a and token_b to "to".
    // Returns amount of both tokens withdrawn
    fn withdraw(e: Env, to: Address, share_amount: i128, min_a: i128, min_b: i128) -> (i128, i128);

    fn get_rsrvs(e: Env) -> (i128, i128);
}

struct LiquidityPool;

#[contractimpl]
impl LiquidityPoolTrait for LiquidityPool {
    fn initialize(e: Env, token_wasm_hash: BytesN<32>, token_a: BytesN<32>, token_b: BytesN<32>) {
        if token_a >= token_b {
            panic!("token_a must be less than token_b");
        }

        let share_contract_id = create_contract(&e, &token_wasm_hash, &token_a, &token_b);
        token::Client::new(&e, &share_contract_id).initialize(
            &e.current_contract_address(),
            &7u32,
            &Bytes::from_slice(&e, b"Pool Share Token"),
            &Bytes::from_slice(&e, b"POOL"),
        );

        put_token_a(&e, token_a);
        put_token_b(&e, token_b);
        put_token_share(&e, share_contract_id.try_into().unwrap());
        put_total_shares(&e, 0);
        put_reserve_a(&e, 0);
        put_reserve_b(&e, 0);
    }

    fn share_id(e: Env) -> BytesN<32> {
        get_token_share(&e)
    }

    fn deposit(e: Env, to: Address, desired_a: i128, min_a: i128, desired_b: i128, min_b: i128) {
        // Depositor needs to authorize the deposit
        to.require_auth();

        let (reserve_a, reserve_b) = (get_reserve_a(&e), get_reserve_b(&e));

        // Calculate deposit amounts
        let amounts = get_deposit_amounts(desired_a, min_a, desired_b, min_b, reserve_a, reserve_b);

        let token_a_client = token::Client::new(&e, &get_token_a(&e));
        let token_b_client = token::Client::new(&e, &get_token_b(&e));

        token_a_client.transfer(&to, &e.current_contract_address(), &amounts.0);
        token_b_client.transfer(&to, &e.current_contract_address(), &amounts.1);

        // Now calculate how many new pool shares to mint
        let (balance_a, balance_b) = (get_balance_a(&e), get_balance_b(&e));
        let total_shares = get_total_shares(&e);

        let zero = 0;
        let new_total_shares = if reserve_a > zero && reserve_b > zero {
            let shares_a = (balance_a * total_shares) / reserve_a;
            let shares_b = (balance_b * total_shares) / reserve_b;
            shares_a.min(shares_b)
        } else {
            (balance_a * balance_b).sqrt()
        };

        mint_shares(&e, to, new_total_shares - total_shares);
        put_reserve_a(&e, balance_a);
        put_reserve_b(&e, balance_b);
    }

    fn swap(e: Env, to: Address, buy_a: bool, out: i128, in_max: i128) {
        to.require_auth();

        let (reserve_a, reserve_b) = (get_reserve_a(&e), get_reserve_b(&e));
        let (reserve_sell, reserve_buy) = if buy_a {
            (reserve_b, reserve_a)
        } else {
            (reserve_a, reserve_b)
        };

        // First calculate how much needs to be sold to buy amount out from the pool
        let n = reserve_sell * out * 1000;
        let d = (reserve_buy - out) * 997;
        let sell_amount = (n / d) + 1;
        if sell_amount > in_max {
            panic!("in amount is over max")
        }

        // Transfer the amount being sold to the contract
        let sell_token = if buy_a {
            get_token_b(&e)
        } else {
            get_token_a(&e)
        };
        let sell_token_client = token::Client::new(&e, &sell_token);
        sell_token_client.transfer(&to, &e.current_contract_address(), &sell_amount);

        let (balance_a, balance_b) = (get_balance_a(&e), get_balance_b(&e));

        // residue_numerator and residue_denominator are the amount that the invariant considers after
        // deducting the fee, scaled up by 1000 to avoid fractions
        let residue_numerator = 997;
        let residue_denominator = 1000;
        let zero = 0;

        let new_invariant_factor = |balance: i128, reserve: i128, out: i128| {
            let delta = balance - reserve - out;
            let adj_delta = if delta > zero {
                residue_numerator * delta
            } else {
                residue_denominator * delta
            };
            residue_denominator * reserve + adj_delta
        };

        let (out_a, out_b) = if buy_a { (out, 0) } else { (0, out) };

        let new_inv_a = new_invariant_factor(balance_a, reserve_a, out_a);
        let new_inv_b = new_invariant_factor(balance_b, reserve_b, out_b);
        let old_inv_a = residue_denominator * reserve_a;
        let old_inv_b = residue_denominator * reserve_b;

        if new_inv_a * new_inv_b < old_inv_a * old_inv_b {
            panic!("constant product invariant does not hold");
        }

        if buy_a {
            transfer_a(&e, to, out_a);
        } else {
            transfer_b(&e, to, out_b);
        }

        put_reserve_a(&e, balance_a - out_a);
        put_reserve_b(&e, balance_b - out_b);
    }

    fn withdraw(e: Env, to: Address, share_amount: i128, min_a: i128, min_b: i128) -> (i128, i128) {
        to.require_auth();

        // First transfer the pool shares that need to be redeemed
        let share_token_client = token::Client::new(&e, &get_token_share(&e));
        share_token_client.transfer(&to, &e.current_contract_address(), &share_amount);

        let (balance_a, balance_b) = (get_balance_a(&e), get_balance_b(&e));
        let balance_shares = get_balance_shares(&e);

        let total_shares = get_total_shares(&e);

        // Now calculate the withdraw amounts
        let out_a = (balance_a * balance_shares) / total_shares;
        let out_b = (balance_b * balance_shares) / total_shares;

        if out_a < min_a || out_b < min_b {
            panic!("min not satisfied");
        }

        burn_shares(&e, balance_shares);
        transfer_a(&e, to.clone(), out_a);
        transfer_b(&e, to, out_b);
        put_reserve_a(&e, balance_a - out_a);
        put_reserve_b(&e, balance_b - out_b);

        (out_a, out_b)
    }

    fn get_rsrvs(e: Env) -> (i128, i128) {
        (get_reserve_a(&e), get_reserve_b(&e))
    }
}

This LiquidityPool contract enables decentralized exchange functionality between two token types (called token_a and token_b) by maintaining a constant product invariant. It accomplishes this through the use of a third token type, called pool shares, which represent ownership in the liquidity pool.

The contract is initialized by calling the initialize() function, passing in the token_a, token_b, and pool share token contract IDs (created using the create_contract() helper function). This function sets up the necessary storage for tracking the pool's reserves and shares, and initializes the pool share token.

Users can deposit token_a and token_b into the pool by calling the deposit() function. This function first ensures the depositor has authorized the transaction, then calculates how much of each token type should be deposited to maintain the constant product invariant (based on the pool's current reserves). It transfers in these amounts, mints new pool shares for the depositor based on the size of their deposit relative to the pool's total reserves, and updates the reserve storage.

Swaps between the two token types can be performed by calling the swap() function, specifying which token type to buy (token_a or token_b) and the amount to buy. The function calculates how much of the selling token needs to be provided to buy the desired amount while maintaining the constant product invariant, ensures this amount is less than or equal to the specified maximum, transfers in the selling token and transfers out the buying token. It also updates the reserve storage to account for the swap.

Finally, the withdraw() function allows pool share owners to redeem their shares for the underlying tokens. It burns the redeemed pool shares, calculates how much of each token type should be withdrawn based on the pool's reserves and the amount of shares redeemed, and transfers out the token amounts (ensuring minimum withdrawal requirements are met). It also updates the reserve storage.

The get_rsrvs() view function can be called to get the current reserve amounts for token_a and token_b. This allows users to check the state of the liquidity pool and inform decisions to deposit, withdraw, or swap.

Contract Usage

Here's the usage flow for the LiquidityPool contract:

Here's the usage flow for the LiquidityPool contract:

The contract owner calls initialize(), passing in the token wasm hash and token_a/token_b/pool share token contract IDs. This sets up the storage and initializes the pool share token.
Users call deposit(), passing in the amount of each token type they want to deposit and the address to mint pool shares to. This brings liquidity into the pool and mints shares to the depositors representing their ownership.
When users want to trade between token_a and token_b, they call swap(), specifying which token they want to buy and the amounts. The pool calculates the exchange rate that maintains the invariant and performs the swap, transferring tokens.
When users want to withdraw their liquidity, they call withdraw(), passing in the amount of pool shares they want to redeem. This burns the shares and transfers the corresponding amounts of token_a and token_b to the user according to the current exchange rate.
At any time, users can call get_rsrvs() to get the current reserve amounts and get an idea of the pool's exchange rates and state. This helps inform decisions to deposit, withdraw, or swap.

Conclusion

Overall, the contract enables decentralized exchange between the two tokens through use of the pool share token to maintain consistent exchange rates and pool shareholder ownership. Users can provide/remove liquidity and perform swaps, and monitor the pool's state to utilize it efficiently.

Soroban Quest : Asset Interop

yuzurush — Sun, 26 Mar 2023 23:20:10 +0000

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 6th quest is called 'Asset Interop'. This quest will provide an example of how asset interoperability works in Soroban.

Joining The Quest

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

sq play 6

And dont forget to fund the quest account right away.

Examining `README.md`

After examining README.md we will need 2 account for this quest, our quest account act as Parent_Account and the other account act as Child_Account. To create account use Stellar Laboratory, and don't forget to fund it. Also the asset that we're going to use is native token(XLM/lumens).

The tasks for the 6th quest is :

Deploy the AllowanceContract using Parent_Account
Invoke the init function of the AllowanceContract
Invoke the incr_allow function of the native token contract to allow your AllowanceContract to make proxy transfers from the Parent_Account to the Child_Account
Invoke the withdraw function of the AllowanceContract using either the Child_Account or Parent_Account

Native Token Contract ID : d93f5c7bb0ebc4a9c8f727c5cebc4e41194d38257e1d0d910356b43bfc528813

The Contract Code

#![no_std]

use soroban_sdk::{contracterror, contractimpl, contracttype, Address, BytesN, Env};


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


#[contracterror]
#[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
#[repr(u32)]
pub enum Error {
    ContractAlreadyInitialized = 1,
    ContractNotInitialized = 2,
    InvalidAuth = 3,
    ChildAlreadyWithdrawn = 4,
    InvalidInvoker = 5,
    InvalidArguments = 6,
}


#[contracttype]
#[derive(Clone)]
pub enum StorageKey {
    Parent,  // Address
    Child,   // Address
    TokenId, // BytesN<32>
    Amount,  // i128
    Step,    // u64
    Latest,  // u64
}


const SECONDS_IN_YEAR: u64 = 365 * 24 * 60 * 60; // = 31,536,000 seconds (fyi)

pub struct AllowanceContract;


pub trait AllowanceTrait {

    fn init(
        e: Env,
        parent: Address,      // the parent account giving the allowance
        child: Address,       // the child account receiving the allowance
        token_id: BytesN<32>, // the id of the token being transferred as an allowance
        amount: i128,         // the total allowance amount given for the year
        step: u64,            // how frequently (in seconds) a withdrawal can be made
    ) -> Result<(), Error>;

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

#[contractimpl]
impl AllowanceTrait for AllowanceContract {

    fn init(
        e: Env,
        parent: Address,
        child: Address,
        token_id: BytesN<32>,
        amount: i128,
        step: u64,
    ) -> Result<(), Error> {

        let token_key = StorageKey::TokenId;
        if e.storage().has(&token_key) {
            return Err(Error::ContractAlreadyInitialized);
        }

        parent.require_auth();


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


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


        e.storage().set(&token_key, &token_id);
        e.storage().set(&StorageKey::Parent, &parent);
        e.storage().set(&StorageKey::Child, &child);
        e.storage().set(&StorageKey::Amount, &amount);
        e.storage().set(&StorageKey::Step, &step);

        let current_ts = e.ledger().timestamp();
        e.storage().set(&StorageKey::Latest, &(current_ts - step));

        Ok(())
    }

    fn withdraw(e: Env, invoker: Address) -> Result<(), Error> {

        let key = StorageKey::TokenId;
        if !e.storage().has(&key) {
            return Err(Error::ContractNotInitialized);
        }

        let child: Address = e.storage().get(&StorageKey::Child).unwrap().unwrap();
        let parent: Address = e.storage().get(&StorageKey::Parent).unwrap().unwrap();

        if invoker != child && invoker != parent {
            return Err(Error::InvalidAuth);
        }

        invoker.require_auth();


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

        let step: u64 = e.storage().get(&StorageKey::Step).unwrap().unwrap();
        let iterations = SECONDS_IN_YEAR / step;
        let amount: i128 = e.storage().get(&StorageKey::Amount).unwrap().unwrap();
        let withdraw_amount = amount / iterations as i128;


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


        client.xfer_from(
            &e.current_contract_address(),
            &parent,
            &child,
            &withdraw_amount,
        );


        let new_latest = latest + step;
        e.storage().set(&StorageKey::Latest, &new_latest);

        Ok(())
    }
}

mod test;

The Allowance contract allows a "parent" account to set up an allowance for a "child" account. The parent specifies:

The token being transferred (token ID)
The total amount allowed for the year
How frequently withdrawals can be made (in seconds)

The child can then withdraw their allowance in increments, as long as it's been at least the specified number of seconds since their last withdrawal.

The contract is located in lib.rs and contains two functions:

init() - Initialized the allowance details
withdraw() - Transfers funds from the parent to the child

The init() function:

Accepts the parent address, child address, token ID, total amount, and withdrawal frequency (step)
Checks that the contract has not already been initialized
Requires the parent address to authorize the initialization
Checks that the step and total amount are valid (not 0 and would result in a non-zero annual amount)
Stores the allowance details by calling env.storage().set()
Returns Ok if successful This function sets up the initial allowance details and ensures the inputs are valid.

The withdraw() function:

Accepts the invoker address (who is calling the function) and contract environment
Checks that the contract has been initialized
Retrieves the parent, child, and withdrawal details from storage
Checks that the invoker is the parent or child
Calculates the withdrawal amount and checks that the last withdrawal was at least step seconds ago
Creates a token contract client and transfers the funds from the parent to the child
Updates the last withdrawal time
Returns Ok if successful

Building The Contract

To build the contract, use the following command:

cd quests/6-asset-interop
cargo build --target wasm32-unknown-unknown --release

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

../target/wasm32-unknown-unknown/release/soroban_asset_interop_contract.wasm

Deploying The Contract as `Parent_Account`

To deploy AllowanceContract contract, use this following command :

soroban contract deploy --wasm /workspace/soroban-quest/quests/4-cross-contract/soroban_asset_interop_contract.wasm

Save the contract ID for later.

Initializing `AllowanceContract`

To invoke init function from AllowanceContract, use this command format:

soroban contract invoke --id <YourContracID> -- init --parent <ParentPublicKey> --child <ChildPublicKey> --token_id 'd93f5c7bb0ebc4a9c8f727c5cebc4e41194d38257e1d0d910356b43bfc528813'  --amount <LumensAmount> --step <WithdrwarRateInSeconds>

With the AllowanceContract already initialized, the Parent_Account needs to authorize the contract to make proxy transfers on its behalf to the Child_Account.

Allowing `AllowanceContract`

To authorize the contract to make proxy transfers, use this command format :

soroban contract invoke --id d93f5c7bb0ebc4a9c8f727c5cebc4e41194d38257e1d0d910356b43bfc528813 -- incr_allow --from <ParentPublicKey> --spender '{"object":{"address":{"contract":"'<AllowanceContractID>'"}}}' --amount <LumensAmount>

Withdrawing the Allowance

To withdraw the Allowance, use this command format :

soroban contract invoke --id <AllowanceContractID> -- withdraw --invoker <ParentorChildPublicKey>

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 6

Congratulations on completing all 6 Soroban quests! You've come a long way, and should feel very accomplished. Keep up the great work!

Soroban Quest : Custom Types

yuzurush — Sun, 26 Mar 2023 18:14:48 +0000

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

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;

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,
}

Animal Type

Animal enum with two variations, Cat and Dog.

pub enum Animal {
    Dog,
    Cat
}

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,
}

RGB Type

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

pub struct RGB(
    pub u32,
    pub u32,
    pub u32
);

Color Type

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

pub enum Color {
    RGB(RGB)
}

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

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
}

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

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

Building the Contract

To build the contract, use the following command:

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

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

../target/wasm32-unknown-unknown/release/soroban_custom_types_contract.wasm

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

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>}'

Invoking c_animal

To invoke c_animal function, use this command format :

soroban contract invoke --id <YourContracID> -- c_animal --_animal <Dog/Cat>

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>"}'

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>]'

Invoking c_color

To invoke c_color function, use this command format :

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

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>"}'

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>"}'

Invoking c_card

To invoke c_card function, use this command format :

soroban contract invoke --id <YourContracID> -- c_card --_card <11/12/13>

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>

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

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

Soroban Quest : Cross Contract

yuzurush — Sun, 26 Mar 2023 15:22:07 +0000

The 4th quest is called "Cross Contract". This quest will give you lesson how cross contract call works in Soroban.

Joining The Quest

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

sq play 4

And dont forget to fund the quest account right away.

Examining `README.md`

After examining README.md, I found that the tasks for the 4th quest is to:

Deploy DataStore contract from the 2nd quest using 4th quest account
Invoke put function from the deployed contract to store some data
Build CrossContractCallcontract, and deploy it
Invoke inv_get function from the deployed CrossContractCall contract to retrieve the data that you previously stored on the deployed DataStore contract

Lets read the contract code to get some more knowledge to do all that.

The Contract Code

#![no_std]
use soroban_sdk::{contractimpl, Address, Bytes, BytesN, Env};

/// We import the compiled binary from our auth store contract in Quest 2,
/// allowing us to use that contract's types and client in this contract.
mod storage_contract {
    // We do this inside a `mod{}` block to avoid collisions between type names
    soroban_sdk::contractimport!(file = "./soroban_auth_store_contract.wasm");
}

/// We define a `trait` which can be used to create shared behavior between
/// types, and can be used to group together signatures for related functions.
pub trait StorageCallTrait {
    // We define in this trait that the `inv_get()` function will accept:
    // - `store_id`: the other contract we are going to invoke
    // - `owner`: the `Address` that was used to `put` data to that contract
    // This funtion will return the data that was stored, in `Bytes`
    fn inv_get(env: Env, store_id: BytesN<32>, owner: Address) -> Bytes;
}

pub struct CrossContractCallContract;

/// The `CrossContractCall` contract implements the trait we defined earlier,
/// and fleshes out what the `inv_get()` function should do with it arguments
/// and how it should create the value to return.
#[contractimpl]
impl StorageCallTrait for CrossContractCallContract {
    /// The `inv_get()` function will create a new client to the auth store
    /// contract, and cross-invoke the `get` function, supplying the `owner`
    /// argument we provide when we invoked `inv_get`.
    fn inv_get(env: Env, store_id: BytesN<32>, owner: Address) -> Bytes {
        let storage_client = storage_contract::Client::new(&env, &store_id);
        storage_client.get(&owner)
    }
}

mod test;

The contract is located in lib.rs and contains one function:

inv_get() - Retrieves data by calling get function on an instance of the auth_store_contract, passing in an owner address

The contract also imports the compiled code of another contract (auth_store_contract) using contractimport. This allows it to use that other contract's types and client within this contract.So in summary, this contract can be used to invoke the get method on an instance of the auth_store_contract, passing in an owner address. It will return the data stored for that owner in the other contract.
This allows contracts to build on and compose other contracts, reusing their functionality. Contracts don't have to be self-contained, but can interact with and use other contracts.

Building The Contract

To build the contract, use the following command:

cd quests/4-cross-contract
cargo build --target wasm32-unknown-unknown --release

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

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

Deploying The Contracts

We need to deploy DataStoreContract contract and CrossContractCall contract, to deploy DataStoreContract contract use this following command :

soroban contract deploy --wasm /workspace/soroban-quest/quests/4-cross-contract/soroban_auth_store_contract.wasm

Save the contract ID for later.
Next is to deploy DataStoreContract contract, usig this command :

soroban contract deploy --wasm /workspace/soroban-quest/target/wasm32-unknown-unknown/release/soroban_cross_contract_call_contract.wasm

Save the contract ID for later.

Storing Data using Deployed `DataStoreContract` Contract

To store data we will invoke put function from the deployed DataStoreContract, using this command format :

soroban contract invoke --id <DeployedDataStoreContractID> -- put --user <QuestPublicKey> --value '<StoredDataInHex>'

Note : To convert string to hex use echo "YourString" | xxd -p

Retrieving Stored Data using deployed `CrossContractCall` Contract

To retrieve the data that we stored earlier, we will invoke inv_get function from the deployed CrossContractCall, using this command format :

soroban contract invoke --id <DeployedCrossContractCallContractID> -- inv_get --store_id '<DeployedDataStoreContractID>' --owner <QuestPublicKey>

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 4

Congratulations! You have already completed 4 out of 6 quests. You have 2 more to go.

Soroban Quest : Reverse Engineer

yuzurush — Sat, 25 Mar 2023 21:10:55 +0000

The third quest is called "Reverse Engineer". This quite quest different from the two previous quest, i will explain more in examining README.md section below.

Joining The Quest

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

sq play 3

And dont forget to fund the quest account right away.

Examining `README.md`

After examining README.md, I found that the tasks for the 3rd quest is to:

Do reverse engineer to find a contractID of ReverseEngineerContract, that already deployed by this specific account GAC7HE4PQWI7H34JQN6QLQ7Y7NTAUZDWJZ4SJ6GXVC4K2DN7N65K5NLI
Invoke submit function from that contractID

Finding Contract ID

For finding contract ID, we will user Stellar Laboratory and soroban lab xdr dec command. Here's how :

Open Stellar Laboratory
Select Explore Endpoints -> Operations -> Operations for Account
Fill "Account ID" with GAC7HE4PQWI7H34JQN6QLQ7Y7NTAUZDWJZ4SJ6GXVC4K2DN7N65K5NLI
Submit
Scroll down find footprint xdr below HostFunctionTypeHostFunctionTypeCreateContract and copy it
Decode the footprint xdr using this command to extract the contractID:

soroban lab xdr dec \
--type LedgerFootprint \
--xdr AAAAAQAAAAcvYZs/BqiEyZduBaT0n+3vak84eWOTyBL5cZnR7S0VdQAAAAEAAAAGnPAdb0BshbRF3Yvo6RrkHJEg0GcybTF5Rpt/1jyB7dQAAAADAAAAAw== \
--output json | grep contract_id

Result :

"contract_id": "9cf01d6f406c85b445dd8be8e91ae41c9120d067326d3179469b7fd63c81edd4",

We already got our contract id,next we will examine the contract code.

The Contract Code

pub struct ReverseEngineerContract;

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

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

The contract is located in lib.rs and contains one functions:

It defines a struct ReverseEngineerContract which represents the contract
It defines a constant SECRET which is a Symbol with the value dancinRaph
It implements a contractimpl for ReverseEngineerContract
This contract has one function submit which takes an Env (the contract environment) and a Symbol secret
The function returns true if the passed in secret matches the SECRET constant, and false otherwise

So in summary, submit function checks if a passed in secret matches a hardcoded constant. So we must invoke submit function with dancinRaph as value for secret

Invoking `submit` Function

To invoke submit function use this command :

soroban contract invoke --id 9cf01d6f406c85b445dd8be8e91ae41c9120d067326d3179469b7fd63c81edd4 -- submit --secret dancinRaph

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 3

Congratulations! You have already completed 3 out of 6 quests. You have 3 more to go.

Soroban Quest : Auth Store

yuzurush — Sat, 25 Mar 2023 18:13:15 +0000

We already completed the first quest in the previous post. The second quest is called "Auth Store". This quest will give you lesson how to store and retrieve data from contract storage using simple authentication.

Joining The Quest

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

sq play 2

And dont forget to fund the quest account right away.

Examining `README.md`

After examining README.md, I found that the tasks for the 2nd quest is to:

Build auth data store contract
Deploy auth data store contract to the futurenet
Invoke put function from the deployed contract to store some data
Invoke get function from the deployed contract to retrieve that data

Lets read the contract code to get some more knowledge to do all that.

The Contract Code

#![no_std]
use error::ContractError;
use soroban_sdk::{bytes, contractimpl, panic_with_error, Address, Bytes, Env};

pub struct DataStoreContract;

#[contractimpl]
impl DataStoreContract {

    pub fn put(env: Env, user: Address, value: Bytes) -> Result<(), ContractError> {

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

that was passed,

        env.storage().set(&user, &value);

        Ok(()) // return ok if function call succeeded
    }

    pub fn get(env: Env, owner: Address) -> Bytes {
        env.storage()
            .get(&owner)
            .unwrap_or_else(|| Ok(bytes!(&env))) // This uses `unwrap_or_else` and closure which only evaluates Bytes(0) when necessary.
            .unwrap()
    }
}

mod error;
mod test;

The contract is located in lib.rs and contains two functions:

put() - Stores data associated with an address if the address has authorized the write
get() - Retrieves data associated with an address

The contract also includes an error module (error.rs) defining the ContractError type for error handling. The contract uses panic_with_error!() to panic with a custom ContractError if invalid input is provided to put(). This demonstrates panicking with a custom error type to provide more detailed error information.

`put()` function

Accepts an address (user), data (value - in hex)
Requires the address to have authorized the write by calling user.require_auth()
Checks that the data is at least 11 bytes long and panics if not
Stores the data associated with the address by calling env.storage().set()
Returns Ok if successful

This will store data to the storage based on specific address.

`get()` Function

Accepts an address (owner) and contract environment (env) as parameters
Retrieves the data associated with the address by calling env.storage().get()
Returns the data or bytes of length 0 if no data is associated with the address

This allows retrieval of stored data associated with an address.

Building the Contract

To build the contract, use the following command:

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

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

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

Deploying the Contract

To deploy the contract, use the following command:

soroban contract deploy --wasm /workspace/soroban-quest/target/wasm32-unknown-unknown/release/soroban_auth_store_contract.wasm

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

Invoking the Contract

First we need to invoke put function to store data using this command format :

soroban contract invoke --id <AuthContractID> --fn put -- --user <QuestPublicKey> --value '<StoredDataInHex>'

Note : To convert string to hex use echo "YourString" | xxd -p
Next we will retrieve the stored data by invoking get function using this command :

soroban contract invoke --id <AuthContractID> -- get --owner <QuestPublicKey>

By running that command you should get your stored data(in hex).

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 2

Congratulations! You have already completed 2 out of 6 quests. You have 4 more to go.

Soroban Quest : Hello World

yuzurush — Sat, 25 Mar 2023 17:30:37 +0000

Let's jump into the first quest, "Hello World". In every quest there's always a README.md file that contains guidance for you to complete each quest, so your first thing to do in every quest is to read it.

Examining `README.md`

README.md file contains steps to play the quest(authenticate with discord, pull in new quests, retrieve your quest account, and more) and also how to solve the quest.

In this first quest we must build hello world contract, deploy it to the futurenet, and invoke the hello function from the contract, all that using our quest account.

Joining The Quest

Before starting a quest, you must take a few preparatory steps:

Authenticate with Discord: Run sq user to authenticate with your Discord account. If unsuccessful, run sq login to sign in and complete KYC/tax submission if required.
Pull in New Quests: When a quest is released, run sq pull in the workspace root to download the new quest files. You can also update quests manually using git.
Retrieve your Quest Account: Run sq play <quest number> to retrieve the account keypair for a quest. Save the account details as you'll need them to complete the quest. In this quest we will use sq play 1. You will get a quest account(public key and secret key) and you will be asked to fund that account or not, select "Yes please!" to fund your quest account.

Examining The Contract and Test Code

The next step is to examining the contract and test code, this is a crucial step in every quest, this will help you complete the quest and learn soroban smart contract along the way.

The Contract Code

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

pub struct HelloContract;

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

mod test;

The contract code is located in lib.rs and has the following structure:

The #![no_std] indicates that this is a no_std contract, meaning it does not use the Rust standard library, it will makes the contract lightweight.
The use soroban_sdk imports bring in types and functions from the Soroban SDK that are needed for the contract.
The HelloContract struct defines the contract.
The #[contractimpl] attribute denotes that the following impl block contains the contract logic.
The hello() function is the main contract function. It accepts a name input and returns a greeting.
A mod test; line includes unit tests for the contract.

The hello() function does the following:

Accepts a name input (to)
Creates a vector (vec) containing:

A reference to the contract environment (env) - supplies some additional functionality, used mostly in every function for soroban smart contract

The "Hello" greeting string (symbol!("Hello"))

The name input (to) - to value is string less than 10 char Returns the vector, effectively returning a greeting containing the input name. For example, calling hello() with a name of "World" would return: ["Hello", "World"]

The Test Code

#![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 located in test.rs and does the following:

Sets up a Soroban environment (Env)
Registers the HelloContract in the environment
Creates a client for the deployed contract
Calls the hello() function on the client, passing in "Dev" as to value
Asserts that the response matches the expected greeting containing "Dev"

If the test passes, we can be confident that the contract logic is working as expected. If the test fails, it indicates a bug in the contract that should be fixed before deploying to production.

To test the contract, use the following command :

cargo test

Building the Contract

To build the contract, use the following command:

cd quests/1-hello-world
cargo build --target wasm32-unknown-unknown --release

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

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

Deploying the Contract

To deploy the contract, use the following command:

soroban contract deploy --wasm /workspace/soroban-quest/target/wasm32-unknown-unknown/release/soroban_hello_world_contract.wasm

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

Invoking the Contract

To invoke the contract, use this command format :

soroban contract invoke --id <YourHelloWorldContractID> -- hello --to <Any String Shorther than 10 char>

You will get result :

["Hello", "<to value supplied>"]

Checking the Quest

This is the last thing you need to do. Check and claim your badge reward. To check use the following command :

sq check 1

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

Soroban Contracts 101: Timelock

yuzurush — Wed, 22 Mar 2023 16:52:06 +0000

Hi there! Welcome to my fifteenth post of my series called "Soroban Contracts 101", where I'll be explaining the basics of Soroban contracts, such as data storage, authentication, custom types, and more. All the code that we're gonna explain throughout this series will mostly come from soroban-contracts-101 github repository.

In this post, i will explain Soroban Timelock example contract. This contract enables users to make deposits of a specified token amount and allows other individuals to claim it either before or after a designated time point.

The Contract Code

#![no_std]

use soroban_sdk::{contractimpl, contracttype, Address, BytesN, Env, Vec};

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

#[derive(Clone)]
#[contracttype]
pub enum DataKey {
    Init,
    Balance,
}

#[derive(Clone)]
#[contracttype]
pub enum TimeBoundKind {
    Before,
    After,
}

#[derive(Clone)]
#[contracttype]
pub struct TimeBound {
    pub kind: TimeBoundKind,
    pub timestamp: u64,
}

#[derive(Clone)]
#[contracttype]
pub struct ClaimableBalance {
    pub token: BytesN<32>,
    pub amount: i128,
    pub claimants: Vec<Address>,
    pub time_bound: TimeBound,
}

pub struct ClaimableBalanceContract;

// The 'timelock' part: check that provided timestamp is before/after
// the current ledger timestamp.
fn check_time_bound(env: &Env, time_bound: &TimeBound) -> bool {
    let ledger_timestamp = env.ledger().timestamp();

    match time_bound.kind {
        TimeBoundKind::Before => ledger_timestamp <= time_bound.timestamp,
        TimeBoundKind::After => ledger_timestamp >= time_bound.timestamp,
    }
}

#[contractimpl]
impl ClaimableBalanceContract {
    pub fn deposit(
        env: Env,
        from: Address,
        token: BytesN<32>,
        amount: i128,
        claimants: Vec<Address>,
        time_bound: TimeBound,
    ) {
        if claimants.len() > 10 {
            panic!("too many claimants");
        }
        if is_initialized(&env) {
            panic!("contract has been already initialized");
        }
        // Make sure `from` address authorized the deposit call with all the
        // arguments.
        from.require_auth();

        // Transfer token from `from` to this contract address.
        token::Client::new(&env, &token).transfer(&from, &env.current_contract_address(), &amount);
        // Store all the necessary info to allow one of the claimants to claim it.
        env.storage().set(
            &DataKey::Balance,
            &ClaimableBalance {
                token,
                amount,
                time_bound,
                claimants,
            },
        );
        // Mark contract as initialized to prevent double-usage.
        // Note, that this is just one way to approach initialization - it may
        // be viable to allow one contract to manage several claimable balances.
        env.storage().set(&DataKey::Init, &());
    }

    pub fn claim(env: Env, claimant: Address) {
        // Make sure claimant has authorized this call, which ensures their
        // identity.
        claimant.require_auth();

        let claimable_balance: ClaimableBalance =
            env.storage().get_unchecked(&DataKey::Balance).unwrap();

        if !check_time_bound(&env, &claimable_balance.time_bound) {
            panic!("time predicate is not fulfilled");
        }

        let claimants = &claimable_balance.claimants;
        if !claimants.contains(&claimant) {
            panic!("claimant is not allowed to claim this balance");
        }

        // Transfer the stored amount of token to claimant after passing
        // all the checks.
        token::Client::new(&env, &claimable_balance.token).transfer(
            &env.current_contract_address(),
            &claimant,
            &claimable_balance.amount,
        );
        // Remove the balance entry to prevent any further claims.
        env.storage().remove(&DataKey::Balance);
    }
}

fn is_initialized(env: &Env) -> bool {
    env.storage().has(&DataKey::Init)
}

mod test;

This contract implements a claimable balance contract, which allows depositing tokens into the contract under certain conditions (time bounds and a list of claimants), and then allowing the claimants to claim the tokens if the time conditions are met.

Here's a brief explanation of the ClaimableBalanceContract contract code:

Defines a ClaimableBalance struct to represent the claimable balance details (token, amount, time bound, list of claimants)
Defines a TimeBound enum and struct to represent time bound options (before/after a timestamp)
It implements a ClaimableBalanceContract with:

deposit - Allows depositing tokens under given conditions. Checks that the number of claimants is within limits, checks that the contract is not already initialized, requires the depositor to authenticate, transfers the tokens to the contract, and stores the claimable balance details.
claim - Allows a claimant to claim the tokens if the time bound is fulfilled. Requires authentication, checks the time bound, checks that the claimant is in the claimants list, and transfers the tokens to the claimant.

is_initialized - A helper function to check if the contract is initialized (has a non-empty Init storage entry)

Contract Usage

Here's the usage flow for the ClaimableBalanceContract contract:

The depositor calls deposit to initialize a claimable balance, providing the token address, amount, list of claimants, and time bound conditions.
Once the time bound conditions are met, one of the claimants calls claim to claim the tokens.

Conclusion

Overall, the contract allows depositing tokens under time-based conditions and a list of claimants, and then when claimants claim the deposit,the contract will distributing the tokens to the claimants once the time conditions are met. This can be useful for conditional or time-locked distributions of funds.Stay tuned for more post in this "Soroban Contracts 101" Series where we will dive deeper into Soroban Contracts and their functionalities.

Soroban Contracts 101: Single Offer Sale

yuzurush — Wed, 22 Mar 2023 16:21:49 +0000

Hi there! Welcome to my fourteenth post of my series called "Soroban Contracts 101", where I'll be explaining the basics of Soroban contracts, such as data storage, authentication, custom types, and more. All the code that we're gonna explain throughout this series will mostly come from soroban-contracts-101 github repository.

In this post, i will explain about Soroban Single Offer Sale example contract. This contract provided a feature to the seller, enabling them to establish an offer for selling token A to numerous buyers in exchange for token B.

The Contract Code


#![no_std]

use soroban_sdk::{contractimpl, contracttype, unwrap::UnwrapOptimized, Address, BytesN, Env};

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

#[derive(Clone)]
#[contracttype]
pub enum DataKey {
    Offer,
}

// Represents an offer managed by the SingleOffer contract.
// If a seller wants to sell 1000 XLM for 100 USDC the `sell_price` would be 1000
// and `buy_price` would be 100 (or 100 and 10, or any other pair of integers
// in 10:1 ratio).
#[derive(Clone)]
#[contracttype]
pub struct Offer {
    // Owner of this offer. Sells sell_token to get buy_token.
    pub seller: Address,
    pub sell_token: BytesN<32>,
    pub buy_token: BytesN<32>,
    // Seller-defined price of the sell token in arbitrary units.
    pub sell_price: u32,
    // Seller-defined price of the buy token in arbitrary units.
    pub buy_price: u32,
}

pub struct SingleOffer;

/*
How this contract should be used:
1. Call `create` once to create the offer and register its seller.
2. Seller may transfer arbitrary amounts of the `sell_token` for sale to the
   contract address for trading. They may also update the offer price.
3. Buyers may call `trade` to trade with the offer. The contract will
   immediately perform the trade and send the respective amounts of `buy_token`
   and `sell_token` to the seller and buyer respectively.
4. Seller may call `withdraw` to claim any remaining `sell_token` balance.
*/
#[contractimpl]
impl SingleOffer {
    // Creates the offer for seller for the given token pair and initial price.
    // See comment above the `Offer` struct for information on pricing.
    pub fn create(
        e: Env,
        seller: Address,
        sell_token: BytesN<32>,
        buy_token: BytesN<32>,
        sell_price: u32,
        buy_price: u32,
    ) {
        if e.storage().has(&DataKey::Offer) {
            panic!("offer is already created");
        }
        if buy_price == 0 || sell_price == 0 {
            panic!("zero price is not allowed");
        }
        // Authorize the `create` call by seller to verify their identity.
        seller.require_auth();
        write_offer(
            &e,
            &Offer {
                seller,
                sell_token,
                buy_token,
                sell_price,
                buy_price,
            },
        );
    }

    // Trades `buy_token_amount` of buy_token from buyer for `sell_token` amount
    // defined by the price.
    // `min_sell_amount` defines a lower bound on the price that the buyer would
    // accept.
    // Buyer needs to authorize the `trade` call and internal `transfer` call to
    // the contract address.
    pub fn trade(e: Env, buyer: Address, buy_token_amount: i128, min_sell_token_amount: i128) {
        // Buyer needs to authorize the trade.
        buyer.require_auth();

        // Load the offer and prepare the token clients to do the trade.
        let offer = load_offer(&e);
        let sell_token_client = token::Client::new(&e, &offer.sell_token);
        let buy_token_client = token::Client::new(&e, &offer.buy_token);

        // Compute the amount of token that buyer needs to receive.
        let sell_token_amount = buy_token_amount
            .checked_mul(offer.sell_price as i128)
            .unwrap_optimized()
            / offer.buy_price as i128;

        if sell_token_amount < min_sell_token_amount {
            panic!("price is too low");
        }

        let contract = e.current_contract_address();

        // Perform the trade in 3 `transfer` steps.
        // Note, that we don't need to verify any balances - the contract would
        // just trap and roll back in case if any of the transfers fails for
        // any reason, including insufficient balance.

        // Transfer the `buy_token` from buyer to this contract.
        // This `transfer` call should be authorized by buyer.
        // This could as well be a direct transfer to the seller, but sending to
        // the contract address allows building more transparent signature
        // payload where the buyer doesn't need to worry about sending token to
        // some 'unknown' third party.
        buy_token_client.transfer(&buyer, &contract, &buy_token_amount);
        // Transfer the `sell_token` from contract to buyer.
        sell_token_client.transfer(&contract, &buyer, &sell_token_amount);
        // Transfer the `buy_token` to the seller immediately.
        buy_token_client.transfer(&contract, &offer.seller, &buy_token_amount);
    }

    // Sends amount of token from this contract to the seller.
    // This is intentionally flexible so that the seller can withdraw any
    // outstanding balance of the contract (in case if they mistakenly
    // transferred wrong token to it).
    // Must be authorized by seller.
    pub fn withdraw(e: Env, token: BytesN<32>, amount: i128) {
        let offer = load_offer(&e);
        offer.seller.require_auth();
        token::Client::new(&e, &token).transfer(
            &e.current_contract_address(),
            &offer.seller,
            &amount,
        );
    }

    // Updates the price.
    // Must be authorized by seller.
    pub fn updt_price(e: Env, sell_price: u32, buy_price: u32) {
        if buy_price == 0 || sell_price == 0 {
            panic!("zero price is not allowed");
        }
        let mut offer = load_offer(&e);
        offer.seller.require_auth();
        offer.sell_price = sell_price;
        offer.buy_price = buy_price;
        write_offer(&e, &offer);
    }

    // Returns the current state of the offer.
    pub fn get_offer(e: Env) -> Offer {
        load_offer(&e)
    }
}

fn load_offer(e: &Env) -> Offer {
    e.storage().get_unchecked(&DataKey::Offer).unwrap()
}

fn write_offer(e: &Env, offer: &Offer) {
    e.storage().set(&DataKey::Offer, offer);
}

mod test;

Here's a brief explanation of the SingleOffer contract code:

Imports token functionality from soroban_token_spec.wasm using soroban_sdk::contractimport
Defines a DataKey enum with an Offer variant to represent the single offer storage key
Defines an Offer struct to hold the details of the offer: seller address, sell/buy token addresses, and sell/buy prices
Defines a SingleOffer unit It implements a contractimpl for SingleOffer with the following functions:

create - Creates an initial offer. Requires seller authentication, checks that non-zero prices are used, and stores the offer.
trade - Allows trading at the current offer price. Requires buyer authentication, loads the offer, creates token clients, computes the amount to trade, checks that the amount is acceptable, and transfers tokens.
withdraw - Allows the seller to withdraw tokens from the contract. Requires authentication and transfers tokens.
updt_price - Allows the seller to update prices. Requires authentication, checks that non-zero prices are used, loads the offer, updates the prices, and stores the updated offer.
get_offer - Simply loads and returns the current offer.

Defines load_offer function, that loads the single offer from storage using the DataKey::Offer key, and unwraps the Result to panic if the offer is not found. It's called from various functions in the contract to load the current offer details.
Defines wrote_offer funtion, It stores the given offer in storage under theDataKey::Offerkey. It's called from thecreatefunction to initialize the offer, and theupdt_price` function to update the offer.

Contract Usage

Here's the usage for the SingleOffer contract:

The seller calls create function to initialize the offer with the token pair and initial prices.
The seller transfers sell tokens to the contract to fund the offer using sell_token function.
Buyers call trade to buy sell tokens at the current price. The contract will handle transfers buy/sell tokens between the buyer, contract, and seller.
The seller can call updt_price to update the offer price.
The seller calls withdraw funtion to withdraw any remaining sell tokens from the contract.

Conclusion

Overall, the contract shows capability of Soroban contract to allows the seller to create a single token offer, fund it with sell tokens, update the price, and withdraw remaining tokens, while allowing buyers to trade at the current price. Stay tuned for more post in this "Soroban Contracts 101" Series where we will dive deeper into Soroban Contracts and their functionalities.

Soroban Contracts 101: Batched Atomic Swaps

yuzurush — Tue, 21 Mar 2023 18:01:16 +0000

Hi there! Welcome to my thirteenth post of my series called "Soroban Contracts 101", where I'll be explaining the basics of Soroban contracts, such as data storage, authentication, custom types, and more. All the code that we're gonna explain throughout this series will mostly come from soroban-contracts-101 github repository.

In my previous post, i already explained about Atomic Swap contract, and in this post i will be explaining batched atomic swaps contract that matches and batches multiple swaps, whereas the atomic swap contract only handles a single swap.

The Contract

#![no_std]

use soroban_sdk::{contractimpl, contracttype, Address, BytesN, Env, Vec};

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

#[derive(Clone)]
#[contracttype]
pub struct SwapSpec {
    pub address: Address,
    pub amount: i128,
    pub min_recv: i128,
}

pub struct AtomicMultiSwapContract;

#[contractimpl]
impl AtomicMultiSwapContract {
    // Swap token A for token B atomically between the parties that want to
    // swap A->B and parties that want to swap B->A.
    // All the parties should have authorized the `swap` via `swap_contract`,
    // but they don't need to authorize `multi_swap` itself.
    pub fn multi_swap(
        env: Env,
        swap_contract: BytesN<32>,
        token_a: BytesN<32>,
        token_b: BytesN<32>,
        swaps_a: Vec<SwapSpec>,
        swaps_b: Vec<SwapSpec>,
    ) {
        let mut swaps_b = swaps_b;
        let swap_client = atomic_swap::Client::new(&env, &swap_contract);
        for acc_a in swaps_a.iter() {
            let acc_a = acc_a.unwrap();
            for i in 0..swaps_b.len() {
                let acc_b = swaps_b.get(i).unwrap().unwrap();

                if acc_a.amount >= acc_b.min_recv && acc_a.min_recv <= acc_b.amount {
                    // As this is a simple 'batching' contract, there is no need
                    // for all swaps to succeed, hence we handle the failures
                    // gracefully to try and clear as many swaps as possible.
                    if swap_client
                        .try_swap(
                            &acc_a.address,
                            &acc_b.address,
                            &token_a,
                            &token_b,
                            &acc_a.amount,
                            &acc_a.min_recv,
                            &acc_b.amount,
                            &acc_b.min_recv,
                        )
                        .is_ok()
                    {
                        swaps_b.remove(i);
                        break;
                    }
                }
            }
        }
    }
}

mod test;

Here's an explanation of the AtomicMultiSwapContract contract:

It imports the atomic swap contract
It defines a SwapSpec struct to represent a single swap specification (address, amount to send, minimum to receive)
It defines an AtomicMultiSwapContract struct
It implements a contractimpl for AtomicMultiSwapContract with a multi_swap function
The multi_swap function:

Loops through swaps that want to send token A and swaps that want to send token B

Matches compatible swaps (where the send amount meets the minimum receive amount for the other party)

Calls the atomic swap contract's try_swap function to attempt the swap

Removes matched swaps from the list

The key point of this AtomicMultiSwapContract contract are:

This contract matches and batches multiple swaps
Parties only need to authorize the atomic swap contract, and don't need additional authorizations for the multi-swap
The AtomicMultiSwapContract contract calls the atomic swap contract to attempt individual swaps
The AtomicMultiSwapContract contract gracefully handles swap attempt failures and continues trying other compatible swaps

So in summary, the Batched Atomic Swap contract builds on the atomic swap contract to enable batching of multiple swaps in a single transaction.

Conclusion

The Batched Atomic Swap contract demonstrates how to batch multiple atomic swaps into a single transaction. By leveraging the atomic swap contract and multiparty authorizations, it's able to match compatible swaps and attempt them via the underlying atomic swap contract. Even if some swap attempts fail, it will continue trying other compatible swaps. The contract shows how authorized calls can be batched to increase efficiency, while still maintaining atomicity and authorization guarantees. Overall, the atomic multi-swap contract provides a useful building block for more complex exchange workflows on Soroban. Stay tuned for more post in this "Soroban Contracts 101" Series where we will dive deeper into Soroban Contracts and their functionalities.

Soroban Contracts 101: Atomic Swaps

yuzurush — Tue, 21 Mar 2023 16:39:52 +0000

Hi there! Welcome to my twelfth post of my series called "Soroban Contracts 101", where I'll be explaining the basics of Soroban contracts, such as data storage, authentication, custom types, and more. All the code that we're gonna explain throughout this series will mostly come from soroban-contracts-101 github repository.

In this twelfth post of the series, I'll be explaining an Atomic Swap example contract. Atomic swaps allow two parties to exchange assets without relying on a third party. For now Soroban-CLI didnt support multi soroban ops per tx and multi-auth yet, so this code cant be build and running yet, but this will give you an insight how atomic swap contract works.

The Contract Code

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

pub struct AtomicSwapContract;

#[contractimpl]
impl AtomicSwapContract {
    // Swap token A for token B atomically. Settle for the minimum requested price
    // for each party (this is an arbitrary choice to demonstrate the usage of
    // allowance; full amounts could be swapped as well).
    pub fn swap(
        env: Env,
        a: Address,
        b: Address,
        token_a: BytesN<32>,
        token_b: BytesN<32>,
        amount_a: i128,
        min_b_for_a: i128,
        amount_b: i128,
        min_a_for_b: i128,
    ) {
        // Verify preconditions on the minimum price for both parties.
        if amount_b < min_b_for_a {
            panic!("not enough token B for token A");
        }
        if amount_a < min_a_for_b {
            panic!("not enough token A for token B");
        }
        // Require authorization for a subset of arguments specific to a party.
        // Notice, that arguments are symmetric - there is no difference between
        // `a` and `b` in the call and hence their signatures can be used
        // either for `a` or for `b` role.
        a.require_auth_for_args(
            (token_a.clone(), token_b.clone(), amount_a, min_b_for_a).into_val(&env),
        );
        b.require_auth_for_args(
            (token_b.clone(), token_a.clone(), amount_b, min_a_for_b).into_val(&env),
        );

        // Perform the swap via two token transfers.
        move_token(&env, token_a, &a, &b, amount_a, min_a_for_b);
        move_token(&env, token_b, &b, &a, amount_b, min_b_for_a);
    }
}

fn move_token(
    env: &Env,
    token: BytesN<32>,
    from: &Address,
    to: &Address,
    approve_amount: i128,
    xfer_amount: i128,
) {
    let token = token::Client::new(&env, &token);
    let contract_address = env.current_contract_address();
    // This call needs to be authorized by `from` address. Since it increases
    // the allowance on behalf of the contract, `from` doesn't need to know `to`
    // at the signature time.
    token.increase_allowance(&from, &contract_address, &approve_amount);
    token.transfer_from(&contract_address, &from, to, &xfer_amount);
}

Here's an explanation of the atomic swap contract code:

It imports the Soroban token contract as token
It defines an AtomicSwapContract struct
It implements a contractimpl for AtomicSwapContract with a swap function
The swap function:

Verifies that the minimum amounts can be met

Gets authorizations from both parties for their part of the swap

Calls move_token twice to perform the atomic swap via token transfers

The move_token function:

Creates a token client for the token being moved

Gets the contract address

Increases the allowance for the sending address

Performs a transfer from the contract to the recipient

The contract requires two parties (addresses a and b) to authorize a swap of two token types (token_A and token_B). Each party specifies:

The token they want to sell (either token A or token B)
The amount of the token they want to sell
The minimum amount of the other token they want to receive

The swap will only proceed if both parties' minimums can be met. The swap is performed atomically via two token transfers (token A to B then token B to A), with each party only authorizing one transfer (either the sending or receiving transfer).

The swap authorization uses Soroban's require_auth_for_args function, which requires authorization for a subset of the function arguments:

a authorizes (token A, token B, amount of token A, minimum token B)
b authorizes (token B, token A, amount of token B, minimum token A)

Note that the arguments are symmetric - a and b are interchangeable. This enables either party to be labeled as a or b, as long as the arguments are adjusted accordingly.
The authorizations ensure that the parties:

Cannot perform swaps unilaterally (without the other party)
Cannot reuse authorizations for swaps with different parameters

The swap itself is implemented via two token transfers (token A to B then token B to A) in the move_token helper function.
For each transfer:

The allowance for the sending contract is increased by the send amount
A transfer is performed from the sending contract to the recipient

This means the sending party only needs to authorize the allowance increase (which specifies the sending contract, not recipient) and not the actual transfer. The sending contract (this atomic swap contract) then performs the transfer to the recipient on behalf of the sender.

Conclusion

So in summary, the atomic swap contract demonstrates how to:

Require multi-party authorization for a swap/transaction
Use require_auth_for_args to get authorizations for subsets of arguments
Perform an atomic token swap via allowances and transfers

We will see more in the future when Soroban-CLI support multi soroban ops per tx and multi-auth. This contract code example showed There's still more room for Soroban as an smart contract platform to improve. Stay tuned for more post in this "Soroban Contracts 101" Series where we will dive deeper into Soroban Contracts and their functionalities.

Soroban Contracts 101 : Allocator

yuzurush — Tue, 21 Mar 2023 15:53:00 +0000

Hi there! Welcome to my eleventh post of my series called "Soroban Contracts 101", where I'll be explaining the basics of Soroban contracts, such as data storage, authentication, custom types, and more. All the code that we're gonna explain throughout this series will mostly come from soroban-contracts-101 github repository.

In this eleventh post of the series, we will explore the Allocator feature in Soroban Contracts, which enables developers to emulate heap memory allocation in a WASM smart contract. We will walk through a simple example to demonstrate how to utilize the allocator provided by the soroban-sdk crate.

Dependencies

To make use of the allocator feature, you need to include the alloc feature in the soroban-sdk dependency in your Cargo.toml file. Add the following lines:

[dependencies]
soroban-sdk = { workspace = true, features = ["alloc"] }

[dev_dependencies]
soroban-sdk = { workspace = true, features = ["testutils", "alloc"] }

Allocator Example: Summing a Vector

In this example, we will write a contract that allocates a temporary vector holding values from 0 to a given count, then computes and returns their sum. The code for the contract is as follows:

#![no_std]
use soroban_sdk::{contractimpl, Env};

extern crate alloc;

pub struct AllocContract;

#[contractimpl]
impl AllocContract {
    /// Allocates a temporary vector holding values (0..count), then computes and returns their sum.
    pub fn sum(_env: Env, count: u32) -> u32 {
        let mut v1 = alloc::vec![];
        (0..count).for_each(|i| v1.push(i));

        let mut sum = 0;
        for i in v1 {
            sum += i;
        }

        sum
    }
}

This contract code implements an AllocContract. The key points of the contract :

Imports the alloc crate, which is required to support allocation under no_std.
Creates a contiguous growable array v1 with contents allocated on the heap memory(WASM linear memory).
Defines a sum function that: > - Takes an Env and a count > - Creates a vector of count elements (0..count) using alloc > - Pushes values from 0 to count into the vector v1 > - Sums the elements > - Returns the sum

Conclusion

This simple AllocContract code illustrates how to use the allocator feature in a Soroban Contract. With the allocator, you can allocated data dynamically at runtime, which means that the contract can adjust its memory requirements as needed, making it more flexible and adaptable. It is important to note that allocating data in heap memory requires the developer to explicitly manage memory and ensure that it is properly allocated and deallocated when no longer needed. Improper management of heap memory can lead to memory leaks, which can cause the contract to run out of memory, Gas costs can increase over time as more and more memory is leaked, making the contract more expensive to interact with, even panicked/fail.

Stay tuned for more post in this "Soroban Contracts 101" Series where we will dive deeper into Soroban Contracts and their functionalities.

DEV Community: yuzurush

Soroban Contracts 101 : Liquidity Pool

The Contract Code

Contract Usage

Conclusion

Soroban Quest : Asset Interop

Joining The Quest

Examining README.md

The Contract Code

Building The Contract

Deploying The Contract as Parent_Account

Initializing AllowanceContract

Allowing AllowanceContract

Withdrawing the Allowance

Checking the Quest

Soroban Quest : Custom Types

Joining The Quest

Examining README.md

The Contract Code

Defining Custom Types

Testing the Contract

Building the Contract

Deploying the Contract

Invoking the Contract Functions

Invoke verify Function From Specific ContractID

Checking the Quest

Soroban Quest : Cross Contract

Joining The Quest

Examining README.md

The Contract Code

Building The Contract

Deploying The Contracts

Storing Data using Deployed DataStoreContract Contract

Retrieving Stored Data using deployed CrossContractCall Contract

Checking the Quest

Soroban Quest : Reverse Engineer

Joining The Quest

Examining README.md

Finding Contract ID

The Contract Code

Invoking submit Function

Checking the Quest

Soroban Quest : Auth Store

Joining The Quest

Examining README.md

The Contract Code

put() function

get() Function

Building the Contract

Deploying the Contract

Invoking the Contract

Checking the Quest

Soroban Quest : Hello World

Examining README.md

Joining The Quest

Examining The Contract and Test Code

The Contract Code

The Test Code

Building the Contract

Deploying the Contract

Invoking the Contract

Checking the Quest

Soroban Contracts 101: Timelock

The Contract Code

Contract Usage

Conclusion

Soroban Contracts 101: Single Offer Sale

The Contract Code

Contract Usage

Conclusion

Soroban Contracts 101: Batched Atomic Swaps

The Contract

Conclusion

Soroban Contracts 101: Atomic Swaps

The Contract Code

Conclusion

Soroban Contracts 101 : Allocator

Dependencies

Allocator Example: Summing a Vector

Conclusion

Examining `README.md`

Deploying The Contract as `Parent_Account`

Initializing `AllowanceContract`

Allowing `AllowanceContract`

Examining `README.md`

Invoke `verify` Function From Specific ContractID

Examining `README.md`

Storing Data using Deployed `DataStoreContract` Contract

Retrieving Stored Data using deployed `CrossContractCall` Contract

Examining `README.md`

Invoking `submit` Function

Examining `README.md`

`put()` function

`get()` Function

Examining `README.md`