neozip-blockchain 0.5.1

package/dist/core/ZipkitVerifier.d.ts

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+/**
+ * ZipkitVerifier - Handles NFT token verification for ZIP files
+ * Verifier API for NZIP-NFT smart contract.
+ */
+import { type ContractConfig } from './contracts';
+import type { TokenMetadata } from '../types';
+export interface VerificationOptions {
+    debug?: boolean;
+    skipHash?: boolean;
+    /**
+     * Enable RPC consensus mechanism for enhanced security
+     * When enabled, queries multiple RPC endpoints and requires majority agreement
+     * Default: false (disabled for quick validation)
+     */
+    rpcConsensus?: boolean;
+    /**
+     * Minimum number of RPC endpoints that must agree (when consensus enabled)
+     * Default: 2 (majority of 3 endpoints)
+     */
+    minRpcConsensus?: number;
+    /**
+     * Validate chainId from RPC matches expected chainId
+     * Default: true
+     */
+    validateRpcChainId?: boolean;
+    /**
+     * Validate contract version matches on-chain version
+     * When enabled, queries on-chain version and validates it matches metadata version (or used version for legacy files)
+     * Default: true (enabled for security)
+     */
+    validateContractVersion?: boolean;
+}
+export interface VerificationResult {
+    success: boolean;
+    message: string;
+    tokenMetadata?: TokenMetadata;
+    verificationDetails?: {
+        tokenId: string;
+        network: string;
+        contractAddress: string;
+        merkleRoot: string;
+        mintDate: string;
+        calculatedMerkleRoot?: string;
+        declaredMerkleRoot?: string;
+        merkleRootMatch?: boolean;
+        onChainValid?: boolean;
+        currentWallet?: string;
+    };
+    errorDetails?: {
+        errorType: 'METADATA_ERROR' | 'MERKLE_ERROR' | 'NETWORK_ERROR' | 'CONTRACT_ERROR';
+        networkName?: string;
+        rpcUrl?: string;
+        contractAddress?: string;
+        tokenId?: string;
+        merkleRoot?: string;
+        calculatedMerkleRoot?: string;
+        onChainMerkleRoot?: string;
+    };
+}
+export interface EnhancedVerificationResult extends VerificationResult {
+    retryAttempts?: number;
+    processingTime?: number;
+    timestamp?: number;
+}
+export interface BatchVerificationResult {
+    success: boolean;
+    totalTokens: number;
+    successfulVerifications: number;
+    failedVerifications: number;
+    results: EnhancedVerificationResult[];
+    processingTime: number;
+}
+export interface VerificationJob {
+    tokenId: string;
+    merkleRoot?: string;
+    priority?: 'low' | 'normal' | 'high';
+    retryCount?: number;
+}
+/**
+ * Blockchain Token Verifier for ZIP files
+ */
+export declare class ZipkitVerifier {
+    private debug;
+    protected maxRetries: number;
+    protected retryDelay: number;
+    protected batchDelay: number;
+    constructor(options?: VerificationOptions & {
+        maxRetries?: number;
+        retryDelay?: number;
+        batchDelay?: number;
+    });
+    /**
+     * Extracts and normalizes token metadata from a tokenized ZIP archive.
+     *
+     * Handles field name variations across different token versions:
+     * - chainId vs networkChainId
+     * - timestamp vs mintedAt
+     * - Validates required fields
+     *
+     * @param zipkit - ZipkitNode instance with loaded archive
+     * @returns Normalized TokenMetadata or null if not tokenized
+     * @throws Error if TOKEN file exists but is invalid
+     *
+     * @example
+     * ```typescript
+     * import { ZipkitNode } from 'neozipkit/node';
+     * import { ZipkitVerifier } from 'neozipkit/blockchain';
+     *
+     * const zipkit = new ZipkitNode();
+     * await zipkit.loadZipFile('archive.nzip');
+     * const metadata = await ZipkitVerifier.extractTokenMetadata(zipkit);
+     * if (metadata) {
+     *   console.log(`Token ID: ${metadata.tokenId}`);
+     *   console.log(`Network: ${metadata.network}`);
+     * }
+     * ```
+     */
+    static extractTokenMetadata(zipkit: any): Promise<TokenMetadata | null>;
+    /**
+     * Instance method for convenience - extracts token metadata from loaded archive
+     * @param zipkit - ZipkitNode instance with loaded archive
+     * @returns Normalized TokenMetadata or null if not tokenized
+     */
+    getTokenMetadata(zipkit: any): Promise<TokenMetadata | null>;
+    /**
+     * Query contract version from blockchain
+     * @param contractAddress - Contract address
+     * @param networkConfig - Network configuration with RPC URLs
+     * @param rpcUrlIndex - Optional RPC URL index (default: 0)
+     * @returns Contract version string or null if query fails
+     */
+    private queryContractVersion;
+    /**
+     * Extract and validate token metadata from ZIP
+     */
+    extractTokenMetadata(tokenBuffer: Buffer): Promise<{
+        success: boolean;
+        metadata?: TokenMetadata;
+        error?: string;
+    }>;
+    /**
+     * Map network name to RPC configuration using contracts.ts (single source of truth)
+     * REQUIRES chainId for security - network names are ambiguous and can match wrong networks
+     *
+     * @param networkName Network name (for logging/display purposes only)
+     * @param chainId Chain ID (REQUIRED - must be provided)
+     * @returns Network configuration or error if chainId is missing or invalid
+     */
+    private getNetworkConfig;
+    /**
+     * Perform merkle root comparison
+     * Uses direct string comparison - merkle roots are hex strings and must match exactly
+     * Case-sensitive comparison ensures no encoding issues or false positives
+     */
+    private compareMerkleRoots;
+    /**
+     * Query multiple RPC endpoints with consensus mechanism
+     * Returns data only if majority of endpoints agree
+     */
+    private queryMultipleRPCsWithConsensus;
+    /**
+     * Verify token against blockchain
+     * @param rpcUrlIndex Optional index of RPC URL to use (default: 0)
+     * @param options Optional verification options including RPC consensus settings
+     */
+    verifyOnChain(tokenId: string, contractAddress: string, networkConfig: ContractConfig, merkleRoot: string, rpcUrlIndex?: number, options?: VerificationOptions, metadataContractVersion?: string): Promise<{
+        success: boolean;
+        isValid?: boolean;
+        onChainMerkleRoot?: string;
+        onChainTokenizationTime?: number;
+        onChainCreator?: string;
+        onChainBlockNumber?: number;
+        error?: string;
+        rpcUrl?: string;
+    }>;
+    /**
+     * Complete verification process
+     * @param rpcUrlIndex Optional index of RPC URL to use (default: 0)
+     */
+    verifyToken(tokenMetadata: TokenMetadata, calculatedMerkleRoot: string | null, options?: VerificationOptions, rpcUrlIndex?: number): Promise<VerificationResult>;
+    /**
+     * Verify token with retry logic and exponential backoff
+     * @param tokenMetadata Token metadata to verify
+     * @param calculatedMerkleRoot Calculated merkle root from archive
+     * @param maxRetries Maximum number of retry attempts (default: uses instance maxRetries)
+     * @returns Enhanced verification result with retry information
+     */
+    verifyTokenWithRetry(tokenMetadata: TokenMetadata, calculatedMerkleRoot: string | null, maxRetries?: number): Promise<EnhancedVerificationResult>;
+    /**
+     * Batch verification for multiple tokens with rate limiting
+     * @param tokens Array of token metadata and merkle roots to verify
+     * @param options Batch processing options
+     * @returns Batch verification result
+     */
+    verifyBatch(tokens: Array<{
+        tokenMetadata: TokenMetadata;
+        calculatedMerkleRoot: string | null;
+    }>, options?: {
+        parallel?: boolean;
+        maxConcurrent?: number;
+    }): Promise<BatchVerificationResult>;
+    /**
+     * Verify tokens in parallel with concurrency control
+     */
+    private verifyBatchParallel;
+    /**
+     * Verify tokens sequentially with rate limiting
+     */
+    private verifyBatchSequential;
+    /**
+     * Process verification jobs with priority queue
+     * @param jobs Array of verification jobs
+     * @param options Processing options
+     * @returns Batch verification result
+     */
+    processVerificationJobs(jobs: VerificationJob[], options?: {
+        maxConcurrent?: number;
+        priorityOrder?: boolean;
+        getTokenMetadata?: (tokenId: string) => Promise<TokenMetadata | null>;
+        getCalculatedMerkleRoot?: (tokenId: string) => Promise<string | null>;
+    }): Promise<BatchVerificationResult>;
+    /**
+     * Sort verification jobs by priority
+     */
+    private sortJobsByPriority;
+    /**
+     * Calculate retry delay with exponential backoff
+     */
+    protected calculateRetryDelay(attempt: number): number;
+    /**
+     * Utility method for delays
+     */
+    protected delay(ms: number): Promise<void>;
+    /**
+     * Get verification statistics
+     */
+    getVerificationStats(): {
+        maxRetries: number;
+        retryDelay: number;
+        batchDelay: number;
+    };
+    /**
+     * Update verification configuration
+     */
+    updateConfig(config: {
+        maxRetries?: number;
+        retryDelay?: number;
+        batchDelay?: number;
+    }): void;
+}
+//# sourceMappingURL=ZipkitVerifier.d.ts.map

package/dist/core/ZipkitVerifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZipkitVerifier.d.ts","sourceRoot":"","sources":["../../src/core/ZipkitVerifier.ts"],"names":[],"mappings":"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"}