Soroban Quest : Hello World

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.

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:

1. 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.
2. 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.
3. 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.