Soroban Contracts 101 : Allocator

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.