neozipkit 0.1.1 → 0.2.1

package/README.md

@@ -56,6 +56,39 @@ for (const entry of entries) {
 
 ### Unified Directory Structure
 
+```
+
+### Merkle Root API (getMerkleRoot)
+
+The `getMerkleRoot()` symbol is an instance method on `ZipKit`/`ZipKitServer` (not a top‑level export). Instantiate and call it on the object:
+
+```typescript
+import ZipKitServer from 'neozipkit/server/platform/server/ZipKitServer';
+
+// Load an existing ZIP from disk and compute Merkle Root (server/Node.js)
+const zip = new ZipKitServer();
+zip.loadUnzipFile('/path/to/archive.zip');
+const merkleRoot = zip.getMerkleRoot(); // string | null
+```
+
+Notes:
+- `getMerkleRoot()` returns `null` if no entries are loaded or if entries don’t have `sha256` set.
+- Ensure each content file has a SHA‑256 hash recorded:
+  - When creating ZIPs, set `useSHA256: true` in `CompressOptions` so hashes are written during compression.
+  - When reading existing ZIPs, calling `extract(entry)` will compute and set `entry.sha256` before you call `getMerkleRoot()`.
+
+Example (creating and then reading back):
+
+```typescript
+import ZipKitServer, { CMP_METHOD } from 'neozipkit/server/platform/server/ZipKitServer';
+
+const zk = new ZipKitServer();
+// createZip uses CompressOptions internally; ensure useSHA256 when you pass options to compression
+await zk.createZip('/tmp/out.zip', { level: 6, useSHA256: true, useZstd: false });
+
+// Load file and compute
+zk.loadUnzipFile('/tmp/out.zip');
+const root = zk.getMerkleRoot();
 ```
 packages/neozipkit/
 ├── src/                           # TypeScript source files
@@ -85,7 +118,7 @@ packages/neozipkit/
 │   ├── server/                    # Server bundle
 │   ├── shared/                    # Shared code
 │   └── index.js/.d.ts             # Main bundle
-├── contracts/                     # Smart contracts for NFT tokenization
+├── contracts/                     # Smart contracts and documentation
 ├── examples/                      # Usage examples
 └── docs/                          # Documentation
 ```
@@ -118,26 +151,11 @@ import { ZipKitOTS } from 'neozipkit/server/platform/servercomponents/ZipKitOTS'
 
 ## 🔗 Blockchain Integration
 
-NeoZipKit includes comprehensive blockchain integration for creating and verifying tokenized ZIP files on Ethereum-compatible networks.
-
-### Supported Features
-
-- **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
+NeoZipKit includes comprehensive blockchain integration for creating and verifying tokenized ZIP files. 
 
-### Blockchain Components
+**📄 For detailed information about smart contracts, deployment, and blockchain integration, see the [contracts documentation](./contracts/).**
 
-- **`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
-
-### Usage Example
+### Quick Example
 
 ```typescript
 import { ZipTokenProcessor, MintingOptions } from 'neozipkit/server/blockchain';
@@ -150,60 +168,6 @@ const options: MintingOptions = {
 
 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);
-}
-```
-
-## 🎯 Smart Contracts
-
-The package includes production-ready smart contracts for ZIP file tokenization:
-
-### Contract Types
-
-#### 🌐 Public 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
-- **Symbol**: `NZIP`
-
-#### 🔒 Private Contract (`NZIP-NFT-Private.sol`)
-- **Owner-only verification** - Only token owners can verify their tokens
-- **Private blockchain metadata** - Sensitive data hidden from public
-- **Selective authorization** - Owners can authorize specific verifiers
-- **Use cases**: Medical records, legal documents, private archives
-- **Symbol**: `NZIPPRV`
-
-### Current Deployment
-
-**✅ 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
-```
-
-### Contract Deployment
-
-Deploy your own contracts using the included scripts:
-
-```bash
-# Setup deployment configuration
-npm run setup-deployment
-
-# Deploy both contracts (public + private)
-npm run deploy:both
-
-# Deploy only public contract
-npm run deploy:public
-
-# Deploy to mainnet
-npm run deploy:both:mainnet
 ```
 
 ## 🔧 Development Workflow
@@ -233,6 +197,16 @@ This runs:
 - **Output**: `./dist`
 - **Declarations**: Generated alongside JavaScript files
 
+### Version constants
+
+Import the library version and release date anywhere in your app:
+
+```ts
+import { NEOZIPKIT_VERSION, NEOZIPKIT_RELEASE_DATE } from 'neozipkit';
+
+console.log('NeoZipKit', NEOZIPKIT_VERSION, NEOZIPKIT_RELEASE_DATE);
+```
+
 ## 📖 API Reference
 
 ### Core Classes
@@ -288,48 +262,21 @@ accumulator.addFile('example.txt', fileBuffer);
 const merkleRoot = accumulator.finalize();
 ```
 
-## 🌐 Network Support
-
-### Supported Networks
 
-- **Base Sepolia** (Chain ID: 84532) - Testing
-- **Base Mainnet** (Chain ID: 8453) - Production
-- **Ethereum Mainnet** - Production
-- **Polygon** - Production
-- **Arbitrum** - Production
-
-### Network Configuration
-
-```typescript
-// Networks are configured in blockchain components
-const networkConfig = {
-  'base': {
-    chainId: 8453,
-    rpcUrl: 'https://mainnet.base.org',
-    explorer: 'https://basescan.org'
-  },
-  'base-sepolia': {
-    chainId: 84532,
-    rpcUrl: 'https://sepolia.base.org',
-    explorer: 'https://sepolia.basescan.org'
-  }
-};
-```
 
 ## 🔐 Security Considerations
 
 ### Development Best Practices
 
-- **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
+- **Input Validation**: Validate all file inputs before processing
+- **Memory Management**: Handle large ZIP files efficiently
 
 ### File Verification
 
 - **Merkle Trees**: All ZIP files use cryptographic Merkle trees for integrity verification
-- **Blockchain Anchoring**: Timestamps and hashes are anchored to blockchain networks
+- **Hash Verification**: Multiple hash algorithms for file integrity checking
 - **Multi-Layer Verification**: Support for both OpenTimestamps and NFT-based verification
 
 ## 📦 Dependencies
@@ -394,7 +341,7 @@ Ready to start using NeoZipKit? Here are some next steps:
 1. **Install the package**: `yarn add neozipkit`
 2. **Choose your use case**: Basic ZIP operations, OpenTimestamps, or NFT tokenization
 3. **Follow the examples**: Check the `examples/` directory for complete implementations
-4. **Deploy contracts**: Use the deployment scripts for blockchain features
+4. **Deploy contracts**: See [contracts documentation](./contracts/) for blockchain features
 5. **Build something amazing**: Leverage the full power of blockchain-backed file verification
 
-For detailed examples and advanced usage, explore the examples directory and blockchain integration documentation.
+For detailed examples and advanced usage, explore the examples directory. For blockchain integration, see the [contracts documentation](./contracts/).

package/contracts/INTEGRATION.md

@@ -0,0 +1,338 @@
+# Contract Integration Guide
+
+This guide shows how to integrate NeoZipKit smart contracts into your application.
+
+## 🚀 Quick Integration
+
+### Basic Setup
+
+```typescript
+import { ZipTokenProcessor, MintingOptions } from 'neozipkit/server/blockchain';
+
+// Configure minting options
+const options: MintingOptions = {
+  contractAddress: 'YOUR_DEPLOYED_CONTRACT_ADDRESS',
+  network: 'base-sepolia',
+  mintToken: true
+};
+
+// Create processor
+const processor = new ZipTokenProcessor('archive.zip', 'merkle_root_hash', options);
+
+// Process and mint token
+const result = await processor.processZipToken(options);
+```
+
+### Environment Configuration
+
+```bash
+# Required environment variables
+export RPC_URL="https://sepolia.base.org"
+export NETWORK="base-sepolia"
+export CONTRACT_ADDRESS="0xYourDeployedContractAddress"
+```
+
+## 🔧 Core Components
+
+### TokenVerifier
+Verify tokenized ZIP files against blockchain:
+
+```typescript
+import { TokenVerifier } from 'neozipkit/server/blockchain/TokenVerifier';
+
+const verifier = new TokenVerifier({
+  network: 'base-sepolia',
+  contractAddress: '0xYourContractAddress'
+});
+
+const isValid = await verifier.verifyToken(tokenId, merkleRoot);
+```
+
+### NFTMinter
+Mint NFTs for ZIP files:
+
+```typescript
+import { NFTMinter } from 'neozipkit/server/blockchain/NFTMinter';
+
+const minter = new NFTMinter({
+  network: 'base-sepolia',
+  contractAddress: process.env.CONTRACT_ADDRESS
+});
+
+const tokenId = await minter.mintToken({
+  to: '0xRecipientAddress',
+  merkleRoot: 'merkle_root_hash',
+  metadata: {
+    name: 'My ZIP Archive',
+    description: 'Tokenized ZIP file',
+    // ... additional metadata
+  }
+});
+```
+
+### TokenQuerier
+Query token information from blockchain:
+
+```typescript
+import { TokenQuerier } from 'neozipkit/server/blockchain/TokenQuerier';
+
+const querier = new TokenQuerier({
+  network: 'base-sepolia',
+  contractAddress: '0xYourContractAddress'
+});
+
+// Get token metadata
+const metadata = await querier.getTokenMetadata(tokenId);
+
+// Get token owner
+const owner = await querier.getTokenOwner(tokenId);
+
+// Check if token exists
+const exists = await querier.tokenExists(tokenId);
+```
+
+### WalletManager
+Manage wallet connections and networks:
+
+```typescript
+import { WalletManager } from 'neozipkit/server/blockchain/WalletManager';
+
+const walletManager = new WalletManager({
+  network: 'base-sepolia',
+  rpcUrl: process.env.RPC_URL
+});
+
+// Get wallet balance
+const balance = await walletManager.getBalance();
+
+// Get network information
+const networkInfo = await walletManager.getNetworkInfo();
+```
+
+## 🌐 Browser Integration
+
+### Browser-Compatible Components
+
+```typescript
+import { TokenVerifierBrowser } from 'neozipkit/browser';
+
+const verifier = new TokenVerifierBrowser({
+  network: 'base-sepolia',
+  rpcUrl: 'https://sepolia.base.org',
+  contractAddress: '0xYourContractAddress'
+});
+
+// Verify token (read-only operation)
+const isValid = await verifier.verifyToken(tokenId, merkleRoot);
+```
+
+### Web3 Wallet Integration
+
+```typescript
+// Connect to user's wallet (MetaMask, etc.)
+if (window.ethereum) {
+  const provider = new ethers.providers.Web3Provider(window.ethereum);
+  await provider.send("eth_requestAccounts", []);
+  
+  const signer = provider.getSigner();
+  const userAddress = await signer.getAddress();
+  
+  // Use with NeoZipKit components
+  const minter = new NFTMinter({
+    signer: signer,
+    contractAddress: process.env.CONTRACT_ADDRESS
+  });
+}
+```
+
+## 📝 Complete Example
+
+### Server-Side Token Creation
+
+```typescript
+import { 
+  ZipTokenProcessor, 
+  NFTMinter, 
+  TokenVerifier 
+} from 'neozipkit/server/blockchain';
+
+async function createAndVerifyToken() {
+  try {
+    // 1. Process ZIP file and create Merkle root
+    const processor = new ZipTokenProcessor('archive.zip', null, {
+      network: 'base-sepolia',
+      contractAddress: process.env.CONTRACT_ADDRESS
+    });
+    
+    const { merkleRoot, zipHash } = await processor.generateHashes();
+    
+    // 2. Mint NFT token
+    const minter = new NFTMinter({
+      network: 'base-sepolia',
+      contractAddress: process.env.CONTRACT_ADDRESS
+    });
+    
+    const tokenId = await minter.mintToken({
+      to: '0xRecipientAddress',
+      merkleRoot: merkleRoot,
+      metadata: {
+        name: 'Archive Token',
+        description: 'Verified ZIP archive',
+        zipHash: zipHash
+      }
+    });
+    
+    console.log(`Token minted with ID: ${tokenId}`);
+    
+    // 3. Verify the token
+    const verifier = new TokenVerifier({
+      network: 'base-sepolia',
+      contractAddress: process.env.CONTRACT_ADDRESS
+    });
+    
+    const isValid = await verifier.verifyToken(tokenId, merkleRoot);
+    console.log(`Token verification: ${isValid ? 'VALID' : 'INVALID'}`);
+    
+    return { tokenId, merkleRoot, isValid };
+    
+  } catch (error) {
+    console.error('Error creating token:', error);
+    throw error;
+  }
+}
+```
+
+### Client-Side Token Verification
+
+```typescript
+import { TokenVerifierBrowser } from 'neozipkit/browser';
+
+async function verifyTokenFromBrowser(tokenId: string, merkleRoot: string) {
+  const verifier = new TokenVerifierBrowser({
+    network: 'base-sepolia',
+    rpcUrl: 'https://sepolia.base.org',
+    contractAddress: '0xYourContractAddress'
+  });
+  
+  try {
+    const isValid = await verifier.verifyToken(tokenId, merkleRoot);
+    
+    if (isValid) {
+      console.log('✅ Token is valid and verified on blockchain');
+    } else {
+      console.log('❌ Token verification failed');
+    }
+    
+    return isValid;
+    
+  } catch (error) {
+    console.error('Verification error:', error);
+    return false;
+  }
+}
+```
+
+## 🔒 Security Best Practices
+
+### Contract Address Management
+
+```typescript
+// ✅ DO: Use environment variables for contract addresses
+const contractAddress = process.env.CONTRACT_ADDRESS;
+
+// ✅ DO: Validate contract addresses
+import { ethers } from 'ethers';
+if (!ethers.utils.isAddress(contractAddress)) {
+  throw new Error('Invalid contract address');
+}
+```
+
+### Input Validation
+
+```typescript
+import { ethers } from 'ethers';
+
+function validateInputs(tokenId: string, address: string) {
+  // Validate token ID
+  if (!tokenId || !/^\d+$/.test(tokenId)) {
+    throw new Error('Invalid token ID');
+  }
+  
+  // Validate Ethereum address
+  if (!ethers.utils.isAddress(address)) {
+    throw new Error('Invalid Ethereum address');
+  }
+}
+```
+
+### Error Handling
+
+```typescript
+async function safeTokenOperation() {
+  try {
+    const result = await processor.processZipToken(options);
+    return result;
+  } catch (error) {
+    if (error.code === 'NETWORK_ERROR') {
+      console.error('Network connectivity issue');
+    } else if (error.code === 'CONTRACT_ERROR') {
+      console.error('Contract interaction failed');
+    } else {
+      console.error('Unexpected error:', error.message);
+    }
+    
+    // Log error for monitoring
+    logger.error('Token operation failed', { error, options });
+    
+    throw error;
+  }
+}
+```
+
+## 📊 Monitoring and Analytics
+
+### Event Listening
+
+```typescript
+import { ethers } from 'ethers';
+
+// Listen for token mint events
+const contract = new ethers.Contract(contractAddress, abi, provider);
+
+contract.on('Transfer', (from, to, tokenId) => {
+  if (from === ethers.constants.AddressZero) {
+    console.log(`New token minted: ${tokenId} to ${to}`);
+    // Log to analytics
+    analytics.track('token_minted', { tokenId, recipient: to });
+  }
+});
+```
+
+### Health Monitoring
+
+```typescript
+async function checkContractHealth() {
+  try {
+    const querier = new TokenQuerier({
+      network: process.env.NETWORK,
+      contractAddress: process.env.CONTRACT_ADDRESS
+    });
+    
+    // Check if contract is responding
+    const totalSupply = await querier.getTotalSupply();
+    
+    return {
+      status: 'healthy',
+      totalSupply: totalSupply,
+      timestamp: new Date().toISOString()
+    };
+    
+  } catch (error) {
+    return {
+      status: 'unhealthy',
+      error: error.message,
+      timestamp: new Date().toISOString()
+    };
+  }
+}
+```

package/contracts/NETWORKS.md

@@ -0,0 +1,156 @@
+# Network Support
+
+NeoZipKit smart contracts support multiple Ethereum-compatible networks for both testing and production use.
+
+## 🌐 Supported Networks
+
+### Testing Networks
+
+#### Base Sepolia (Recommended for Testing)
+- **Chain ID**: 84532
+- **RPC URL**: https://sepolia.base.org
+- **Explorer**: https://sepolia.basescan.org
+- **Faucet**: https://bridge.base.org/deposit
+- **Gas Token**: ETH (Sepolia)
+- **Use Case**: Development and testing
+
+### Production Networks
+
+#### Base Mainnet (Recommended for Production)
+- **Chain ID**: 8453
+- **RPC URL**: https://mainnet.base.org
+- **Explorer**: https://basescan.org
+- **Gas Token**: ETH
+- **Use Case**: Production deployments
+
+#### Ethereum Mainnet
+- **Chain ID**: 1
+- **RPC URL**: https://mainnet.infura.io/v3/YOUR-PROJECT-ID
+- **Explorer**: https://etherscan.io
+- **Gas Token**: ETH
+- **Use Case**: High-security production deployments
+
+#### Polygon
+- **Chain ID**: 137
+- **RPC URL**: https://polygon-rpc.com
+- **Explorer**: https://polygonscan.com
+- **Gas Token**: MATIC
+- **Use Case**: Low-cost production deployments
+
+#### Arbitrum One
+- **Chain ID**: 42161
+- **RPC URL**: https://arb1.arbitrum.io/rpc
+- **Explorer**: https://arbiscan.io
+- **Gas Token**: ETH
+- **Use Case**: Fast, low-cost production deployments
+
+## ⚙️ Network Configuration
+
+### JavaScript/TypeScript Configuration
+
+```typescript
+// Networks are configured in blockchain components
+const networkConfig = {
+  'base': {
+    chainId: 8453,
+    rpcUrl: 'https://mainnet.base.org',
+    explorer: 'https://basescan.org'
+  },
+  'base-sepolia': {
+    chainId: 84532,
+    rpcUrl: 'https://sepolia.base.org',
+    explorer: 'https://sepolia.basescan.org'
+  },
+  'ethereum': {
+    chainId: 1,
+    rpcUrl: 'https://mainnet.infura.io/v3/YOUR-PROJECT-ID',
+    explorer: 'https://etherscan.io'
+  },
+  'polygon': {
+    chainId: 137,
+    rpcUrl: 'https://polygon-rpc.com',
+    explorer: 'https://polygonscan.com'
+  },
+  'arbitrum': {
+    chainId: 42161,
+    rpcUrl: 'https://arb1.arbitrum.io/rpc',
+    explorer: 'https://arbiscan.io'
+  }
+};
+```
+
+### Environment Configuration
+
+```bash
+# Base Sepolia (Testing)
+export NETWORK="base-sepolia"
+export RPC_URL="https://sepolia.base.org"
+export CHAIN_ID="84532"
+
+# Base Mainnet (Production)
+export NETWORK="base-mainnet" 
+export RPC_URL="https://mainnet.base.org"
+export CHAIN_ID="8453"
+```
+
+## 💰 Gas Costs Comparison
+
+| Network | Average Gas Price | Contract Deployment Cost | Token Mint Cost |
+|---------|------------------|-------------------------|-----------------|
+| Base Sepolia | ~0.001 gwei | ~$0.01 | ~$0.001 |
+| Base Mainnet | ~0.01 gwei | ~$0.10 | ~$0.01 |
+| Ethereum | ~20 gwei | ~$50-200 | ~$10-50 |
+| Polygon | ~30 gwei | ~$0.05 | ~$0.01 |
+| Arbitrum | ~0.1 gwei | ~$1-5 | ~$0.25 |
+
+*Costs are approximate and vary based on network congestion*
+
+## 🔧 Setup Instructions
+
+### 1. Choose Your Network
+
+For development: **Base Sepolia**
+For production: **Base Mainnet** or **Ethereum**
+
+### 2. Get Test Tokens (for testnets)
+
+**Base Sepolia**:
+1. Visit https://bridge.base.org/deposit
+2. Connect your wallet
+3. Bridge Ethereum Sepolia ETH to Base Sepolia
+
+### 3. Configure RPC Endpoints
+
+**Recommended RPC Providers**:
+- **Alchemy**: https://dashboard.alchemy.com/
+- **Infura**: https://infura.io/
+- **QuickNode**: https://quicknode.com/
+- **Public RPCs**: Use for testing only
+
+### 4. Update Application Configuration
+
+```typescript
+import { WalletManager } from 'neozipkit/server/blockchain';
+
+
+## 🚨 Important Notes
+
+### Testnet Limitations
+- **No real value**: Testnet tokens have no monetary value
+- **Reset periodically**: Testnet data may be wiped
+- **Limited faucets**: May have daily limits for test tokens
+
+### Mainnet Considerations
+- **Real costs**: All transactions cost real money
+- **Irreversible**: Mistakes cannot be undone
+- **Security critical**: Use secure key management
+- **Audit first**: Thoroughly test on testnets before mainnet
+
+### Network Selection Guidelines
+
+- **Development**: Use Base Sepolia for fastest, cheapest testing
+- **Staging**: Use Base Sepolia or Ethereum Sepolia for final testing
+- **Production**: Choose based on cost, speed, and security requirements
+  - **High security**: Ethereum Mainnet
+  - **Balanced**: Base Mainnet
+  - **Low cost**: Polygon or Arbitrum