neozipkit 0.2.1 → 0.3.0

package/contracts/README.md

@@ -1,152 +1,256 @@
-# NeoZipKit Smart Contracts
+# Smart Contracts
 
-This directory contains production-ready smart contracts for ZIP file tokenization and their deployment utilities.
+This directory contains the smart contracts and related data for the NeoZipKit library.
 
-## 🎯 Contract Types
+## Contract Files
 
-### 🌐 Main Contract (`NZIP-NFT.sol`)
-- **Universal verification** - Anyone can verify any token
-- **Public blockchain metadata** - All data visible on blockchain
-- **Use cases**: Certificates, public records, open-source projects, general tokenization
-- **Symbol**: `NZIP`
+- **`src/NZIP-NFT.sol`** - Main production contract for ZIP file tokenization
+- **`src/NZIP-NFT-v2.0.sol`** - Version 2.0 contract implementation
+- **`ABI.txt`** - Contract ABI (Application Binary Interface)
+- **`Bytecode.txt`** - Contract bytecode for deployment
 
-## 📍 Current Deployment
+## Contract Information
 
-**✅ Production Contract (v2.0)**:
-```
-Address: 0xFD76a5d420704F34d84b0767961835c43D7b30a8
-Network: Base Sepolia
-Version: 2.0.0
-Status: ✅ ACTIVE - Use for all new integrations
-Explorer: https://sepolia.basescan.org/address/0xFD76a5d420704F34d84b0767961835c43D7b30a8
+### Current Production Contract
+- **Address**: `0x6313074922717351986929879903441992482216`
+- **Network**: Base Sepolia (Chain ID: 84532)
+- **Version**: 2.10.0
+- **Status**: ✅ Active
+
+### Contract Features
+- ZIP file tokenization as ERC-721 NFTs
+- Merkle root verification for file integrity
+- Duplicate prevention via composite key system
+- Blockchain metadata storage
+- Universal verification (anyone can verify tokens)
+
+## Compilation and Deployment
+
+### Compiling the Contract
+
+To compile the contract and generate compiled ABI and bytecode:
+
+```bash
+cd contracts
+yarn install          # First time only
+yarn compile:extract  # Compile and extract ABI/bytecode
 ```
 
-## 🔧 Supported Features
+This will:
+- Compile `src/NZIP-NFT.sol` using Hardhat
+- Extract the ABI and write it to `ABI-compiled.txt`
+- Extract the bytecode and write it to `Bytecode-compiled.txt`
 
-- **NFT Tokenization**: Convert ZIP files into ERC-721 NFTs with complete metadata
-- **Blockchain Verification**: Verify ZIP file authenticity against blockchain tokens
-- **OpenTimestamps**: Bitcoin blockchain timestamping for file integrity
-- **Multi-Network Support**: Base Mainnet, Base Sepolia, Ethereum, Polygon, Arbitrum
-- **Smart Contracts**: Production-ready contracts for public and private tokenization
+**⚠️ IMPORTANT:** The compilation script does NOT overwrite `ABI.txt` and `Bytecode.txt` (these are the deployed versions). The compiled files are written to `ABI-compiled.txt` and `Bytecode-compiled.txt` for review. Only manually copy them to `ABI.txt` and `Bytecode.txt` if you want to use the new compilation for deployment.
 
-## 🏗️ Blockchain Components
+### Deploying the Contract
 
-- **`TokenVerifier`** - Verify tokenized ZIP files against blockchain
-- **`NFTMinter`** - Mint NFTs for ZIP files
-- **`TokenQuerier`** - Query token information from blockchain
-- **`CertificateToken`** - Generate certificates for tokenized files
-- **`ZipTokenProcessor`** - Process ZIP files for tokenization
-- **`WalletManager`** - Manage wallet connections and networks
+**SECURITY WARNING**: Contract deployment requires a private key with sufficient funds for gas fees.
 
-## 📁 Directory Structure
+- ⚠️ **NEVER** hardcode private keys in deployment scripts
+- ⚠️ **NEVER** commit private keys to version control
+- ✅ Use environment variables or interactive prompts for private keys
+- ✅ Use testnet keys for development/testing
+- ✅ Use secure key management (HSMs, KMS) for production deployments
+- ✅ Verify network selection before deployment (especially for mainnet)
 
-```
-contracts/
-├── src/                           # Smart contract source files
-│   ├── NZIP-NFT.sol              # Main tokenization contract
-│   ├── NZIP-NFT-Private.sol      # Private tokenization contract
-│   └── *.sol                     # Legacy and deprecated contracts
-├── constants.ts                   # Contract addresses and deployment info
-└── *.md                          # Documentation files
-```
+For complete security guidelines, see [../SECURITY.md](../SECURITY.md).
+
+Deploy to any supported network using the interactive deployment script:
 
-## 🚀 Quick Start
-
-1. **Deploy contract using Remix IDE**:
-   - Open [Remix IDE](https://remix.ethereum.org/)
-   - Upload contract files from `src/` directory
-   - Compile and deploy using Remix 
-
-2. **Integrate with your application**:
-   ```typescript
-   import { ZipTokenProcessor, MintingOptions } from 'neozipkit/server/blockchain';
-   
-   const options: MintingOptions = {
-     wallet: 'path/to/wallet.json',
-     network: 'base-sepolia',
-     mintToken: true
-   };
-
-   const processor = new ZipTokenProcessor('archive.zip', 'merkle_root_hash', options);
-   const result = await processor.processZipToken(options);
-
-   if (result.error) {
-     console.error('Processing failed:', result.error);
-   } else {
-     console.log('Success!', result);
-   }
-   ```
-3. **Command-line deployment scripts**
-
-   - Base Mainnet
-     ```bash
-     cd /Users/stevenburg/Projects/NeoWare/neozipkit
-     export PRIVATE_KEY=0xYOUR_DEPLOYER_PRIVATE_KEY
-     export BASE_RPC_URL=https://mainnet.base.org
-     node contracts/deploy-bytecode.mjs
-     ```
-
-   - Base Sepolia
-     ```bash
-     cd /Users/stevenburg/Projects/NeoWare/neozipkit
-     export PRIVATE_KEY=0xYOUR_DEPLOYER_PRIVATE_KEY
-     export NETWORK=base-sepolia
-     export BASE_RPC_URL=https://sepolia.base.org
-     node contracts/deploy-bytecode.mjs
-     ```
-
-   - Ethereum Mainnet
-     ```bash
-     cd /Users/stevenburg/Projects/NeoWare/neozipkit
-     export PRIVATE_KEY=0xYOUR_DEPLOYER_PRIVATE_KEY
-     export NETWORK=eth
-     export ETH_RPC_URL=https://mainnet.infura.io/v3/YOUR_KEY
-     node contracts/deploy-bytecode.mjs
-     ```
-
-## 📦 Contract Constants and ABI
-
-Contract addresses and deployment info are in `contracts/constants.ts`, while the ABI is in `src/blockchain/abi.ts`.
-
-**Contract Constants** (`contracts/constants.ts`):
-- `CONTRACT_ADDRESSES`: ChainId → address map (`NZIP_NFT` group)
-- `DEPRECATED_CONTRACTS`: Historical addresses
-- `CURRENT_DEPLOYMENT`: Current network, chainId, address, and tx/explorer info
-
-**Contract ABI** (`src/blockchain/abi.ts`):
-- `NZIP_CONTRACT_ABI`: Full contract ABI for integration
-
-Example usage:
-```ts
-// For deployment scripts and contract management
-import { CONTRACT_ADDRESSES, CURRENT_DEPLOYMENT } from '../contracts/constants';
-
-// For application integration
-import { NZIP_CONTRACT_ABI } from 'neozipkit/blockchain/abi';
-import { CONTRACT_ADDRESSES } from 'neozipkit/blockchain/constants';
-
-const baseSepolia = CONTRACT_ADDRESSES.NZIP_NFT[84532];
-console.log('Base Sepolia NZIP‑NFT:', baseSepolia);
-console.log('ABI functions:', NZIP_CONTRACT_ABI.map((f: any) => f.name).filter(Boolean));
+```bash
+cd contracts
+node deploy-interactive.js
 ```
 
-## 🔐 Security Considerations
+The script will prompt you for:
+- Private key (not saved, entered securely)
+- Network selection (ETH, ETH Sepolia, Base, Base Sepolia, Arbitrum, Arbitrum Sepolia, Polygon, Polygon Sepolia)
+- Confirmation before deployment
 
-### Development Best Practices
+**Note**: The interactive deployment script does not save your private key. It is only used during the deployment process and never stored.
 
-- **Private Keys**: Never commit private keys or mnemonics to version control
-- **Network Security**: Use secure RPC endpoints and validate all inputs
-- **Smart Contract Audits**: Audit contracts before production deployment
-- **Error Handling**: Implement comprehensive error handling for all operations
-- **Type Safety**: Leverage TypeScript for compile-time error detection
+### Verifying the Contract
 
-### File Verification
+After deployment, verify the contract on the blockchain scanner:
 
-- **Merkle Trees**: All ZIP files use cryptographic Merkle trees for integrity verification
-- **Blockchain Anchoring**: Timestamps and hashes are anchored to blockchain networks
-- **Multi-Layer Verification**: Support for both OpenTimestamps and NFT-based verification
+```bash
+cd contracts
+yarn verify <contractAddress> <network>
+```
 
-## 📄 Additional Documentation
+Example:
+```bash
+yarn verify 0x2716c4609fD97DaEdF429BC4B4Ec2faa81e2cC60 arbitrumSepolia
+```
 
-- **[Network Configuration](./NETWORKS.md)** - Supported networks and configuration
-- **[Integration Guide](./INTEGRATION.md)** - How to integrate contracts with your application
+For detailed verification instructions, see [VERIFICATION.md](./VERIFICATION.md).
+
+## Integration
+
+The contract ABI and bytecode are automatically imported by the NeoZipKit library for blockchain operations. No manual configuration is required for basic usage.
+
+For advanced deployment and configuration, refer to the main project documentation.
+
+## Testnet Faucets
+
+**Testnets are recommended for early release versions of NeoZipKit.** Testnet tokens have no real-world value and are intended solely for development and testing purposes. Before requesting tokens, ensure your wallet is configured to connect to the appropriate testnet network. Most faucets have daily limits and rate restrictions to prevent abuse.
+
+### Ethereum Sepolia
+
+Ethereum Sepolia is the primary Ethereum testnet. **Note:** Sepolia testnet has been experiencing instability since the Pectra upgrade (March 2025), including transaction processing failures and RPC timeouts. Consider using Base Sepolia for more reliable testing.
+
+#### Alchemy Faucet
+- **URL**: https://sepoliafaucet.com/
+- **Daily Limit**: Up to 0.5 Sepolia ETH per day
+- **Requirements**: 
+  - Alchemy account (free registration)
+  - Sign in required
+- **Steps**:
+  1. Visit https://sepoliafaucet.com/
+  2. Sign in with your Alchemy account (create one if needed)
+  3. Enter your Ethereum wallet address
+  4. Click "Send Me ETH"
+  5. Wait for tokens to arrive (usually within minutes)
+
+#### Chainlink Faucet
+- **URL**: https://faucets.chain.link/sepolia
+- **Daily Limit**: 0.5 ETH per request
+- **Requirements**: 
+  - Wallet connection (MetaMask, WalletConnect, etc.)
+- **Steps**:
+  1. Visit https://faucets.chain.link/sepolia
+  2. Connect your wallet
+  3. Ensure your wallet is set to Sepolia network
+  4. Select "0.5 ETH" from the token options
+  5. Click "Drip" to receive tokens
+
+#### QuickNode Faucet
+- **URL**: https://faucet.quicknode.com/ethereum/sepolia
+- **Daily Limit**: 0.01 ETH per 24 hours
+- **Requirements**: 
+  - MetaMask wallet
+  - Optional: Share a tweet about QuickNode to double your daily limit
+- **Steps**:
+  1. Visit https://faucet.quicknode.com/ethereum/sepolia
+  2. Connect your MetaMask wallet
+  3. Ensure MetaMask is configured for Sepolia network (Chain ID: 11155111)
+  4. Optionally share a tweet to increase your limit
+  5. Click "Send Me ETH"
+
+#### Stakely Faucet
+- **URL**: https://stakely.io/faucet/ethereum-sepolia-testnet-eth
+- **Daily Limit**: 0.5 ETH per request
+- **Requirements**: 
+  - Twitter account
+  - Public tweet with request ID
+- **Steps**:
+  1. Visit https://stakely.io/faucet/ethereum-sepolia-testnet-eth
+  2. Enter your Ethereum Sepolia wallet address
+  3. Complete the captcha verification
+  4. Copy the provided request ID
+  5. Share a public tweet containing the request ID
+  6. Wait for processing and token delivery
+
+#### Tatum Faucet
+- **URL**: https://tatum.io/faucets/sepolia
+- **Daily Limit**: 0.002 Sepolia ETH every 24 hours
+- **Requirements**: 
+  - Tatum account (free registration)
+  - Minimum 0.001 ETH in your mainnet wallet (for verification)
+- **Steps**:
+  1. Visit https://tatum.io/faucets/sepolia
+  2. Sign up for a Tatum Dashboard account
+  3. Ensure your mainnet wallet has at least 0.001 ETH
+  4. Enter your Sepolia wallet address
+  5. Request tokens (available once every 24 hours)
+
+### Base Sepolia
+
+Base Sepolia is the official testnet for Base (Coinbase's L2 network). It's generally more stable than Ethereum Sepolia and recommended for testing.
+
+#### Alchemy Faucet
+- **URL**: https://basefaucet.com/
+- **Daily Limit**: Up to 0.5 Base Sepolia ETH per day
+- **Requirements**: 
+  - Alchemy account (free registration)
+  - Sign in required
+- **Steps**:
+  1. Visit https://basefaucet.com/
+  2. Sign in with your Alchemy account
+  3. Enter your Base wallet address
+  4. Click "Send Me ETH"
+  5. Wait for tokens to arrive
+
+#### Chainlink Faucet
+- **URL**: https://faucets.chain.link/
+- **Daily Limit**: 0.5 ETH per request
+- **Requirements**: 
+  - Wallet connection (MetaMask, WalletConnect, etc.)
+- **Steps**:
+  1. Visit https://faucets.chain.link/
+  2. Connect your wallet
+  3. Select "Base Sepolia" from the network dropdown
+  4. Choose "0.5 ETH" from token options
+  5. Click "Drip" to receive tokens
+
+#### Coinbase Developer Platform Faucet
+- **URL**: https://docs.base.org/tools/network-faucets
+- **Daily Limit**: 1 claim per 24 hours
+- **Requirements**: 
+  - Access to Coinbase Developer Platform
+- **Steps**:
+  1. Visit https://docs.base.org/tools/network-faucets
+  2. Navigate to the Base Sepolia faucet section
+  3. Enter your Base Sepolia wallet address
+  4. Request testnet tokens
+  5. Wait for confirmation (usually within minutes)
+
+#### thirdweb Faucet
+- **URL**: Available via https://docs.base.org/tools/network-faucets
+- **Daily Limit**: 1 claim per 24 hours
+- **Requirements**: 
+  - Wallet connection via EOA (Externally Owned Account) or social logins
+- **Steps**:
+  1. Visit the Base documentation faucet page
+  2. Access the thirdweb faucet option
+  3. Connect your wallet (EOA or social login)
+  4. Ensure your wallet is set to Base Sepolia network
+  5. Claim your testnet funds
+
+### Arbitrum Sepolia
+
+Arbitrum Sepolia is the testnet for Arbitrum One, an Ethereum Layer 2 scaling solution.
+
+#### Chainlink Faucet
+- **URL**: https://faucets.chain.link/
+- **Daily Limit**: 0.5 ETH per request
+- **Requirements**: 
+  - Wallet connection (MetaMask, WalletConnect, etc.)
+- **Steps**:
+  1. Visit https://faucets.chain.link/
+  2. Connect your wallet
+  3. Select "Arbitrum Sepolia" from the network dropdown
+  4. Choose "0.5 ETH" from token options
+  5. Click "Drip" to receive tokens
+
+#### QuickNode Faucet
+- **URL**: https://faucet.quicknode.com/
+- **Daily Limit**: Varies by network
+- **Requirements**: 
+  - MetaMask wallet
+  - Network configuration for Arbitrum Sepolia
+- **Steps**:
+  1. Visit https://faucet.quicknode.com/
+  2. Select "Arbitrum Sepolia" from available networks
+  3. Connect your MetaMask wallet
+  4. Ensure MetaMask is configured for Arbitrum Sepolia (Chain ID: 421614)
+  5. Request testnet tokens
+
+### General Tips
+
+- **Wallet Configuration**: Always ensure your wallet is set to the correct testnet network before requesting tokens
+- **Rate Limits**: Most faucets have daily limits; plan your testing activities accordingly
+- **Network Congestion**: If you experience delays, try again later or use an alternative faucet
+- **Multiple Faucets**: You can use multiple faucets to accumulate more testnet tokens if needed
+- **No Real Value**: Remember that testnet tokens have no real-world value and cannot be converted to mainnet tokens

package/contracts/VERIFICATION.md

@@ -0,0 +1,308 @@
+# Contract Verification Guide
+
+This guide explains how to verify your deployed NeoZip NFT contract on blockchain scanners using Hardhat and Etherscan API V2.
+
+## Overview
+
+Contract verification makes your contract's source code publicly visible on block explorers, allowing users to:
+- View and audit the contract source code
+- Interact with the contract through the explorer's UI
+- Verify that the deployed bytecode matches the source code
+
+All verification uses **Etherscan API V2**, which is the unified API for Etherscan and its family of block explorers (Arbiscan, Basescan, Polygonscan, etc.).
+
+## Prerequisites
+
+1. **Etherscan API Key**: Get a free API key from [Etherscan](https://etherscan.io/apis)
+   - This single API key works for all Etherscan-based explorers (Etherscan, Arbiscan, Basescan, Polygonscan)
+   - No need for separate API keys per network
+
+2. **Hardhat Setup**: Ensure you've installed dependencies:
+   ```bash
+   cd contracts
+   yarn install
+   ```
+
+3. **Environment Variable**: Set your Etherscan API key:
+   ```bash
+   export ETHERSCAN_API_KEY=your_api_key_here
+   ```
+   
+   Or add it to `hardhat.config.js`:
+   ```javascript
+   etherscan: {
+     apiKey: {
+       mainnet: "your_api_key_here",
+       // ... other networks
+     }
+   }
+   ```
+
+## Quick Start
+
+### Step 1: Compile the Contract
+
+Before deploying, compile the contract to generate compiled ABI and bytecode:
+
+```bash
+cd contracts
+yarn compile:extract
+```
+
+This will:
+- Compile `src/NZIP-NFT.sol` using Hardhat
+- Extract the ABI and write it to `ABI-compiled.txt`
+- Extract the bytecode and write it to `Bytecode-compiled.txt`
+
+**⚠️ IMPORTANT:** The compilation script does NOT overwrite `ABI.txt` and `Bytecode.txt` (these are the deployed versions that match contracts already on-chain). The compiled files are written to `ABI-compiled.txt` and `Bytecode-compiled.txt` for review. Only manually copy them to `ABI.txt` and `Bytecode.txt` if you want to use the new compilation for deployment.
+
+### Step 2: Deploy the Contract
+
+Deploy using the interactive deployment script:
+
+```bash
+cd contracts
+node deploy-interactive.js
+```
+
+Or use any other deployment method. Make sure to save the contract address.
+
+### Step 3: Verify the Contract
+
+After deployment, verify the contract:
+
+```bash
+cd contracts
+yarn verify <contractAddress> <network>
+```
+
+**Examples:**
+```bash
+# Verify on Arbitrum Sepolia
+yarn verify 0x2716c4609fD97DaEdF429BC4B4Ec2faa81e2cC60 arbitrumSepolia
+
+# Verify on Ethereum Sepolia
+yarn verify 0x2716c4609fD97DaEdF429BC4B4Ec2faa81e2cC60 sepolia
+
+# Verify on Base Sepolia
+yarn verify 0x2716c4609fD97DaEdF429BC4B4Ec2faa81e2cC60 baseSepolia
+```
+
+## Supported Networks
+
+The verification script supports the following networks:
+
+| Network Name | Hardhat Config Name | Explorer |
+|-------------|---------------------|----------|
+| Ethereum Mainnet | `ethereum` | [Etherscan](https://etherscan.io) |
+| Ethereum Sepolia | `sepolia` | [Sepolia Etherscan](https://sepolia.etherscan.io) |
+| Base Mainnet | `base` | [Basescan](https://basescan.org) |
+| Base Sepolia | `baseSepolia` | [Base Sepolia Explorer](https://sepolia.basescan.org) |
+| Arbitrum One | `arbitrum` | [Arbiscan](https://arbiscan.io) |
+| Arbitrum Sepolia | `arbitrumSepolia` | [Arbitrum Sepolia Explorer](https://sepolia.arbiscan.io) |
+| Polygon Mainnet | `polygon` | [Polygonscan](https://polygonscan.com) |
+| Polygon Sepolia (Amoy) | `polygonSepolia` | [Amoy Polygonscan](https://amoy.polygonscan.com) |
+
+### Network Name Aliases
+
+You can use any of these names when verifying:
+- `sepolia`, `eth-sepolia`, `ethereum-sepolia`
+- `baseSepolia`, `base-sepolia`
+- `arbitrumSepolia`, `arbitrum-sepolia`
+- `polygonSepolia`, `polygon-sepolia`, `amoy`
+
+## Detailed Verification Steps
+
+### 1. Get Your Etherscan API Key
+
+1. Visit [Etherscan API](https://etherscan.io/apis)
+2. Sign up or log in to your Etherscan account
+3. Create a new API key
+4. Copy the API key
+
+### 2. Set the API Key
+
+**Option A: Environment Variable (Recommended)**
+```bash
+export ETHERSCAN_API_KEY=your_api_key_here
+```
+
+**Option B: hardhat.config.js**
+```javascript
+etherscan: {
+  apiKey: {
+    mainnet: "your_api_key_here",
+    sepolia: "your_api_key_here",
+    // ... same key for all networks
+  }
+}
+```
+
+### 3. Verify the Contract
+
+```bash
+cd contracts
+yarn verify <contractAddress> <network>
+```
+
+The script will:
+1. Validate the contract address
+2. Check network configuration
+3. Verify the API key is set
+4. Submit verification request to the appropriate explorer
+5. Display the explorer URL once verified
+
+## Troubleshooting
+
+### Error: "Etherscan API key not found"
+
+**Solution:**
+- Set the `ETHERSCAN_API_KEY` environment variable
+- Or add it to `hardhat.config.js` in the `etherscan.apiKey` section
+
+### Error: "Bytecode mismatch"
+
+This error means the deployed bytecode doesn't match the compiled source code.
+
+**Common Causes:**
+1. Contract was compiled with different compiler settings
+2. Source code has changed since deployment
+3. Different Solidity version was used
+
+**Solutions:**
+1. **Recompile and redeploy:**
+   ```bash
+   cd contracts
+   yarn compile:extract
+   # Redeploy with new bytecode
+   node deploy-interactive.js
+   # Verify again
+   yarn verify <address> <network>
+   ```
+
+2. **Match exact compiler settings:**
+   - Check the deployed contract's compiler version on the explorer
+   - Update `hardhat.config.js` to match:
+     ```javascript
+     solidity: {
+       version: "0.8.19", // Match deployed version
+       settings: {
+         optimizer: {
+           enabled: true,
+           runs: 200 // Match deployed settings
+         }
+       }
+     }
+     ```
+
+### Error: "Already Verified"
+
+This is not an error! The contract is already verified on the explorer. You can view it on the explorer's website.
+
+### Error: "Network not configured"
+
+**Solution:**
+- Check that the network name matches one in `hardhat.config.js`
+- Use the exact network name from the config (e.g., `arbitrumSepolia`, not `arbitrum-sepolia`)
+
+### Verification Takes Too Long
+
+Verification can take 30 seconds to several minutes depending on:
+- Network congestion
+- Explorer API response time
+- Contract complexity
+
+Wait for the process to complete. If it times out, try again after a few minutes.
+
+## Compiler Settings
+
+The contract is compiled with these settings (defined in `hardhat.config.js`):
+
+```javascript
+solidity: {
+  version: "0.8.20",
+  settings: {
+    optimizer: {
+      enabled: true,
+      runs: 200
+    },
+    evmVersion: "paris"
+  }
+}
+```
+
+**Important:** When deploying, ensure these settings match. If you deploy with different settings, verification will fail with a bytecode mismatch.
+
+## Manual Verification (Alternative)
+
+If automatic verification fails, you can verify manually on the explorer:
+
+1. Visit the contract address on the appropriate explorer
+2. Click "Contract" tab
+3. Click "Verify and Publish"
+4. Select "Via Standard JSON Input" (recommended) or "Via Solidity (Single file)"
+5. Fill in the required information:
+   - Compiler version: `0.8.20`
+   - Optimization: `Yes` (200 runs)
+   - EVM Version: `Paris`
+6. Upload the Standard JSON Input or flattened contract source
+
+## Best Practices
+
+1. **Always compile before deploying:**
+   ```bash
+   yarn compile:extract
+   ```
+
+2. **Verify immediately after deployment:**
+   - Verification is easier when done right after deployment
+   - The contract is fresh in the explorer's cache
+
+3. **Keep compiler settings consistent:**
+   - Use the same settings for compilation and deployment
+   - Document any changes to compiler settings
+
+4. **Test on testnets first:**
+   - Verify on testnets (Sepolia, Base Sepolia, Arbitrum Sepolia) before mainnet
+   - Testnets are free and help catch issues early
+
+5. **Save deployment information:**
+   - Keep a record of deployed addresses and networks
+   - Note the compiler settings used for each deployment
+
+## Network-Specific Notes
+
+### Arbitrum Sepolia
+
+- Uses Etherscan API V2 (same as other networks)
+- API endpoint: `https://api-sepolia.arbiscan.io/api`
+- Explorer: `https://sepolia.arbiscan.io`
+
+### Base Sepolia
+
+- Uses Basescan (Etherscan-based)
+- API endpoint: `https://api-sepolia.basescan.org/api`
+- Explorer: `https://sepolia.basescan.org`
+
+### Polygon Sepolia (Amoy)
+
+- Uses Polygonscan (Etherscan-based)
+- API endpoint: `https://api-amoy.polygonscan.com/api`
+- Explorer: `https://amoy.polygonscan.com`
+
+## Additional Resources
+
+- [Etherscan API Documentation](https://docs.etherscan.io/)
+- [Hardhat Verification Plugin](https://hardhat.org/hardhat-runner/plugins/nomicfoundation-hardhat-verify)
+- [OpenZeppelin Contracts](https://docs.openzeppelin.com/contracts) (used by NZIP-NFT.sol)
+
+## Support
+
+If you encounter issues not covered in this guide:
+
+1. Check the error message carefully
+2. Verify your API key is correct and active
+3. Ensure the network is properly configured
+4. Try recompiling and redeploying if bytecode mismatch occurs
+5. Check the explorer's status page for API issues
+