raffle-contracts/lib/erc721a/docs/erc721a.md

ERC721A

erc721a/contracts/ERC721A.sol

Implementation of ERC721 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

Structs

TokenOwnership

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

constructor(string memory name_, string memory symbol_)

Initializes the contract by setting a name and a symbol to the token collection.

supportsInterface

IERC165-supportsInterface

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 to learn more about how these ids are created.

See migration for supportsInterface.

totalSupply

IERC721Enumerable-totalSupply

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.

balanceOf

IERC721-balanceOf

function balanceOf(address owner) public view override returns (uint256)

Returns the number of tokens in owner's account.

ownerOf

IERC721-ownerOf

function ownerOf(uint256 tokenId) public view override returns (address)

Returns the owner of the tokenId token.

Requirements:

• tokenId must exist.

name

IERC721Metadata-name

function name() public view virtual override returns (string memory)

Returns the token collection name.

symbol

IERC721Metadata-symbol

function symbol() public view virtual override returns (string memory)

Returns the token collection symbol.

tokenURI

IERC721Metadata-tokenURI

function tokenURI(uint256 tokenId) public view virtual override returns (string memory)

Returns the Uniform Resource Identifier (URI) for tokenId token.

See _baseURI and _toString.

approve

IERC721-approve

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

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

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

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.

transferFrom

IERC721-transferFrom

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

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

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

function _nextTokenId() internal view virtual returns (uint256)

Returns the next token ID to be minted.

_totalMinted

function _totalMinted() internal view returns (uint256)

Returns the total amount of tokens minted.

_numberMinted

function _numberMinted(address owner) internal view returns (uint256)

Returns the number of tokens minted by or on behalf of owner.

_totalBurned

function _totalBurned() internal view returns (uint256)

Returns the total amount of tokens burned.

_numberBurned

function _numberBurned(address owner) internal view returns (uint256)

Returns the number of tokens burned by or on behalf of owner.

_getAux

function _getAux(address owner) internal view returns (uint64)

Returns the auxiliary data for owner (e.g. number of whitelist mint slots used).

_setAux

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

function _ownershipOf(uint256 tokenId) internal view returns (TokenOwnership memory)

Returns the token ownership data for tokenId. See 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

function _ownershipAt(uint256 index) internal view returns (TokenOwnership memory)

Returns the token ownership data at the index slot. See TokenOwnership.

The token ownership data may or may not be initialized.

_initializeOwnershipAt

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

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

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

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

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, 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

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

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

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

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

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

function _msgSenderERC721A() internal view virtual returns (address) 

Returns the message sender (defaults to msg.sender).

If you are writing GSN compatible contracts, you need to override this function
(to return _msgSender() if using with OpenZeppelin).

_extraData

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

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 before bulk minting.

Events

Transfer

IERC721-Transfer

event Transfer(address from, address to, uint256 tokenId)

Emitted when tokenId token is transferred from from to to.

Approval

IERC721-Approval

event Approval(address owner, address approved, uint256 tokenId)

Emitted when owner enables approved to manage the tokenId token.

ApprovalForAll

IERC721-ApprovalForAll

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

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.