neozipkit 0.1.1 → 0.3.0

package/src/blockchain/core/contracts.ts

@@ -0,0 +1,370 @@
+// Contract addresses and configurations for different networks
+
+export interface ContractConfig {
+  address: string
+  network: string
+  chainId: number
+  explorerUrl: string
+  rpcUrls: string[]
+  nameAliases?: string[]  // Alternative network name formats (e.g., ["base-sepolia", "base sepolia"])
+}
+
+// NZIP NFT Contract configurations by network
+export const CONTRACT_CONFIGS: Record<number, ContractConfig> = {
+  // Base Sepolia (Primary testnet)
+  84532: {
+    // address: '0xFD76a5d420704F34d84b0767961835c43D7b30a8', // Production contract v2.0
+    address: '0xdAe9D83d7AC62197fAE7704abc66b13DA28D3143', // Production contract v2.10
+    network: 'Base Sepolia',
+    chainId: 84532,
+    explorerUrl: 'https://sepolia.basescan.org',
+    rpcUrls: [
+      'https://sepolia.base.org',
+      'https://base-sepolia-rpc.publicnode.com',
+      'https://base-sepolia.gateway.tenderly.co'
+    ],
+    nameAliases: ['base-sepolia', 'base sepolia', 'basesepolia', 'base-sepolia-testnet']
+  },
+  
+  // Base Mainnet (Production)
+  8453: {
+    // address: '0x2716c4609fD97DaEdF429BC4B4Ec2faa81e2cC60',  // Production contract v2.0
+    address: '0xd871Fba59F85108aF29299786DD8243B38dD9686',  // Production contract v2.10
+    network: 'Base Mainnet',
+    chainId: 8453,
+    explorerUrl: 'https://basescan.org',
+    rpcUrls: [
+      'https://mainnet.base.org',
+      'https://base.drpc.org',
+      'https://base.gateway.tenderly.co'
+    ],
+    nameAliases: ['base-mainnet', 'base mainnet', 'basemainnet', 'base']
+  },
+  
+  // Ethereum Sepolia (Testnet)
+  // WARNING: Sepolia testnet has been experiencing instability since the Pectra upgrade (March 2025)
+  // Network issues include transaction processing failures and RPC timeouts
+  // Consider using Base Sepolia (84532) for more reliable testing
+  11155111: {
+    address: '0x2716c4609fD97DaEdF429BC4B4Ec2faa81e2cC60', // Production contract v2.10
+    network: 'Sepolia Testnet',
+    chainId: 11155111,
+    explorerUrl: 'https://sepolia.etherscan.io',
+    rpcUrls: [
+      // Official Sepolia RPC endpoints (most reliable)
+      'https://rpc.sepolia.ethpandaops.io',
+      
+      // Popular public RPC providers
+      'https://eth-sepolia.public.blastapi.io',
+      'https://ethereum-sepolia-rpc.publicnode.com',
+      'https://sepolia.drpc.org',
+      'https://1rpc.io/sepolia',
+    ],
+    nameAliases: ['sepolia-testnet', 'sepolia testnet', 'sepoliatestnet', 'sepolia', 'ethereum-sepolia', 'ethereum sepolia']
+  },
+  
+  // Arbitrum Sepolia (Testnet)
+  421614: {
+    address: '0x2716c4609fD97DaEdF429BC4B4Ec2faa81e2cC60', // Production contract v2.10
+    network: 'Arbitrum Sepolia',
+    chainId: 421614,
+    explorerUrl: 'https://sepolia.arbiscan.io',
+    rpcUrls: [
+      'https://sepolia-rollup.arbitrum.io/rpc',
+      'https://arbitrum-sepolia-rpc.publicnode.com'
+    ],
+    nameAliases: ['arbitrum-sepolia', 'arbitrum sepolia', 'arbitrumsepolia', 'arbitrum-sepolia-testnet']
+  },
+  
+  // Arbitrum One (Production)
+  // Note: Same contract address as Arbitrum Sepolia due to deterministic deployment
+  // (same deployer address + same nonce = same contract address on both networks)
+  42161: {
+    address: '0x2716c4609fD97DaEdF429BC4B4Ec2faa81e2cC60', // Production contract v2.10
+    network: 'Arbitrum One',
+    chainId: 42161,
+    explorerUrl: 'https://arbiscan.io',
+    rpcUrls: [
+      'https://arb1.arbitrum.io/rpc',
+      'https://arbitrum.llamarpc.com',
+      'https://arbitrum.publicnode.com'
+    ],
+    nameAliases: ['arbitrum-one', 'arbitrum one', 'arbitrumone', 'arbitrum', 'arbitrum-mainnet', 'arbitrum mainnet']
+  },
+  
+  // Ethereum Mainnet (Production) - disabled until NZIP is deployed
+  // 1: {
+  //   address: '0x0000000000000000000000000000000000000000',
+  //   network: 'Ethereum Mainnet',
+  //   chainId: 1,
+  //   explorerUrl: 'https://etherscan.io',
+  //   rpcUrls: []
+  // }
+}
+
+// Contract ABI (ethers.js human-readable format)
+export const NZIP_CONTRACT_ABI = [
+  "function publicMintZipFile(string memory merkleRootHash, uint256 creationTimestamp, string memory ipfsHash, string memory metadataURI) public returns (uint256)",
+  "function totalSupply() external view returns (uint256)",
+  "function getTokensByMerkleRoot(string memory merkleRoot) external view returns (uint256[])",
+  "function getTokensByOwner(address owner) external view returns (uint256[])",
+  "function getZipFileInfo(uint256 tokenId) external view returns (tuple(string merkleRootHash, string ipfsHash, address creator, uint256 creationTimestamp, uint256 tokenizationTime, uint256 blockNumber))",
+  "function ownerOf(uint256 tokenId) external view returns (address)",
+  "function balanceOf(address owner) external view returns (uint256)",
+  "function isZipFileTokenized(string memory merkleRootHash, uint256 creationTimestamp) external view returns (bool exists, uint256 tokenId)",
+  "function verifyZipFile(uint256 tokenId, string memory providedMerkleRoot) external view returns (bool isValid)",
+  "function getVersion() external pure returns (string memory)",
+  "event Transfer(address indexed from, address indexed to, uint256 indexed tokenId)",
+  "event ZipFileTokenized(uint256 indexed tokenId, address indexed creator, string merkleRootHash, uint256 creationTimestamp, string ipfsHash, uint256 tokenizationTime, uint256 blockNumber)"
+]
+
+// Contract ABI (Web3.js JSON format)
+export const NZIP_CONTRACT_ABI_WEB3 = [
+  {
+    inputs: [
+      { name: "merkleRootHash", type: "string" },
+      { name: "creationTimestamp", type: "uint256" },
+      { name: "ipfsHash", type: "string" },
+      { name: "metadataURI", type: "string" }
+    ],
+    name: "publicMintZipFile",
+    outputs: [{ name: "", type: "uint256" }],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "totalSupply",
+    outputs: [{ name: "", type: "uint256" }],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [{ name: "merkleRoot", type: "string" }],
+    name: "getTokensByMerkleRoot",
+    outputs: [{ name: "", type: "uint256[]" }],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    name: "getZipFileInfo",
+    outputs: [
+      {
+        components: [
+          { name: "merkleRootHash", type: "string" },
+          { name: "ipfsHash", type: "string" },
+          { name: "creator", type: "address" },
+          { name: "creationTimestamp", type: "uint256" },
+          { name: "tokenizationTime", type: "uint256" },
+          { name: "blockNumber", type: "uint256" }
+        ],
+        name: "",
+        type: "tuple"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    name: "ownerOf",
+    outputs: [{ name: "", type: "address" }],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [{ name: "owner", type: "address" }],
+    name: "balanceOf",
+    outputs: [{ name: "", type: "uint256" }],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      { name: "merkleRootHash", type: "string" },
+      { name: "creationTimestamp", type: "uint256" }
+    ],
+    name: "isZipFileTokenized",
+    outputs: [
+      { name: "exists", type: "bool" },
+      { name: "tokenId", type: "uint256" }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      { name: "tokenId", type: "uint256" },
+      { name: "providedMerkleRoot", type: "string" }
+    ],
+    name: "verifyZipFile",
+    outputs: [{ name: "isValid", type: "bool" }],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "getVersion",
+    outputs: [{ name: "", type: "string" }],
+    stateMutability: "pure",
+    type: "function"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      { indexed: true, name: "from", type: "address" },
+      { indexed: true, name: "to", type: "address" },
+      { indexed: true, name: "tokenId", type: "uint256" }
+    ],
+    name: "Transfer",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      { indexed: true, name: "tokenId", type: "uint256" },
+      { indexed: true, name: "creator", type: "address" },
+      { indexed: false, name: "merkleRootHash", type: "string" },
+      { indexed: false, name: "creationTimestamp", type: "uint256" },
+      { indexed: false, name: "ipfsHash", type: "string" },
+      { indexed: false, name: "tokenizationTime", type: "uint256" },
+      { indexed: false, name: "blockNumber", type: "uint256" }
+    ],
+    name: "ZipFileTokenized",
+    type: "event"
+  }
+]
+
+// Default configuration (Base Sepolia for development)
+export const DEFAULT_NETWORK = 84532
+export const CURRENT_DEPLOYMENT = CONTRACT_CONFIGS[DEFAULT_NETWORK]
+
+// Helper functions
+export const getContractConfig = (chainId: number): ContractConfig => {
+  return CONTRACT_CONFIGS[chainId] || CURRENT_DEPLOYMENT
+}
+
+export const getSupportedNetworks = (): number[] => {
+  return Object.keys(CONTRACT_CONFIGS).map(Number)
+}
+
+export const isNetworkSupported = (chainId: number): boolean => {
+  return chainId in CONTRACT_CONFIGS
+}
+
+/**
+ * Normalize network name for matching (lowercase, trim, replace spaces with hyphens)
+ */
+export function normalizeNetworkName(networkName: string): string {
+  return networkName.toLowerCase().trim().replace(/\s+/g, '-').replace(/_/g, '-')
+}
+
+/**
+ * Get chain ID by network name (supports aliases)
+ * Returns chain ID if found, null otherwise
+ */
+export function getChainIdByName(networkName: string): number | null {
+  const normalized = normalizeNetworkName(networkName)
+  
+  // Search through all configs
+  for (const [chainIdStr, config] of Object.entries(CONTRACT_CONFIGS)) {
+    const chainId = Number(chainIdStr)
+    
+    // Check primary network name
+    if (normalizeNetworkName(config.network) === normalized) {
+      return chainId
+    }
+    
+    // Check name aliases
+    if (config.nameAliases) {
+      for (const alias of config.nameAliases) {
+        if (normalizeNetworkName(alias) === normalized) {
+          return chainId
+        }
+      }
+    }
+  }
+  
+  return null
+}
+
+/**
+ * Get network configuration by network name (supports aliases)
+ * Returns ContractConfig if found, null otherwise
+ */
+export function getNetworkByName(networkName: string): ContractConfig | null {
+  const chainId = getChainIdByName(networkName)
+  if (chainId === null) {
+    return null
+  }
+  return getContractConfig(chainId)
+}
+
+/**
+ * Get all supported network name aliases
+ * Returns array of all supported network names (primary + aliases)
+ */
+export function getSupportedNetworkNames(): string[] {
+  const names: string[] = []
+  
+  for (const config of Object.values(CONTRACT_CONFIGS)) {
+    // Add primary network name
+    names.push(config.network)
+    
+    // Add aliases
+    if (config.nameAliases) {
+      names.push(...config.nameAliases)
+    }
+  }
+  
+  return names
+}
+
+/**
+ * Fuzzy match network name (for backward compatibility)
+ * Handles partial matches like "sepolia" matching "Base Sepolia" or "Arbitrum Sepolia"
+ * Returns best match or null
+ */
+export function fuzzyMatchNetworkName(networkName: string): ContractConfig | null {
+  const normalized = normalizeNetworkName(networkName)
+  
+  // First try exact match
+  const exactMatch = getNetworkByName(networkName)
+  if (exactMatch) {
+    return exactMatch
+  }
+  
+  // Try partial matching
+  const matches: Array<{ config: ContractConfig; score: number }> = []
+  
+  for (const config of Object.values(CONTRACT_CONFIGS)) {
+    const configNormalized = normalizeNetworkName(config.network)
+    let score = 0
+    
+    // Check if normalized input is contained in config name or vice versa
+    if (configNormalized.includes(normalized) || normalized.includes(configNormalized)) {
+      score = Math.max(configNormalized.length, normalized.length) / Math.min(configNormalized.length, normalized.length)
+      matches.push({ config, score })
+    }
+    
+    // Check aliases
+    if (config.nameAliases) {
+      for (const alias of config.nameAliases) {
+        const aliasNormalized = normalizeNetworkName(alias)
+        if (aliasNormalized.includes(normalized) || normalized.includes(aliasNormalized)) {
+          score = Math.max(aliasNormalized.length, normalized.length) / Math.min(aliasNormalized.length, normalized.length)
+          matches.push({ config, score })
+        }
+      }
+    }
+  }
+  
+  // Return best match (highest score)
+  if (matches.length > 0) {
+    matches.sort((a, b) => b.score - a.score)
+    return matches[0].config
+  }
+  
+  return null
+}

package/src/blockchain/core/index.ts

@@ -0,0 +1,71 @@
+/**
+ * Core Blockchain Module Exports
+ * Platform-agnostic blockchain functionality for ZIP file tokenization
+ */
+
+// Export all types from consolidated types location
+export * from '../../types';
+
+export {
+  ZipkitMinter,
+  MintingOptions,
+  MintingResult,
+  DuplicateCheckResult,
+  WalletInfo,
+  validatePrivateKey
+} from './ZipkitMinter';
+
+export {
+  ZipkitVerifier,
+  VerificationOptions,
+  VerificationResult
+} from './ZipkitVerifier';
+
+export { TokenMetadata } from '../../types';
+
+// Export core wallet functionality
+export {
+  CoreWalletManager,
+  WalletAnalyzer,
+  CommonTokenConfig,
+  TokenInfo,
+  WalletBasicInfo,
+  TokenScanResult,
+  NZipTokenDetails
+} from './WalletManager';
+
+export { 
+  NZIP_CONTRACT_ABI, 
+  NZIP_CONTRACT_ABI_WEB3,
+  CONTRACT_CONFIGS,
+  CURRENT_DEPLOYMENT,
+  DEFAULT_NETWORK,
+  getContractConfig,
+  getSupportedNetworks,
+  isNetworkSupported,
+  getChainIdByName,
+  getSupportedNetworkNames,
+  getNetworkByName,
+  normalizeNetworkName,
+  ContractConfig
+} from './contracts';
+
+// Export OpenTimestamps utilities
+export { 
+  createTimestamp,
+  deserializeOts,
+  parseVerifyResult,
+  upgradeOTS,
+  createOtsMetadataEntry,
+  bufferToArrayBuffer,
+  getOtsEntry,
+  getOtsBuffer,
+  getMerkleRootSafe,
+  verifyOts,
+  verifyOtsZip,
+  // Export interfaces
+  TimestampResult,
+  TimestampInfo,
+  DeserializeOtsResult,
+  OtsVerifyResult
+} from './ZipkitOTS';

package/src/blockchain/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Blockchain Module Exports
+ * Unified blockchain functionality for ZIP file tokenization
+ */
+
+// Export core blockchain functionality (platform-agnostic)
+export * from './core';
+
+// Export browser-specific blockchain functionality
+export * from './browser';
+
+// Export Node.js-specific blockchain functionality (only WalletManagerNode is Node-specific)
+export { 
+  WalletManagerNode, 
+  ZipkitWallet 
+} from './node';
+
+// Export enhanced verification types from core (now available in core)
+export type { 
+  EnhancedVerificationResult, 
+  BatchVerificationResult, 
+  VerificationJob 
+} from './core/ZipkitVerifier';
+
+// Export Logger utility for console control (from core module)
+export { Logger, configureLoggerFromEnvironment } from '../core';
+export type { LogLevel, LoggerConfig } from '../core';

package/src/blockchain/node/WalletManagerNode.ts

@@ -0,0 +1,171 @@
+/**
+ * WalletManagerNode - Node.js-specific wallet functionality with file system operations
+ * Extends CoreWalletManager with file-based wallet management
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { ethers } from 'ethers';
+import { CoreWalletManager } from '../core/WalletManager';
+import { WalletSetupResult, WalletInfo, MintingOptions } from '../../types';
+import { Logger } from '../../core/components/Logger';
+
+/**
+ * Node.js-specific wallet manager with file system operations
+ */
+export class WalletManagerNode extends CoreWalletManager {
+  constructor() {
+    super();
+  }
+
+  /**
+   * Setup wallet with file system support
+   */
+  async setupWalletWithOptions(options: MintingOptions): Promise<WalletSetupResult> {
+    try {
+      let privateKey: string;
+      
+      if ((options as any).wallet) {
+        const val = (options as any).wallet as string;
+        if (fs.existsSync(val)) {
+          const loaded = this.loadWalletFromFile(val);
+          if (!loaded) throw new Error(`Could not load valid private key from ${val}`);
+          privateKey = loaded;
+        } else {
+          privateKey = val;
+        }
+      } else {
+        const existing = this.findExistingWallets();
+        if (existing.length > 0) {
+          const selected = existing[0];
+          const relativePath = path.relative(process.cwd(), selected);
+          Logger.log(`Using existing wallet: ${relativePath}`);
+          const loaded = this.loadWalletFromFile(selected);
+          if (!loaded) throw new Error(`Could not load valid private key from ${selected}`);
+          privateKey = loaded;
+        } else {
+          Logger.log('No existing wallet found. Creating new wallet...');
+          privateKey = await this.createNewWallet();
+        }
+      }
+
+      return await super.setupWallet(privateKey, options.network, (options as any).mintToken === true);
+    } catch (error) {
+      Logger.error('Error setting up wallet:', error);
+      return { 
+        wallet: null, 
+        provider: null, 
+        success: false, 
+        message: `Wallet setup failed: ${error instanceof Error ? error.message : String(error)}` 
+      };
+    }
+  }
+
+  /**
+   * Find existing wallet files
+   */
+  private findExistingWallets(): string[] {
+    const walletFiles: string[] = [];
+    const currentDir = process.cwd();
+    const walletDir = path.join(currentDir, 'wallet');
+    const walletFileNames = ['neozip-wallet.json'];
+    
+    for (const fileName of walletFileNames) {
+      const filePath = path.join(currentDir, fileName);
+      if (fs.existsSync(filePath)) walletFiles.push(filePath);
+    }
+    
+    if (fs.existsSync(walletDir)) {
+      for (const fileName of walletFileNames) {
+        const filePath = path.join(walletDir, fileName);
+        if (fs.existsSync(filePath)) walletFiles.push(filePath);
+      }
+    }
+    
+    return walletFiles;
+  }
+
+  /**
+   * Load wallet from file
+   * 
+   * SECURITY WARNING: This method reads private keys from disk.
+   * - Only use for development/testing
+   * - Wallet files are automatically excluded from git via .gitignore
+   * - Wallet files are excluded from NPM packages via .npmignore
+   * - Use secure key management (HSMs, KMS) for production
+   */
+  private loadWalletFromFile(filePath: string): string | null {
+    try {
+      const content = fs.readFileSync(filePath, 'utf8').trim();
+      try {
+        const walletData = JSON.parse(content);
+        if (walletData.privateKey) {
+          Logger.log(`Found wallet file: ${filePath}`);
+          Logger.log(`Wallet address: ${walletData.address}`);
+          return walletData.privateKey;
+        }
+      } catch {
+        if (content.startsWith('0x') && content.length === 66) {
+          Logger.log(`Found private key file: ${filePath}`);
+          return content;
+        }
+      }
+      return null;
+    } catch (error) {
+      Logger.warn(`Could not read wallet file ${filePath}:`, error);
+      return null;
+    }
+  }
+
+  /**
+   * Create a new wallet and save to file
+   * 
+   * SECURITY WARNING: This method saves private keys to disk.
+   * - Only use for development/testing
+   * - Never commit wallet files to version control
+   * - Use secure key management for production
+   * - Wallet files are automatically excluded via .gitignore and .npmignore
+   * - Protect file system permissions on wallet files
+   */
+  private async createNewWallet(): Promise<string> {
+    Logger.log('Creating a new wallet...');
+    const newWallet = ethers.Wallet.createRandom();
+    const walletInfo: WalletInfo = { 
+      address: newWallet.address, 
+      privateKey: newWallet.privateKey, 
+      mnemonic: newWallet.mnemonic?.phrase || "" 
+    };
+    
+    const walletDir = path.join(process.cwd(), 'wallet');
+    if (!fs.existsSync(walletDir)) fs.mkdirSync(walletDir, { recursive: true });
+    
+    const walletFilePath = path.join(walletDir, 'neozip-wallet.json');
+    fs.writeFileSync(walletFilePath, JSON.stringify(walletInfo, null, 2));
+    
+    Logger.log(`New wallet created and saved to ${walletFilePath}`);
+    Logger.log(`Wallet address: ${newWallet.address}`);
+    Logger.log(`IMPORTANT: Please fund this wallet with testnet ETH to use for minting NFTs!`);
+    Logger.log(`SECURITY: Wallet file is automatically excluded from git (.gitignore) and NPM packages (.npmignore)`);
+    Logger.log(`SECURITY: Never commit wallet files to version control`);
+    Logger.log(`SECURITY: Use secure key management (HSMs, KMS) for production applications`);
+    
+    return newWallet.privateKey;
+  }
+
+  /**
+   * Detect NZIP contract from deployment file
+   */
+  static detectNZipContract(): string | undefined {
+    const deploymentPath = path.join(process.cwd(), 'zipfile-nft-deployment.json');
+    if (fs.existsSync(deploymentPath)) {
+      try { 
+        const deploymentInfo = JSON.parse(fs.readFileSync(deploymentPath, 'utf8')); 
+        if (deploymentInfo.address) return deploymentInfo.address; 
+      } catch {}
+    }
+    return undefined;
+  }
+}
+
+// Re-export the old class name for backward compatibility
+export { WalletManagerNode as ZipkitWallet };

package/src/blockchain/node/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Node Blockchain Module Exports
+ * Node.js-specific blockchain functionality for ZIP file tokenization
+ * 
+ * Note: ZipkitMinter and ZipkitVerifier convenience methods (retry, batch) 
+ * are now available in the core module. Only WalletManagerNode is Node.js-specific
+ * due to file system operations.
+ */
+
+export { WalletManagerNode, ZipkitWallet } from './WalletManagerNode';
+
+// Re-export specific core functionality to avoid duplicates
+export { 
+  ZipkitMinter,
+  ZipkitVerifier,
+  CoreWalletManager,
+  WalletAnalyzer,
+  createTimestamp,
+  verifyOts,
+  verifyOtsZip
+} from '../core';
+export type {
+  MintingOptions,
+  MintingResult,
+  VerificationOptions,
+  VerificationResult,
+  WalletInfo,
+  NetworkConfig,
+  TokenMetadata,
+  WalletSetupResult,
+  CommonTokenConfig,
+  TokenInfo,
+  WalletBasicInfo,
+  TokenScanResult,
+  NZipTokenDetails,
+  TimestampResult,
+  TimestampInfo,
+  DeserializeOtsResult,
+  OtsVerifyResult
+} from '../core';