ERC721A Upgradeable

4.3.0 verified Fri May 01 auth: no javascript

ERC721A-Upgradeable (v4.3.0) is the upgradeable variant of ERC721A, a gas-efficient ERC721 implementation for batch minting popularized by NFTs. It uses the diamond storage pattern (EIP-2535) for storage layout compatibility across upgrades. Major version changes break storage (e.g., 3.x to 4.x). Requires OpenZeppelin's initializer pattern and a separate initializerERC721A modifier. Release cadence follows ERC721A main package. Differentiators: batch minting to save gas, upgradeable-friendly storage, explicit tooling recommendations (OpenZeppelin Upgrades Plugins). No peer dependencies beyond Solidity ^0.8.4.

Common errors

error TypeError: Wrong number of arguments to _mint, expected 3 but got 2 ↓

cause Using old ERC721A _mint signature with tokenId instead of quantity.

fix

Use _mint(address to, uint256 quantity) instead of _mint(address to, uint256 tokenId, bytes memory).

error Initializable: contract is already initialized ↓

cause Calling initialize() after it has already been called, or using only initializer modifier without initializerERC721A.

fix

Ensure initialize() is called only once, and use initializerERC721A for ERC721AUpgradeable parts.

Warnings

breaking Major version upgrades (e.g., 3.x to 4.x) have storage incompatibilities, making existing proxies unsafe to upgrade. ↓

fix Deploy a new proxy with the new implementation; do not upgrade an existing proxy across major versions.

gotcha If using OpenZeppelin extensions (e.g., ERC2981), supportsInterface may not be automatically added; must manually override. ↓

fix Override supportsInterface to include both ERC721A and extension interfaces, e.g., function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) { return super.supportsInterface(interfaceId) || ...; }

gotcha Must use both initializerERC721A and initializer modifiers if inheriting from OpenZeppelin contracts. ↓

fix Define initialize() with both modifiers: function initialize() initializerERC721A initializer public { ... }

deprecated Version 3.x is considered deprecated; use 4.x for diamond storage and latest features. ↓

fix Migrate to version 4.x following the official migration guide.

Install

npm install erc721a-upgradeable

yarn add erc721a-upgradeable

pnpm add erc721a-upgradeable

Imports

ERC721AUpgradeable

wrong

import '@openzeppelin/contracts/token/ERC721/ERC721.sol';

correct

import 'erc721a-upgradeable/contracts/ERC721AUpgradeable.sol';

Must use the upgradeable variant, not the base ERC721A or OpenZeppelin ERC721.

initializerERC721A

wrong

contract MyContract is ERC721AUpgradeable { function initialize() initializer public { ... } }

correct

contract MyContract is ERC721AUpgradeable { function initialize() initializerERC721A public { ... } }

initializerERC721A replaces initializer for ERC721A specific initialization; both modifiers may be needed when mixing other base contracts.

__ERC721A_init
wrong
```
__ERC721A_init_unchained('MyToken', 'MTK');
```
correct
```
__ERC721A_init('MyToken', 'MTK');
```
Use __ERC721A_init for full initialization including inherited setup; __ERC721A_init_unchained is only for base contract chains.
_mint
wrong
```
_mint(msg.sender, tokenId);
```
correct
```
_mint(msg.sender, quantity);
```
In ERC721A, _mint takes quantity (number of tokens to mint) instead of a single tokenId.

Quickstart

Deploys an upgradeable ERC721A contract with Ownable, batch minting function, and admin mint function.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.4;

import 'erc721a-upgradeable/contracts/ERC721AUpgradeable.sol';
import '@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol';

contract MyNFT is ERC721AUpgradeable, OwnableUpgradeable {
    function initialize() initializerERC721A initializer public {
        __ERC721A_init('MyNFT', 'NFT');
        __Ownable_init();
    }

    function mint(uint256 quantity) external payable {
        _mint(msg.sender, quantity);
    }

    function adminMint(uint256 quantity) external payable onlyOwner {
        _mint(msg.sender, quantity);
    }
}