Utilities

Miscellaneous contracts containing utility functions, often related to working with different data types.

Contracts

Address

Collection of functions related to the address type

isContract(address account) → bool internal

Returns true if account is a contract.

It is unsafe to assume that an address for which this function returns false is an externally-owned account (EOA) and not a contract.

Among others, isContract will return false for the following types of addresses:

  • an externally-owned account

  • a contract in construction

  • an address where a contract will be created

  • an address where a contract lived, but was destroyed

toPayable(address account) → address payable internal

Converts an address into address payable. Note that this is simply a type cast: the actual underlying value is not changed.

Available since v2.4.0.

sendValue(address payable recipient, uint256 amount) internal

Replacement for Solidity’s transfer: sends amount wei to recipient, forwarding all available gas and reverting on errors.

EIP1884 increases the gas cost of certain opcodes, possibly making contracts go over the 2300 gas limit imposed by transfer, making them unable to receive funds via transfer. sendValue removes this limitation.

because control is transferred to recipient, care must be taken to not create reentrancy vulnerabilities. Consider using ReentrancyGuard or the checks-effects-interactions pattern.

Available since v2.4.0.

SafeCast

Wrappers over Solidity’s uintXX casting operators with added overflow checks.

Downcasting from uint256 in Solidity does not revert on overflow. This can easily result in undesired exploitation or bugs, since developers usually assume that overflows raise errors. SafeCast restores this intuition by reverting the transaction when such an operation overflows.

Using this library instead of the unchecked operations eliminates an entire class of bugs, so it’s recommended to use it always.

Can be combined with SafeMath to extend it to smaller types, by performing all math on uint256 and then downcasting.

Available since v2.5.0.

toUint128(uint256 value) → uint128 internal

Returns the downcasted uint128 from uint256, reverting on overflow (when the input is greater than largest uint128).

Counterpart to Solidity’s uint128 operator.

Requirements:

  • input must fit into 128 bits

toUint64(uint256 value) → uint64 internal

Returns the downcasted uint64 from uint256, reverting on overflow (when the input is greater than largest uint64).

Counterpart to Solidity’s uint64 operator.

Requirements:

  • input must fit into 64 bits

toUint32(uint256 value) → uint32 internal

Returns the downcasted uint32 from uint256, reverting on overflow (when the input is greater than largest uint32).

Counterpart to Solidity’s uint32 operator.

Requirements:

  • input must fit into 32 bits

toUint16(uint256 value) → uint16 internal

Returns the downcasted uint16 from uint256, reverting on overflow (when the input is greater than largest uint16).

Counterpart to Solidity’s uint16 operator.

Requirements:

  • input must fit into 16 bits

toUint8(uint256 value) → uint8 internal

Returns the downcasted uint8 from uint256, reverting on overflow (when the input is greater than largest uint8).

Counterpart to Solidity’s uint8 operator.

Requirements:

  • input must fit into 8 bits.

Arrays

Collection of functions related to array types.

findUpperBound(uint256[] array, uint256 element) → uint256 internal

Searches a sorted array and returns the first index that contains a value greater or equal to element. If no such index exists (i.e. all values in the array are strictly less than element), the array length is returned. Time complexity O(log n).

array is expected to be sorted in ascending order, and to contain no repeated elements.

EnumerableSet

Library for managing sets of primitive types.

Sets have the following properties:

  • Elements are added, removed, and checked for existence in constant time (O(1)).

  • Elements are enumerated in O(n). No guarantees are made on the ordering.

As of v2.5.0, only address sets are supported.

Include with using EnumerableSet for EnumerableSet.AddressSet;.

Available since v2.5.0.

add(struct EnumerableSet.AddressSet set, address value) → bool internal

Add a value to a set. O(1). Returns false if the value was already in the set.

remove(struct EnumerableSet.AddressSet set, address value) → bool internal

Removes a value from a set. O(1). Returns false if the value was not present in the set.

contains(struct EnumerableSet.AddressSet set, address value) → bool internal

Returns true if the value is in the set. O(1).

enumerate(struct EnumerableSet.AddressSet set) → address[] internal

Returns an array with all values in the set. O(N). Note that there are no guarantees on the ordering of values inside the array, and it may change when more values are added or removed. WARNING: This function may run out of gas on large sets: use length and get instead in these cases.

length(struct EnumerableSet.AddressSet set) → uint256 internal

Returns the number of elements on the set. O(1).

get(struct EnumerableSet.AddressSet set, uint256 index) → address internal

Returns the element stored at position index in the set. O(1). Note that there are no guarantees on the ordering of values inside the array, and it may change when more values are added or removed.

Requirements:

  • index must be strictly less than length.

Create2

Helper to make usage of the CREATE2 EVM opcode easier and safer. CREATE2 can be used to compute in advance the address where a smart contract will be deployed, which allows for interesting new mechanisms known as 'counterfactual interactions'.

See the EIP for more information.

Available since v2.5.0.

deploy(bytes32 salt, bytes bytecode) → address internal

Deploys a contract using CREATE2. The address where the contract will be deployed can be known in advance via computeAddress. Note that a contract cannot be deployed twice using the same salt.

computeAddress(bytes32 salt, bytes bytecode) → address internal

Returns the address where a contract will be stored if deployed via deploy. Any change in the bytecode or salt will result in a new destination address.

computeAddress(bytes32 salt, bytes bytecodeHash, address deployer) → address internal

Returns the address where a contract will be stored if deployed via deploy from a contract located at deployer. If deployer is this contract’s address, returns the same value as computeAddress.

ReentrancyGuard

Contract module that helps prevent reentrant calls to a function.

Inheriting from ReentrancyGuard will make the nonReentrant modifier available, which can be applied to functions to make sure there are no nested (reentrant) calls to them.

Note that because there is a single nonReentrant guard, functions marked as nonReentrant may not call one another. This can be worked around by making those functions private, and then adding external nonReentrant entry points to them.

If you would like to learn more about reentrancy and alternative ways to protect against it, check out our blog post Reentrancy After Istanbul.

Since v2.5.0: this module is now much more gas efficient, given net gas metering changes introduced in the Istanbul hardfork.

Modifiers
Functions

nonReentrant() modifier

Prevents a contract from calling itself, directly or indirectly. Calling a nonReentrant function from another nonReentrant function is not supported. It is possible to prevent this from happening by making the nonReentrant function external, and make it call a private function that does the actual work.

constructor() internal