Utilities
The following documentation provides reasoning and examples for functions and constants found in openzeppelin::utils
and openzeppelin::tests::utils.
| Expect this module to evolve (as it has already done). |
Core utilities
utils
use openzeppelin::utils;Module containing core utilities of the library.
try_selector_with_fallback(target: ContractAddress, selector: felt252, fallback: felt252, args: Span<felt252>) → SyscallResult<Span<felt252>> function
Tries to call a given selector on a given contract, and if it fails, tries to call a fallback selector.
It was designed for falling back to the camelCase selector for backward compatiblity in the
case of a failure of the snake_case selector.
Returns a SyscallResult with the result of the successful call.
Note that:
-
If the first call succeeds, the second call is not attempted.
-
If the first call fails with an error different than
ENTRYPOINT_NOT_FOUND, the error is returned without falling back to the second selector. -
If the first call fails with
ENTRYPOINT_NOT_FOUND, the second call is attempted, and if it fails its error is returned.
| The fallback mechanism won’t work on live chains (mainnet or testnets) until they implement panic handling in their runtime. |
UnwrapAndCast trait
Trait for exposing an unwrap_and_cast function to SyscallResult objects. This may be useful
when unwrapping a syscall result to a type implementing the Serde trait, and you want to avoid the boilerplate of
casting and unwrapping the result multiple times.
Usage example:
use openzeppelin::utils::selectors;
use openzeppelin::utils::UnwrapAndCast;
fn call_and_cast_to_bool(target: ContractAddress, args: Span<felt252>) -> bool {
try_selector_with_fallback(
target, selectors::has_role, selectors::hasRole, args
).unwrap_and_cast()
}
fn call_and_cast_to_felt252(target: ContractAddress, args: Span<felt252>) -> felt252 {
try_selector_with_fallback(
target, selectors::get_role_admin, selectors::getRoleAdmin, args
).unwrap_and_cast()
}Note that it can be automatically casted to any type implementing the Serde trait.
selectors
use openzeppelin::utils::selectors;Module containing constants matching multiple selectors used through the library. To see the full list of selectors, see selectors.cairo.
serde
use openzeppelin::utils::serde;Module containing utilities related to serialization and deserialization of Cairo data structures.
SerializedAppend trait
Importing this trait allows the ability to append a serialized representation of a Cairo data structure already
implementing the Serde trait to a felt252 buffer.
Usage example:
use openzeppelin::utils::serde::SerializedAppend;
use starknet::ContractAddress;
fn to_calldata(recipient: ContractAddress, amount: u256) -> Array<felt252> {
let mut calldata = array![];
calldata.append_serde(recipient);
calldata.append_serde(amount);
calldata
}Note that the append_serde method is automatically available for arrays of felts, and it accepts any data structure
that implements the Serde trait.
Test utilities
utils
use openzeppelin::tests::utils;Module containing utilities for testing the library.
deploy(contract_class_hash: felt252, calldata: Array<felt252>) → ContractAddress function
Uses the deploy_syscall to deploy an instance of the contract given the class hash and the calldata.
The contract_address_salt is always set to zero, and deploy_from_zero is set to false.
Usage example:
use openzeppelin::presets::Account;
use openzeppelin::tests::utils;
use starknet::ContractAddress;
const PUBKEY: felt252 = 'PUBKEY';
fn deploy_test_contract() -> ContractAddress {
let calldata = array![PUBKEY];
utils::deploy(Account::TEST_CLASS_HASH, calldata)
}pop_log<T>(address: ContractAddress) → Option<T> function
Pops the earliest unpopped logged event for the contract as the requested type and checks that there’s no more keys or data left on the event, preventing unaccounted params.
This function also removes the first key from the event, to match the event structure key params without the event ID.
Required traits for T:
-
Drop -
starknet::Event
Requirements:
-
No extra data or keys are left on the raw event after deserialization.
| This method doesn’t currently work for component events that are not flattened because an extra key is added, pushing the event ID key to the second position. |
assert_indexed_keys<T>(event: T, expected_keys: Span<felt252>) function
Asserts that expected_keys exactly matches the indexed keys from event.
expected_keys must include all indexed event keys for event in the order
that they’re defined.
Required traits for T:
-
Drop -
starknet::Event
assert_no_events_left(address: ContractAddress) function
Asserts that there are no more events left in the queue for the given address.
drop_event(address: ContractAddress) function
Removes an event from the queue for the given address.
If the queue is empty, this function won’t do anything.
constants
use openzeppelin::tests::utils::constants;Module containing constants that are repeatedly used among tests. To see the full list, see constants.cairo.