neozipkit 0.1.1 → 0.3.0

package/src/blockchain/README.md

@@ -0,0 +1,222 @@
+## Blockchain Module APIs
+
+This directory provides all blockchain-related functionality for NeoZipKit, including:
+- OpenTimestamps utilities
+- NFT contract interactions (verification, querying, minting)
+- Wallet utilities and token processing
+- Network constants and contract ABI
+
+## 📁 Module Structure
+
+```
+src/blockchain/
+├── core/                    # Core blockchain functionality
+│   ├── WalletManager.ts     # CoreWalletManager - platform-agnostic wallet operations
+│   ├── ZipkitMinter.ts      # Core minting functionality
+│   ├── ZipkitVerifier.ts    # Core verification functionality
+│   ├── ZipkitOTS.ts         # OpenTimestamps utilities
+│   ├── contracts.ts         # Contract ABI + network configs + addresses
+│   ├── types.ts             # Shared blockchain types
+│   └── index.ts             # Core exports
+├── browser/                 # Browser-specific implementations
+│   ├── WalletManagerBrowser.ts    # Browser wallet management
+│   ├── ZipkitMinterBrowser.ts     # Browser minting
+│   ├── TokenVerifierBrowser.ts    # Browser token verification
+│   └── index.ts             # Browser exports
+├── server/                  # Server-specific implementations
+│   ├── WalletManagerServer.ts     # Server wallet management with file system
+│   ├── ZipkitMinterServer.ts      # Server minting
+│   ├── ZipkitVerifierServer.ts    # Server verification
+│   └── index.ts             # Server exports
+└── index.ts                 # Main module exports
+```
+
+### Package Entry
+Import from the package root or from `src/blockchain` directly:
+
+```ts
+// Yes! You can import directly from the blockchain directory
+import { 
+  ZipkitMinter,
+  ZipkitVerifier,
+  CoreWalletManager,
+  WalletManagerServer,
+  WalletManagerBrowser,
+  WalletAnalyzer,
+  CONTRACT_CONFIGS,
+  NZIP_CONTRACT_ABI,
+  CURRENT_DEPLOYMENT
+} from 'neozipkit/blockchain';
+
+// Or from the main package (re-exports everything from blockchain)
+import { ZipkitMinter, ZipkitVerifier, CoreWalletManager, WalletAnalyzer } from 'neozipkit';
+
+// From source (monorepo/local development)
+import { ZipkitMinter, ZipkitVerifier, CoreWalletManager, WalletAnalyzer } from '../src/blockchain';
+```
+
+### Direct NFT APIs
+
+Use the individual classes directly for minting and verification:
+
+```ts
+import { ZipkitMinter, ZipkitVerifier, CoreWalletManager } from 'neozipkit/blockchain';
+
+// Use classes directly
+const walletManager = new CoreWalletManager();
+const minter = new ZipkitMinter('archive.zip', 'abc123...', { walletPrivateKey: '0x...', network: 'base-sepolia' });
+const verifier = new ZipkitVerifier({ debug: false });
+```
+
+### OpenTimestamps (ZipKitOTS.ts)
+Bitcoin blockchain timestamping utilities for ZIP file integrity verification.
+
+#### Core Functions
+
+**Timestamp Creation & Verification:**
+- `createTimestamp(hashDigest: string, options?: { debug?: boolean }): Promise<Buffer | null>`
+  - Creates an OpenTimestamps proof for a hash digest. Submits hash to OpenTimestamps servers for Bitcoin blockchain anchoring.
+- `verifyOts(hashDigest: string | null, ots: ArrayBuffer | null, options?: { debug?: boolean }): Promise<TimestampResult | { error: string } | null>`
+  - Verifies an OpenTimestamps proof against a hash digest. Returns verification result, error object, or null if inputs invalid.
+- `verifyOtsZip(zip: any): Promise<OtsVerifyResult>`
+  - Verifies OpenTimestamps proof within a ZIP file. Extracts merkle root and OTS proof, then verifies against Bitcoin blockchain.
+
+**ZIP Integration:**
+- `getOtsEntry(zip: any): any | null`
+  - Finds the OpenTimestamps entry in a ZIP file. Searches for TIMESTAMP_METADATA first, then TIMESTAMP_SUBMITTED.
+- `getOtsBuffer(zip: any, otsEntry: any): Promise<Buffer | null>`
+  - Extracts OTS proof data from a ZIP entry.
+- `getMerkleRootSafe(zip: any): string | null`
+  - Safely extracts merkle root from a ZIP file.
+
+**Data Processing:**
+- `deserializeOts(tsResult: TimestampResult, options?: { debug?: boolean }): Promise<string | null>`
+  - Deserializes OpenTimestamps verification result into JSON format. Extracts blockchain attestation data and transaction details.
+- `parseVerifyResult(verifyResult: TimestampResult): Promise<TimestampInfo>`
+  - Parses timestamp verification result into readable information. Formats blockchain attestation data with human-readable messages and dates.
+
+**Upgrade:**
+- `upgradeOTS(zipFilePath: string, upgradedOts: Buffer): Promise<void>`
+  - Upgrades OpenTimestamps proof in an existing ZIP file. Replaces old timestamp metadata with upgraded OTS proof data.
+- `createOtsMetadataEntry(zipKit: any, ots: Buffer | null): any | null`
+  - Creates a ZIP metadata entry containing OpenTimestamps proof. Creates a special ZIP entry marked as metadata that stores OTS proof data.
+
+**Utility Functions:**
+- `bufferToArrayBuffer(buf: Buffer): ArrayBuffer`
+  - Converts a Node.js Buffer to an ArrayBuffer.
+
+#### Types & Interfaces
+
+```typescript
+export interface TimestampResult {
+  merkleRoot: string | null;
+  ots: ArrayBuffer | null;
+  verified: boolean;
+  results: any | null;
+  error: string | null;
+  attestations: any | null;
+  upgradedOts: ArrayBuffer | null;
+}
+
+export interface TimestampInfo {
+  message: string;
+  results: string[];
+  attestDate: Date | null;
+  attestHeight: number | null;
+  submittedUri: string | null;
+  otsUpgraded: boolean;
+}
+
+export interface OtsVerifyResult {
+  status: 'none' | 'valid' | 'pending' | 'error';
+  message?: string;
+  blockHeight?: number;
+  attestedAt?: Date;
+  upgraded?: boolean;
+  upgradedOts?: Buffer;
+}
+
+export interface DeserializeOtsResult {
+  attestStr: string | null;
+  needsUpdateMsg: string | null;
+  attestationValues: any[];
+}
+```
+
+#### Usage Example
+
+```typescript
+import { createTimestamp, verifyOtsZip, upgradeOTS } from 'neozipkit/blockchain';
+
+// Create timestamp for a file's hash
+const otsProof = await createTimestamp(merkleRoot);
+
+// Verify a loaded ZIP file
+const result = await verifyOtsZip(zipInstance);
+if (result.status === 'valid') {
+  console.log(`Verified! Block: ${result.blockHeight}`);
+  
+  // Upgrade proof if available
+  if (result.upgradedOts) {
+    await upgradeOTS(zipPath, result.upgradedOts);
+  }
+}
+```
+
+### Contract Configuration (contracts.ts)
+All contract-related constants and configurations in one place:
+
+- `CONTRACT_CONFIGS`: Network configurations with contract addresses, RPC URLs, and explorer URLs
+- `NZIP_CONTRACT_ABI`: Full ABI for the NZIP‑NFT contract
+- `CURRENT_DEPLOYMENT`: Current default deployment (Base Sepolia)
+- `DEFAULT_NETWORK`: Default network chain ID (84532)
+- Helper functions: `getContractConfig()`, `getSupportedNetworks()`, `isNetworkSupported()`
+
+**Supported Networks**:
+- Base Sepolia (84532) - Primary testnet
+- Base Mainnet (8453) - Production
+
+### Token Verification (ZipKitVerifier.ts)
+- High-level verification API for NZIP‑NFT contract and on-chain checks.
+
+### Token Query
+Token querying functionality is integrated into the core wallet and verification classes:
+- `CoreWalletManager.queryWalletTokens()` - Query tokens for a wallet address
+- `ZipkitVerifier.queryBlockchainForExistingToken()` - Query for existing tokens by merkle root
+
+### Wallet Management
+- `class CoreWalletManager`: Platform-agnostic wallet operations (core functionality)
+- `class WalletManagerServer`: Server-specific wallet management with file system operations
+- `class WalletManagerBrowser`: Browser-specific wallet management with provider connections
+- `class WalletAnalyzer`: Analyze balances, scan NZIP tokens, ERC‑20s and NFTs.
+- Types re‑exported: `TokenInfo`, `NZipTokenDetails`, `WalletBasicInfo`, `TokenScanResult`, `CommonTokenConfig`.
+
+### NFT Minting (ZipkitMinter.ts)
+- High‑level minting API for NZIP‑NFT contract.
+- Core functionality in `core/ZipkitMinter.ts`
+- Browser-specific implementation in `browser/ZipkitMinterBrowser.ts`
+- Server-specific implementation in `server/ZipkitMinterServer.ts`
+
+### NFT Verification (ZipkitVerifier.ts)
+- High‑level verification API for NZIP‑NFT contract.
+- Core functionality in `core/ZipkitVerifier.ts`
+- Browser token verification in `browser/TokenVerifierBrowser.ts`
+- Server-specific implementation in `server/ZipkitVerifierServer.ts`
+
+  - Helpers to format token and wallet data for display.
+
+Re‑exports (index.ts):
+Wallet formatting helpers have been removed. Use your app's UI layer for presentation formatting.
+
+### ZIP Metadata Helpers
+ZIP metadata functionality is integrated into the core ZIP handling classes:
+- Token metadata validation and processing is handled by `ZipkitMinter` and `ZipkitVerifier`
+- Metadata entries are managed through the core ZIP utilities
+
+### Module Types (types.ts)
+Exports shared types used across blockchain operations, including:
+- `NZipTokenInfo`, `NZipTokenDetails`, `ZipFileInfo`, `WalletInfo`, `BlockchainVerification`, and others used by certificate/token helpers.
+
+### Notes
+- All OTS utilities suppress verbose logs by default. Pass `{ debug: true }` to see OpenTimestamps logs.
+- Contract addresses vary per network; see `CONTRACT_CONFIGS` and keep them updated after deployments.

package/src/{browser → blockchain/browser}/TokenVerifierBrowser.ts

@@ -4,23 +4,12 @@
 //  Copyright (c) 2025 NeoWare, Inc. All rights reserved.
 // ======================================
 
-import ZipKitBrowser from './ZipKitBrowser';
-import { ZipEntry } from '../shared/ZipKit';
-import { TOKENIZED_METADATA } from '../shared/constants/Headers';
-import { NZIP_CONTRACT_ABI, CURRENT_DEPLOYMENT } from '../server/blockchain/constants';
-
-// Token types (adapted for browser)
-export interface NZipTokenInfo {
-  version: string;
-  tokenId: string;
-  contractAddress: string;
-  network: string;
-  networkChainId: number;
-  transactionHash: string;
-  merkleRoot: string;
-  fileName: string;
-  mintedAt: string;
-}
+import ZipkitBrowser from '../../browser/ZipkitBrowser';
+import { ZipEntry } from '../../core';
+import { TOKENIZED_METADATA } from '../../core/constants/Headers';
+import { TokenMetadata } from '../../types';
+import { NZIP_CONTRACT_ABI, getContractConfig } from '../core/contracts';
+import { ethers } from 'ethers';
 
 export interface TokenVerificationOptions {
   skipHash?: boolean;
@@ -31,7 +20,7 @@ export interface TokenVerificationOptions {
 
 export interface TokenVerificationResult {
   isTokenized: boolean;
-  tokenMetadata: NZipTokenInfo | null;
+  tokenMetadata: TokenMetadata | null;
   calculatedMerkleRoot: string | null;
   blockchainMerkleRoot: string | null;
   blockchainTimestamp?: number; // Actual blockchain timestamp from tokenizationTime
@@ -49,28 +38,6 @@ export interface BlockchainVerification {
   blockNumber?: number;
 }
 
-// Network configuration for blockchain queries
-const NETWORK_CONFIG: Record<string, any> = {
-  'Base Sepolia': {
-    chainId: 84532,
-    rpcUrls: [
-      'https://sepolia.base.org',
-      'https://base-sepolia.g.alchemy.com/v2/demo',
-      'https://base-sepolia-rpc.publicnode.com',
-      'https://base-sepolia.blockpi.network/v1/rpc/public'
-    ]
-  },
-  'Base Mainnet': {
-    chainId: 8453,
-    rpcUrls: [
-      'https://mainnet.base.org',
-      'https://base-mainnet.g.alchemy.com/v2/demo',
-      'https://base-rpc.publicnode.com',
-      'https://base.blockpi.network/v1/rpc/public'
-    ]
-  }
-};
-
 // Use the complete contract ABI from constants
 const CONTRACT_ABI = NZIP_CONTRACT_ABI;
 
@@ -78,10 +45,10 @@ const CONTRACT_ABI = NZIP_CONTRACT_ABI;
  * Browser-compatible token verification class
  */
 export class TokenVerifierBrowser {
-  private zipKit: ZipKitBrowser;
+  private zipkit: ZipkitBrowser;
 
-  constructor(zipKit: ZipKitBrowser) {
-    this.zipKit = zipKit;
+  constructor(zipkit: ZipkitBrowser) {
+    this.zipkit = zipkit;
   }
 
   /**
@@ -106,7 +73,7 @@ export class TokenVerifierBrowser {
 
     try {
       // Extract the token metadata
-      const tokenData = await this.zipKit.extractBlob(tokenEntry);
+      const tokenData = await this.zipkit.extractBlob(tokenEntry);
       
       if (!tokenData) {
         return {
@@ -164,9 +131,15 @@ export class TokenVerifierBrowser {
       const blockchainData = await this.queryBlockchainData(tokenMetadata);
       
       if (!blockchainData.merkleRoot) {
+        // Add owner information to tokenMetadata even if merkle root is not available
+        const enhancedTokenMetadata = {
+          ...tokenMetadata,
+          owner: blockchainData.owner || undefined
+        };
+        
         return {
           isTokenized: true,
-          tokenMetadata,
+          tokenMetadata: enhancedTokenMetadata,
           calculatedMerkleRoot,
           blockchainMerkleRoot: null,
           blockchainTimestamp: blockchainData.timestamp ?? undefined,
@@ -175,16 +148,30 @@ export class TokenVerifierBrowser {
         };
       }
 
-      const verificationPassed = blockchainData.merkleRoot === calculatedMerkleRoot;
+      // Normalize both merkle roots for comparison (trim whitespace, lowercase)
+      const normalizedBlockchain = blockchainData.merkleRoot?.toLowerCase().trim() || '';
+      const normalizedCalculated = calculatedMerkleRoot?.toLowerCase().trim() || '';
+      const verificationPassed = normalizedBlockchain === normalizedCalculated;
+      
+      // Log mismatch only (success is silent)
+      if (!verificationPassed) {
+        console.warn(`[TokenVerifier] ⚠️ Merkle root mismatch - Calculated: ${calculatedMerkleRoot}, Blockchain: ${blockchainData.merkleRoot}`);
+      }
+      
+      // Add owner information to tokenMetadata
+      const enhancedTokenMetadata = {
+        ...tokenMetadata,
+        owner: blockchainData.owner || undefined
+      };
       
       return {
         isTokenized: true,
-        tokenMetadata,
+        tokenMetadata: enhancedTokenMetadata,
         calculatedMerkleRoot,
         blockchainMerkleRoot: blockchainData.merkleRoot,
         blockchainTimestamp: blockchainData.timestamp ?? undefined,
         verificationPassed,
-        errorMessage: verificationPassed ? undefined : 'Merkle root mismatch - archive may be tampered'
+        errorMessage: verificationPassed ? undefined : `Merkle root mismatch - Calculated: ${calculatedMerkleRoot}, Blockchain: ${blockchainData.merkleRoot}`
       };
       
     } catch (error) {
@@ -202,7 +189,7 @@ export class TokenVerifierBrowser {
   /**
    * Validates token metadata structure
    */
-  private validateTokenInfo(tokenMetadata: any): tokenMetadata is NZipTokenInfo {
+  private validateTokenInfo(tokenMetadata: any): tokenMetadata is TokenMetadata {
     return tokenMetadata &&
            typeof tokenMetadata.version === 'string' &&
            typeof tokenMetadata.tokenId === 'string' &&
@@ -211,7 +198,6 @@ export class TokenVerifierBrowser {
            typeof tokenMetadata.networkChainId === 'number' &&
            typeof tokenMetadata.transactionHash === 'string' &&
            typeof tokenMetadata.merkleRoot === 'string' &&
-           typeof tokenMetadata.fileName === 'string' &&
            typeof tokenMetadata.mintedAt === 'string';
   }
 
@@ -224,6 +210,7 @@ export class TokenVerifierBrowser {
       const contentEntries = zipEntries.filter(entry => entry.filename !== TOKENIZED_METADATA);
       
       if (contentEntries.length === 0) {
+        console.error(`[TokenVerifier] ❌ No content entries found after filtering`);
         return null;
       }
 
@@ -231,41 +218,96 @@ export class TokenVerifierBrowser {
       for (const entry of contentEntries) {
         if (!entry.sha256) {
           // Extract the file to calculate its SHA-256 hash
-          await this.zipKit.extractBlob(entry);
+          await this.zipkit.extractBlob(entry);
         }
       }
 
       // Calculate merkle root from content files
-      // This would need to be implemented based on the ZipKit's merkle tree functionality
-      // For now, we'll use a placeholder that would need to be implemented
-      return await this.zipKit.getMerkleRoot?.() || null;
+      // getMerkleRoot() already excludes TOKENIZED_METADATA, TIMESTAMP_SUBMITTED, and TIMESTAMP_METADATA
+      const merkleRoot = await this.zipkit.getMerkleRoot?.() || null;
+      
+      if (!merkleRoot) {
+        console.error(`[TokenVerifier] ❌ Failed to calculate merkle root`);
+      }
+      
+      return merkleRoot;
     } catch (error) {
-      console.error('Error calculating merkle root:', error);
+      console.error(`[TokenVerifier] ❌ Error calculating merkle root:`, error);
       return null;
     }
   }
 
   /**
-   * Queries the blockchain to get the actual merkle root and timestamp stored in the smart contract
+   * Queries the blockchain to get the actual merkle root, timestamp, and owner stored in the smart contract
    */
-  private async queryBlockchainData(tokenMetadata: NZipTokenInfo): Promise<{merkleRoot: string | null, timestamp: number | null}> {
+  private async queryBlockchainData(tokenMetadata: TokenMetadata): Promise<{merkleRoot: string | null, timestamp: number | null, owner: string | null}> {
     try {
-      // Dynamic import of ethers to avoid SSR issues
-      const { ethers } = await import('ethers');
+      // Get network configuration from contracts.ts (single source of truth)
+      if (!tokenMetadata.networkChainId) {
+        console.error(`[TokenVerifier] ❌ No chainId in token metadata`);
+        return { merkleRoot: null, timestamp: null, owner: null };
+      }
+      
+      const networkConfig = getContractConfig(tokenMetadata.networkChainId);
       
-      const networkConfig = NETWORK_CONFIG[tokenMetadata.network];
       if (!networkConfig) {
-        console.warn(`Unsupported network: ${tokenMetadata.network}`);
-        return { merkleRoot: null, timestamp: null };
+        console.error(`[TokenVerifier] ❌ Could not resolve network configuration for chainId: ${tokenMetadata.networkChainId}`);
+        return { merkleRoot: null, timestamp: null, owner: null };
       }
 
-      // Try multiple RPC endpoints
+      // Test RPC endpoints first to find working ones (same as server-side)
+      const workingRpcUrls: string[] = [];
+      
       for (const rpcUrl of networkConfig.rpcUrls) {
+        try {
+          const controller = new AbortController();
+          const timeoutId = setTimeout(() => controller.abort(), 5000);
+          
+          const testResponse = await fetch(rpcUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              jsonrpc: '2.0',
+              method: 'eth_chainId',
+              params: [],
+              id: 1
+            }),
+            signal: controller.signal
+          });
+          
+          clearTimeout(timeoutId);
+          
+          if (testResponse.ok) {
+            const contentType = testResponse.headers.get('content-type');
+            if (contentType && contentType.includes('application/json')) {
+              const testData = await testResponse.json() as { jsonrpc?: string; result?: string };
+              if (testData?.jsonrpc && testData?.result) {
+                const actualChainId = parseInt(testData.result, 16);
+                if (actualChainId === tokenMetadata.networkChainId) {
+                  workingRpcUrls.push(rpcUrl);
+                }
+              }
+            }
+          }
+        } catch (testError: any) {
+          // Silently skip failed endpoints
+        }
+      }
+      
+      if (workingRpcUrls.length === 0) {
+        // Fallback to all endpoints if none tested successfully
+        workingRpcUrls.push(...networkConfig.rpcUrls);
+      }
+
+      // Try multiple RPC endpoints (only working ones if available)
+      for (let i = 0; i < workingRpcUrls.length; i++) {
+        const rpcUrl = workingRpcUrls[i];
+        
         try {
           const provider = new ethers.JsonRpcProvider(rpcUrl);
           
           // Test connection with a timeout
-          const blockNumber = await Promise.race([
+          await Promise.race([
             provider.getBlockNumber(),
             new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout')), 5000))
           ]);
@@ -276,23 +318,27 @@ export class TokenVerifierBrowser {
           // Call getZipFileInfo to get the blockchain-stored data
           const zipInfo = await contract.getZipFileInfo(tokenMetadata.tokenId);
           
+          // Get the token owner
+          const owner = await contract.ownerOf(tokenMetadata.tokenId);
+          
           return {
             merkleRoot: zipInfo.merkleRootHash,
-            timestamp: Number(zipInfo.tokenizationTime)
+            timestamp: Number(zipInfo.tokenizationTime),
+            owner: owner
           };
           
-        } catch (error) {
-          console.warn(`RPC ${rpcUrl} failed:`, error);
+        } catch (error: any) {
+          // Continue to next endpoint on error
           continue;
         }
       }
       
-      console.warn(`All RPC endpoints failed for network: ${tokenMetadata.network}`);
-      return { merkleRoot: null, timestamp: null };
+      console.error(`[TokenVerifier] ❌ All RPC endpoints failed for network: ${tokenMetadata.network}`);
+      return { merkleRoot: null, timestamp: null, owner: null };
       
-    } catch (error) {
-      console.error('Blockchain query error:', error);
-      return { merkleRoot: null, timestamp: null };
+    } catch (error: any) {
+      console.error(`[TokenVerifier] ❌ Blockchain query error:`, error?.message || error);
+      return { merkleRoot: null, timestamp: null, owner: null };
     }
   }
 
@@ -311,15 +357,15 @@ export class TokenVerifierBrowser {
   /**
    * Creates a formatted summary of token information
    */
-  createTokenSummary(tokenMetadata: NZipTokenInfo): string {
+  createTokenSummary(tokenMetadata: TokenMetadata): string {
     return `
 🎫 NFT Token Information:
    Token ID: ${tokenMetadata.tokenId}
    Network: ${tokenMetadata.network}
    Contract: ${tokenMetadata.contractAddress}
    Transaction: ${tokenMetadata.transactionHash}
-   File: ${tokenMetadata.fileName}
-   Minted: ${new Date(tokenMetadata.mintedAt).toLocaleString()}
+    Type: Tokenized Archive
+   Minted: ${tokenMetadata.mintedAt ? new Date(tokenMetadata.mintedAt).toLocaleString() : 'Unknown'}
    `;
   }
 }
@@ -327,18 +373,18 @@ export class TokenVerifierBrowser {
 /**
  * Creates a new TokenVerifierBrowser instance
  */
-export function createTokenVerifier(zipKit: ZipKitBrowser): TokenVerifierBrowser {
-  return new TokenVerifierBrowser(zipKit);
+export function createTokenVerifier(zipkit: ZipkitBrowser): TokenVerifierBrowser {
+  return new TokenVerifierBrowser(zipkit);
 }
 
 /**
  * Convenience function to check for tokenization
  */
 export async function checkForTokenization(
-  zipKit: ZipKitBrowser,
+  zipkit: ZipkitBrowser,
   zipEntries: ZipEntry[],
   options: TokenVerificationOptions = {}
 ): Promise<TokenVerificationResult> {
-  const verifier = new TokenVerifierBrowser(zipKit);
+  const verifier = new TokenVerifierBrowser(zipkit);
   return verifier.checkForTokenization(zipEntries, options);
 }