Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: unify interface NatSpec #666

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

chore: unify interface NatSpec #666

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2fb1dd8
update interfaces, update fmt
zerosnacks Mar 3, 2025
6874544
clean up
zerosnacks Mar 3, 2025
af59257
document ERC-165 identifier
zerosnacks Mar 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 14 additions & 6 deletions foundry.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,17 @@ needs_undefined_env_var = "${UNDEFINED_RPC_URL_PLACEHOLDER}"
line_length = 120
tab_width = 4
bracket_spacing = false
int_types = 'long'
multiline_func_header = 'attributes_first'
quote_style = 'double'
number_underscore = 'preserve'
single_line_statement_blocks = 'preserve'
ignore = ["src/console.sol", "src/console2.sol"]
int_types = "long"
multiline_func_header = "attributes_first"
quote_style = "double"
number_underscore = "preserve"
hex_underscore = "remove"
single_line_statement_blocks = "preserve"
override_spacing = false
wrap_comments = false
ignore = [
"src/console.sol",
"src/console2.sol",
]
contract_new_lines = false
sort_imports = false
107 changes: 63 additions & 44 deletions src/interfaces/IERC1155.sol
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,71 +3,90 @@ pragma solidity >=0.6.2;

import {IERC165} from "./IERC165.sol";

/// @title ERC-1155 Multi Token Standard
/// @dev See https://eips.ethereum.org/EIPS/eip-1155
/// Note: The ERC-165 identifier for this interface is 0xd9b67a26.
/// @title ERC-1155: Multi Token Standard
/// @dev SEE: https://eips.ethereum.org/EIPS/eip-1155
/// NOTE: The ERC-165 identifier for this interface is 0xd9b67a26.
interface IERC1155 is IERC165 {
/// @dev
/// - Either `TransferSingle` or `TransferBatch` MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "Safe Transfer Rules" section of the standard).
/// - The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender).
/// - Either `TransferSingle` or `TransferBatch` MUST emit when tokens are transferred, including zero value
/// transfers as well as minting or burning (see "Safe Transfer Rules" section of the standard).
/// - The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer
/// (SHOULD be msg.sender).
/// - The `_from` argument MUST be the address of the holder whose balance is decreased.
/// - The `_to` argument MUST be the address of the recipient whose balance is increased.
/// - The `_id` argument MUST be the token type being transferred.
/// - The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by.
/// - The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the
/// recipient balance is increased by.
/// - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address).
/// - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address).
event TransferSingle(
address indexed _operator, address indexed _from, address indexed _to, uint256 _id, uint256 _value
);

/// @dev
/// - Either `TransferSingle` or `TransferBatch` MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "Safe Transfer Rules" section of the standard).
/// - The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender).
/// - Either `TransferSingle` or `TransferBatch` MUST emit when tokens are transferred, including zero value
/// transfers as well as minting or burning (see "Safe Transfer Rules" section of the standard).
/// - The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer
/// (SHOULD be msg.sender).
/// - The `_from` argument MUST be the address of the holder whose balance is decreased.
/// - The `_to` argument MUST be the address of the recipient whose balance is increased.
/// - The `_ids` argument MUST be the list of tokens being transferred.
/// - The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified in _ids) the holder balance is decreased by and match what the recipient balance is increased by.
/// - The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified
/// in _ids) the holder balance is decreased by and match what the recipient balance is increased by.
/// - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address).
/// - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address).
event TransferBatch(
address indexed _operator, address indexed _from, address indexed _to, uint256[] _ids, uint256[] _values
);

/// @dev MUST emit when approval for a second party/operator address to manage all tokens for an owner address is enabled or disabled (absence of an event assumes disabled).
/// @dev
/// - MUST emit when approval for a second party/operator address to manage all tokens for an owner address is
/// enabled or disabled (absence of an event assumes disabled).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it should be indented here and other comments

event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved);

/// @dev MUST emit when the URI is updated for a token ID. URIs are defined in RFC 3986.
/// The URI MUST point to a JSON file that conforms to the "ERC-1155 Metadata URI JSON Schema".
/// @dev
/// - MUST emit when the URI is updated for a token ID. URIs are defined in RFC 3986.
/// - The URI MUST point to a JSON file that conforms to the "ERC-1155 Metadata URI JSON Schema".
event URI(string _value, uint256 indexed _id);

/// @notice Transfers `_value` amount of an `_id` from the `_from` address to the `_to` address specified (with safety call).
/// @dev Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section of the standard).
/// @notice Transfers `_value` amount of an `_id` from the `_from` address to the `_to` address specified (with
/// safety call).
/// @param _from Source address.
/// @param _to Target address.
/// @param _id ID of the token type.
/// @param _value Transfer amount.
/// @param _data Additional data with no specified format, MUST be sent unaltered in call to `onERC1155Received` on `_to`.
/// @dev
/// - Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section of the standard).
/// - MUST revert if `_to` is the zero address.
/// - MUST revert if balance of holder for token `_id` is lower than the `_value` sent.
/// - MUST revert on any other error.
/// - MUST emit the `TransferSingle` event to reflect the balance change (see "Safe Transfer Rules" section of the standard).
/// - After the above conditions are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard).
/// @param _from Source address
/// @param _to Target address
/// @param _id ID of the token type
/// @param _value Transfer amount
/// @param _data Additional data with no specified format, MUST be sent unaltered in call to `onERC1155Received` on `_to`
/// - MUST emit the `TransferSingle` event to reflect the balance change (see "Safe Transfer Rules" section of the
/// standard).
/// After the above conditions are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0).
/// If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard).
function safeTransferFrom(address _from, address _to, uint256 _id, uint256 _value, bytes calldata _data) external;

/// @notice Transfers `_values` amount(s) of `_ids` from the `_from` address to the `_to` address specified (with safety call).
/// @dev Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section of the standard).
/// @notice Transfers `_values` amount(s) of `_ids` from the `_from` address to the `_to` address specified (with
/// safety call).
/// @param _from Source address.
/// @param _to Target address.
/// @param _ids IDs of each token type (order and length must match _values array).
/// @param _values Transfer amounts per token type (order and length must match _ids array).
/// @param _data Additional data with no specified format, MUST be sent unaltered in call to the `ERC1155TokenReceiver` hook(s) on `_to`.
/// @dev Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval"
/// section of the standard).
/// - MUST revert if `_to` is the zero address.
/// - MUST revert if length of `_ids` is not the same as length of `_values`.
/// - MUST revert if any of the balance(s) of the holder(s) for token(s) in `_ids` is lower than the respective amount(s) in `_values` sent to the recipient.
/// - MUST revert if any of the balance(s) of the holder(s) for token(s) in `_ids` is lower than the respective
/// amount(s) in `_values` sent to the recipient.
/// - MUST revert on any other error.
/// - MUST emit `TransferSingle` or `TransferBatch` event(s) such that all the balance changes are reflected (see "Safe Transfer Rules" section of the standard).
/// - Balance changes and events MUST follow the ordering of the arrays (_ids[0]/_values[0] before _ids[1]/_values[1], etc).
/// - After the above conditions for the transfer(s) in the batch are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call the relevant `ERC1155TokenReceiver` hook(s) on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard).
/// @param _from Source address
/// @param _to Target address
/// @param _ids IDs of each token type (order and length must match _values array)
/// @param _values Transfer amounts per token type (order and length must match _ids array)
/// @param _data Additional data with no specified format, MUST be sent unaltered in call to the `ERC1155TokenReceiver` hook(s) on `_to`
/// - MUST emit `TransferSingle` or `TransferBatch` event(s) such that all the balance changes are reflected (see
/// "Safe Transfer Rules" section of the standard).
/// - Balance changes and events MUST follow the ordering of the arrays (_ids[0]/_values[0] before
/// _ids[1]/_values[1], etc).
/// After the above conditions for the transfer(s) in the batch are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0).
/// If so, it MUST call the relevant `ERC1155TokenReceiver` hook(s) on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard).
function safeBatchTransferFrom(
address _from,
address _to,
Expand All @@ -77,29 +96,29 @@ interface IERC1155 is IERC165 {
) external;

/// @notice Get the balance of an account's tokens.
/// @param _owner The address of the token holder
/// @param _id ID of the token
/// @return The _owner's balance of the token type requested
/// @param _owner The address of the token holder.
/// @param _id ID of the token.
/// @return The _owner's balance of the token type requested.
function balanceOf(address _owner, uint256 _id) external view returns (uint256);

/// @notice Get the balance of multiple account/token pairs
/// @param _owners The addresses of the token holders
/// @param _ids ID of the tokens
/// @return The _owner's balance of the token types requested (i.e. balance for each (owner, id) pair)
/// @notice Get the balance of multiple account/token pairs.
/// @param _owners The addresses of the token holders.
/// @param _ids ID of the tokens.
/// @return The _owner's balance of the token types requested (i.e. balance for each (owner, id) pair).
function balanceOfBatch(address[] calldata _owners, uint256[] calldata _ids)
external
view
returns (uint256[] memory);

/// @notice Enable or disable approval for a third party ("operator") to manage all of the caller's tokens.
/// @dev MUST emit the ApprovalForAll event on success.
/// @param _operator Address to add to the set of authorized operators
/// @param _approved True if the operator is approved, false to revoke approval
/// @param _operator Address to add to the set of authorized operators.
/// @param _approved True if the operator is approved, false to revoke approval.
function setApprovalForAll(address _operator, bool _approved) external;

/// @notice Queries the approval status of an operator for a given owner.
/// @param _owner The owner of the tokens
/// @param _operator Address of authorized operator
/// @return True if the operator is approved, false if not
/// @param _owner The owner of the tokens.
/// @param _operator Address of authorized operator.
/// @return True if the operator is approved, false if not.
function isApprovedForAll(address _owner, address _operator) external view returns (bool);
}
14 changes: 8 additions & 6 deletions src/interfaces/IERC165.sol
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
// SPDX-License-Identifier: MIT
pragma solidity >=0.6.2;

/// @title ERC-165: Standard Interface Detection
/// @dev SEE: https://eips.ethereum.org/EIPS/eip-165
interface IERC165 {
/// @notice Query if a contract implements an interface
/// @param interfaceID The interface identifier, as specified in ERC-165
/// @dev Interface identification is specified in ERC-165. This function
/// uses less than 30,000 gas.
/// @return `true` if the contract implements `interfaceID` and
/// `interfaceID` is not 0xffffffff, `false` otherwise
/// @notice Checks if the contract implements a specific interface.
/// @param interfaceID The 4-byte identifier of the interface, as specified in ERC-165.
/// @return `true` if the contract implements `interfaceID` and `interfaceID` is not `0xffffffff`,
/// otherwise `false`.
/// @dev The interface identifier (`interfaceID`) is defined in ERC-165.
/// This function should consume less than 30,000 gas.
function supportsInterface(bytes4 interfaceID) external view returns (bool);
}
66 changes: 41 additions & 25 deletions src/interfaces/IERC20.sol
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,59 @@
// SPDX-License-Identifier: MIT
pragma solidity >=0.6.2;

/// @dev Interface of the ERC20 standard as defined in the EIP.
/// @dev This includes the optional name, symbol, and decimals metadata.
/// @title ERC-20: Token Standard
/// @dev SEE: https://eips.ethereum.org/EIPS/eip-20
interface IERC20 {
/// @dev Emitted when `value` tokens are moved from one account (`from`) to another (`to`).
/// @notice Emitted when `value` tokens are moved from one account (`from`) to another (`to`).
event Transfer(address indexed from, address indexed to, uint256 value);

/// @dev Emitted when the allowance of a `spender` for an `owner` is set, where `value`
/// is the new allowance.
/// @notice Emitted when the allowance of a `spender` for an `owner` is set,
/// where `value` is the new allowance.
event Approval(address indexed owner, address indexed spender, uint256 value);

/// @notice Returns the amount of tokens in existence.
/// @notice Returns the name of the token.
function name() external view returns (string memory);

/// @notice Returns the symbol of the token.
function symbol() external view returns (string memory);

/// @notice Returns the number of decimal places used for user representation.
function decimals() external view returns (uint8);

/// @notice Returns the total supply of tokens in existence.
function totalSupply() external view returns (uint256);

/// @notice Returns the amount of tokens owned by `account`.
/// @notice Returns the balance of tokens owned by a given `account`.
function balanceOf(address account) external view returns (uint256);

/// @notice Moves `amount` tokens from the caller's account to `to`.
/// @notice Transfers `amount` tokens from the caller’s account to the `to` address.
/// @param to The recipient address.
/// @param amount The number of tokens to transfer.
/// @return A boolean indicating whether the transfer was successful.
/// @dev Emits a {Transfer} event.
function transfer(address to, uint256 amount) external returns (bool);

/// @notice Returns the remaining number of tokens that `spender` is allowed
/// to spend on behalf of `owner`
function allowance(address owner, address spender) external view returns (uint256);

/// @notice Sets `amount` as the allowance of `spender` over the caller's tokens.
/// @dev Be aware of front-running risks: https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729
function approve(address spender, uint256 amount) external returns (bool);

/// @notice Moves `amount` tokens from `from` to `to` using the allowance mechanism.
/// `amount` is then deducted from the caller's allowance.
/// @notice Transfers `amount` tokens from `from` to `to` using the allowance mechanism.
/// The caller must have prior approval for at least `amount` tokens from `from`.
/// The allowance is reduced accordingly.
/// @param from The address holding the tokens.
/// @param to The recipient address.
/// @param amount The number of tokens to transfer.
/// @return A boolean indicating whether the transfer was successful.
/// @dev Emits a {Transfer} event.
function transferFrom(address from, address to, uint256 amount) external returns (bool);

/// @notice Returns the name of the token.
function name() external view returns (string memory);

/// @notice Returns the symbol of the token.
function symbol() external view returns (string memory);
/// @notice Approves `spender` to transfer up to `amount` tokens on behalf of the caller.
/// @param spender The address that will be allowed to spend the tokens.
/// @param amount The maximum number of tokens that can be spent.
/// @return A boolean indicating whether the approval was successful.
/// @dev Emits an {Approval} event. Be aware of the allowance front-running attack:
/// https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729.
function approve(address spender, uint256 amount) external returns (bool);

/// @notice Returns the decimals places of the token.
function decimals() external view returns (uint8);
/// @notice Returns the remaining number of tokens that `spender` is allowed to spend on behalf of `owner`.
/// @param owner The owner of the tokens.
/// @param spender The spender who has been approved.
/// @return The number of tokens `spender` can still spend.
function allowance(address owner, address spender) external view returns (uint256);
}
Loading