diff --git a/src/interfaces/IERC173.sol b/src/interfaces/IERC173.sol new file mode 100644 index 00000000..2a107488 --- /dev/null +++ b/src/interfaces/IERC173.sol @@ -0,0 +1,25 @@ +// SPDX-License-Identifier: MIT +pragma solidity >=0.8.30; + +/// @title ERC-173 Contract Ownership Standard Interface +/// @notice Interface for contract ownership with custom errors +/// @dev This interface includes all custom errors used by ERC-173 implementations +interface IERC173 { + /// @notice Thrown when attempting to transfer ownership while not being the owner. + error OwnableUnauthorizedAccount(); + + /// @notice Thrown when attempting to transfer ownership of a renounced contract. + error OwnableAlreadyRenounced(); + + /// @dev This emits when ownership of a contract changes. + event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); + + /// @notice Get the address of the owner + /// @return The address of the owner. + function owner() external view returns (address); + + /// @notice Set the address of the new owner of the contract + /// @dev Set _newOwner to address(0) to renounce any ownership. + /// @param _newOwner The address of the new owner of the contract + function transferOwnership(address _newOwner) external; +} diff --git a/src/interfaces/IERC20.sol b/src/interfaces/IERC20.sol new file mode 100644 index 00000000..56fb7612 --- /dev/null +++ b/src/interfaces/IERC20.sol @@ -0,0 +1,142 @@ +// SPDX-License-Identifier: MIT +pragma solidity >=0.8.30; + +/// @title ERC-20 Token Standard Interface +/// @notice Interface for ERC-20 token contracts with custom errors +/// @dev This interface includes all custom errors used by ERC-20 implementations +interface IERC20 { + /// @notice Thrown when an account has insufficient balance for a transfer or burn. + /// @param _sender Address attempting the transfer. + /// @param _balance Current balance of the sender. + /// @param _needed Amount required to complete the operation. + error ERC20InsufficientBalance(address _sender, uint256 _balance, uint256 _needed); + + /// @notice Thrown when the sender address is invalid (e.g., zero address). + /// @param _sender Invalid sender address. + error ERC20InvalidSender(address _sender); + + /// @notice Thrown when the receiver address is invalid (e.g., zero address). + /// @param _receiver Invalid receiver address. + error ERC20InvalidReceiver(address _receiver); + + /// @notice Thrown when a spender tries to use more than the approved allowance. + /// @param _spender Address attempting to spend. + /// @param _allowance Current allowance for the spender. + /// @param _needed Amount required to complete the operation. + error ERC20InsufficientAllowance(address _spender, uint256 _allowance, uint256 _needed); + + /// @notice Thrown when the spender address is invalid (e.g., zero address). + /// @param _spender Invalid spender address. + error ERC20InvalidSpender(address _spender); + + /// @notice Thrown when a permit signature is invalid or expired. + /// @param _owner The address that signed the permit. + /// @param _spender The address that was approved. + /// @param _value The amount that was approved. + /// @param _deadline The deadline for the permit. + /// @param _v The recovery byte of the signature. + /// @param _r The r value of the signature. + /// @param _s The s value of the signature. + error ERC2612InvalidSignature( + address _owner, address _spender, uint256 _value, uint256 _deadline, uint8 _v, bytes32 _r, bytes32 _s + ); + + /// @notice Emitted when tokens are transferred between two addresses. + /// @param _from Address sending the tokens. + /// @param _to Address receiving the tokens. + /// @param _value Amount of tokens transferred. + event Transfer(address indexed _from, address indexed _to, uint256 _value); + + /// @notice Emitted when an approval is made for a spender by an owner. + /// @param _owner The address granting the allowance. + /// @param _spender The address receiving the allowance. + /// @param _value The amount approved. + event Approval(address indexed _owner, address indexed _spender, uint256 _value); + + /// @notice Returns the name of the token. + /// @return The token name. + function name() external view returns (string memory); + + /// @notice Returns the symbol of the token. + /// @return The token symbol. + function symbol() external view returns (string memory); + + /// @notice Returns the number of decimals used for token precision. + /// @return The number of decimals. + function decimals() external view returns (uint8); + + /// @notice Returns the total supply of tokens. + /// @return The total token supply. + function totalSupply() external view returns (uint256); + + /// @notice Returns the balance of a specific account. + /// @param _account The address of the account. + /// @return The account balance. + function balanceOf(address _account) external view returns (uint256); + + /// @notice Returns the remaining number of tokens that a spender is allowed to spend on behalf of an owner. + /// @param _owner The address of the token owner. + /// @param _spender The address of the spender. + /// @return The remaining allowance. + function allowance(address _owner, address _spender) external view returns (uint256); + + /// @notice Approves a spender to transfer up to a certain amount of tokens on behalf of the caller. + /// @dev Emits an {Approval} event. + /// @param _spender The address approved to spend tokens. + /// @param _value The number of tokens to approve. + function approve(address _spender, uint256 _value) external; + + /// @notice Transfers tokens to another address. + /// @dev Emits a {Transfer} event. + /// @param _to The address to receive the tokens. + /// @param _value The amount of tokens to transfer. + function transfer(address _to, uint256 _value) external; + + /// @notice Transfers tokens on behalf of another account, provided sufficient allowance exists. + /// @dev Emits a {Transfer} event and decreases the spender's allowance. + /// @param _from The address to transfer tokens from. + /// @param _to The address to transfer tokens to. + /// @param _value The amount of tokens to transfer. + function transferFrom(address _from, address _to, uint256 _value) external; + + /// @notice Burns (destroys) a specific amount of tokens from the caller's balance. + /// @dev Emits a {Transfer} event to the zero address. + /// @param _value The amount of tokens to burn. + function burn(uint256 _value) external; + + /// @notice Burns tokens from another account, deducting from the caller's allowance. + /// @dev Emits a {Transfer} event to the zero address. + /// @param _account The address whose tokens will be burned. + /// @param _value The amount of tokens to burn. + function burnFrom(address _account, uint256 _value) external; + + /// @notice Returns the current nonce for an owner. + /// @dev This value changes each time a permit is used. + /// @param _owner The address of the owner. + /// @return The current nonce. + function nonces(address _owner) external view returns (uint256); + + /// @notice Returns the domain separator used in the encoding of the signature for {permit}. + /// @dev This value is unique to a contract and chain ID combination to prevent replay attacks. + /// @return The domain separator. + function DOMAIN_SEPARATOR() external view returns (bytes32); + + /// @notice Sets the allowance for a spender via a signature. + /// @dev This function implements EIP-2612 permit functionality. + /// @param _owner The address of the token owner. + /// @param _spender The address of the spender. + /// @param _value The amount of tokens to approve. + /// @param _deadline The deadline for the permit (timestamp). + /// @param _v The recovery byte of the signature. + /// @param _r The r value of the signature. + /// @param _s The s value of the signature. + function permit( + address _owner, + address _spender, + uint256 _value, + uint256 _deadline, + uint8 _v, + bytes32 _r, + bytes32 _s + ) external; +} diff --git a/src/interfaces/IERC721.sol b/src/interfaces/IERC721.sol new file mode 100644 index 00000000..4d4d70cd --- /dev/null +++ b/src/interfaces/IERC721.sol @@ -0,0 +1,118 @@ +// SPDX-License-Identifier: MIT +pragma solidity >=0.8.30; + +/// @title ERC-721 Token Standard Interface +/// @notice Interface for ERC-721 token contracts with custom errors +/// @dev This interface includes all custom errors used by ERC-721 implementations +interface IERC721 { + /// @notice Error indicating the queried owner address is invalid (zero address). + error ERC721InvalidOwner(address _owner); + + /// @notice Error indicating that the queried token does not exist. + error ERC721NonexistentToken(uint256 _tokenId); + + /// @notice Error indicating the sender does not match the token owner. + error ERC721IncorrectOwner(address _sender, uint256 _tokenId, address _owner); + + /// @notice Error indicating the sender address is invalid. + error ERC721InvalidSender(address _sender); + + /// @notice Error indicating the receiver address is invalid. + error ERC721InvalidReceiver(address _receiver); + + /// @notice Error indicating the operator lacks approval to transfer the given token. + error ERC721InsufficientApproval(address _operator, uint256 _tokenId); + + /// @notice Error indicating the approver address is invalid. + error ERC721InvalidApprover(address _approver); + + /// @notice Error indicating the operator address is invalid. + error ERC721InvalidOperator(address _operator); + + /// @notice Emitted when ownership of an NFT changes by any mechanism. + event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId); + + /// @notice Emitted when the approved address for an NFT is changed or reaffirmed. + event Approval(address indexed _owner, address indexed _approved, uint256 indexed _tokenId); + + /// @notice Emitted when an operator is enabled or disabled for an owner. + event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved); + + /// @notice Returns the token collection name. + /// @return The name of the token collection. + function name() external view returns (string memory); + + /// @notice Returns the token collection symbol. + /// @return The symbol of the token collection. + function symbol() external view returns (string memory); + + /// @notice Returns the number of tokens owned by a given address. + /// @param _owner The address to query the balance of. + /// @return The balance (number of tokens) owned by `_owner`. + function balanceOf(address _owner) external view returns (uint256); + + /// @notice Returns the owner of a given token ID. + /// @param _tokenId The token ID to query. + /// @return The address of the token owner. + function ownerOf(uint256 _tokenId) external view returns (address); + + /// @notice Returns the approved address for a given token ID. + /// @param _tokenId The token ID to query the approval of. + /// @return The approved address for the token. + function getApproved(uint256 _tokenId) external view returns (address); + + /// @notice Returns true if an operator is approved to manage all of an owner's assets. + /// @param _owner The token owner. + /// @param _operator The operator address. + /// @return True if the operator is approved for all tokens of the owner. + function isApprovedForAll(address _owner, address _operator) external view returns (bool); + + /// @notice Approves another address to transfer the given token ID. + /// @param _approved The address to be approved. + /// @param _tokenId The token ID to approve. + function approve(address _approved, uint256 _tokenId) external; + + /// @notice Approves or revokes permission for an operator to manage all caller's assets. + /// @param _operator The operator address to set approval for. + /// @param _approved True to approve, false to revoke. + function setApprovalForAll(address _operator, bool _approved) external; + + /// @notice Transfers a token from one address to another. + /// @param _from The current owner of the token. + /// @param _to The address to receive the token. + /// @param _tokenId The token ID to transfer. + function transferFrom(address _from, address _to, uint256 _tokenId) external; + + /// @notice Safely transfers a token, checking if the receiver can handle ERC-721 tokens. + /// @param _from The current owner of the token. + /// @param _to The address to receive the token. + /// @param _tokenId The token ID to transfer. + function safeTransferFrom(address _from, address _to, uint256 _tokenId) external; + + /// @notice Safely transfers a token with additional data. + /// @param _from The current owner of the token. + /// @param _to The address to receive the token. + /// @param _tokenId The token ID to transfer. + /// @param _data Additional data with no specified format. + function safeTransferFrom(address _from, address _to, uint256 _tokenId, bytes calldata _data) external; + + /// @notice Provide the metadata URI for a given token ID. + /// @param _tokenId tokenID of the NFT to query the metadata from + /// @return the URI providing the detailed metadata of the specified tokenID + function tokenURI(uint256 _tokenId) external view returns (string memory); +} + +/// @title ERC-721 Token Receiver Interface +/// @notice Interface for contracts that want to handle safe transfers of ERC-721 tokens. +/// @dev Contracts implementing this must return the selector to confirm token receipt. +interface IERC721Receiver { + /// @notice Handles the receipt of an NFT. + /// @param _operator The address which called `safeTransferFrom`. + /// @param _from The previous owner of the token. + /// @param _tokenId The NFT identifier being transferred. + /// @param _data Additional data with no specified format. + /// @return The selector to confirm the token transfer. + function onERC721Received(address _operator, address _from, uint256 _tokenId, bytes calldata _data) + external + returns (bytes4); +} diff --git a/src/interfaces/IERC721Enumerable.sol b/src/interfaces/IERC721Enumerable.sol new file mode 100644 index 00000000..f7bb1827 --- /dev/null +++ b/src/interfaces/IERC721Enumerable.sol @@ -0,0 +1,111 @@ +// SPDX-License-Identifier: MIT +pragma solidity >=0.8.30; + +/// @title ERC-721 Enumerable Token Standard Interface +/// @notice Interface for ERC-721 token contracts with enumeration support and custom errors +/// @dev This interface includes all custom errors used by ERC-721 Enumerable implementations +interface IERC721Enumerable { + /// @notice Thrown when querying or transferring from an invalid owner address. + error ERC721InvalidOwner(address _owner); + + /// @notice Thrown when operating on a non-existent token. + error ERC721NonexistentToken(uint256 _tokenId); + + /// @notice Thrown when the provided owner does not match the actual owner of the token. + error ERC721IncorrectOwner(address _sender, uint256 _tokenId, address _owner); + + /// @notice Thrown when the sender address is invalid. + error ERC721InvalidSender(address _sender); + + /// @notice Thrown when the receiver address is invalid. + error ERC721InvalidReceiver(address _receiver); + + /// @notice Thrown when the operator lacks sufficient approval for a transfer. + error ERC721InsufficientApproval(address _operator, uint256 _tokenId); + + /// @notice Thrown when an invalid approver is provided. + error ERC721InvalidApprover(address _approver); + + /// @notice Thrown when an invalid operator is provided. + error ERC721InvalidOperator(address _operator); + + /// @notice Thrown when an index is out of bounds during enumeration. + error ERC721OutOfBoundsIndex(address _owner, uint256 _index); + + /// @notice Emitted when a token is transferred between addresses. + event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId); + + /// @notice Emitted when a token is approved for transfer by another address. + event Approval(address indexed _owner, address indexed _approved, uint256 indexed _tokenId); + + /// @notice Emitted when an operator is approved or revoked for all tokens of an owner. + event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved); + + /// @notice Returns the name of the token collection. + /// @return The token collection name. + function name() external view returns (string memory); + + /// @notice Returns the symbol of the token collection. + /// @return The token symbol. + function symbol() external view returns (string memory); + + /// @notice Returns the total number of tokens in existence. + /// @return The total supply of tokens. + function totalSupply() external view returns (uint256); + + /// @notice Returns the number of tokens owned by an address. + /// @param _owner The address to query. + /// @return The balance (number of tokens owned). + function balanceOf(address _owner) external view returns (uint256); + + /// @notice Returns the owner of a given token ID. + /// @param _tokenId The token ID to query. + /// @return The address of the token owner. + function ownerOf(uint256 _tokenId) external view returns (address); + + /// @notice Returns a token ID owned by a given address at a specific index. + /// @param _owner The address to query. + /// @param _index The index of the token. + /// @return The token ID owned by `_owner` at `_index`. + function tokenOfOwnerByIndex(address _owner, uint256 _index) external view returns (uint256); + + /// @notice Returns the approved address for a given token ID. + /// @param _tokenId The token ID to query. + /// @return The approved address for the token. + function getApproved(uint256 _tokenId) external view returns (address); + + /// @notice Returns whether an operator is approved for all tokens of an owner. + /// @param _owner The token owner. + /// @param _operator The operator address. + /// @return True if approved for all, false otherwise. + function isApprovedForAll(address _owner, address _operator) external view returns (bool); + + /// @notice Approves another address to transfer a specific token ID. + /// @param _approved The address being approved. + /// @param _tokenId The token ID to approve. + function approve(address _approved, uint256 _tokenId) external; + + /// @notice Approves or revokes an operator to manage all tokens of the caller. + /// @param _operator The operator address. + /// @param _approved True to approve, false to revoke. + function setApprovalForAll(address _operator, bool _approved) external; + + /// @notice Transfers a token from one address to another. + /// @param _from The current owner of the token. + /// @param _to The recipient address. + /// @param _tokenId The token ID to transfer. + function transferFrom(address _from, address _to, uint256 _tokenId) external; + + /// @notice Safely transfers a token, checking for receiver contract compatibility. + /// @param _from The current owner of the token. + /// @param _to The recipient address. + /// @param _tokenId The token ID to transfer. + function safeTransferFrom(address _from, address _to, uint256 _tokenId) external; + + /// @notice Safely transfers a token with additional data. + /// @param _from The current owner of the token. + /// @param _to The recipient address. + /// @param _tokenId The token ID to transfer. + /// @param _data Additional data to send to the receiver contract. + function safeTransferFrom(address _from, address _to, uint256 _tokenId, bytes calldata _data) external; +}