A fully on-chain generative NFT project that guarantees configurable rarity for each trait and strict uniqueness of every NFT (no duplicate combinations possible). All traits and images are generated and stored on-chain using Solidity smart contracts.

• 100% On-Chain: All images and metadata generated on-chain
• Configurable Rarity: Fine-tune rarity weights via JSON configuration
• Guaranteed Uniqueness: No duplicate trait combinations possible
• Multi-Phase Minting: GTD (free), Whitelist, and Public phases
• Automatic Verification: All contracts verified on BaseScan
• Web3 Integration: Includes a minting dapp

Dgenz_Onchain/
├── 📁 layers/                    # PNG trait images (organize by category)
├── 📁 svgs/                     # Generated SVGs (auto-generated)
├── 📁 contracts/                # Solidity smart contracts
│   ├── DgenzOC.sol             # Main NFT contract
│   ├── SVGAssembler.sol        # SVG assembly contract
│   ├── DgenzTraits.sol         # Trait definitions library
│   ├── DgenzRarity.sol         # Rarity calculation library
│   ├── BackgroundRenderer.sol   # Background SVG renderer
│   ├── RaceRenderer.sol         # Race SVG renderer
│   ├── OutfitRenderer.sol       # Outfit SVG renderer
│   ├── EyesRenderer.sol         # Eyes SVG renderer
│   ├── TopHeadRenderer.sol      # Top head SVG renderer
│   ├── AccessoryRenderer.sol    # Accessory SVG renderer
│   ├── MouthRenderer.sol        # Mouth SVG renderer
│   └── CheckmarkRenderer.sol    # Checkmark SVG renderer
├── 📁 scripts/                  # Deployment and utility scripts
├── 📁 webapp/                   # Minting dapp (Next.js)
├── 📄 generate_all.js           # Main generation script
├── 📄 compile_and_deploy.js     # Full deployment workflow
├── 📄 import_allowlist.js       # Allowlist import utility
├── 📄 update_webapp.js          # Webapp configuration updater
├── 📄 calculate_bytecode_size.js # Contract size calculator
├── 📄 calculate_total_combinations.js # Trait combination calculator
├── 📄 rarity_config.json        # Trait rarity configuration
├── 📄 shared_layers_order.json  # Layer ordering configuration
├── 📄 deployed_addresses.json   # Deployed contract addresses
├── 📄 gtd_list.csv              # GTD allowlist (CSV format)
├── 📄 whitelist.csv             # Whitelist allowlist (CSV format)
└── 📄 README.md                 # This documentation file

Edit generate_all.js to customize your collection:

const TRAITS_LIB = 'DgenzTraits'; // Traits library name
const CONTRACT_NAME = 'DgenzOC'; // Contract name
const COLLECTION_NAME = 'Dgenz Onchain';  // Collection name
const SYMBOL = 'DGOC'; // Symbol
const COLLECTION_DESCRIPTION = '1069 Dgenz Onchain.'; // Collection description
const ROYALTY_FEE_BPS = 690; // 690 = 6,9% (in basis points)
const MAX_SUPPLY = 1069; // Max supply
const MAX_MINT_PER_ADDRESS_GTD = 1; // Max mint per address in GTD phase
const MAX_MINT_PER_ADDRESS_WHITELIST = 3; // Max mint per address in Whitelist phase
const MAX_MINT_PER_ADDRESS_PUBLIC = 5; // Max mint per address in Public phase
const WHITELIST_PRICE = '0.0003 ether'; // Price for whitelist mint
const PUBLIC_PRICE = '0.00069 ether'; // Price for public mint
const MINT_COUNT_ON_DEPLOY = 1; // Number of NFTs to mint during deployment

Configure the trait order in generate_all.js:

const LAYER_ORDER = [
  'Background',
  'Race', 
  'Outfit',
  'Eyes',
  'Top Head',
  'Accessory',
  'Mouth',
  'Checkmark'
];

1. Add PNG files to appropriate layers/ subfolder
2. Run generation: node generate_all.js
3. Deploy: npx hardhat run compile_and_deploy.js --network base

npm install

Create a .env file:

PRIVATE_KEY=your_private_key
RPC_URL=https://base-mainnet.g.alchemy.com/v2/YOUR_API_KEY
BASESCAN_API_KEY=your_basescan_api_key

Place PNG trait images in layers/ subfolders:

layers/
├── Background/
├── Race/
├── Outfit/
├── Eyes/
├── Top Head/
├── Accessory/
├── Mouth/
└── Checkmark/

node generate_rarity_config.js

Edit rarity_config.json to set trait weights.

node generate_all.js

npx hardhat run compile_and_deploy.js --network base

flowchart TD
    A[Prepare PNG Layers] --> B[Configure rarity_config.json]
    B --> C[Run generate_all.js]
    C --> D[Contracts Generated]
    D --> E[Deploy with compile_and_deploy.js]
    E --> F[Contracts Deployed & Verified]
    F --> G[Set up allowlists]
    G --> H[Configure webapp]
    H --> I[Launch Collection]

graph TD
    A[DgenzOC - Main Contract] --> B[SVGAssembler]
    B --> C[BackgroundRenderer]
    B --> D[RaceRenderer]
    B --> E[OutfitRenderer]
    B --> F[EyesRenderer]
    B --> G[TopHeadRenderer]
    B --> H[AccessoryRenderer]
    B --> I[MouthRenderer]
    B --> J[CheckmarkRenderer]
    A --> K[DgenzTraits Library]
    A --> L[DgenzRarity Library]

• DgenzOC: Main ERC721 contract with minting logic
• SVGAssembler: Combines trait SVGs into final image
• Renderer Contracts: Store SVG code for each trait
• DgenzTraits: Trait definitions and metadata
• DgenzRarity: Weighted random selection logic

The contract supports three minting phases:

• GTD Phase (0): Free minting for GTD-listed addresses
• Whitelist Phase (1): 0.0003 ETH for whitelist-listed addresses
• Public Phase (2): 0.00069 ETH for everyone

# Set minting phase
npx hardhat run scripts/set_phase.js --network base 1

# Pause/Unpause minting
npx hardhat console --network base
const contract = await ethers.getContractAt("DgenzOC", "CONTRACT_ADDRESS");
await contract.pause(); // or await contract.unpause();

# Import GTD list (adds to both GTD and Whitelist)
node import_allowlist.js gtd

# Import whitelist (adds to Whitelist only)
node import_allowlist.js whitelist

Create CSV files (gtd_list.csv, whitelist.csv) with one address per line.

Note: GTD addresses are automatically added to both GTD and Whitelist lists, while Whitelist addresses are only added to the Whitelist.

node update_webapp.js
cd webapp
npm install
# Add NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID to .env.local
# Edit page.tsx
npm run dev

• mint(uint256 quantity) - Mint NFTs
• tokenURI(uint256 tokenId) - Get token metadata and SVG image
• getMintPrice(address minter) - Get mint price for a given address
• getMaxMintPerAddress(address minter) - Get maximum mint per address
• totalSupply() - Get total number of minted tokens
• totalMinted() - Alias for totalSupply() (ERC721A compatibility)
• currentPhase() - Get current minting phase (GTD, WHITELIST, PUBLIC)
• supportsInterface(bytes4 interfaceId) - Check ERC interface support
• getRoyaltyInfo(uint256 tokenId, uint256 salePrice) - Get royalty information

• setPhase(MintPhase phase) - Change minting phase (GTD, WHITELIST, PUBLIC)
• addToGTDList(address[] calldata addrs) - Add addresses to GTD list
• addToWhitelist(address[] calldata addrs) - Add addresses to whitelist
• pause() - Pause minting (emergency control)
• unpause() - Resume minting after pause
• withdraw() - Withdraw contract funds to owner
• bumpRandomness(uint256 extra) - Improve entropy of random generation system

• mintedPerAddress(address) - Number of tokens minted per address
• isGTDListed(address) - Check if address is in GTD list
• isWhitelistListed(address) - Check if address is in whitelist
• tokenTraits(uint256 tokenId) - Get traits of a specific token
• isCombinationMinted(bytes32 hash) - Check if a trait combination has already been minted

• GTD_PRICE - Price for GTD phase (0 ETH)
• WHITELIST_PRICE - Price for whitelist phase (0.0003 ETH)
• PUBLIC_PRICE - Price for public phase (0.00069 ETH)
• MAX_SUPPLY - Maximum supply (1069)
• MAX_MINT_PER_ADDRESS_GTD - Max mint per address in GTD phase (1)
• MAX_MINT_PER_ADDRESS_WHITELIST - Max mint per address in whitelist phase (3)
• MAX_MINT_PER_ADDRESS_PUBLIC - Max mint per address in public phase (5)

• _generateSeedFromHash(bytes32 hash, uint256 salt) - Generate random seed from hash
• _generateTraitsFromHash(bytes32 hash) - Generate traits from hash
• _random(uint256 tokenId, uint256 salt) - Internal random generation function
• _random(uint256 tokenId, uint256 salt, uint8 max) - Version with maximum limit

• _buildAttributes(Traits memory t) - Build JSON attributes for metadata
• _addAttribute(string memory result, bool first, string memory traitName, string memory traitValue) - Add attribute to metadata
• _attribute(string memory trait_type, string memory value) - Format individual attribute
• _base64(bytes memory data) - Encode data to base64 for image URIs

• Minted(address indexed minter, uint256 indexed tokenId) - Emitted when minting a token
• Withdrawn(address indexed to, uint256 amount) - Emitted when withdrawing funds
• PhaseChanged(MintPhase indexed oldPhase, MintPhase indexed newPhase) - Emitted when changing phase

• Never share private keys - Use dedicated wallets
• Test on testnets - Deploy to Base Sepolia first
• Fund your wallet - Ensure sufficient ETH for gas
• Review contracts - Check generated code before mainnet

• Node.js >= 18
• Hardhat
• Base network RPC URL
• BaseScan API key
• Wallet with ETH for gas

• BaseScan
• Base Network
• Hardhat Documentation
• OpenZeppelin Contracts

"Stack too deep" errors

• Ensure viaIR: true in hardhat.config.js
• Reduce number of traits per layer

Environment variable errors

• Use npx hardhat run instead of node
• Check .env file configuration

Contract verification fails

• Wait 10-15 seconds after deployment
• Check constructor arguments match

Minting fails

• Check current phase and pricing
• Ensure wallet has sufficient ETH
• Verify contract is not paused

For questions or support:

• Contact: @0x_Quickosss

MIT License

Ready to launch your on-chain NFT collection! 🚀