{"id":25235,"library":"erc721a-upgradeable","title":"ERC721A Upgradeable","description":"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.","status":"active","version":"4.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/chiru-labs/ERC721A-Upgradeable","tags":["javascript"],"install":[{"cmd":"npm install erc721a-upgradeable","lang":"bash","label":"npm"},{"cmd":"yarn add erc721a-upgradeable","lang":"bash","label":"yarn"},{"cmd":"pnpm add erc721a-upgradeable","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Must use the upgradeable variant, not the base ERC721A or OpenZeppelin ERC721.","wrong":"import '@openzeppelin/contracts/token/ERC721/ERC721.sol';","symbol":"ERC721AUpgradeable","correct":"import 'erc721a-upgradeable/contracts/ERC721AUpgradeable.sol';"},{"note":"initializerERC721A replaces initializer for ERC721A specific initialization; both modifiers may be needed when mixing other base contracts.","wrong":"contract MyContract is ERC721AUpgradeable { function initialize() initializer public { ... } }","symbol":"initializerERC721A","correct":"contract MyContract is ERC721AUpgradeable { function initialize() initializerERC721A public { ... } }"},{"note":"Use __ERC721A_init for full initialization including inherited setup; __ERC721A_init_unchained is only for base contract chains.","wrong":"__ERC721A_init_unchained('MyToken', 'MTK');","symbol":"__ERC721A_init","correct":"__ERC721A_init('MyToken', 'MTK');"},{"note":"In ERC721A, _mint takes quantity (number of tokens to mint) instead of a single tokenId.","wrong":"_mint(msg.sender, tokenId);","symbol":"_mint","correct":"_mint(msg.sender, quantity);"}],"quickstart":{"code":"// SPDX-License-Identifier: MIT\npragma solidity ^0.8.4;\n\nimport 'erc721a-upgradeable/contracts/ERC721AUpgradeable.sol';\nimport '@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol';\n\ncontract MyNFT is ERC721AUpgradeable, OwnableUpgradeable {\n    function initialize() initializerERC721A initializer public {\n        __ERC721A_init('MyNFT', 'NFT');\n        __Ownable_init();\n    }\n\n    function mint(uint256 quantity) external payable {\n        _mint(msg.sender, quantity);\n    }\n\n    function adminMint(uint256 quantity) external payable onlyOwner {\n        _mint(msg.sender, quantity);\n    }\n}","lang":"solidity","description":"Deploys an upgradeable ERC721A contract with Ownable, batch minting function, and admin mint function."},"warnings":[{"fix":"Deploy a new proxy with the new implementation; do not upgrade an existing proxy across major versions.","message":"Major version upgrades (e.g., 3.x to 4.x) have storage incompatibilities, making existing proxies unsafe to upgrade.","severity":"breaking","affected_versions":">=4.0.0 <5.0.0"},{"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) || ...; }","message":"If using OpenZeppelin extensions (e.g., ERC2981), supportsInterface may not be automatically added; must manually override.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Define initialize() with both modifiers: function initialize() initializerERC721A initializer public { ... }","message":"Must use both initializerERC721A and initializer modifiers if inheriting from OpenZeppelin contracts.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Migrate to version 4.x following the official migration guide.","message":"Version 3.x is considered deprecated; use 4.x for diamond storage and latest features.","severity":"deprecated","affected_versions":"3.x"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use _mint(address to, uint256 quantity) instead of _mint(address to, uint256 tokenId, bytes memory).","cause":"Using old ERC721A _mint signature with tokenId instead of quantity.","error":"TypeError: Wrong number of arguments to _mint, expected 3 but got 2"},{"fix":"Ensure initialize() is called only once, and use initializerERC721A for ERC721AUpgradeable parts.","cause":"Calling initialize() after it has already been called, or using only initializer modifier without initializerERC721A.","error":"Initializable: contract is already initialized"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}