Rust Testing Framework Functions Documentation

This documentation provides an overview of the available functions in the Rust Testing Framework, focusing on the functionalities offered by the BlockchainStateWrapper type.

Introduction

This page lists the currently available functions in the Rust Testing Framework, specifically those provided by the BlockchainStateWrapper type.

Please note that most functions in this framework use the num_bigint::BigUint type for numbers. It is essential to differentiate this type from the BigUint type used inside smart contracts, as they are distinct types. It is recommended to use the Rust version outside of lambda functions and only use the managed type when interacting directly with the smart contract.

State-checking Functions

These functions are designed to check the blockchain state and will cause the test to fail if the check is unsuccessful.

check_klv_balance

check_klv_balance(&self, address: &Address, expected_balance: &num_bigint::BigUint)

This function checks the KLV balance for the given address.

check_kda_balance

check_kda_balance(&self, address: &Address, token_id: &[u8], expected_balance: &num_bigint::BigUint)

Checks the fungible Kda balance for the specified address.

check_nft_balance

check_nft_balance<T>(&self, address: &Address, token_id: &[u8], nonce: u64, expected_balance: &num_bigint::BigUint, opt_expected_attributes: Option<&T>)

This function checks the NFT balance for a specific nonce associated with an address and optionally verifies the NFT attributes. If you are only interested in the balance, pass Option::None for opt_expected_attributes. If the Rust compiler struggles to deduce the generic T, you can use one of the following approaches:

b_mock.check_nft_balance::<Empty>(..., None);

b_mock.check_nft_balance(..., Option::<Empty>::None);

State-getter Functions

These functions retrieve the current state and are generally used after a transaction to verify that tokens have reached their intended destination. Most functions will trigger a panic if an invalid address is provided as an argument.

get_klv_balance

get_klv_balance(&self, address: &Address) -> num_bigint::BigUint

Gets the KLV balance for the specified account.

get_kda_balance

get_kda_balance(&self, address: &Address, token_id: &[u8], token_nonce: u64) -> num_bigint::BigUint

Retrieves the Kda balance for the specified account. If you are interested in the balance of a fungible token, set token_nonce to 0.

get_nft_attributes

get_nft_attributes<T: TopDecode>(&self, address: &Address, token_id: &[u8], token_nonce: u64) -> Option<T>

Fetches the NFT attributes for a token owned by the specified address. It will return Option::None if no attributes are found.

dump_state

dump_state(&self)

Prints the current state to the console, which is useful for debugging.

dump_state_for_account_hex_attributes

dump_state_for_account_hex_attributes(&self, address: &Address)

Similar to the previous function but specifically dumps the state for the given account.

dump_state_for_account

dump_state_for_account<AttributesType: TopDecode + core::fmt::Debug>(&self, address: &Address)

Like the function above, it dumps the state for the specified account but also prints the attributes in a user-friendly format. This is particularly useful for debugging NFT attributes.

State-altering Functions

These functions modify the state in various ways.

create_user_account

create_user_account(&mut self, klv_balance: &num_bigint::BigUint) -> Address

Creates a new user account with the provided KLV balance. The framework generates a pseudo-random address for this account.

create_user_account_fixed_address

create_user_account_fixed_address(&mut self, address: &Address, klv_balance: &num_bigint::BigUint)

Similar to the previous function but allows you to create an account with a fixed address when necessary.

create_sc_account

create_sc_account<CB, ContractObjBuilder>(&mut self, klv_balance: &num_bigint::BigUint, owner: Option<&Address>, obj_builder: ContractObjBuilder, contract_wasm_path: &str) -> ContractObjWrapper<CB, ContractObjBuilder>

Creates a smart contract account. The obj_builder parameter requires sc_namespace::contract_obj. This function returns a ContractObjWrapper, which contains the address of the newly created smart contract and the function used to create instances of your contract. If you only need the address for setting the balance, you can use the address_ref method to obtain a reference to the stored address. The contract_wasm_path is relative to the tests folder where the current test file is located.

create_sc_account_fixed_address

create_sc_account_fixed_address<CB, ContractObjBuilder>(&mut self, address: &Address, klv_balance: &num_bigint::BigUint, owner: Option<&Address>, obj_builder: ContractObjBuilder, contract_wasm_path: &str) -> ContractObjWrapper<CB, ContractObjBuilder>

Similar to the previous function, but it allows the caller to specify the address instead of generating a random one.

set_klv_balance

set_klv_balance(&mut self, address: &Address, balance: &num_bigint::BigUint)

Sets the KLV balance for the specified account.

set_kda_balance

set_kda_balance(&mut self, address: &Address, token_id: &[u8], balance: &num_bigint::BigUint)

Sets the fungible token balance for the specified account.

set_nft_balance

set_nft_balance<T: TopEncode>(&mut self, address: &Address, token_id: &[u8], nonce: u64, balance: &num_bigint::BigUint, attributes: &T)

Sets the non-fungible token balance for the specified account along with the associated attributes. Attributes can be of any serializable type. If you do not require attributes, you can pass "empty" using various approaches, such as &(), &Vec::<u8>::new(), BoxedBytes::empty(), etc.

set_kda_local_roles

set_kda_local_roles(&mut self, address: &Address, token_id: &[u8], roles: &[KdaLocalRole])

Sets the Kda token roles for the specified address and token, typically used during setup steps.

set_block_epoch

set_block_epoch(&mut self, block_epoch: u64)

set_block_nonce

set_block_nonce(&mut self, block_nonce: u64)

set_block_round

set_block_round(&mut self, block_round: u64)

set_block_timestamp

set_block_timestamp(&mut self, block_timestamp: u64)

set_block_random_seed

set_block_random_seed(&mut self, block_random_seed: Box<[u8; 48]>)

These functions allow you to set various values for the current block information.

set_prev_block_epoch

set_prev_block_epoch(&mut self, block_epoch: u64)

set_prev_block_nonce

set_prev_block_nonce(&mut self, block_nonce: u64)

set_prev_block_round

set_prev_block_round(&mut self, block_round: u64)

set_prev_block_timestamp

set_prev_block_timestamp(&mut self, block_timestamp: u64)

set_prev_block_random_seed

set_prev_block_random_seed(&mut self, block_random_seed: Box<[u8; 48]>)

These functions are similar to the previous set but apply to the previous block.

Smart Contract Execution Functions

These functions facilitate interactions with smart contracts. While they can be categorized as state-altering functions, they have been placed in a separate section for clarity.

execute_tx

execute_tx(&mut self, caller: &Address, sc_wrapper: &ContractObjWrapper<...>, klv_payment: &num_bigint::BigUint, tx_fn: TxFn) -> TxResult

Executes a transaction towards the specified smart contract, optionally including a KLV payment (use 0 for no payment). tx_fn is a lambda function that accepts a contract object as an argument. For more details on how to write such a lambda, refer to the Crowdfunding test examples.

execute_kda_transfer

execute_kda_transfer(&mut self, caller: &Address, sc_wrapper: &ContractObjWrapper<...>, token_id: &[u8], kda_nonce: u64, kda_amount: &num_bigint::BigUint, tx_fn: TxFn) -> TxResult

Similar to the previous function but executes an Kda/NFT transfer instead of a KLV transfer.

execute_kda_multi_transfer

execute_kda_multi_transfer(&mut self, caller: &Address, sc_wrapper: &ContractObjWrapper<...>, kda_transfers: &[TxInputKDA], tx_fn: TxFn) -> TxResult

Similar to the function above but performs a MultiKDANFT transfer.

execute_query

execute_query(&mut self, sc_wrapper: &ContractObjWrapper<...>, query_fn: TxFn) -> TxResult

Executes a SCQuery on the smart contract. None of the changes are committed to the state, but the function requires mutability to perform temporary changes. Just like on the real blockchain, there is no caller or token transfer for queries.

execute_in_managed_environment

execute_in_managed_environment(&self, f: Func) -> T

Executes an arbitrary function and returns its result, which can be of any type. This function is rarely used but can be helpful when performing checks involving managed types, which cannot be created outside of lambda functions.

Undocumented Functions

Several scenario generation functions have not been included in this documentation. We advise against using scenario generation, as it is time-consuming, and the results are often unreadable scenario files. If scenarios are necessary, we recommend writing them manually. If you still wish to explore scenario generation, you can find examples in the Crowdfunding test examples.