Check NFT supply invariants
totalSupply, the highest token id, and the count of live owners drift apart in collections with burns, gaps, or enumeration tricks; assert the invariants before trusting any number.
Procedure
Read the reported supply and the cap:
cast call $NFT "totalSupply()(uint256)" --rpc-url $RPC cast call $NFT "maxSupply()(uint256)" --rpc-url $RPCCheck whether ids are contiguous:
for i in $(seq 1 $N); do cast call $NFT "ownerOf(uint256)(address)" $i --rpc-url $RPC \ || echo "missing $i"; doneReconstruct supply from mint and burn events and compare with
totalSupply():mints=$(cast logs --address $NFT "Transfer(address,address,uint256)" --from-block $START --json \ | jq '[.[]|select(.topics[1]==ZERO)]|length') burns=$(... select(.topics[2]==ZERO) ... ) echo $((mints - burns))Check the invariant
totalSupply() <= maxSupply, ortotalSupply() + burned == maxSupplyif the collection burns toward a fixed cap.Verify owner enumeration is not relied upon for correctness;
balanceOfsummed over live holders should equaltotalSupplywhen owners are tracked.For ERC-721A-style lazy ownership, confirm
totalSupplyreflects the batch, not the number ofTransferevents.
Pitfalls
- ERC-721A emits one
Transferper batch mint, so naive event counting undercounts unless you account for batches. totalSupplyoften starts at 0 while ids start at 1; the cap-versus-supply off-by-one either oversells a slot or wastes one.- Burned ids that are re-mintable break the "supply never grows after the cap" invariant.
- A proxy upgrade that resets
_totalMintedreports a supply contradicting the events. - Marketplace item counts include un-minted reservations, so their number differs from
totalSupply.
Verification
echo $((mints - burns)); cast call $NFT "totalSupply()(uint256)" --rpc-url $RPC
Pass: the event-derived count equals totalSupply(), ids are contiguous or the gaps are explained, and totalSupply() <= maxSupply. Report both numbers, the gap list, and the burn count.