DEV Community: Shada Tosin

Soroban Series 3: Building a Soroban Voting Contract

Shada Tosin — Fri, 22 Dec 2023 09:17:06 +0000

Introduction

Welcome to this comprehensive tutorial on building a Soroban-based voting contract. Soroban is a lightweight smart contract framework designed for simplicity and efficiency. In this tutorial, we'll go through the step-by-step implementation of a basic voting contract using the Soroban framework.

Source Code: Link
Demo: Link
Video: Link

Prerequisites

Before we begin, make sure you have the following:

Rust installed (check Rust Installation Guide)
A basic understanding of Rust programming language
Familiarity with Soroban smart contracts and blockchain concepts (check Soroban Starter Guide)

Setting Up the Project

Create a New Rust Project:

Create a new Rust project using the following command:

   cargo new soroban_voting_contract

Navigate to the Project Directory:

Navigate to the project directory:

   cd soroban_voting_contract

Add Dependencies:

Open the Cargo.toml file and add the following dependencies:

   [workspace.dependencies]
   soroban-sdk = "20.0.3"
   soroban-token-sdk = "20.0.3"

Create Contract Code:

Create a new file called lib.rs in the src directory and copy the provided Soroban contract code into it.

Understanding the Soroban Voting Contract

Let's dive deeper into the key components of the Soroban voting contract:

1. Storage Management

The contract leverages Soroban's storage capabilities for efficient data management. It defines data keys such as NextProposalId and Proposals to organize the storage of proposal information.

2. Initialization Function

pub fn initialize(e: Env) {
        assert!(
            !e.storage().instance().has(&DataKey::NextProposalId),
            "already initialized"
        );
        let initial_proposal_id: u128 = 1;
        e.storage()
            .instance()
            .set(&DataKey::NextProposalId, &initial_proposal_id);
        e.storage()
            .instance()
            .extend_ttl(INSTANCE_LIFETIME_THRESHOLD, INSTANCE_BUMP_AMOUNT);
    }

The initialize function sets up the initial state of the contract. It checks whether the contract is already initialized and, if not, initializes the NextProposalId and extends the contract's lifetime.

3. Proposal Creation

pub fn create_proposal(
        e: Env,
        sender: Address,
        name: String,
        description: String,
        goal: u128,
    ) -> u128 {
        sender.require_auth();
        let proposal_id = get_next_proposal_id(&e);

        let created_at = get_ledger_timestamp(&e);
        let proposal = Proposal {
            id: proposal_id,
            name: name.clone(),
            description: description.clone(),
            goal,
            created_at,
            is_active: true,
            status: ProposalStatus::Active,
            last_voted_at: 0,
            vote_count: 0,
            created_by: sender.clone(),
        };

        e.storage()
            .persistent()
            .set(&DataKey::Proposals(proposal_id), &proposal);
        e.storage().persistent().extend_ttl(
            &DataKey::Proposals(proposal_id),
            LIFETIME_THRESHOLD,
            BUMP_AMOUNT,
        );

        set_proposal_by_user(&e, &proposal_id);

        // emit events
        events::proposal_created(&e, proposal_id, sender, name, created_at);

        proposal_id
    }

The create_proposal function allows users to create a new voting proposal. It performs validation checks, including verifying the sender's authorization, generates a unique proposal ID, and stores the proposal details in persistent storage.

4. Voting Mechanism

pub fn vote(e: Env, proposal_id: u128, voter: Address) {
        voter.require_auth();
        let mut proposal = get_proposal(&e, &proposal_id);
        assert!(proposal.is_active, "proposal is not active");
        assert!(
            proposal.status == ProposalStatus::Active,
            "proposal is not active"
        );
        proposal.last_voted_at = get_ledger_timestamp(&e);
        proposal.vote_count += 1;
        e.storage()
            .persistent()
            .set(&DataKey::Proposals(proposal_id), &proposal);
        e.storage().persistent().extend_ttl(
            &DataKey::Proposals(proposal_id),
            LIFETIME_THRESHOLD,
            BUMP_AMOUNT,
        );

        // emit events
        events::proposal_voted(&e, proposal_id, voter);
    }

The vote function enables users to cast their votes for a specific proposal. It checks the proposal's status, updates the vote count, and emits relevant events to notify other stakeholders.

5. Proposal Status Management

pub fn status(e: Env, proposal_id: u128) -> ProposalStatus {
        let mut proposal = get_proposal(&e, &proposal_id);

        if proposal.status != ProposalStatus::Active {
            return proposal.status;
        }

        if proposal.vote_count >= proposal.goal {
            proposal.is_active = false;
            proposal.status = ProposalStatus::Ended;

            e.storage()
                .persistent()
                .set(&DataKey::Proposals(proposal_id), &proposal);
            e.storage().persistent().extend_ttl(
                &DataKey::Proposals(proposal_id),
                LIFETIME_THRESHOLD,
                BUMP_AMOUNT,
            );
            // emit events
            events::proposal_reached_target(&e, proposal_id, proposal.goal);
            return proposal.status;
        }

        return ProposalStatus::Active;
    }

The status function checks the status of a proposal and handles its lifecycle. If the proposal reaches its goal, it is marked as ended, and events are emitted to inform the relevant parties.

6. Proposal Cancellation

pub fn cancel_proposal(e: Env, sender: Address, proposal_id: u128) {
        sender.require_auth();
        let mut proposal = get_proposal(&e, &proposal_id);
        assert!(
            proposal.created_by == sender,
            "only the creator can cancel the proposal"
        );
        assert!(proposal.is_active, "proposal is not active");
        assert!(
            proposal.status == ProposalStatus::Active,
            "proposal is not active"
        );
        proposal.is_active = false;
        proposal.status = ProposalStatus::Cancelled;
        e.storage()
            .persistent()
            .set(&DataKey::Proposals(proposal_id), &proposal);
        e.storage().persistent().extend_ttl(
            &DataKey::Proposals(proposal_id),
            LIFETIME_THRESHOLD,
            BUMP_AMOUNT,
        );

        events::proposal_cancelled(&e, proposal_id);
    }

The cancel_proposal function allows the creator to cancel an active proposal. It checks the authorization of the sender, sets the proposal as inactive, and updates its status accordingly.

7. Utility Functions

Utility functions such as get_proposal and get_proposals are provided to retrieve specific proposals or all proposals associated with a user.

Compiling and Deploying the Contract

Compile the Contract:

Open a terminal and navigate to the project directory. Compile the contract using the following command:

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

Deployment:

Deploy the compiled contract on Stellar Testnet or Futurenet. Refer to the documentation of the specific platform for detailed deployment instructions.

Advanced Features and Considerations

Now that you've built a basic Soroban voting contract, consider exploring advanced features and optimizations:

Gas Efficiency: Optimize the contract for gas efficiency to reduce transaction costs.
Security Audits: Perform security audits to identify and address potential vulnerabilities.
Event Handling: Enhance event handling mechanisms for better communication with external applications.
Integration with Oracles: Explore integration with Oracles to bring external data into the contract.

Conclusion

Congratulations! You've successfully created a Soroban-based voting contract. This tutorial serves as a foundation for building more complex smart contracts using Soroban. Feel free to explore and extend the functionality based on your requirements. Check the Soroban documentation for more details and advanced features. Happy coding!

Soroban Series 2: Building a Name Resolution Service

Shada Tosin — Mon, 28 Aug 2023 21:57:12 +0000

This is the second part of my Soroban Smart Contract Series. You can check out the first part here. I gave an overview of how to build a Decentralized Application in Soroban and also dropped some links to guide you in your journey.

Here is the link to the complete source code: Github.

The Name service contract will be divided into three major contracts namely the registry, the registrar and the resolver.

The Registry

This is the core contract that holds all the domain names for resolutions including the top-level domains. In this project we abstracted the interface of the project (thanks to the Slender Project for the inspiration) in order to seamlessly allow us do cross contract calls and test them.

All domain names in the registry are stored as a record shown below

#[derive(Clone, Debug)]
#[contracttype]
pub struct Record {
    pub owner: Address,
    pub resolver: Address,
    pub ttl: u32,
}

We then created a trait for the Contract which will be implemented.

#[contractspecfn(name = "Spec", export = false)]
#[contractclient(name = "SnsRegistryClient")]
pub trait SnsRegistryTrait {
    fn initialize(e: Env, admin: Address);
    fn set_record(
        e: Env,
        caller: Address,
        node: BytesN<32>,
        owner: Address,
        resolver: Address,
        ttl: u32,
    );
    fn set_owner(e: Env, caller: Address, node: BytesN<32>, owner: Address);
    fn set_subnode_owner(
        e: Env,
        caller: Address,
        node: BytesN<32>,
        label: BytesN<32>,
        owner: Address,
    );
    fn set_resolver(e: Env, caller: Address, node: BytesN<32>, resolver: Address);
    fn set_ttl(e: Env, caller: Address, node: BytesN<32>, ttl: u32);
    fn set_approval_for_all(e: Env, caller: Address, operator: Address, approved: bool);
    fn owner(e: Env, node: BytesN<32>) -> Address;
    fn resolver(e: Env, node: BytesN<32>) -> Address;
    fn ttl(e: Env, node: BytesN<32>) -> u32;
    fn record(e: Env, node: BytesN<32>) -> Record;
    fn record_exist(e: Env, node: BytesN<32>) -> bool;
    fn is_approved_for_all(e: Env, operator: Address, owner: Address) -> bool;
}

After creating the interface, we will begin building the core logic of the contract

fn initialize(e: Env, admin: Address) {
        if has_administrator(&e) {
            panic!("already initialized")
        }
        set_administrator(&e, &admin);
    }

    fn set_record(
        e: Env,
        caller: Address,
        node: BytesN<32>,
        owner: Address,
        resolver: Address,
        ttl: u32,
    ) {
        caller.require_auth();
        require_node_authorised(&e, &node, &caller);
        set_parent_node_owner(&e, &node, &owner);
        set_resolver_ttl(&e, &node, &resolver, &ttl);
    }

As mentioned in the first series, the initialize function acts as the constructor and allows the contract deployer to set certain values that will be used over the lifetime of the contract.
You will notice in the above code that the Name is a BytesN<32> which is a special type in Soroban that can be used to represent a SHA256 hash.

The Registrar

This is the contract that manages the registry and also registers and renews domains on its TLD (Top Level Domain). The major functions in this contract are shown below.

pub fn register(
        e: Env,
        caller: Address,
        owner: Address,
        name: BytesN<32>,
        duration: u64,
    ) -> u64 {
        caller.require_auth();
        // Comment out to allow anyone to register a name
        // require_active_controller(&e, &caller);
        require_registry_ownership(&e);
        assert!(is_name_available(&e, &name), "name is not available");

        // [todo] test this to see how it works
        let expiry_date = get_ledger_timestamp(&e) + duration;
        if expiry_date + GRACE_PERIOD > u64::MAX {
            panic!("duration is too long");
        }

        set_domain_owner(&e, &name, &owner);
        set_domain_expiry(&e, &name, &expiry_date);

        let base_node = get_base_node(&e);
        let registry = get_registry(&e);
        let registry_client = registry_contract::Client::new(&e, &registry);
        registry_client.set_subnode_owner(&e.current_contract_address(), &base_node, &name, &owner);

        expiry_date
    }

    pub fn renew(e: Env, caller: Address, name: BytesN<32>, duration: u64) -> u64 {
        caller.require_auth();
        require_active_controller(&e, &caller);
        require_registry_ownership(&e);
        assert!(!is_name_available(&e, &name), "name is not registered");

        let expiry_date = get_domain_expiry(&e, &name);
        // Check if the domain is expired or not registered by getting the expiry date which can either be a timestamp or 0
        // If the expiry date is 0 then the domain is not registered and therefore adding the grace period will certainly make it less than the current timestamp
        if expiry_date + GRACE_PERIOD < get_ledger_timestamp(&e) {
            panic!("domain is expired or not registered");
        }

        let new_expiry_date = expiry_date + duration;
        if new_expiry_date + GRACE_PERIOD > u64::MAX {
            panic!("duration is too long");
        }

        set_domain_expiry(&e, &name, &new_expiry_date);

        new_expiry_date
    }

From the above code, we can see that the contract will register and renew the domain based on availability and will give a certain number of days as grace period for the user to renew their subscription.

The Resolver

The resolver holds the mapping of a domain name to an address as well as a collection of text records. Some of its core functions are shown below.

fn set_name(e: &Env, node: &BytesN<32>, name: &Address) {
    e.storage()
        .persistent()
        .set(&DataKey::Names(node.clone()), name);
    e.storage()
        .persistent()
        .bump(&DataKey::Names(node.clone()), BUMP_AMOUNT);
}

fn set_text(e: &Env, node: &BytesN<32>, text: &String) {
    let mut texts = get_text(&e, &node);
    texts.push_back(text.clone());
    e.storage()
        .persistent()
        .set(&DataKey::Texts(node.clone()), &texts);
    e.storage()
        .persistent()
        .bump(&DataKey::Texts(node.clone()), BUMP_AMOUNT);
}
fn get_name(e: &Env, node: &BytesN<32>) -> Address {
    e.storage()
        .persistent()
        .get::<_, Address>(&DataKey::Names(node.clone()))
        .expect("No name found")
}

fn get_text(e: &Env, node: &BytesN<32>) -> Vec<String> {
    e.storage()
        .persistent()
        .get::<_, Vec<String>>(&DataKey::Texts(node.clone()))
        .unwrap_or(Vec::new(&e))
}

The Frontend

The frontend was put together with NextJS and Shadcn.

Soroban Series 1: Building a Payment Streaming App

Shada Tosin — Tue, 22 Aug 2023 21:05:46 +0000

Streaming payments are a convenient way for users to pay a beneficiary over a period of time while ensuring that at every point in time only the value accrued can be withdrawn by the beneficiary.

In this article I will be building a decentralized application on the Stellar Network with Soroban.

Here is the link to the complete source code: Github.

The Backend

The first step to creating a Soroban smart contract is to setup the environment as described here.
Once the environment is set up, you should use cargo to start a new project. You can also clone an existing repository like this one and use it as a starter project.

Nb: Given the fact that Soroban is still actively being developed with no stable release a lot of the patterns in this article might not be supported fully in the nearest future.

- Using the Latest Soroban CLI Version

In order to use the latest release of Soroban CLI with all the new features available we will add the below code to the config.toml file in the .cargo directory.

[alias] # command aliases
install_soroban = "install --git https://github.com/stellar/soroban-tools --rev 9b75c00fd19c0baf379c84668d90bfe444734173 --root ./target soroban-cli --debug"

The '9b75c00fd19c0baf379c84668d90bfe444734173' is the git commit id of the latest release of Soroban CLI in the Github repository.
After making this modification, you can follow the steps outlined here to install the necessary dependencies.

- Building the Streaming Contract

The Payment Streaming contract will be centred around the Stream Struct that will hold important information about a payment stream

#[derive(Clone, Debug)]
#[contracttype]
pub struct Stream {
    pub id: u32,
    pub sender: Address,
    pub recipient: Address,
    pub start_time: u64,
    pub stop_time: u64,
    pub deposit: i128,
    pub rate_per_second: u64,
    pub remaining_balance: i128,
    pub token_address: Address,
    pub token_symbol: String,
    pub token_decimals: u32,
}

We will then create the contract struct and implement it

#[contract]
struct StreamToken;

#[contractimpl]
#[allow(clippy::needless_pass_by_value)]
impl StreamToken {
    // Implement the contract
}

Before implementing the contract, we will have to create DataKeys that will be used to store out states.

#[derive(Clone)]
#[contracttype]
pub enum DataKey {
    Token,
    NextStreamId,
    Streams(u32),
    UserStreams(Address),
}

The token is the default token address supported by the contract, the Streams key is a mapping of the Streams to the Stream Id while the UserStreams key is a mapping of a user's address to a collection of streams.

Every smart contract in Soroban must be initialized with the pub fn initialize(e: Env) initialization function.

pub fn initialize(e: Env, token: Address, start_id: u32) {
    assert!(
        !e.storage().instance().has(&DataKey::NextStreamId),
        "already initialized"
    );
    e.storage()
        .instance()
        .set(&DataKey::NextStreamId, &start_id);
    e.storage().instance().set(&DataKey::Token, &token);
    e.storage().instance().bump(INSTANCE_BUMP_AMOUNT);
}

In the above code, we are checking whether a stream Id exist which will signify that the contract has already been initialized. If not, we are going to set the token to be used in this streaming contract and the start id.
To better understand how states are stored, you can check out these Soroban articles.

We will then implement some get functions to get the stream by Id and the stream by User Address

fn get_stream(e: &Env, stream_id: &u32) -> Stream {
    e.storage()
        .persistent()
        .get::<_, Stream>(&DataKey::Streams(stream_id.clone()))
        .expect("invalid stream id")
}

fn get_streams_by_user(e: &Env, who: &Address) -> Vec<Stream> {
    e.storage()
        .persistent()
        .get::<_, Vec<Stream>>(&DataKey::UserStreams(who.clone()))
        .unwrap_or(Vec::new(&e))
}

These functions will be exposed in the contract implementation as shown below

pub fn get_stream(e: Env, stream_id: u32) -> Stream {
        get_stream(&e, &stream_id)
    }

    pub fn get_streams_by_user(e: Env, caller: Address) -> Vec<Stream> {
        get_streams_by_user(&e, &caller)
    }

One of the core ability of the streaming contract is the way the balance of a user is dynamically generated and changes at each point within the streaming interval.

fn get_balance_of(e: &Env, caller: &Address, stream: &Stream) -> i128 {
    let start_time = stream.start_time;
    let stop_time = stream.stop_time;
    let current_ledger_time = get_ledger_timestamp(&e);
    let delta = get_delta_of(&start_time, &stop_time, &current_ledger_time);

    let mut local_balance = LocalBalance {
        recipient_balance: 0,
        withdrawal_amount: 0,
        sender_balance: 0,
    };
    local_balance.recipient_balance = (delta * stream.rate_per_second) as i128;

    // If the stream `balance` does not equal `deposit`, it means there have been withdrawals.
    // We have to subtract the total amount withdrawn from the amount of money that has been streamed until now.
    if stream.deposit > stream.remaining_balance {
        local_balance.withdrawal_amount = stream.deposit - stream.remaining_balance;
        check_nonnegative_amount(local_balance.withdrawal_amount);
        local_balance.recipient_balance =
            local_balance.recipient_balance - local_balance.withdrawal_amount;
        check_nonnegative_amount(local_balance.recipient_balance);
    }

    if caller.clone() == stream.recipient {
        local_balance.recipient_balance
    } else if caller.clone() == stream.sender {
        local_balance.sender_balance = stream.remaining_balance - local_balance.recipient_balance;
        check_nonnegative_amount(local_balance.sender_balance);
        local_balance.sender_balance
    } else {
        0
    }
}

This function will also be called in the contract implementation

    /// Returns the amount of tokens that have already been released to the recipient.
    /// Panics if the id does not point to a valid stream.
    /// @param stream_id The id of the stream
    /// @param who The address of the caller
    /// @return The amount of tokens that have already been released
    pub fn balance_of(e: Env, stream_id: u32, caller: Address) -> i128 {
        let stream = get_stream(&e, &stream_id);

        get_balance_of(&e, &caller, &stream)
    }

To create the stream, we are going to make a bunch of assertions and panic if any of those assertions fails, then we are going to create a mutable struct to hold the duration and rate per second to be calculated from the provided start and end time.
There will also be a cross contract call to the token contract to get the token symbol and decimal. To learn more about cross contract calls in Soroban, you can check out this article.

Once all the required information have been gotten, we will then create the Stream struct and persist it in the Soroban storage.

We also have the capability to withdraw from the stream for both the sender and receiver as implemented below

pub fn withdraw_from_stream(e: Env, recipient: Address, stream_id: u32, amount: i128) {
        recipient.require_auth();
        assert!(amount > 0, "amount is zero or negative");
        assert!(
            recipient != e.current_contract_address(),
            "stream to the contract itself"
        );

        let mut stream = get_stream(&e, &stream_id);
        require_sender_or_recipient(&stream, &recipient);

        let balance = get_balance_of(&e, &recipient, &stream);
        assert!(balance >= amount, "amount exceeds the available balance");

        stream.remaining_balance = stream.remaining_balance - amount;

        if stream.remaining_balance == 0 {
            remove_stream(&e, &stream_id);
        } else {
            set_stream(&e, &stream_id, &stream);
        }

        transfer(&e, &recipient, &amount);

        events::withdraw_from_stream(&e, recipient, stream_id, amount);
    }

The above code will allow the receiver to withdraw up to the amount that has been streamed and the sender to withdraw the balance remaining.

To cancel the stream, we have implemented a cancel_stream function that can only be called by either the sender or receiver

    pub fn cancel_stream(e: Env, caller: Address, stream_id: u32) {
        caller.require_auth();
        let stream = get_stream(&e, &stream_id);
        require_sender_or_recipient(&stream, &caller);

        let sender_balance = get_balance_of(&e, &stream.sender, &stream);
        let recipient_balance = get_balance_of(&e, &stream.recipient, &stream);

        remove_stream(&e, &stream_id);

        if recipient_balance > 0 {
            transfer(&e, &stream.recipient, &recipient_balance);
        }
        if sender_balance > 0 {
            transfer(&e, &stream.sender, &sender_balance);
        }

        events::cancel_stream(
            &e,
            stream_id,
            stream.sender,
            stream.recipient,
            sender_balance,
            recipient_balance,
        );
    }

We will also implement some tests functions to confirm that our code is working as it should.

The Frontend

The frontend was put together with NextJS and Shadcn. While the main focus of the application was the backend, lets look at the hook that was used to show how someone can call the create stream function as well as get the streams mapped to his wallet account.

Wrapping Up

Soroban is a new smart contract platform that is built on a well tested blockchain infrastructure (Stellar). While the ecosystem is still new, some interesting projects are already springing up and I personally will be looking forward to a better developer experience especially with regards to querying on-chain data and listening to events emitted from the smart contracts.