Write a Smart Contract to Store & Retrieve Data with Increment Example

Now that we’ve built a basic Hello World example contract, we’ll write a simple contract that stores and retrieves data. This will help you see the basics of Soroban’s storage system. This is going to follow along with the increment example, which has a single function that increments an internal counter and returns the value. If you want to see a working example, try it in Devcontainers. This tutorial assumes that you’ve already completed the previous steps in Getting Started: Setup, Hello World, and Deploy to Testnet.

Adding the increment contract

In addition to creating a new project, the stellar contract init command also allows us to initialize a new contract workspace within an existing project. In this example, we’re going to initialize a new contract and use the --name flag to specify the name of our new contract, increment. This command will not overwrite existing files unless we explicitly pass in the --overwrite flag. From within our soroban-hello-world directory, run:

stellar contract init . --name increment

This creates a new contracts/increment directory with placeholder code in src/lib.rs and src/test.rs, which we’ll replace with our new increment contract and corresponding tests.

└── contracts
    ├── increment
        ├── Cargo.toml
        ├── Makefile
        └── src
            ├── lib.rs
            └── test.rs

We will go through the contract code in more detail below, but for now, replace the placeholder code in contracts/increment/src/lib.rs with the following.

#![no_std]
use soroban_sdk::{contract, contractimpl, log, symbol_short, Env, Symbol};

const COUNTER: Symbol = symbol_short!("COUNTER");

#[contract]
pub struct IncrementContract;

#[contractimpl]
impl IncrementContract {
    /// Increment increments an internal counter, and returns the value.
    pub fn increment(env: Env) -> u32 {
        let mut count: u32 = env.storage().instance().get(&COUNTER).unwrap_or(0);
        log!(&env, "count: {}", count);

        count += 1;
        env.storage().instance().set(&COUNTER, &count);
        env.storage().instance().extend_ttl(50, 100);

        count
    }
}

mod test;

Imports

This contract begins similarly to our Hello World contract, with an annotation to exclude the Rust standard library, and imports of the types and macros we need from the soroban-sdk crate.

contracts/increment/src/lib.rs

#![no_std]
use soroban_sdk::{contract, contractimpl, log, symbol_short, Env, Symbol};

Contract Data Keys

const COUNTER: Symbol = symbol_short!("COUNTER");

Contract data is associated with a key, which can be used at a later time to look up the value. Symbol is a short (up to 32 characters long) string type with limited character space (only a-zA-Z0-9_ characters are allowed). Identifiers like contract function names and contract data keys are represented by Symbols. The symbol_short!() macro is a convenient way to pre-compute short symbols up to 9 characters in length at compile time using Symbol::short. It generates a compile-time constant that adheres to the valid character set of letters (a-zA-Z), numbers (0-9), and underscores (_). If a symbol exceeds the 9-character limit, Symbol::new should be utilized for creating symbols at runtime.

Contract Data Access

let mut count: u32 = env
    .storage()
    .instance()
    .get(&COUNTER)
    .unwrap_or(0); // If no value set, assume 0.

The Env.storage() function is used to access and update contract data. The executing contract is the only contract that can query or modify contract data that it has stored. The data stored is viewable on ledger anywhere the ledger is viewable, but contracts executing within the Soroban environment are restricted to their own data. The get() function gets the current value associated with the counter key. If no value is currently stored, the value given to unwrap_or(...) is returned instead. Values stored as contract data and retrieved are transmitted from the environment and expanded into the type specified. In this case a u32. If the value can be expanded, the type returned will be a u32. Otherwise, if a developer cast it to be some other type, a panic would occur at the unwrap.

env.storage()
    .instance()
    .set(&COUNTER, &count);

The set() function stores the new count value against the key, replacing the existing value.

Managing Contract Data TTLs with `extend_ttl()`

env.storage().instance().extend_ttl(100, 100);

All contract data has a Time To Live (TTL), measured in ledgers, that must be periodically extended. If an entry’s TTL is not periodically extended, the entry will eventually become “archived.” You can learn more about this in the State Archival document. For now, it’s worth knowing that there are three kinds of storage: Persistent, Temporary, and Instance. This contract only uses Instance storage: env.storage().instance(). Every time the counter is incremented, this storage’s TTL gets extended by 100 ledgers, or about 500 seconds.

Build the contract

From inside soroban-hello-world, run:

stellar contract build

Check that it built:

ls target/wasm32v1-none/release/*.wasm

You should see both hello_world.wasm and increment.wasm.

Tests

Replace the placeholder code in contracts/increment/src/test.rs with the following increment test code.

contracts/increment/src/test.rs

#![cfg(test)]
use crate::{IncrementContract, IncrementContractClient};
use soroban_sdk::Env;

#[test]
fn test() {
    let env = Env::default();
    let contract_id = env.register(IncrementContract, ());
    let client = IncrementContractClient::new(&env, &contract_id);

    assert_eq!(client.increment(), 1);
    assert_eq!(client.increment(), 2);
    assert_eq!(client.increment(), 3);
}

This uses the same concepts described in the Hello World example. Make sure it passes:

cargo test

You’ll see that this runs tests for the whole workspace; both the Hello World contract and the new Increment contract. If you want to see the output of the log! call, run the tests with --nocapture:

cargo test -- --nocapture

You should see the the diagnostic log events with the count data in the output:

running 1 test
[Diagnostic Event] contract:CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM,
    topics:[log],
    data:["count: {}", 1]
[Diagnostic Event] contract:CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM,
    topics:[log],
    data:["count: {}", 2]
[Diagnostic Event] contract:CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM,
    topics:[log],
    data:["count: {}", 3]
test test::test ... ok

Take it further

Can you figure out how to add get_current_value function to the contract? What about decrement or reset functions?

Summary

In this section, we added a new contract to this project, that made use of Soroban’s storage capabilities to store and retrieve data. We also learned about the different kinds of storage and how to manage their TTLs. Next we’ll learn a bit more about deploying contracts to Soroban’s Testnet network and interact with our incrementor contract using the CLI.

​Adding the increment contract

​Imports

​Contract Data Keys

​Contract Data Access

​Managing Contract Data TTLs with extend_ttl()

​Build the contract

​Tests

​Take it further

​Summary