You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
630 lines
14 KiB
Markdown
630 lines
14 KiB
Markdown
# ERC721A
|
|
|
|
[`erc721a/contracts/ERC721A.sol`](https://github.com/chiru-labs/ERC721A/blob/main/contracts/ERC721A.sol)
|
|
|
|
Implementation of [ERC721](https://eips.ethereum.org/EIPS/eip-721) Non-Fungible Token Standard, including the Metadata extension. Built to optimize for lower gas during batch mints.
|
|
|
|
Token IDs are minted sequentially (e.g. 0, 1, 2, 3...) starting from `_startTokenId()`.
|
|
|
|
An owner cannot have more than `2**64 - 1` (max value of `uint64`) tokens.
|
|
|
|
Inherits:
|
|
|
|
- [IERC721A](interfaces.md#ierc721a)
|
|
|
|
## Structs
|
|
|
|
### TokenOwnership
|
|
|
|
```solidity
|
|
struct TokenOwnership {
|
|
// The address of the owner.
|
|
address addr;
|
|
// Keeps track of the start time of ownership with minimal overhead for tokenomics.
|
|
uint64 startTimestamp;
|
|
// Whether the token has been burned.
|
|
bool burned;
|
|
}
|
|
```
|
|
|
|
Holds ownership data for each token.
|
|
|
|
`startTimestamp` is the timestamp when the token is minted to, transferred to, or burned by `addr`.
|
|
|
|
|
|
## Functions
|
|
|
|
### constructor
|
|
|
|
```solidity
|
|
constructor(string memory name_, string memory symbol_)
|
|
```
|
|
|
|
Initializes the contract by setting a `name` and a `symbol` to the token collection.
|
|
|
|
### supportsInterface
|
|
|
|
`IERC165-supportsInterface`
|
|
|
|
```solidity
|
|
function supportsInterface(bytes4 interfaceId) public view virtual returns (bool)
|
|
```
|
|
|
|
Returns `true` if this contract implements the interface defined by `interfaceId`.
|
|
|
|
See the corresponding [EIP section](https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified) to learn more about how these ids are created.
|
|
|
|
See [migration](migration.md#supportsInterface) for `supportsInterface`.
|
|
|
|
### totalSupply
|
|
|
|
`IERC721Enumerable-totalSupply`
|
|
|
|
```solidity
|
|
function totalSupply() public view returns (uint256)
|
|
```
|
|
|
|
Returns the total number of tokens in existence.
|
|
|
|
Burned tokens will reduce the count.
|
|
|
|
To get the total number of tokens minted, please see [`_totalMinted`](#_totalMinted).
|
|
|
|
### balanceOf
|
|
|
|
`IERC721-balanceOf`
|
|
|
|
```solidity
|
|
function balanceOf(address owner) public view override returns (uint256)
|
|
```
|
|
|
|
Returns the number of tokens in `owner`'s account.
|
|
|
|
### ownerOf
|
|
|
|
`IERC721-ownerOf`
|
|
|
|
```solidity
|
|
function ownerOf(uint256 tokenId) public view override returns (address)
|
|
```
|
|
|
|
Returns the owner of the `tokenId` token.
|
|
|
|
Requirements:
|
|
|
|
- `tokenId` must exist.
|
|
|
|
### name
|
|
|
|
`IERC721Metadata-name`
|
|
|
|
```solidity
|
|
function name() public view virtual override returns (string memory)
|
|
```
|
|
|
|
Returns the token collection name.
|
|
|
|
### symbol
|
|
|
|
`IERC721Metadata-symbol`
|
|
|
|
```solidity
|
|
function symbol() public view virtual override returns (string memory)
|
|
```
|
|
|
|
Returns the token collection symbol.
|
|
|
|
### tokenURI
|
|
|
|
`IERC721Metadata-tokenURI`
|
|
|
|
```solidity
|
|
function tokenURI(uint256 tokenId) public view virtual override returns (string memory)
|
|
```
|
|
|
|
Returns the Uniform Resource Identifier (URI) for `tokenId` token.
|
|
|
|
See [`_baseURI`](#_baseURI) and [`_toString`](#_toString).
|
|
|
|
|
|
### approve
|
|
|
|
`IERC721-approve`
|
|
|
|
```solidity
|
|
function approve(address to, uint256 tokenId) public override
|
|
```
|
|
|
|
Gives permission to `to` to transfer `tokenId` token to another account. The approval is cleared when the token is transferred.
|
|
|
|
Only a single account can be approved at a time, so approving the zero address clears previous approvals.
|
|
|
|
Requirements:
|
|
|
|
- The caller must own the token or be an approved operator.
|
|
- `tokenId` must exist.
|
|
|
|
Emits an `Approval` event.
|
|
|
|
### getApproved
|
|
|
|
```solidity
|
|
function getApproved(uint256 tokenId) public view override returns (address)
|
|
```
|
|
|
|
`IERC721-getApproved`
|
|
|
|
Returns the account approved for `tokenId` token.
|
|
|
|
Requirements:
|
|
|
|
- `tokenId` must exist.
|
|
|
|
### setApprovalForAll
|
|
|
|
`IERC721-setApprovalForAll`
|
|
|
|
```solidity
|
|
function setApprovalForAll(
|
|
address operator,
|
|
bool approved
|
|
) public virtual override
|
|
```
|
|
|
|
Approve or remove `operator` as an operator for the caller. Operators can call `transferFrom` or `safeTransferFrom` for any token owned by the caller.
|
|
|
|
Requirements:
|
|
|
|
- The `operator` cannot be the caller.
|
|
|
|
Emits an `ApprovalForAll` event.
|
|
|
|
### isApprovedForAll
|
|
|
|
`IERC721-isApprovedForAll`
|
|
|
|
```solidity
|
|
function isApprovedForAll(
|
|
address owner,
|
|
address operator
|
|
) public view virtual override returns (bool)
|
|
```
|
|
|
|
Returns if the `operator` is allowed to manage all of the assets of owner.
|
|
|
|
See [`setApprovalForAll`](#setApprovalForAll).
|
|
|
|
### transferFrom
|
|
|
|
`IERC721-transferFrom`
|
|
|
|
```solidity
|
|
function transferFrom(
|
|
address from,
|
|
address to,
|
|
uint256 tokenId
|
|
) public virtual override
|
|
```
|
|
|
|
Transfers `tokenId` token from `from` to `to`.
|
|
|
|
Requirements:
|
|
|
|
- `from` cannot be the zero address.
|
|
- `to` cannot be the zero address.
|
|
- `tokenId` token must be owned by `from`.
|
|
- If the caller is not `from`, it must be approved to move this token by either `approve` or `setApprovalForAll`.
|
|
|
|
Emits a `Transfer` event.
|
|
|
|
### safeTransferFrom
|
|
|
|
`IERC721-safeTransferFrom`
|
|
|
|
```solidity
|
|
function safeTransferFrom(
|
|
address from,
|
|
address to,
|
|
uint256 tokenId,
|
|
bytes memory _data
|
|
) public virtual override
|
|
```
|
|
|
|
Safely transfers `tokenId` token from `from` to `to`, checking first that contract recipients are aware of the ERC721 protocol to prevent tokens from being forever locked.
|
|
|
|
The `data` parameter is forwarded in `IERC721Receiver.onERC721Received` to contract recipients (optional, default: `""`).
|
|
|
|
Requirements:
|
|
|
|
- `from` cannot be the zero address.
|
|
- `to` cannot be the zero address.
|
|
- `tokenId` token must be owned by `from`.
|
|
- If the caller is not `from`, it must be approved to move this token by either `approve` or `setApprovalForAll`.
|
|
- If `to` refers to a smart contract, it must implement `IERC721Receiver.onERC721Received`, which is called upon a safe transfer.
|
|
|
|
Emits a `Transfer` event.
|
|
|
|
|
|
### \_startTokenId
|
|
|
|
```solidity
|
|
function _startTokenId() internal view virtual returns (uint256)
|
|
```
|
|
|
|
Returns the starting token ID (default: `0`).
|
|
|
|
To change the starting token ID, override this function to return a different constant.
|
|
|
|
|
|
### \_nextTokenId
|
|
|
|
```solidity
|
|
function _nextTokenId() internal view virtual returns (uint256)
|
|
```
|
|
|
|
Returns the next token ID to be minted.
|
|
|
|
|
|
### \_totalMinted
|
|
|
|
```solidity
|
|
function _totalMinted() internal view returns (uint256)
|
|
```
|
|
|
|
Returns the total amount of tokens minted.
|
|
|
|
### \_numberMinted
|
|
|
|
```solidity
|
|
function _numberMinted(address owner) internal view returns (uint256)
|
|
```
|
|
|
|
Returns the number of tokens minted by or on behalf of `owner`.
|
|
|
|
### \_totalBurned
|
|
|
|
```solidity
|
|
function _totalBurned() internal view returns (uint256)
|
|
```
|
|
|
|
Returns the total amount of tokens burned.
|
|
|
|
|
|
### \_numberBurned
|
|
|
|
```solidity
|
|
function _numberBurned(address owner) internal view returns (uint256)
|
|
```
|
|
|
|
Returns the number of tokens burned by or on behalf of `owner`.
|
|
|
|
### \_getAux
|
|
|
|
```solidity
|
|
function _getAux(address owner) internal view returns (uint64)
|
|
```
|
|
|
|
Returns the auxiliary data for `owner` (e.g. number of whitelist mint slots used).
|
|
|
|
### \_setAux
|
|
|
|
```solidity
|
|
function _setAux(address owner, uint64 aux) internal
|
|
```
|
|
|
|
Sets the auxiliary data for `owner` (e.g. number of whitelist mint slots used).
|
|
|
|
If there are multiple variables, please pack them into a `uint64`.
|
|
|
|
|
|
### \_ownershipOf
|
|
|
|
```solidity
|
|
function _ownershipOf(uint256 tokenId) internal view returns (TokenOwnership memory)
|
|
```
|
|
|
|
Returns the token ownership data for `tokenId`. See [`TokenOwnership`](#TokenOwnership).
|
|
|
|
The gas spent here starts off proportional to the maximum mint batch size.
|
|
|
|
It gradually moves to O(1) as tokens get transferred around in the collection over time.
|
|
|
|
|
|
### \_ownershipAt
|
|
|
|
```solidity
|
|
function _ownershipAt(uint256 index) internal view returns (TokenOwnership memory)
|
|
```
|
|
|
|
Returns the token ownership data at the `index` slot. See [`TokenOwnership`](#TokenOwnership).
|
|
|
|
The token ownership data may or may not be initialized.
|
|
|
|
|
|
### \_initializeOwnershipAt
|
|
|
|
```solidity
|
|
function _initializeOwnershipAt(uint256 index) internal
|
|
```
|
|
|
|
Initializes the token ownership data at the `index` slot, if it has not been initialized.
|
|
|
|
If the batch minted is very large, this function can be used to initialize some tokens to
|
|
reduce the first-time transfer costs.
|
|
|
|
|
|
### \_exists
|
|
|
|
```solidity
|
|
function _exists(uint256 tokenId) internal view returns (bool)
|
|
```
|
|
|
|
Returns whether `tokenId` exists.
|
|
|
|
Tokens can be managed by their owner or approved accounts via `approve` or `setApprovalForAll`.
|
|
|
|
Tokens start existing when they are minted via `_mint`.
|
|
|
|
### \_safeMint
|
|
|
|
```solidity
|
|
function _safeMint(
|
|
address to,
|
|
uint256 quantity,
|
|
bytes memory _data
|
|
) internal
|
|
```
|
|
|
|
The `data` parameter is forwarded in `IERC721Receiver.onERC721Received` to contract recipients (optional, default: `""`).
|
|
|
|
**Safe minting is reentrancy safe since V3.**
|
|
|
|
See [`_mint`](#_mint).
|
|
|
|
### \_mint
|
|
|
|
```solidity
|
|
function _mint(
|
|
address to,
|
|
uint256 quantity
|
|
) internal
|
|
```
|
|
|
|
Mints `quantity` tokens and transfers them to `to`.
|
|
|
|
> To prevent excessive first-time token transfer costs, please limit the `quantity` to a reasonable number (e.g. 30).
|
|
>
|
|
> Extremely large `quantity` amounts (e.g. > 5000) may result in some marketplaces and indexers to drop some `Transfer` events,
|
|
> and cause some mints to not appear.
|
|
|
|
Requirements:
|
|
|
|
- `to` cannot be the zero address.
|
|
- `quantity` must be greater than `0`.
|
|
|
|
Emits a `Transfer` event.
|
|
|
|
### \_mintERC2309
|
|
|
|
```solidity
|
|
function _mintERC2309(
|
|
address to,
|
|
uint256 quantity
|
|
) internal
|
|
```
|
|
|
|
Mints `quantity` tokens and transfers them to `to`.
|
|
|
|
This function is intended for efficient minting **only** during contract creation.
|
|
|
|
It emits only one `ConsecutiveTransfer` as defined in [ERC2309](https://eips.ethereum.org/EIPS/eip-2309),
|
|
instead of a sequence of `Transfer` event(s).
|
|
|
|
Calling this function outside of contract creation **will** make your contract non-compliant with the ERC721 standard.
|
|
|
|
For full ERC721 compliance, substituting ERC721 `Transfer` event(s) with the ERC2309
|
|
`ConsecutiveTransfer` event is only permissible during contract creation.
|
|
|
|
> To prevent overflows, the function limits `quantity` to a maximum of 5000.
|
|
|
|
Requirements:
|
|
|
|
- `to` cannot be the zero address.
|
|
- `quantity` must be greater than `0`.
|
|
|
|
Emits a `ConsecutiveTransfer` event.
|
|
|
|
### \_burn
|
|
|
|
```solidity
|
|
function _burn(uint256 tokenId, bool approvalCheck) internal virtual
|
|
```
|
|
|
|
Destroys `tokenId`.
|
|
|
|
The approval is cleared when the token is burned.
|
|
|
|
Requirements:
|
|
|
|
- `tokenId` must exist.
|
|
- If `approvalCheck` is `true`, the caller must own `tokenId` or be an approved operator.
|
|
|
|
Emits a `Transfer` event.
|
|
|
|
|
|
### \_baseURI
|
|
|
|
```solidity
|
|
function _baseURI() internal view virtual returns (string memory)
|
|
```
|
|
|
|
Base URI for computing `tokenURI`.
|
|
|
|
If set, the resulting URI for each token will be the concatenation of the `baseURI` and the `tokenId`.
|
|
|
|
Empty by default, it can be overridden in child contracts.
|
|
|
|
|
|
### \_beforeTokenTransfers
|
|
|
|
```solidity
|
|
function _beforeTokenTransfers(
|
|
address from,
|
|
address to,
|
|
uint256 startTokenId,
|
|
uint256 quantity
|
|
) internal virtual
|
|
```
|
|
|
|
Hook that is called before a set of serially-ordered token IDs are about to be transferred. This includes minting.
|
|
|
|
Also called before burning one token.
|
|
|
|
`startTokenId` - the first token ID to be transferred.
|
|
`quantity` - the amount to be transferred.
|
|
|
|
Calling conditions:
|
|
|
|
- When `from` and `to` are both non-zero, `from`'s `tokenId` will be transferred to `to`.
|
|
- When `from` is zero, `tokenId` will be minted for `to`.
|
|
- When `to` is zero, `tokenId` will be burned by `from`.
|
|
- `from` and `to` are never both zero.
|
|
|
|
|
|
### \_afterTokenTransfers
|
|
|
|
```solidity
|
|
function _afterTokenTransfers(
|
|
address from,
|
|
address to,
|
|
uint256 startTokenId,
|
|
uint256 quantity
|
|
) internal virtual
|
|
```
|
|
|
|
Hook that is called after a set of serially-ordered token IDs are about to be transferred. This includes minting.
|
|
|
|
Also called after burning one token.
|
|
|
|
`startTokenId` - the first token ID to be transferred.
|
|
`quantity` - the amount to be transferred.
|
|
|
|
Calling conditions:
|
|
|
|
- When `from` and `to` are both non-zero, `from`'s `tokenId` will be transferred to `to`.
|
|
- When `from` is zero, `tokenId` will be minted for `to`.
|
|
- When `to` is zero, `tokenId` will be burned by `from`.
|
|
- `from` and `to` are never both zero.
|
|
|
|
|
|
### \_toString
|
|
|
|
```solidity
|
|
function _toString(uint256 value) internal pure returns (string memory)
|
|
```
|
|
|
|
Converts a `uint256` to its ASCII `string` decimal representation.
|
|
|
|
This function is provided as a drop-in replacement for OpenZeppelin's `Strings.toString(uint256 value)`.
|
|
|
|
|
|
### \_msgSenderERC721A
|
|
|
|
```solidity
|
|
function _msgSenderERC721A() internal view virtual returns (address)
|
|
```
|
|
|
|
Returns the message sender (defaults to `msg.sender`).
|
|
|
|
If you are writing [GSN compatible contracts](https://docs.openzeppelin.com/contracts/2.x/gsn),
|
|
you need to override this function
|
|
(to return `_msgSender()` if using with OpenZeppelin).
|
|
|
|
### \_extraData
|
|
|
|
```solidity
|
|
function _extraData(
|
|
address from,
|
|
address to,
|
|
uint24 previousExtraData
|
|
) internal view virtual returns (uint24)
|
|
```
|
|
|
|
Called during each token transfer to set the 24bit `extraData` field.
|
|
|
|
This is an advanced storage hitchhiking feature for storing token related data.
|
|
|
|
Intended to be overridden by the deriving contract to return the value to be stored after transfer.
|
|
|
|
`previousExtraData` - the value of `extraData` before transfer.
|
|
|
|
Calling conditions:
|
|
|
|
- When `from` and `to` are both non-zero, `from`'s `tokenId` will be transferred to `to`.
|
|
- When `from` is zero, `tokenId` will be minted for `to`.
|
|
- When `to` is zero, `tokenId` will be burned by `from`.
|
|
- `from` and `to` are never both zero.
|
|
|
|
### \_setExtraDataAt
|
|
|
|
```solidity
|
|
function _setExtraDataAt(uint256 index, uint24 extraData) internal
|
|
```
|
|
|
|
Directly sets the `extraData` for the ownership data at `index`.
|
|
|
|
This is an advanced storage hitchhiking feature for storing token related data.
|
|
|
|
Requirements:
|
|
|
|
- The token at `index` must be initialized.
|
|
For bulk mints, `index` is the value of [`_nextTokenId`](#_nextTokenId) before bulk minting.
|
|
|
|
|
|
## Events
|
|
|
|
### Transfer
|
|
|
|
`IERC721-Transfer`
|
|
|
|
```solidity
|
|
event Transfer(address from, address to, uint256 tokenId)
|
|
```
|
|
|
|
Emitted when `tokenId` token is transferred from `from` to `to`.
|
|
|
|
### Approval
|
|
|
|
`IERC721-Approval`
|
|
|
|
```solidity
|
|
event Approval(address owner, address approved, uint256 tokenId)
|
|
```
|
|
|
|
Emitted when `owner` enables `approved` to manage the `tokenId` token.
|
|
|
|
### ApprovalForAll
|
|
|
|
`IERC721-ApprovalForAll`
|
|
|
|
```solidity
|
|
event ApprovalForAll(address owner, address operator, bool approved)
|
|
```
|
|
|
|
Emitted when `owner` enables or disables (`approved`) `operator` to manage all of its assets.
|
|
|
|
### ConsecutiveTransfer
|
|
|
|
`IERC2309-ConsecutiveTransfer`
|
|
|
|
```solidity
|
|
event ConsecutiveTransfer(
|
|
uint256 indexed fromTokenId,
|
|
uint256 toTokenId,
|
|
address indexed from,
|
|
address indexed to
|
|
)
|
|
```
|
|
|
|
Emitted when tokens from `fromTokenId` to `toTokenId` (inclusive) are transferred from `from` to `to`, during contract creation.
|