{"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,"search_vec":"'-2535':32 '0.8.4':87 '3':45 '4':48 'across':37 'batch':20,67 'beyond':85 'break':42 'cadenc':61 'chang':41 'compat':36 'depend':84 'diamond':28 'differenti':66 'e.g':44 'effici':16 'eip':31 'erc721':17 'erc721a':1,4,12,63 'erc721a-upgradeable':3 'explicit':76 'follow':62 'friend':74 'gas':15,71 'gas-effici':14 'implement':18 'initi':53 'initializererc721a':58 'javascript':88 'layout':35 'main':64 'major':39 'mint':21,68 'modifi':59 'nfts':24 'openzeppelin':51,79 'packag':65 'pattern':30,54 'peer':83 'plugin':81 'popular':22 'recommend':78 'releas':60 'requir':50 'save':70 'separ':57 'solid':86 'storag':29,34,43,75 'tool':77 'upgrad':2,5,9,38,73,80 'upgradeable-friend':72 'use':26 'v4.3.0':6 'variant':10 'version':40 'x':46,49","created_at":"2026-05-01T13:43:42.986881+00:00","updated_at":"2026-05-01T13:43:42.986881+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://www.erc721a.org","github":"https://github.com/chiru-labs/ERC721A-Upgradeable","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/erc721a-upgradeable","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","database","auth-security"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-05-01","next_check":"2026-07-30","install_tag":null}}