Struct StateBuilder

pub struct StateBuilder<S = StateApi> { /* private fields */ }

A state builder that allows the creation of StateMap, StateSet, and StateBox.

It is parametrized by a parameter S that is assumed to implement HasStateApi to support testing with the deprecated test_infrastructure. The S defaults to StateApi, which is sufficient to test with the concordium-smart-contract-testing library.

The StateBuilder is designed to provide an abstraction over the contract state, abstracting over the exact keys (keys in the sense of key-value store, which is the low-level semantics of contract state) that are used when storing specific values.

Implementations

impl<S> StateBuilder<S>

where S: HasStateApi,

pub fn open(state: S) -> Self

Open a new state_builder. Only a single instance of the state_builder should exist during contract execution, thus this should only be called at the very beginning of execution.

pub fn new_state_container(&mut self) -> (S, [u8; 8])

Provide clone of HasStateApi instance and new key prefix for any container-like type wishing to store its data on blockchain.

Container types StateBox, StateSet, StateMap provided by Concordium SDK are created using this method internally. Contract developers can use it to implement their own containers.

Any container type which provides more ergonomic APIs and behavior atop raw storage is expected to have two items:

• Handle-like object which implements HasStateApi. It provides access to contract VM features, including storage management. This object is not serialized, instead it’s provided by executon environment. Can be treated as handle, relatively cheap to clone.
• Prefix for keys of all entries managed by new container. Storage of Concordium contract behaves like flat key-value dictionary, so each container must have unique prefix for the keys of any entries it stores to avoid collisions with other containers. This prefix is serialized as (part of) persistent representation of container.

Returns

A pair of:

• Object which gives access to low-level storage API. Same as the one held by StateBuilder itself and usually the one which refers to current contract storage.
• New unique key prefix for this container.

pub fn new_map<K, V>(&mut self) -> StateMap<K, V, S>

Create a new empty StateMap.

pub fn new_set<T>(&mut self) -> StateSet<T, S>

Create a new empty StateSet.

pub fn new_box<T: Serial>(&mut self, value: T) -> StateBox<T, S>

Create a new StateBox and insert the value into the state. This stores the serialized value in the contract state. Thus if the StateBox is dropped without calling delete then the value will remain in contract state, leading to a space leak.

Note that this dropping can happen implicitly via assignment. For example,

struct MyState<S: HasStateApi> {
    inner: StateBox<u64, S>,
}
fn incorrect_replace<S: HasStateApi>(
    state_builder: &mut StateBuilder<S>,
    state: &mut MyState<S>,
) {
    // The following is incorrect. The old value of `inner` is not properly deleted.
    // from the state.
    state.inner = state_builder.new_box(0); // ⚠️
}

Instead, the old value should be manually deleted.

fn correct_replace<S: HasStateApi>(
    state_builder: &mut StateBuilder<S>,
    state: &mut MyState<S>,
) {
    let old_box = mem::replace(&mut state.inner, state_builder.new_box(0));
    old_box.delete()
}

impl StateBuilder<StateApi>

pub fn new_btree_set<K>(&mut self) -> StateBTreeSet<K>

Create a new empty StateBTreeSet.

pub fn new_btree_map<K, V>(&mut self) -> StateBTreeMap<K, V>

Create a new empty StateBTreeMap.

pub fn new_btree_set_degree<const M: usize, K>(&mut self) -> StateBTreeSet<K, M>

Create a new empty StateBTreeSet, setting the minimum degree M of the B-Tree explicitly. M must be 2 or higher otherwise constructing the B-Tree results in aborting.

pub fn new_btree_map_degree<const M: usize, K, V>( &mut self, ) -> StateBTreeMap<K, V, M>

Create a new empty StateBTreeMap, setting the minimum degree M of the B-Tree explicitly. M must be 2 or higher otherwise constructing the B-Tree results in aborting.

impl StateBuilder<TestStateApi>

pub fn new() -> Self

👎Deprecated since 8.1.0: Deprecated in favor of concordium-smart-contract-testing.

Create a new Self with an empty TestStateApi.

Trait Implementations

impl<S: Default> Default for StateBuilder<S>

fn default() -> StateBuilder<S>

Returns the “default value” for a type.