CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-openzeppelin-solidity

Secure Smart Contract library providing battle-tested implementations of industry-standard Solidity contracts including ERC20, ERC721, ERC1155 tokens, access control mechanisms, proxy patterns, and governance systems for Ethereum and EVM-compatible blockchains.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

utilities.mddocs/

Utilities

OpenZeppelin Contracts provides a comprehensive set of utility functions including mathematical operations, cryptographic utilities, data structures, and helper functions essential for smart contract development.

Core Imports

Import utility contracts using Solidity import statements:

import "@openzeppelin/contracts/utils/Address.sol";
import "@openzeppelin/contracts/utils/Strings.sol";
import "@openzeppelin/contracts/utils/math/Math.sol";
import "@openzeppelin/contracts/utils/math/SignedMath.sol";
import "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
import "@openzeppelin/contracts/utils/cryptography/MerkleProof.sol";
import "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
import "@openzeppelin/contracts/utils/structs/EnumerableMap.sol";
import "@openzeppelin/contracts/utils/Counters.sol";
import "@openzeppelin/contracts/utils/Create2.sol";

Capabilities

Mathematical Operations

Comprehensive math utilities for safe arithmetic operations with various rounding modes and overflow protection.

library Math {
    function max(uint256 a, uint256 b) internal pure returns (uint256);
    function min(uint256 a, uint256 b) internal pure returns (uint256);
    function average(uint256 a, uint256 b) internal pure returns (uint256);
    function ceilDiv(uint256 a, uint256 b) internal pure returns (uint256);
    function mulDiv(uint256 x, uint256 y, uint256 denominator) internal pure returns (uint256);
    function mulDiv(uint256 x, uint256 y, uint256 denominator, Rounding rounding) internal pure returns (uint256);
    function sqrt(uint256 a) internal pure returns (uint256);
    function sqrt(uint256 a, Rounding rounding) internal pure returns (uint256);
    function log2(uint256 value) internal pure returns (uint256);
    function log2(uint256 value, Rounding rounding) internal pure returns (uint256);
    function log10(uint256 value) internal pure returns (uint256);
    function log10(uint256 value, Rounding rounding) internal pure returns (uint256);
    function log256(uint256 value) internal pure returns (uint256);
    function log256(uint256 value, Rounding rounding) internal pure returns (uint256);
}

enum Rounding {
    Down,
    Up,
    Zero
}

library SignedMath {
    function max(int256 a, int256 b) internal pure returns (int256);
    function min(int256 a, int256 b) internal pure returns (int256);
    function average(int256 a, int256 b) internal pure returns (int256);
    function abs(int256 n) internal pure returns (uint256);
}

Usage Example

pragma solidity ^0.8.0;

import "@openzeppelin/contracts/utils/math/Math.sol";

contract MathExample {
    function calculateReward(uint256 totalRewards, uint256 userStake, uint256 totalStake) 
        public pure returns (uint256) {
        // Safe multiplication and division to avoid overflow
        return Math.mulDiv(totalRewards, userStake, totalStake);
    }
    
    function calculateSqrt(uint256 value) public pure returns (uint256) {
        return Math.sqrt(value, Math.Rounding.Up);
    }
}

Address Utilities

Collection of functions for working with addresses, including contract detection and safe function calls.

library Address {
    function isContract(address account) internal view returns (bool);
    function sendValue(address payable recipient, uint256 amount) internal;
    function functionCall(address target, bytes memory data) internal returns (bytes memory);
    function functionCall(address target, bytes memory data, string memory errorMessage) internal returns (bytes memory);
    function functionCallWithValue(address target, bytes memory data, uint256 value) internal returns (bytes memory);
    function functionCallWithValue(address target, bytes memory data, uint256 value, string memory errorMessage) internal returns (bytes memory);
    function functionStaticCall(address target, bytes memory data) internal view returns (bytes memory);
    function functionStaticCall(address target, bytes memory data, string memory errorMessage) internal view returns (bytes memory);
    function functionDelegateCall(address target, bytes memory data) internal returns (bytes memory);
    function functionDelegateCall(address target, bytes memory data, string memory errorMessage) internal returns (bytes memory);
}

Usage Example

pragma solidity ^0.8.0;

import "@openzeppelin/contracts/utils/Address.sol";

contract AddressExample {
    using Address for address;
    
    function safeCall(address target, bytes calldata data) external {
        require(target.isContract(), "Target is not a contract");
        target.functionCall(data, "Call failed");
    }
    
    function sendEther(address payable recipient, uint256 amount) external {
        Address.sendValue(recipient, amount);
    }
}

String Utilities

String manipulation functions for converting between data types and string representations.

library Strings {
    function toString(uint256 value) internal pure returns (string memory);
    function toHexString(uint256 value) internal pure returns (string memory);
    function toHexString(uint256 value, uint256 length) internal pure returns (string memory);
    function toHexString(address addr) internal pure returns (string memory);
}

Usage Example

pragma solidity ^0.8.0;

import "@openzeppelin/contracts/utils/Strings.sol";

contract StringExample {
    function generateTokenURI(uint256 tokenId) external view returns (string memory) {
        return string(abi.encodePacked(
            "https://api.example.com/tokens/",
            Strings.toString(tokenId),
            ".json"
        ));
    }
}

Cryptographic Utilities

Essential cryptographic functions for signature verification, merkle proof validation, and hash operations.

library ECDSA {
    function recover(bytes32 hash, bytes memory signature) internal pure returns (address);
    function recover(bytes32 hash, bytes32 r, bytes32 vs) internal pure returns (address);
    function recover(bytes32 hash, uint8 v, bytes32 r, bytes32 s) internal pure returns (address);
    function toEthSignedMessageHash(bytes32 hash) internal pure returns (bytes32);
    function toEthSignedMessageHash(bytes memory message) internal pure returns (bytes32);
    function toTypedDataHash(bytes32 domainSeparator, bytes32 structHash) internal pure returns (bytes32);
}

library MerkleProof {
    function verify(bytes32[] memory proof, bytes32 root, bytes32 leaf) internal pure returns (bool);
    function verifyCalldata(bytes32[] calldata proof, bytes32 root, bytes32 leaf) internal pure returns (bool);
    function processProof(bytes32[] memory proof, bytes32 leaf) internal pure returns (bytes32);
    function processProofCalldata(bytes32[] calldata proof, bytes32 leaf) internal pure returns (bytes32);
    function multiProofVerify(bytes32[] memory proof, bool[] memory proofFlags, bytes32 root, bytes32[] memory leaves) internal pure returns (bool);
    function multiProofVerifyCalldata(bytes32[] calldata proof, bool[] calldata proofFlags, bytes32 root, bytes32[] memory leaves) internal pure returns (bool);
}

Usage Example

pragma solidity ^0.8.0;

import "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
import "@openzeppelin/contracts/utils/cryptography/MerkleProof.sol";

contract CryptoExample {
    using ECDSA for bytes32;
    
    bytes32 public merkleRoot;
    mapping(address => bool) public hasClaimed;
    
    function verifySignature(bytes32 hash, bytes memory signature, address signer) 
        public pure returns (bool) {
        return hash.recover(signature) == signer;
    }
    
    function claim(bytes32[] calldata proof, uint256 amount) external {
        require(!hasClaimed[msg.sender], "Already claimed");
        
        bytes32 leaf = keccak256(abi.encodePacked(msg.sender, amount));
        require(MerkleProof.verify(proof, merkleRoot, leaf), "Invalid proof");
        
        hasClaimed[msg.sender] = true;
        // Transfer tokens or execute claim logic
    }
}

Data Structures

Enumerable sets and maps providing gas-efficient storage and iteration capabilities.

library EnumerableSet {
    struct Bytes32Set { /* private */ }
    struct AddressSet { /* private */ }
    struct UintSet { /* private */ }
    
    function add(Bytes32Set storage set, bytes32 value) internal returns (bool);
    function remove(Bytes32Set storage set, bytes32 value) internal returns (bool);
    function contains(Bytes32Set storage set, bytes32 value) internal view returns (bool);
    function length(Bytes32Set storage set) internal view returns (uint256);
    function at(Bytes32Set storage set, uint256 index) internal view returns (bytes32);
    function values(Bytes32Set storage set) internal view returns (bytes32[] memory);
}

library EnumerableMap {
    struct Bytes32ToBytes32Map { /* private */ }
    struct UintToAddressMap { /* private */ }
    struct UintToUintMap { /* private */ }
    struct AddressToUintMap { /* private */ }
    struct Bytes32ToUintMap { /* private */ }
    
    function set(Bytes32ToBytes32Map storage map, bytes32 key, bytes32 value) internal returns (bool);
    function remove(Bytes32ToBytes32Map storage map, bytes32 key) internal returns (bool);
    function contains(Bytes32ToBytes32Map storage map, bytes32 key) internal view returns (bool);
    function length(Bytes32ToBytes32Map storage map) internal view returns (uint256);
    function at(Bytes32ToBytes32Map storage map, uint256 index) internal view returns (bytes32, bytes32);
    function tryGet(Bytes32ToBytes32Map storage map, bytes32 key) internal view returns (bool, bytes32);
    function get(Bytes32ToBytes32Map storage map, bytes32 key) internal view returns (bytes32);
}

Usage Example

pragma solidity ^0.8.0;

import "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";

contract SetExample {
    using EnumerableSet for EnumerableSet.AddressSet;
    
    EnumerableSet.AddressSet private admins;
    
    function addAdmin(address admin) external {
        admins.add(admin);
    }
    
    function removeAdmin(address admin) external {
        admins.remove(admin);
    }
    
    function isAdmin(address account) external view returns (bool) {
        return admins.contains(account);
    }
    
    function getAdminCount() external view returns (uint256) {
        return admins.length();
    }
    
    function getAllAdmins() external view returns (address[] memory) {
        return admins.values();
    }
}

Counters

Simple counter implementation that can only be incremented, decremented, or reset.

library Counters {
    struct Counter { /* private */ }
    
    function current(Counter storage counter) internal view returns (uint256);
    function increment(Counter storage counter) internal;
    function decrement(Counter storage counter) internal;
    function reset(Counter storage counter) internal;
}

CREATE2 Deployment

Helper functions for deterministic contract deployment using CREATE2 opcode.

library Create2 {
    function deploy(uint256 amount, bytes32 salt, bytes memory bytecode) internal returns (address);
    function computeAddress(bytes32 salt, bytes32 bytecodeHash) internal view returns (address);
    function computeAddress(bytes32 salt, bytes32 bytecodeHash, address deployer) internal pure returns (address);
}

Context and Introspection

Base context information and interface detection utilities.

abstract contract Context {
    function _msgSender() internal view virtual returns (address);
    function _msgData() internal view virtual returns (bytes calldata);
}

library ERC165Checker {
    function supportsERC165(address account) internal view returns (bool);
    function supportsInterface(address account, bytes4 interfaceId) internal view returns (bool);
    function getSupportedInterfaces(address account, bytes4[] memory interfaceIds) internal view returns (bool[] memory);
    function supportsAllInterfaces(address account, bytes4[] memory interfaceIds) internal view returns (bool);
}

Base64 Encoding

Base64 encoding utilities for data URI generation and off-chain compatibility.

library Base64 {
    function encode(bytes memory data) internal pure returns (string memory);
}

Multicall

Batch multiple function calls into a single transaction.

abstract contract Multicall {
    function multicall(bytes[] calldata data) external virtual returns (bytes[] memory results);
}

Type Casting Utilities

Safe type casting utilities preventing overflow/underflow issues when downcasting between different integer sizes.

library SafeCast {
    function toUint248(uint256 value) internal pure returns (uint248);
    function toUint240(uint256 value) internal pure returns (uint240);
    function toUint232(uint256 value) internal pure returns (uint232);
    function toUint224(uint256 value) internal pure returns (uint224);
    function toUint216(uint256 value) internal pure returns (uint216);
    function toUint208(uint256 value) internal pure returns (uint208);
    function toUint200(uint256 value) internal pure returns (uint200);
    function toUint192(uint256 value) internal pure returns (uint192);
    function toUint184(uint256 value) internal pure returns (uint184);
    function toUint176(uint256 value) internal pure returns (uint176);
    function toUint168(uint256 value) internal pure returns (uint168);
    function toUint160(uint256 value) internal pure returns (uint160);
    function toUint152(uint256 value) internal pure returns (uint152);
    function toUint144(uint256 value) internal pure returns (uint144);
    function toUint136(uint256 value) internal pure returns (uint136);
    function toUint128(uint256 value) internal pure returns (uint128);
    function toUint120(uint256 value) internal pure returns (uint120);
    function toUint112(uint256 value) internal pure returns (uint112);
    function toUint104(uint256 value) internal pure returns (uint104);
    function toUint96(uint256 value) internal pure returns (uint96);
    function toUint88(uint256 value) internal pure returns (uint88);
    function toUint80(uint256 value) internal pure returns (uint80);
    function toUint72(uint256 value) internal pure returns (uint72);
    function toUint64(uint256 value) internal pure returns (uint64);
    function toUint56(uint256 value) internal pure returns (uint56);
    function toUint48(uint256 value) internal pure returns (uint48);
    function toUint40(uint256 value) internal pure returns (uint40);
    function toUint32(uint256 value) internal pure returns (uint32);
    function toUint24(uint256 value) internal pure returns (uint24);
    function toUint16(uint256 value) internal pure returns (uint16);
    function toUint8(uint256 value) internal pure returns (uint8);
    function toInt248(int256 value) internal pure returns (int248);
    function toInt240(int256 value) internal pure returns (int240);
    function toInt232(int256 value) internal pure returns (int232);
    function toInt224(int256 value) internal pure returns (int224);
    function toInt216(int256 value) internal pure returns (int216);
    function toInt208(int256 value) internal pure returns (int208);
    function toInt200(int256 value) internal pure returns (int200);
    function toInt192(int256 value) internal pure returns (int192);
    function toInt184(int256 value) internal pure returns (int184);
    function toInt176(int256 value) internal pure returns (int176);
    function toInt168(int256 value) internal pure returns (int168);
    function toInt160(int256 value) internal pure returns (int160);
    function toInt152(int256 value) internal pure returns (int152);
    function toInt144(int256 value) internal pure returns (int144);
    function toInt136(int256 value) internal pure returns (int136);
    function toInt128(int256 value) internal pure returns (int128);
    function toInt120(int256 value) internal pure returns (int120);
    function toInt112(int256 value) internal pure returns (int112);
    function toInt104(int256 value) internal pure returns (int104);
    function toInt96(int256 value) internal pure returns (int96);
    function toInt88(int256 value) internal pure returns (int88);
    function toInt80(int256 value) internal pure returns (int80);
    function toInt72(int256 value) internal pure returns (int72);
    function toInt64(int256 value) internal pure returns (int64);
    function toInt56(int256 value) internal pure returns (int56);
    function toInt48(int256 value) internal pure returns (int48);
    function toInt40(int256 value) internal pure returns (int40);
    function toInt32(int256 value) internal pure returns (int32);
    function toInt24(int256 value) internal pure returns (int24);
    function toInt16(int256 value) internal pure returns (int16);
    function toInt8(int256 value) internal pure returns (int8);
    function toUint256(int256 value) internal pure returns (uint256);
}

Advanced Cryptographic Utilities

Extended cryptographic operations for structured data signing and signature validation.

library EIP712 {
    function _domainSeparatorV4() internal view returns (bytes32);
    function _hashTypedDataV4(bytes32 structHash) internal view virtual returns (bytes32);
    function _buildDomainSeparator(bytes32 typeHash, bytes32 nameHash, bytes32 versionHash) private view returns (bytes32);
}

library SignatureChecker {
    function isValidSignatureNow(address signer, bytes32 hash, bytes memory signature) internal view returns (bool);
}

Advanced Data Structures

Efficient data structures for specialized use cases requiring high performance and low gas usage.

library BitMaps {
    struct BitMap {
        mapping(uint256 => uint256) _data;
    }
    
    function get(BitMap storage bitmap, uint256 index) internal view returns (bool);
    function setTo(BitMap storage bitmap, uint256 index, bool value) internal;
    function set(BitMap storage bitmap, uint256 index) internal;
    function unset(BitMap storage bitmap, uint256 index) internal;
}

library DoubleEndedQueue {
    struct Bytes32Deque {
        int128 _begin;
        int128 _end;
        mapping(int128 => bytes32) _data;
    }
    
    function pushBack(Bytes32Deque storage deque, bytes32 value) internal;
    function popBack(Bytes32Deque storage deque) internal returns (bytes32 value);
    function pushFront(Bytes32Deque storage deque, bytes32 value) internal;
    function popFront(Bytes32Deque storage deque) internal returns (bytes32 value);
    function front(Bytes32Deque storage deque) internal view returns (bytes32 value);
    function back(Bytes32Deque storage deque) internal view returns (bytes32 value);
    function at(Bytes32Deque storage deque, uint256 index) internal view returns (bytes32 value);
    function clear(Bytes32Deque storage deque) internal;
    function length(Bytes32Deque storage deque) internal view returns (uint256);
    function empty(Bytes32Deque storage deque) internal view returns (bool);
}

Historical Data Management

Checkpoint system for tracking historical values with efficient querying for governance and voting systems.

library Checkpoints {
    struct History {
        Checkpoint[] _checkpoints;
    }
    
    struct Checkpoint {
        uint32 _blockNumber;
        uint224 _value;
    }
    
    function push(History storage self, uint256 value) internal returns (uint256, uint256);
    function getAtBlock(History storage self, uint256 blockNumber) internal view returns (uint256);
    function latest(History storage self) internal view returns (uint256);
    function length(History storage self) internal view returns (uint256);
}

Array Utilities

Efficient array operations including searching, sorting, and manipulation functions.

library Arrays {
    function findUpperBound(uint256[] storage array, uint256 element) internal view returns (uint256);
}

Storage Management

Low-level storage slot management utilities for upgradeable contracts and proxy patterns.

library StorageSlot {
    struct AddressSlot {
        address value;
    }
    
    struct BooleanSlot {
        bool value;
    }
    
    struct Bytes32Slot {
        bytes32 value;
    }
    
    struct Uint256Slot {
        uint256 value;
    }
    
    function getAddressSlot(bytes32 slot) internal pure returns (AddressSlot storage r);
    function getBooleanSlot(bytes32 slot) internal pure returns (BooleanSlot storage r);
    function getBytes32Slot(bytes32 slot) internal pure returns (Bytes32Slot storage r);
    function getUint256Slot(bytes32 slot) internal pure returns (Uint256Slot storage r);
}

Utility Best Practices

  1. Gas Efficiency: Use appropriate data structures based on your access patterns
  2. Safe Math: Always use OpenZeppelin's math utilities for overflow protection
  3. Address Validation: Check if addresses are contracts before making calls
  4. Signature Verification: Validate signatures properly using ECDSA utilities
  5. Merkle Proofs: Use merkle trees for efficient batch operations and airdrops
  6. Data Structures: Choose between sets and maps based on whether you need key-value storage

Error Handling

Utility libraries may revert with various errors:

  • ECDSA: ECDSAInvalidSignature(), ECDSAInvalidSignatureLength(uint256 length), ECDSAInvalidSignatureS(bytes32 s), ECDSAInvalidSignatureV(uint8 v)
  • Address: Various call-related errors depending on the target contract
  • Math: Overflow/underflow errors in older Solidity versions (handled automatically in 0.8+)

Install with Tessl CLI

npx tessl i tessl/npm-openzeppelin-solidity

docs

access-control.md

crosschain.md

finance.md

governance.md

index.md

metatx.md

proxy.md

security.md

tokens.md

utilities.md

tile.json