Contract Name:
KillerWhalesS1
Contract Source Code:
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.19;
import "@openzeppelin/contracts/access/Ownable.sol";
import "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
///@notice The owner will always be a multisig wallet.
/* -------------------------------------------------------------------------- */
/* errors */
/* -------------------------------------------------------------------------- */
error InsufficientEth();
error EpisodeDoesNotExist();
error EpisodeAlreadyPurchased();
error NotOwnerOrAdmin();
error SignerCannotBeZeroAddress();
error InvalidSignature();
error VoucherExpired();
error CannotPurchaseWithoutSignerApproval();
error ErrWithdrawingETH();
/* -------------------------------------------------------------------------- */
/* KillerWhalesS1 */
/* -------------------------------------------------------------------------- */
/**
* @title Contract for purchasing episodes for Season 1 of KillerWhales using HelloToken
* @author 0xSimon
*/
contract KillerWhalesS1 is Ownable {
using ECDSA for bytes32;
/* -------------------------------------------------------------------------- */
/* events */
/* -------------------------------------------------------------------------- */
/**
* @notice emits when an episode is purchased by a user
*/
event EpisodesPurchased(address indexed user, uint256[] episode);
event SeasonPassPurchased(address indexed user);
event SignerChanged(address signer);
event SignerOnlyChanged(bool signerOnly);
event PricePerEpisodeChanged(uint256 pricePerEpisode);
/* -------------------------------------------------------------------------- */
/* statse */
/* -------------------------------------------------------------------------- */
/**
* @dev The max episodeID (i.e. available episodes 0, 1, ..., 4)
*/
uint256 private constant MAX_EPISODE_ID = 4;
/**
* @notice The Bitpos if a user owns the season pass
*/
uint256 private constant OWNS_SEASON_PASS_BITPOS = (1 << 255);
/**
* @notice The HelloToken contract
*/
IERC20 public immutable HELLO_TOKEN;
/**
* @notice The price per episode
*/
uint256 public pricePerEpisode = 1 ether;
/**
* @notice The signer providing signatures for discounts on episodes
*/
address public signer;
/**
* @notice if true, episodes can only be purchased through signatures
*/
bool public signerOnly;
/**
* @notice A mapping that stores purchased episodes for every user
* @dev Maps between an address to a bitmap that contains purchased episodes
* @dev Assumptions:
* - There are only 5 episodes in Season 1 therefore the bitmap can never overflow
* Examples:
* - If a user has purchased episode 0, the bitmap would look like:
* 00000001
* - If a user has purchased episodes 1 & 3, the bitmap would look like:
* 00001010
*/
mapping(address => uint256) public episodePurchasedBitmap;
/* -------------------------------------------------------------------------- */
/* constructor */
/* -------------------------------------------------------------------------- */
/**
* @notice Deploys the contract and saves the HelloToken contract address and the signer
* @dev `msg.sender` is assigned to the owner, pay attention if this contract is deployed via another contract
* @param _helloToken The address of HelloToken
* @param _signer Address of the discount signer
*/
constructor(address _helloToken, address _signer) {
HELLO_TOKEN = IERC20(_helloToken);
if (_signer == address(0)) {
_revert(SignerCannotBeZeroAddress.selector);
}
signer = _signer;
}
/* -------------------------------------------------------------------------- */
/* external */
/* -------------------------------------------------------------------------- */
/**
* @notice Purchase episodes without discount
* @notice HelloTokens will be transferred to this contract
* @notice Ensure approvals for HelloToken has been set
* @param episodeIds the episodeIDs to be purchased
* @dev Reverts if the any of the episodes in the argument has been purchased already
* @dev Reverts if the any of the episodes in the argument does not exist (i.e. > MAX_EPISODE_ID)
*/
function purchaseEpisodesNoDiscount(uint256[] calldata episodeIds) external {
if (signerOnly) {
_revert(CannotPurchaseWithoutSignerApproval.selector);
}
// calculate total price
uint256 __totalPrice = episodeIds.length * pricePerEpisode;
// update state
_grantEpisodes(msg.sender, episodeIds);
// transfer tokens
HELLO_TOKEN.transferFrom(msg.sender, address(this), __totalPrice);
}
/**
* @notice Purchase espidoes with discount
* @notice HelloTokens will be transferred to this contract
* @notice Ensure approvals for HelloToken has been set
* @param episodeIds the episodeIDs to be purchased
* @param _discount the discount to be applied in basisPoint (e.g. 500 for 5% discount)
* @param _expirationTimestamp the expiration timestamp for which this discount can be applied
* @param signature the signature signed by `signer`
*/
function purchaseEpisodeWithDiscount(
uint256[] calldata episodeIds,
uint256 _discount,
uint256 _expirationTimestamp,
bytes calldata signature
) external {
if (signerOnly) {
_revert(CannotPurchaseWithoutSignerApproval.selector);
}
// check signature
_checkDiscountSignature(episodeIds, _discount, _expirationTimestamp, signature);
// calculate total price - discount
uint256 __totalPrice = episodeIds.length * pricePerEpisode * (10_000 - _discount) / 10_000;
// update state
_grantEpisodes(msg.sender, episodeIds);
// transfer tokens
HELLO_TOKEN.transferFrom(msg.sender, address(this), __totalPrice);
}
/// @notice Purchase episodes with a total price and signature
/// @notice HelloTokens will be transferred to this contract
/// @notice grant episodes to the user
/// @param episodeIds the episodeIDs to be purchased
/// @param totalPrice the total price of the episodes
/// @param _expirationTimestamp the expiration timestamp for which this price is applied
/// @param signature the signature signed by `signer`
function purchaseEpisodesSignatureOnly(
uint256[] calldata episodeIds,
uint256 totalPrice,
uint256 _expirationTimestamp,
bytes calldata signature
) external {
// check signature
_checkTotalPriceSignature(episodeIds, totalPrice, _expirationTimestamp, signature);
// update state
_grantEpisodes(msg.sender, episodeIds);
// transfer tokens
HELLO_TOKEN.transferFrom(msg.sender, address(this), totalPrice);
}
/* -------------------------------------------------------------------------- */
/* owner */
/* -------------------------------------------------------------------------- */
/**
* @notice Owner only - Updates the address of the discount signer
* @param _signer Address of the discount signer
*/
function setSigner(address _signer) external onlyOwner {
if (_signer == address(0)) {
_revert(SignerCannotBeZeroAddress.selector);
}
signer = _signer;
emit SignerChanged(_signer);
}
/**
* @notice Owner only - Updates the signerOnly flag
* @param _signerOnly if true, episodes can only be purchased through signatures
*/
function setSignerOnly(bool _signerOnly) external onlyOwner {
signerOnly = _signerOnly;
emit SignerOnlyChanged(_signerOnly);
}
/**
* @notice Owner only - Updates the price per episode
* @param _price Price per episode
*/
function setPricePerEpisode(uint256 _price) external onlyOwner {
pricePerEpisode = _price;
emit PricePerEpisodeChanged(_price);
}
/**
* @notice sends all the eth in the contract to the owner
*/
function withdrawETH() external onlyOwner {
(bool os,) = payable(msg.sender).call{value: address(this).balance}("");
if (!os) revert ErrWithdrawingETH();
}
/**
* @notice sends the balance of this contract's `erc20` balance to the owner
* @param erc20 - the token address to claim from
*/
function withdrawERC20(address erc20) external onlyOwner {
IERC20 token = IERC20(erc20);
token.transfer(msg.sender, token.balanceOf(address(this)));
}
/* -------------------------------------------------------------------------- */
/* views */
/* -------------------------------------------------------------------------- */
/**
* @notice Returns the episodes purchased by the supplied address
* @param account The address to check
*/
function episodesOfOwner(address account) external view returns (uint256[] memory) {
uint256[] memory episodes = new uint256[](MAX_EPISODE_ID + 1);
uint256 map = episodePurchasedBitmap[account];
uint256 count;
assembly {
let i := 0
let len := add(MAX_EPISODE_ID, 1)
for {} lt(i, len) { i := add(i, 1) } {
// Check if the bit is set
if gt(and(map, shl(i, 1)), 0) {
count := add(count, 1)
mstore(add(episodes, mul(count, 0x20)), i)
}
}
}
// Resizing the array according to the count
assembly {
mstore(episodes, count)
}
return episodes;
}
function isSeasonPassHolder(address account) external view returns (bool) {
return _isSeasonPassHolder(episodePurchasedBitmap[account]);
}
function _isSeasonPassHolder(uint256 bitmap) internal pure returns (bool) {
return (bitmap & OWNS_SEASON_PASS_BITPOS) != 0;
}
/**
* @notice Returns whether an episode has been purchased by the supplied address
* @param account The address to check
* @param account The episodeId to check
* @dev Reverts if an episode does not exist (i.e. > MAX_EPISODE_ID)
*/
function ownsEpisode(address account, uint256 episodeId) external view returns (bool) {
if (episodeId > MAX_EPISODE_ID) {
_revert(EpisodeDoesNotExist.selector);
}
uint256 map = episodePurchasedBitmap[account];
if (_isSeasonPassHolder(map)) {
return true;
}
return (map & (1 << episodeId)) != 0;
}
/* -------------------------------------------------------------------------- */
/* internal */
/* -------------------------------------------------------------------------- */
function _revert(bytes4 code) internal pure {
assembly {
mstore(0x0, code)
revert(0x0, 0x04)
}
}
/**
* @dev Checks whether a signature is valid for discount on purchase
* @dev Reverts if now > expirationTimestamp
* @dev Reverts if the signature is invalid
* @param _discount the discount in basis point (e.g. 500 for 5% discount)
* @param _expirationTimestamp the expiration timestamp for which this discount can be applied
* @param signature the signature
*/
function _checkDiscountSignature(
uint256[] memory episodeIds,
uint256 _discount,
uint256 _expirationTimestamp,
bytes memory signature
) internal view {
bytes32 hash = keccak256(
abi.encodePacked(
msg.sender, episodeIds, _discount, block.chainid, address(this), _expirationTimestamp, "discount"
)
);
if (block.timestamp > _expirationTimestamp) {
_revert(VoucherExpired.selector);
}
if (hash.toEthSignedMessageHash().recover(signature) != signer) {
_revert(InvalidSignature.selector);
}
}
/**
* @dev Checks whether a signature is valid for price on purchase
* @dev Reverts if now > expirationTimestamp
* @dev Reverts if the signature is invalid
* @param _totalPrice the total price for all the episodes
* @param _expirationTimestamp the expiration timestamp for which this discount can be applied
* @param signature the signature
*/
function _checkTotalPriceSignature(
uint256[] memory episodeIds,
uint256 _totalPrice,
uint256 _expirationTimestamp,
bytes memory signature
) internal view {
bytes32 hash = keccak256(
abi.encodePacked(
msg.sender, episodeIds, _totalPrice, block.chainid, address(this), _expirationTimestamp, "totalPrice"
)
);
if (block.timestamp > _expirationTimestamp) {
_revert(VoucherExpired.selector);
}
if (hash.toEthSignedMessageHash().recover(signature) != signer) {
_revert(InvalidSignature.selector);
}
}
/**
* @dev Updates episodePurchasedBitmap for a user
* @dev Reverts if any of the episodes does not exist
* @dev Reverts if any of the episodes has been been purchased
* @param user the address to be updated
* @param episodeIds the IDs of the purchased episodes
*/
function _grantEpisodes(address user, uint256[] memory episodeIds) internal {
uint256 existingEpisodeBitmap = episodePurchasedBitmap[user];
uint256 newEpisodeBitmap = existingEpisodeBitmap;
// loop, check episodeId
for (uint256 i; i < episodeIds.length;) {
uint256 episodeId = episodeIds[i];
// episode doesn't exist
if (episodeId > MAX_EPISODE_ID) {
_revert(EpisodeDoesNotExist.selector);
}
uint256 shiftedEpisodeId = 1 << episodeId;
//buying 5 episodes is equivalent to buying the season pass, therefore, the episode CAN be repurchased only in this specific case.
if (episodeIds.length != MAX_EPISODE_ID + 1) {
// episode already purchased
if ((existingEpisodeBitmap & shiftedEpisodeId) != 0) {
_revert(EpisodeAlreadyPurchased.selector);
}
}
// update bitmap
newEpisodeBitmap |= shiftedEpisodeId;
// next loop
unchecked {
++i;
}
}
// got all episodes => season pass
if (episodeIds.length == MAX_EPISODE_ID + 1) {
newEpisodeBitmap |= OWNS_SEASON_PASS_BITPOS;
emit SeasonPassPurchased(user);
}
// update
episodePurchasedBitmap[user] = newEpisodeBitmap;
emit EpisodesPurchased(user, episodeIds);
}
}
// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v4.7.0) (access/Ownable.sol)
pragma solidity ^0.8.0;
import "../utils/Context.sol";
/**
* @dev Contract module which provides a basic access control mechanism, where
* there is an account (an owner) that can be granted exclusive access to
* specific functions.
*
* By default, the owner account will be the one that deploys the contract. This
* can later be changed with {transferOwnership}.
*
* This module is used through inheritance. It will make available the modifier
* `onlyOwner`, which can be applied to your functions to restrict their use to
* the owner.
*/
abstract contract Ownable is Context {
address private _owner;
event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);
/**
* @dev Initializes the contract setting the deployer as the initial owner.
*/
constructor() {
_transferOwnership(_msgSender());
}
/**
* @dev Throws if called by any account other than the owner.
*/
modifier onlyOwner() {
_checkOwner();
_;
}
/**
* @dev Returns the address of the current owner.
*/
function owner() public view virtual returns (address) {
return _owner;
}
/**
* @dev Throws if the sender is not the owner.
*/
function _checkOwner() internal view virtual {
require(owner() == _msgSender(), "Ownable: caller is not the owner");
}
/**
* @dev Leaves the contract without owner. It will not be possible to call
* `onlyOwner` functions anymore. Can only be called by the current owner.
*
* NOTE: Renouncing ownership will leave the contract without an owner,
* thereby removing any functionality that is only available to the owner.
*/
function renounceOwnership() public virtual onlyOwner {
_transferOwnership(address(0));
}
/**
* @dev Transfers ownership of the contract to a new account (`newOwner`).
* Can only be called by the current owner.
*/
function transferOwnership(address newOwner) public virtual onlyOwner {
require(newOwner != address(0), "Ownable: new owner is the zero address");
_transferOwnership(newOwner);
}
/**
* @dev Transfers ownership of the contract to a new account (`newOwner`).
* Internal function without access restriction.
*/
function _transferOwnership(address newOwner) internal virtual {
address oldOwner = _owner;
_owner = newOwner;
emit OwnershipTransferred(oldOwner, newOwner);
}
}
// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v4.8.0) (utils/cryptography/ECDSA.sol)
pragma solidity ^0.8.0;
import "../Strings.sol";
/**
* @dev Elliptic Curve Digital Signature Algorithm (ECDSA) operations.
*
* These functions can be used to verify that a message was signed by the holder
* of the private keys of a given address.
*/
library ECDSA {
enum RecoverError {
NoError,
InvalidSignature,
InvalidSignatureLength,
InvalidSignatureS,
InvalidSignatureV // Deprecated in v4.8
}
function _throwError(RecoverError error) private pure {
if (error == RecoverError.NoError) {
return; // no error: do nothing
} else if (error == RecoverError.InvalidSignature) {
revert("ECDSA: invalid signature");
} else if (error == RecoverError.InvalidSignatureLength) {
revert("ECDSA: invalid signature length");
} else if (error == RecoverError.InvalidSignatureS) {
revert("ECDSA: invalid signature 's' value");
}
}
/**
* @dev Returns the address that signed a hashed message (`hash`) with
* `signature` or error string. This address can then be used for verification purposes.
*
* The `ecrecover` EVM opcode allows for malleable (non-unique) signatures:
* this function rejects them by requiring the `s` value to be in the lower
* half order, and the `v` value to be either 27 or 28.
*
* IMPORTANT: `hash` _must_ be the result of a hash operation for the
* verification to be secure: it is possible to craft signatures that
* recover to arbitrary addresses for non-hashed data. A safe way to ensure
* this is by receiving a hash of the original message (which may otherwise
* be too long), and then calling {toEthSignedMessageHash} on it.
*
* Documentation for signature generation:
* - with https://web3js.readthedocs.io/en/v1.3.4/web3-eth-accounts.html#sign[Web3.js]
* - with https://docs.ethers.io/v5/api/signer/#Signer-signMessage[ethers]
*
* _Available since v4.3._
*/
function tryRecover(bytes32 hash, bytes memory signature) internal pure returns (address, RecoverError) {
if (signature.length == 65) {
bytes32 r;
bytes32 s;
uint8 v;
// ecrecover takes the signature parameters, and the only way to get them
// currently is to use assembly.
/// @solidity memory-safe-assembly
assembly {
r := mload(add(signature, 0x20))
s := mload(add(signature, 0x40))
v := byte(0, mload(add(signature, 0x60)))
}
return tryRecover(hash, v, r, s);
} else {
return (address(0), RecoverError.InvalidSignatureLength);
}
}
/**
* @dev Returns the address that signed a hashed message (`hash`) with
* `signature`. This address can then be used for verification purposes.
*
* The `ecrecover` EVM opcode allows for malleable (non-unique) signatures:
* this function rejects them by requiring the `s` value to be in the lower
* half order, and the `v` value to be either 27 or 28.
*
* IMPORTANT: `hash` _must_ be the result of a hash operation for the
* verification to be secure: it is possible to craft signatures that
* recover to arbitrary addresses for non-hashed data. A safe way to ensure
* this is by receiving a hash of the original message (which may otherwise
* be too long), and then calling {toEthSignedMessageHash} on it.
*/
function recover(bytes32 hash, bytes memory signature) internal pure returns (address) {
(address recovered, RecoverError error) = tryRecover(hash, signature);
_throwError(error);
return recovered;
}
/**
* @dev Overload of {ECDSA-tryRecover} that receives the `r` and `vs` short-signature fields separately.
*
* See https://eips.ethereum.org/EIPS/eip-2098[EIP-2098 short signatures]
*
* _Available since v4.3._
*/
function tryRecover(
bytes32 hash,
bytes32 r,
bytes32 vs
) internal pure returns (address, RecoverError) {
bytes32 s = vs & bytes32(0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff);
uint8 v = uint8((uint256(vs) >> 255) + 27);
return tryRecover(hash, v, r, s);
}
/**
* @dev Overload of {ECDSA-recover} that receives the `r and `vs` short-signature fields separately.
*
* _Available since v4.2._
*/
function recover(
bytes32 hash,
bytes32 r,
bytes32 vs
) internal pure returns (address) {
(address recovered, RecoverError error) = tryRecover(hash, r, vs);
_throwError(error);
return recovered;
}
/**
* @dev Overload of {ECDSA-tryRecover} that receives the `v`,
* `r` and `s` signature fields separately.
*
* _Available since v4.3._
*/
function tryRecover(
bytes32 hash,
uint8 v,
bytes32 r,
bytes32 s
) internal pure returns (address, RecoverError) {
// EIP-2 still allows signature malleability for ecrecover(). Remove this possibility and make the signature
// unique. Appendix F in the Ethereum Yellow paper (https://ethereum.github.io/yellowpaper/paper.pdf), defines
// the valid range for s in (301): 0 < s < secp256k1n ÷ 2 + 1, and for v in (302): v ∈ {27, 28}. Most
// signatures from current libraries generate a unique signature with an s-value in the lower half order.
//
// If your library generates malleable signatures, such as s-values in the upper range, calculate a new s-value
// with 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141 - s1 and flip v from 27 to 28 or
// vice versa. If your library also generates signatures with 0/1 for v instead 27/28, add 27 to v to accept
// these malleable signatures as well.
if (uint256(s) > 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0) {
return (address(0), RecoverError.InvalidSignatureS);
}
// If the signature is valid (and not malleable), return the signer address
address signer = ecrecover(hash, v, r, s);
if (signer == address(0)) {
return (address(0), RecoverError.InvalidSignature);
}
return (signer, RecoverError.NoError);
}
/**
* @dev Overload of {ECDSA-recover} that receives the `v`,
* `r` and `s` signature fields separately.
*/
function recover(
bytes32 hash,
uint8 v,
bytes32 r,
bytes32 s
) internal pure returns (address) {
(address recovered, RecoverError error) = tryRecover(hash, v, r, s);
_throwError(error);
return recovered;
}
/**
* @dev Returns an Ethereum Signed Message, created from a `hash`. This
* produces hash corresponding to the one signed with the
* https://eth.wiki/json-rpc/API#eth_sign[`eth_sign`]
* JSON-RPC method as part of EIP-191.
*
* See {recover}.
*/
function toEthSignedMessageHash(bytes32 hash) internal pure returns (bytes32) {
// 32 is the length in bytes of hash,
// enforced by the type signature above
return keccak256(abi.encodePacked("\x19Ethereum Signed Message:\n32", hash));
}
/**
* @dev Returns an Ethereum Signed Message, created from `s`. This
* produces hash corresponding to the one signed with the
* https://eth.wiki/json-rpc/API#eth_sign[`eth_sign`]
* JSON-RPC method as part of EIP-191.
*
* See {recover}.
*/
function toEthSignedMessageHash(bytes memory s) internal pure returns (bytes32) {
return keccak256(abi.encodePacked("\x19Ethereum Signed Message:\n", Strings.toString(s.length), s));
}
/**
* @dev Returns an Ethereum Signed Typed Data, created from a
* `domainSeparator` and a `structHash`. This produces hash corresponding
* to the one signed with the
* https://eips.ethereum.org/EIPS/eip-712[`eth_signTypedData`]
* JSON-RPC method as part of EIP-712.
*
* See {recover}.
*/
function toTypedDataHash(bytes32 domainSeparator, bytes32 structHash) internal pure returns (bytes32) {
return keccak256(abi.encodePacked("\x19\x01", domainSeparator, structHash));
}
}
// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v4.6.0) (token/ERC20/IERC20.sol)
pragma solidity ^0.8.0;
/**
* @dev Interface of the ERC20 standard as defined in the EIP.
*/
interface IERC20 {
/**
* @dev Emitted when `value` tokens are moved from one account (`from`) to
* another (`to`).
*
* Note that `value` may be zero.
*/
event Transfer(address indexed from, address indexed to, uint256 value);
/**
* @dev Emitted when the allowance of a `spender` for an `owner` is set by
* a call to {approve}. `value` is the new allowance.
*/
event Approval(address indexed owner, address indexed spender, uint256 value);
/**
* @dev Returns the amount of tokens in existence.
*/
function totalSupply() external view returns (uint256);
/**
* @dev Returns the amount of tokens owned by `account`.
*/
function balanceOf(address account) external view returns (uint256);
/**
* @dev Moves `amount` tokens from the caller's account to `to`.
*
* Returns a boolean value indicating whether the operation succeeded.
*
* Emits a {Transfer} event.
*/
function transfer(address to, uint256 amount) external returns (bool);
/**
* @dev Returns the remaining number of tokens that `spender` will be
* allowed to spend on behalf of `owner` through {transferFrom}. This is
* zero by default.
*
* This value changes when {approve} or {transferFrom} are called.
*/
function allowance(address owner, address spender) external view returns (uint256);
/**
* @dev Sets `amount` as the allowance of `spender` over the caller's tokens.
*
* Returns a boolean value indicating whether the operation succeeded.
*
* IMPORTANT: Beware that changing an allowance with this method brings the risk
* that someone may use both the old and the new allowance by unfortunate
* transaction ordering. One possible solution to mitigate this race
* condition is to first reduce the spender's allowance to 0 and set the
* desired value afterwards:
* https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729
*
* Emits an {Approval} event.
*/
function approve(address spender, uint256 amount) external returns (bool);
/**
* @dev Moves `amount` tokens from `from` to `to` using the
* allowance mechanism. `amount` is then deducted from the caller's
* allowance.
*
* Returns a boolean value indicating whether the operation succeeded.
*
* Emits a {Transfer} event.
*/
function transferFrom(
address from,
address to,
uint256 amount
) external returns (bool);
}
// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts v4.4.1 (utils/Context.sol)
pragma solidity ^0.8.0;
/**
* @dev Provides information about the current execution context, including the
* sender of the transaction and its data. While these are generally available
* via msg.sender and msg.data, they should not be accessed in such a direct
* manner, since when dealing with meta-transactions the account sending and
* paying for execution may not be the actual sender (as far as an application
* is concerned).
*
* This contract is only required for intermediate, library-like contracts.
*/
abstract contract Context {
function _msgSender() internal view virtual returns (address) {
return msg.sender;
}
function _msgData() internal view virtual returns (bytes calldata) {
return msg.data;
}
}
// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v4.8.0) (utils/Strings.sol)
pragma solidity ^0.8.0;
import "./math/Math.sol";
/**
* @dev String operations.
*/
library Strings {
bytes16 private constant _SYMBOLS = "0123456789abcdef";
uint8 private constant _ADDRESS_LENGTH = 20;
/**
* @dev Converts a `uint256` to its ASCII `string` decimal representation.
*/
function toString(uint256 value) internal pure returns (string memory) {
unchecked {
uint256 length = Math.log10(value) + 1;
string memory buffer = new string(length);
uint256 ptr;
/// @solidity memory-safe-assembly
assembly {
ptr := add(buffer, add(32, length))
}
while (true) {
ptr--;
/// @solidity memory-safe-assembly
assembly {
mstore8(ptr, byte(mod(value, 10), _SYMBOLS))
}
value /= 10;
if (value == 0) break;
}
return buffer;
}
}
/**
* @dev Converts a `uint256` to its ASCII `string` hexadecimal representation.
*/
function toHexString(uint256 value) internal pure returns (string memory) {
unchecked {
return toHexString(value, Math.log256(value) + 1);
}
}
/**
* @dev Converts a `uint256` to its ASCII `string` hexadecimal representation with fixed length.
*/
function toHexString(uint256 value, uint256 length) internal pure returns (string memory) {
bytes memory buffer = new bytes(2 * length + 2);
buffer[0] = "0";
buffer[1] = "x";
for (uint256 i = 2 * length + 1; i > 1; --i) {
buffer[i] = _SYMBOLS[value & 0xf];
value >>= 4;
}
require(value == 0, "Strings: hex length insufficient");
return string(buffer);
}
/**
* @dev Converts an `address` with fixed length of 20 bytes to its not checksummed ASCII `string` hexadecimal representation.
*/
function toHexString(address addr) internal pure returns (string memory) {
return toHexString(uint256(uint160(addr)), _ADDRESS_LENGTH);
}
}
// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v4.8.0) (utils/math/Math.sol)
pragma solidity ^0.8.0;
/**
* @dev Standard math utilities missing in the Solidity language.
*/
library Math {
enum Rounding {
Down, // Toward negative infinity
Up, // Toward infinity
Zero // Toward zero
}
/**
* @dev Returns the largest of two numbers.
*/
function max(uint256 a, uint256 b) internal pure returns (uint256) {
return a > b ? a : b;
}
/**
* @dev Returns the smallest of two numbers.
*/
function min(uint256 a, uint256 b) internal pure returns (uint256) {
return a < b ? a : b;
}
/**
* @dev Returns the average of two numbers. The result is rounded towards
* zero.
*/
function average(uint256 a, uint256 b) internal pure returns (uint256) {
// (a + b) / 2 can overflow.
return (a & b) + (a ^ b) / 2;
}
/**
* @dev Returns the ceiling of the division of two numbers.
*
* This differs from standard division with `/` in that it rounds up instead
* of rounding down.
*/
function ceilDiv(uint256 a, uint256 b) internal pure returns (uint256) {
// (a + b - 1) / b can overflow on addition, so we distribute.
return a == 0 ? 0 : (a - 1) / b + 1;
}
/**
* @notice Calculates floor(x * y / denominator) with full precision. Throws if result overflows a uint256 or denominator == 0
* @dev Original credit to Remco Bloemen under MIT license (https://xn--2-umb.com/21/muldiv)
* with further edits by Uniswap Labs also under MIT license.
*/
function mulDiv(
uint256 x,
uint256 y,
uint256 denominator
) internal pure returns (uint256 result) {
unchecked {
// 512-bit multiply [prod1 prod0] = x * y. Compute the product mod 2^256 and mod 2^256 - 1, then use
// use the Chinese Remainder Theorem to reconstruct the 512 bit result. The result is stored in two 256
// variables such that product = prod1 * 2^256 + prod0.
uint256 prod0; // Least significant 256 bits of the product
uint256 prod1; // Most significant 256 bits of the product
assembly {
let mm := mulmod(x, y, not(0))
prod0 := mul(x, y)
prod1 := sub(sub(mm, prod0), lt(mm, prod0))
}
// Handle non-overflow cases, 256 by 256 division.
if (prod1 == 0) {
return prod0 / denominator;
}
// Make sure the result is less than 2^256. Also prevents denominator == 0.
require(denominator > prod1);
///////////////////////////////////////////////
// 512 by 256 division.
///////////////////////////////////////////////
// Make division exact by subtracting the remainder from [prod1 prod0].
uint256 remainder;
assembly {
// Compute remainder using mulmod.
remainder := mulmod(x, y, denominator)
// Subtract 256 bit number from 512 bit number.
prod1 := sub(prod1, gt(remainder, prod0))
prod0 := sub(prod0, remainder)
}
// Factor powers of two out of denominator and compute largest power of two divisor of denominator. Always >= 1.
// See https://cs.stackexchange.com/q/138556/92363.
// Does not overflow because the denominator cannot be zero at this stage in the function.
uint256 twos = denominator & (~denominator + 1);
assembly {
// Divide denominator by twos.
denominator := div(denominator, twos)
// Divide [prod1 prod0] by twos.
prod0 := div(prod0, twos)
// Flip twos such that it is 2^256 / twos. If twos is zero, then it becomes one.
twos := add(div(sub(0, twos), twos), 1)
}
// Shift in bits from prod1 into prod0.
prod0 |= prod1 * twos;
// Invert denominator mod 2^256. Now that denominator is an odd number, it has an inverse modulo 2^256 such
// that denominator * inv = 1 mod 2^256. Compute the inverse by starting with a seed that is correct for
// four bits. That is, denominator * inv = 1 mod 2^4.
uint256 inverse = (3 * denominator) ^ 2;
// Use the Newton-Raphson iteration to improve the precision. Thanks to Hensel's lifting lemma, this also works
// in modular arithmetic, doubling the correct bits in each step.
inverse *= 2 - denominator * inverse; // inverse mod 2^8
inverse *= 2 - denominator * inverse; // inverse mod 2^16
inverse *= 2 - denominator * inverse; // inverse mod 2^32
inverse *= 2 - denominator * inverse; // inverse mod 2^64
inverse *= 2 - denominator * inverse; // inverse mod 2^128
inverse *= 2 - denominator * inverse; // inverse mod 2^256
// Because the division is now exact we can divide by multiplying with the modular inverse of denominator.
// This will give us the correct result modulo 2^256. Since the preconditions guarantee that the outcome is
// less than 2^256, this is the final result. We don't need to compute the high bits of the result and prod1
// is no longer required.
result = prod0 * inverse;
return result;
}
}
/**
* @notice Calculates x * y / denominator with full precision, following the selected rounding direction.
*/
function mulDiv(
uint256 x,
uint256 y,
uint256 denominator,
Rounding rounding
) internal pure returns (uint256) {
uint256 result = mulDiv(x, y, denominator);
if (rounding == Rounding.Up && mulmod(x, y, denominator) > 0) {
result += 1;
}
return result;
}
/**
* @dev Returns the square root of a number. If the number is not a perfect square, the value is rounded down.
*
* Inspired by Henry S. Warren, Jr.'s "Hacker's Delight" (Chapter 11).
*/
function sqrt(uint256 a) internal pure returns (uint256) {
if (a == 0) {
return 0;
}
// For our first guess, we get the biggest power of 2 which is smaller than the square root of the target.
//
// We know that the "msb" (most significant bit) of our target number `a` is a power of 2 such that we have
// `msb(a) <= a < 2*msb(a)`. This value can be written `msb(a)=2**k` with `k=log2(a)`.
//
// This can be rewritten `2**log2(a) <= a < 2**(log2(a) + 1)`
// → `sqrt(2**k) <= sqrt(a) < sqrt(2**(k+1))`
// → `2**(k/2) <= sqrt(a) < 2**((k+1)/2) <= 2**(k/2 + 1)`
//
// Consequently, `2**(log2(a) / 2)` is a good first approximation of `sqrt(a)` with at least 1 correct bit.
uint256 result = 1 << (log2(a) >> 1);
// At this point `result` is an estimation with one bit of precision. We know the true value is a uint128,
// since it is the square root of a uint256. Newton's method converges quadratically (precision doubles at
// every iteration). We thus need at most 7 iteration to turn our partial result with one bit of precision
// into the expected uint128 result.
unchecked {
result = (result + a / result) >> 1;
result = (result + a / result) >> 1;
result = (result + a / result) >> 1;
result = (result + a / result) >> 1;
result = (result + a / result) >> 1;
result = (result + a / result) >> 1;
result = (result + a / result) >> 1;
return min(result, a / result);
}
}
/**
* @notice Calculates sqrt(a), following the selected rounding direction.
*/
function sqrt(uint256 a, Rounding rounding) internal pure returns (uint256) {
unchecked {
uint256 result = sqrt(a);
return result + (rounding == Rounding.Up && result * result < a ? 1 : 0);
}
}
/**
* @dev Return the log in base 2, rounded down, of a positive value.
* Returns 0 if given 0.
*/
function log2(uint256 value) internal pure returns (uint256) {
uint256 result = 0;
unchecked {
if (value >> 128 > 0) {
value >>= 128;
result += 128;
}
if (value >> 64 > 0) {
value >>= 64;
result += 64;
}
if (value >> 32 > 0) {
value >>= 32;
result += 32;
}
if (value >> 16 > 0) {
value >>= 16;
result += 16;
}
if (value >> 8 > 0) {
value >>= 8;
result += 8;
}
if (value >> 4 > 0) {
value >>= 4;
result += 4;
}
if (value >> 2 > 0) {
value >>= 2;
result += 2;
}
if (value >> 1 > 0) {
result += 1;
}
}
return result;
}
/**
* @dev Return the log in base 2, following the selected rounding direction, of a positive value.
* Returns 0 if given 0.
*/
function log2(uint256 value, Rounding rounding) internal pure returns (uint256) {
unchecked {
uint256 result = log2(value);
return result + (rounding == Rounding.Up && 1 << result < value ? 1 : 0);
}
}
/**
* @dev Return the log in base 10, rounded down, of a positive value.
* Returns 0 if given 0.
*/
function log10(uint256 value) internal pure returns (uint256) {
uint256 result = 0;
unchecked {
if (value >= 10**64) {
value /= 10**64;
result += 64;
}
if (value >= 10**32) {
value /= 10**32;
result += 32;
}
if (value >= 10**16) {
value /= 10**16;
result += 16;
}
if (value >= 10**8) {
value /= 10**8;
result += 8;
}
if (value >= 10**4) {
value /= 10**4;
result += 4;
}
if (value >= 10**2) {
value /= 10**2;
result += 2;
}
if (value >= 10**1) {
result += 1;
}
}
return result;
}
/**
* @dev Return the log in base 10, following the selected rounding direction, of a positive value.
* Returns 0 if given 0.
*/
function log10(uint256 value, Rounding rounding) internal pure returns (uint256) {
unchecked {
uint256 result = log10(value);
return result + (rounding == Rounding.Up && 10**result < value ? 1 : 0);
}
}
/**
* @dev Return the log in base 256, rounded down, of a positive value.
* Returns 0 if given 0.
*
* Adding one to the result gives the number of pairs of hex symbols needed to represent `value` as a hex string.
*/
function log256(uint256 value) internal pure returns (uint256) {
uint256 result = 0;
unchecked {
if (value >> 128 > 0) {
value >>= 128;
result += 16;
}
if (value >> 64 > 0) {
value >>= 64;
result += 8;
}
if (value >> 32 > 0) {
value >>= 32;
result += 4;
}
if (value >> 16 > 0) {
value >>= 16;
result += 2;
}
if (value >> 8 > 0) {
result += 1;
}
}
return result;
}
/**
* @dev Return the log in base 10, following the selected rounding direction, of a positive value.
* Returns 0 if given 0.
*/
function log256(uint256 value, Rounding rounding) internal pure returns (uint256) {
unchecked {
uint256 result = log256(value);
return result + (rounding == Rounding.Up && 1 << (result * 8) < value ? 1 : 0);
}
}
}