Utilities

This crate provides miscellaneous components and libraries containing utility functions to handle common tasks.

Core

utils

use openzeppelin_utils;

Module containing core utilities of the library.

Members

Inner modules

• cryptography
• deployments
• math
• contract_clock
• serde

Inner modules

cryptography module

See openzeppelin_utils::cryptography.

deployments module

See openzeppelin_utils::deployments.

math module

See openzeppelin_utils::math.

contract_clock module

See openzeppelin_utils::contract_clock.

serde module

See openzeppelin_utils::serde.

cryptography

use openzeppelin_utils::cryptography;

Module containing utilities related to cryptography.

Members

Inner modules

• nonces
• snip12

Inner modules

nonces module

See openzeppelin_utils::cryptography::nonces::NoncesComponent.

snip12 module

See openzeppelin_utils::cryptography::snip12.

deployments

use openzeppelin_utils::deployments;

Module containing utility functions for calculating contract addresses through deploy_syscall and the Universal Deployer Contract (UDC).

Members

Structs

• DeployerInfo(caller_address, udc_address)

Functions

• calculate_contract_address_from_deploy_syscall(salt, class_hash, constructor_calldata, deployer_address)
• compute_hash_on_elements(data)
• calculate_contract_address_from_udc(salt, class_hash, constructor_calldata, deployer_info)

Structs

DeployerInfo(caller_address: ContractAddress, udc_address: ContractAddress) struct

Struct containing arguments necessary in utils::calculate_contract_address_from_udc for origin-dependent deployment calculations.

Functions

calculate_contract_address_from_deploy_syscall(salt: felt252, class_hash: ClassHash, constructor_calldata: Span<felt252>, deployer_address: ContractAddress) → ContractAddress function

Returns the contract address when passing the given arguments to deploy_syscall.

compute_hash_on_elements(data: Span<felt252>) → felt252 function

Creates a Pedersen hash chain with the elements of data and returns the finalized hash.

calculate_contract_address_from_udc(salt: felt252, class_hash: ClassHash, constructor_calldata: Span<felt252>, deployer_info: Option<DeployerInfo>) → ContractAddress function

Returns the calculated contract address for UDC deployments.

Origin-independent deployments (deployed from zero) should pass Option::None as deployer_info.

Origin-dependent deployments hash salt with caller_address (member of DeployerInfo) and pass the hashed salt to the inner deploy_syscall as the contract_address_salt argument.

math

use openzeppelin_utils::math;

Module containing math utilities.

Members

Functions

• average(a, b)

Functions

average(a: T, b: T) → T function

Returns the average of two unsigned integers. The result is rounded down.

T is a generic value matching different numeric implementations.

contract_clock

use openzeppelin_utils::contract_clock;

Module providing a trait for the EIP-6372 standard along with default clock implementations based on either block number or block timestamp.

Traits

• ERC6372Clock

Implementations

• ERC6372BlockNumberClock
• ERC6372TimestampClock

ERC6372Clock github-icon

use openzeppelin_utils::contract_clock::ERC6372Clock;

A trait for the EIP-6372 standard that allows flexible internal clock implementation — based on block timestamp, block number, or a custom logic.

Functions

• clock()
• CLOCK_MODE()

Functions

clock() → u64 external

Returns the current timepoint determined by the contract’s operational mode, intended for use in time-sensitive logic.

Requirements:

• This function MUST always be non-decreasing.

CLOCK_MODE() → ByteArray external

Returns a description of the clock the contract is operating in.

Requirements:

• The output MUST be formatted like a URL query string, decodable in standard JavaScript.

Implementations

ERC6372BlockNumberClock impl

Implementation of the ERC6372Clock trait that uses the block number as its clock reference.

ERC6372TimestampClock impl

Implementation of the ERC6372Clock trait that uses the block timestamp as its clock reference.

serde

use openzeppelin_utils::serde;

Module containing utilities related to serialization and deserialization of Cairo data structures.

Members

Traits

• SerializedAppend

Traits

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.

Cryptography

NoncesComponent

use openzeppelin_utils::cryptography::nonces::NoncesComponent;

This component provides a simple mechanism for handling incremental nonces for a set of addresses. It is commonly used to prevent replay attacks when contracts accept signatures as input.

Embeddable Implementations

NoncesImpl

• nonces(self, owner)

Internal Implementations

InternalImpl

• use_nonce(self, owner)
• use_checked_nonce(self, owner, nonce)

Embeddable functions

nonces(self: @ContractState, owner: ContractAddress) → felt252 external

Returns the next unused nonce for an owner.

Internal functions

use_nonce(ref self: ComponentState, owner: ContractAddress) → felt252 internal

Consumes a nonce, returns the current value, and increments nonce.

For each account, the nonce has an initial value of 0, can only be incremented by one, and cannot be decremented or reset. This guarantees that the nonce never overflows.

use_checked_nonce(ref self: ComponentState, owner: ContractAddress, nonce: felt252) → felt252 internal

Same as use_nonce but checking that nonce is the next valid one for owner.

snip12

use openzeppelin_utils::snip12;

Supports on-chain generation of message hashes compliant with SNIP12.

For a full walkthrough on how to use this module, see the SNIP12 and Typed Messages guide.