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 underno_std
. - Creates a contiguous growable array
v1
with contents allocated on the heap memory(WASM linear memory). - Defines a
sum
function that: > - Takes anEnv
and acount
> - Creates a vector ofcount
elements (0..count) usingalloc
> - Pushes values from0
tocount
into the vectorv1
> - 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.
Top comments (1)
Is this memory allocation on Soroban required, or it is just a kind of a best practice?