neozipkit 0.1.1

package/README.md

@@ -0,0 +1,400 @@
+# neozipkit
+
+Advanced ZIP file creation and verification library with blockchain timestamping and NFT tokenization capabilities.
+
+## 🌟 Features
+
+- **Advanced ZIP compression** with support for multiple compression methods (Deflate, ZStandard, Stored)
+- **Blockchain timestamping** using OpenTimestamps for file integrity verification
+- **NFT tokenization** for creating blockchain-backed ZIP file certificates
+- **Hash-based verification** with Merkle tree support
+- **Browser and server compatibility** with clean platform separation
+- **TypeScript support** with full type definitions
+
+## 📦 Installation
+
+```bash
+yarn add neozipkit
+```
+
+## 🚀 Quick Start
+
+### Basic ZIP Creation
+
+```typescript
+import { ZipKitBrowser } from 'neozipkit/browser';
+import { CompressOptions } from 'neozipkit';
+
+const zipKit = new ZipKitBrowser();
+const options: CompressOptions = {
+  useZstd: false, // Use deflate compression
+  level: 6
+};
+
+// Add files to ZIP
+await zipKit.addFile('example.txt', fileBuffer, options);
+const zipBuffer = await zipKit.finalize();
+```
+
+### ZIP Verification
+
+```typescript
+import { ZipKitBrowser } from 'neozipkit/browser';
+import { ZipEntry } from 'neozipkit';
+
+const zipKit = new ZipKitBrowser();
+const entries: ZipEntry[] = await zipKit.loadFromBuffer(zipBuffer);
+
+// Verify file integrity
+for (const entry of entries) {
+  const isValid = await zipKit.verifyEntry(entry);
+  console.log(`${entry.filename}: ${isValid ? 'Valid' : 'Invalid'}`);
+}
+```
+
+## 🏗️ Package Architecture
+
+### Unified Directory Structure
+
+```
+packages/neozipkit/
+├── src/                           # TypeScript source files
+│   ├── browser/                   # Browser-only implementations
+│   │   ├── ZipKitBrowser.ts
+│   │   ├── CertificateGeneratorBrowser.ts
+│   │   └── TokenVerifierBrowser.ts
+│   ├── server/                    # Server-only implementations
+│   │   ├── blockchain/            # Blockchain integration utilities
+│   │   │   ├── TokenVerifier.ts   # Verify tokenized ZIP files
+│   │   │   ├── NFTMinter.ts       # Mint NFTs for ZIP files
+│   │   │   ├── WalletManager.ts   # Manage wallet connections
+│   │   │   └── ...               # Additional blockchain components
+│   │   └── platform/              # Server platform code
+│   │       ├── server/            # Server-specific ZIP operations
+│   │       └── servercomponents/  # OpenTimestamps & server utilities
+│   ├── shared/                    # Shared utilities
+│   │   ├── components/            # Core ZIP utilities
+│   │   ├── constants/             # Headers, errors, etc.
+│   │   ├── types/                 # Type definitions
+│   │   ├── ZipKit.ts              # Main ZipKit class
+│   │   └── ZipEntry.ts            # ZIP entry handling
+│   ├── browser-index.ts           # Browser-specific exports
+│   └── index.ts                   # Main exports (all platforms)
+├── dist/                          # Compiled JavaScript output
+│   ├── browser.js/.d.ts           # Browser-only bundle
+│   ├── server/                    # Server bundle
+│   ├── shared/                    # Shared code
+│   └── index.js/.d.ts             # Main bundle
+├── contracts/                     # Smart contracts for NFT tokenization
+├── examples/                      # Usage examples
+└── docs/                          # Documentation
+```
+
+## 📚 Import Patterns
+
+### Browser Applications (Recommended)
+
+```typescript
+// Browser-only bundle (excludes Node.js dependencies)
+import { ZipKitBrowser, CertificateGeneratorBrowser } from 'neozipkit/browser';
+import { TOKENIZED_METADATA } from 'neozipkit/browser';
+```
+
+### Universal Applications (Next.js, Node.js)
+
+```typescript
+// Main bundle (includes both browser and server when possible)
+import { ZipKitBrowser, CertificateGeneratorBrowser } from 'neozipkit';
+import { TOKENIZED_METADATA } from 'neozipkit/shared/constants/Headers';
+```
+
+### Server-Only Components (Node.js)
+
+```typescript
+// Direct TypeScript imports for server components
+import { TokenVerifier } from 'neozipkit/server/blockchain/TokenVerifier';
+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
+
+### Blockchain Components
+
+- **`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
+
+```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);
+}
+```
+
+## 🎯 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
+
+### Build Process
+
+```bash
+# Full build process
+npm run build
+
+# Individual steps
+npm run clean        # Remove compiled files
+npm run compile      # TypeScript compilation
+npm run watch        # Watch mode for development
+```
+
+This runs:
+1. `npm run clean` - Removes old compiled files
+2. `npm run compile` - Compiles TypeScript to dist/
+3. `npm run create-browser-entry` - Creates browser-only bundle
+
+### TypeScript Configuration
+
+- **Target**: ES2020
+- **Module**: CommonJS
+- **Source**: `./src`
+- **Output**: `./dist`
+- **Declarations**: Generated alongside JavaScript files
+
+## 📖 API Reference
+
+### Core Classes
+
+- **`ZipKit`** - Core ZIP functionality (shared)
+- **`ZipKitBrowser`** - Browser-compatible ZIP operations
+- **`ZipKitServer`** - Server-side ZIP operations with full Node.js support
+- **`ZipEntry`** - ZIP entry representation and manipulation
+- **`HashAccumulator`** - Hash accumulation for Merkle tree verification
+
+### Platform-Specific Components
+
+#### Browser Components
+- **`CertificateGeneratorBrowser`** - Generate verification certificates
+- **`TokenVerifierBrowser`** - Browser-based token verification
+- **`ZipKitStampBrowser`** - Browser timestamping utilities
+
+#### Server Components
+- **`ZipKitOTS`** - OpenTimestamps integration
+- **Blockchain Classes** - Complete blockchain integration suite
+
+### Constants and Types
+
+- **`constants/Headers`** - ZIP header constants and compression methods
+- **`constants/Errors`** - Error definitions
+- **`shared/types`** - TypeScript type definitions
+- **`CMP_METHOD`** - Compression method constants
+
+### Compression Methods
+
+```typescript
+import { CMP_METHOD } from 'neozipkit/shared/constants/Headers';
+
+// Available compression methods
+const compressionType = entry.cmpMethod;
+
+if (compressionType === CMP_METHOD.ZSTD) {
+  console.log('ZStandard compression');
+} else if (compressionType === CMP_METHOD.DEFLATED) {
+  console.log('Deflate compression');
+} else if (compressionType === CMP_METHOD.STORED) {
+  console.log('No compression');
+}
+```
+
+### Hash Accumulation
+
+```typescript
+import { HashAccumulator } from 'neozipkit/shared/components/HashAccumulator';
+
+const accumulator = new HashAccumulator();
+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
+
+### File Verification
+
+- **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
+
+## 📦 Dependencies
+
+### Core Dependencies
+
+- **`ethers`** (peer dependency) - Blockchain operations
+- **`opentimestamps`** - Bitcoin blockchain timestamping
+- **`uuid`** - Unique identifier generation
+- **`web3`** (peer dependency) - Alternative blockchain interface
+
+### Development Dependencies
+
+- **`@types/node`** - Node.js type definitions
+- **`typescript`** - TypeScript compiler
+
+## 🔄 Migration Guide
+
+### From Previous Versions
+
+If upgrading from previous versions:
+
+1. **Update Import Paths**:
+   ```typescript
+   // OLD
+   import { TokenVerifier } from 'neozipkit/server-components/blockchain/TokenVerifier';
+   
+   // NEW
+   import { checkForTokenizationServer } from 'neozipkit/server/blockchain/TokenVerifier';
+   ```
+
+2. **Browser Imports**: Replace main package imports with browser-specific imports for browser applications
+3. **Contract Addresses**: Update to use the new production contract address
+4. **Build Process**: Remove any manual copying scripts - everything now uses TypeScript compilation
+
+## 🤝 Contributing
+
+### Development Setup
+
+1. Clone the repository and install dependencies
+2. Make changes to TypeScript files in `src/`
+3. Run `npm run build` to compile changes
+4. Test changes in consuming applications
+5. Commit only source files, not generated files
+
+### Making Changes
+
+- Edit TypeScript files in `src/` directories
+- Update exports in `src/index.ts` if adding new public modules
+- Update `package.json` exports if creating new public modules
+- Run build process to generate JavaScript
+- Test in portal application
+
+## 📄 License
+
+MIT
+
+## 🎉 Getting Started
+
+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
+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.

package/contracts/Lock.sol

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity ^0.8.28;
+
+// Uncomment this line to use console.log
+// import "hardhat/console.sol";
+
+contract Lock {
+    uint public unlockTime;
+    address payable public owner;
+
+    event Withdrawal(uint amount, uint when);
+
+    constructor(uint _unlockTime) payable {
+        require(
+            block.timestamp < _unlockTime,
+            "Unlock time should be in the future"
+        );
+
+        unlockTime = _unlockTime;
+        owner = payable(msg.sender);
+    }
+
+    function withdraw() public {
+        // Uncomment this line, and the import of "hardhat/console.sol", to print a log in your terminal
+        // console.log("Unlock time is %o and block timestamp is %o", unlockTime, block.timestamp);
+
+        require(block.timestamp >= unlockTime, "You can't withdraw yet");
+        require(msg.sender == owner, "You aren't the owner");
+
+        emit Withdrawal(address(this).balance, block.timestamp);
+
+        owner.transfer(address(this).balance);
+    }
+}

package/contracts/bytecode.txt

@@ -0,0 +1 @@
+608060405234801561000f575f5ffd5b5033604051806040016040528060128152602001712732b7ad34b8102334b6329027232a103b1960711b8152506040518060400160405280600481526020016304e5a49560e41b815250815f9081610067919061019c565b506001610074828261019c565b5050506001600160a01b0381166100a457604051631e4fbdf760e01b81525f600482015260240160405180910390fd5b6100ad816100b3565b50610256565b600780546001600160a01b038381166001600160a01b0319831681179093556040519116919082907f8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e0905f90a35050565b634e487b7160e01b5f52604160045260245ffd5b600181811c9082168061012c57607f821691505b60208210810361014a57634e487b7160e01b5f52602260045260245ffd5b50919050565b601f82111561019757805f5260205f20601f840160051c810160208510156101755750805b601f840160051c820191505b81811015610194575f8155600101610181565b50505b505050565b81516001600160401b038111156101b5576101b5610104565b6101c9816101c38454610118565b84610150565b6020601f8211600181146101fb575f83156101e45750848201515b5f19600385901b1c1916600184901b178455610194565b5f84815260208120601f198516915b8281101561022a578785015182556020948501946001909201910161020a565b508482101561024757868401515f19600387901b60f8161c191681555b50505050600190811b01905550565b612549806102635f395ff3fe608060405234801561000f575f5ffd5b50600436106101a0575f3560e01c806370d4d9fd116100f3578063a5e20a9c11610093578063ca3685d91161006e578063ca3685d9146103c4578063e985e9c5146103ea578063f2fde38b146103fd578063fe974bfe14610410575f5ffd5b8063a5e20a9c1461037f578063b88d4fde1461039e578063c87b56dd146103b1575f5ffd5b80638da5cb5b116100ce5780638da5cb5b1461033357806395d89b41146103445780639e8a1e7e1461034c578063a22cb4651461036c575f5ffd5b806370d4d9fd146102ee578063715018a6146103185780637f5950bd14610320575f5ffd5b806318160ddd1161015e5780635cefc90b116101395780635cefc90b1461028d5780635dce1ad8146102b55780636352211e146102c857806370a08231146102db575f5ffd5b806318160ddd1461025557806323b872dd1461026757806342842e0e1461027a575f5ffd5b8062ca4f78146101a457806301ffc9a7146101cc57806306fdde03146101df578063081812fc146101f4578063095ea7b31461021f5780630d8e6e2c14610234575b5f5ffd5b6101b76101b2366004611d5f565b610430565b60405190151581526020015b60405180910390f35b6101b76101da366004611db7565b6104d0565b6101e76104e0565b6040516101c39190611e00565b610207610202366004611e12565b61056f565b6040516001600160a01b0390911681526020016101c3565b61023261022d366004611e44565b610596565b005b6040805180820190915260058152640322e302e360dc1b60208201526101e7565b6008545b6040519081526020016101c3565b610232610275366004611e6c565b6105a5565b610232610288366004611e6c565b61062e565b6102a061029b366004611e12565b61064d565b604080519283526020830191909152016101c3565b6102596102c3366004611ea6565b610890565b6102076102d6366004611e12565b6108c2565b6102596102e9366004611ee7565b6108cc565b6103016102fc366004611ea6565b61093e565b6040805192151583526020830191909152016101c3565b610232610967565b61025961032e366004611f00565b61097a565b6007546001600160a01b0316610207565b6101e7610c5e565b61035f61035a366004611fbe565b610c6d565b6040516101c39190611fef565b61023261037a366004612031565b610e15565b61025961038d366004611e12565b600a6020525f908152604090205481565b6102326103ac36600461206a565b610e20565b6101e76103bf366004611e12565b610e38565b6103d76103d2366004611e12565b610e43565b6040516101c397969594939291906120e0565b6101b76103f8366004612148565b611019565b61023261040b366004611ee7565b611046565b61042361041e366004611e12565b611083565b6040516101c39190612179565b5f828152600260205260408120546001600160a01b031661046c5760405162461bcd60e51b81526004016104639061220d565b60405180910390fd5b8160405160200161047d9190612252565b60408051601f1981840301815282825280516020918201205f878152600983529290922091926104b1926001019101612295565b6040516020818303038152906040528051906020012014905092915050565b5f6104da826112fa565b92915050565b60605f80546104ee9061225d565b80601f016020809104026020016040519081016040528092919081815260200182805461051a9061225d565b80156105655780601f1061053c57610100808354040283529160200191610565565b820191905f5260205f20905b81548152906001019060200180831161054857829003601f168201915b5050505050905090565b5f6105798261131e565b505f828152600460205260409020546001600160a01b03166104da565b6105a1828233611356565b5050565b6001600160a01b0382166105ce57604051633250574960e11b81525f6004820152602401610463565b5f6105da838333611363565b9050836001600160a01b0316816001600160a01b031614610628576040516364283d7b60e01b81526001600160a01b0380861660048301526024820184905282166044820152606401610463565b50505050565b61064883838360405180602001604052805f815250610e20565b505050565b5f8181526002602052604081205481906001600160a01b03166106825760405162461bcd60e51b81526004016104639061220d565b5f83815260096020526040808220815160e081019092528054829082906106a89061225d565b80601f01602080910402602001604051908101604052809291908181526020018280546106d49061225d565b801561071f5780601f106106f65761010080835404028352916020019161071f565b820191905f5260205f20905b81548152906001019060200180831161070257829003601f168201915b505050505081526020016001820180546107389061225d565b80601f01602080910402602001604051908101604052809291908181526020018280546107649061225d565b80156107af5780601f10610786576101008083540402835291602001916107af565b820191905f5260205f20905b81548152906001019060200180831161079257829003601f168201915b505050505081526020016002820180546107c89061225d565b80601f01602080910402602001604051908101604052809291908181526020018280546107f49061225d565b801561083f5780601f106108165761010080835404028352916020019161083f565b820191905f5260205f20905b81548152906001019060200180831161082257829003601f168201915b505050918352505060038201546001600160a01b03166020820152600482015460408201526005820154606082015260069091015460809091015260c081015160a090910151909590945092505050565b5f82826040516020016108a4929190612306565b60405160208183030381529060405280519060200120905092915050565b5f6104da8261131e565b5f6001600160a01b0382166109355760405162461bcd60e51b815260206004820152602960248201527f4552433732313a2061646472657373207a65726f206973206e6f7420612076616044820152683634b21037bbb732b960b91b6064820152608401610463565b6104da82611455565b5f5f5f61094b8585610890565b5f908152600a6020526040902054801515969095509350505050565b61096f61149a565b6109785f6114c7565b565b5f5f8651116109cb5760405162461bcd60e51b815260206004820152601960248201527f46696c65206e616d652063616e6e6f7420626520656d707479000000000000006044820152606401610463565b5f855111610a1b5760405162461bcd60e51b815260206004820181905260248201527f4d65726b6c6520726f6f7420686173682063616e6e6f7420626520656d7074796044820152606401610463565b5f8411610a7c5760405162461bcd60e51b815260206004820152602960248201527f4372656174696f6e2074696d657374616d70206d75737420626520677265617460448201526806572207468616e20360bc1b6064820152608401610463565b5f610a878686610890565b5f818152600a602052604090205490915015610b0b5760405162461bcd60e51b815260206004820152603a60248201527f5a49502066696c652077697468207468697320636f6e74656e7420616e64207460448201527f696d657374616d7020616c726561647920746f6b656e697a65640000000000006064820152608401610463565b60088054905f610b1a8361231e565b9091555050600854610b2c3382611518565b835115610b3d57610b3d8185611531565b6040805160e08101825289815260208082018a9052818301889052336060830152608082018990524260a08301524360c08301525f84815260099091529190912081518190610b8c9082612386565b5060208201516001820190610ba19082612386565b5060408201516002820190610bb69082612386565b5060608201516003820180546001600160a01b0319166001600160a01b039092169190911790556080820151600482015560a0820151600582015560c0909101516006909101555f828152600a60205260409081902082905551339082907f0f09874b9c74d4595582d6c98e63000a1e9b6d57d383f3faa9b82ec744bc2db190610c4b908c908c908c908c9042904390612440565b60405180910390a3979650505050505050565b6060600180546104ee9061225d565b60605f6008546001600160401b03811115610c8a57610c8a611cb8565b604051908082528060200260200182016040528015610cb3578160200160208202803683370190505b5090505f60015b6008548111610d7d575f818152600260205260409020546001600160a01b031615610d6b5784604051602001610cf09190612252565b60408051601f1981840301815282825280516020918201205f85815260098352929092209192610d24926001019101612295565b6040516020818303038152906040528051906020012003610d6b5780838381518110610d5257610d52612494565b602090810291909101015281610d678161231e565b9250505b80610d758161231e565b915050610cba565b505f816001600160401b03811115610d9757610d97611cb8565b604051908082528060200260200182016040528015610dc0578160200160208202803683370190505b5090505f5b82811015610e0c57838181518110610ddf57610ddf612494565b6020026020010151828281518110610df957610df9612494565b6020908102919091010152600101610dc5565b50949350505050565b6105a1338383611580565b610e2b8484846105a5565b610628338585858561161e565b60606104da82611746565b60096020525f9081526040902080548190610e5d9061225d565b80601f0160208091040260200160405190810160405280929190818152602001828054610e899061225d565b8015610ed45780601f10610eab57610100808354040283529160200191610ed4565b820191905f5260205f20905b815481529060010190602001808311610eb757829003601f168201915b505050505090806001018054610ee99061225d565b80601f0160208091040260200160405190810160405280929190818152602001828054610f159061225d565b8015610f605780601f10610f3757610100808354040283529160200191610f60565b820191905f5260205f20905b815481529060010190602001808311610f4357829003601f168201915b505050505090806002018054610f759061225d565b80601f0160208091040260200160405190810160405280929190818152602001828054610fa19061225d565b8015610fec5780601f10610fc357610100808354040283529160200191610fec565b820191905f5260205f20905b815481529060010190602001808311610fcf57829003601f168201915b5050505060038301546004840154600585015460069095015493946001600160a01b039092169390925087565b6001600160a01b039182165f90815260056020908152604080832093909416825291909152205460ff1690565b61104e61149a565b6001600160a01b03811661107757604051631e4fbdf760e01b81525f6004820152602401610463565b611080816114c7565b50565b6110c86040518060e001604052806060815260200160608152602001606081526020015f6001600160a01b031681526020015f81526020015f81526020015f81525090565b5f828152600260205260409020546001600160a01b03166110fb5760405162461bcd60e51b81526004016104639061220d565b5f8281526009602052604090819020815160e081019092528054829082906111229061225d565b80601f016020809104026020016040519081016040528092919081815260200182805461114e9061225d565b80156111995780601f1061117057610100808354040283529160200191611199565b820191905f5260205f20905b81548152906001019060200180831161117c57829003601f168201915b505050505081526020016001820180546111b29061225d565b80601f01602080910402602001604051908101604052809291908181526020018280546111de9061225d565b80156112295780601f1061120057610100808354040283529160200191611229565b820191905f5260205f20905b81548152906001019060200180831161120c57829003601f168201915b505050505081526020016002820180546112429061225d565b80601f016020809104026020016040519081016040528092919081815260200182805461126e9061225d565b80156112b95780601f10611290576101008083540402835291602001916112b9565b820191905f5260205f20905b81548152906001019060200180831161129c57829003601f168201915b505050918352505060038201546001600160a01b03166020820152600482015460408201526005820154606082015260069091015460809091015292915050565b5f6001600160e01b03198216632483248360e11b14806104da57506104da82611851565b5f818152600260205260408120546001600160a01b0316806104da57604051637e27328960e01b815260048101849052602401610463565b61064883838360016118a0565b5f828152600260205260408120546001600160a01b039081169083161561138f5761138f8184866119a4565b6001600160a01b038116156113c9576113aa5f855f5f6118a0565b6001600160a01b0381165f90815260036020526040902080545f190190555b6001600160a01b038516156113f7576001600160a01b0385165f908152600360205260409020805460010190555b5f8481526002602052604080822080546001600160a01b0319166001600160a01b0389811691821790925591518793918516917fddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef91a4949350505050565b5f6001600160a01b03821661147f576040516322718ad960e21b81525f6004820152602401610463565b506001600160a01b03165f9081526003602052604090205490565b6007546001600160a01b031633146109785760405163118cdaa760e01b8152336004820152602401610463565b600780546001600160a01b038381166001600160a01b0319831681179093556040519116919082907f8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e0905f90a35050565b6105a1828260405180602001604052805f815250611a08565b5f8281526006602052604090206115488282612386565b506040518281527ff8e1a15aba9398e019f0b49df1a4fde98ee17ae345cb5f6b5e2c27f5033e8ce79060200160405180910390a15050565b6001600160a01b0382166115b257604051630b61174360e31b81526001600160a01b0383166004820152602401610463565b6001600160a01b038381165f81815260056020908152604080832094871680845294825291829020805460ff191686151590811790915591519182527f17307eab39ab6107e8899845ad3d59bd9653f200f220920489ca2b5937696c31910160405180910390a3505050565b6001600160a01b0383163b1561173f57604051630a85bd0160e11b81526001600160a01b0384169063150b7a02906116609088908890879087906004016124a8565b6020604051808303815f875af192505050801561169a575060408051601f3d908101601f19168201909252611697918101906124e4565b60015b611701573d8080156116c7576040519150601f19603f3d011682016040523d82523d5f602084013e6116cc565b606091505b5080515f036116f957604051633250574960e11b81526001600160a01b0385166004820152602401610463565b805160208201fd5b6001600160e01b03198116630a85bd0160e11b1461173d57604051633250574960e11b81526001600160a01b0385166004820152602401610463565b505b5050505050565b60606117518261131e565b505f828152600660205260408120805461176a9061225d565b80601f01602080910402602001604051908101604052809291908181526020018280546117969061225d565b80156117e15780601f106117b8576101008083540402835291602001916117e1565b820191905f5260205f20905b8154815290600101906020018083116117c457829003601f168201915b505050505090505f6117fd60408051602081019091525f815290565b905080515f0361180e575092915050565b8151156118405780826040516020016118289291906124ff565b60405160208183030381529060405292505050919050565b61184984611a1f565b949350505050565b5f6001600160e01b031982166380ac58cd60e01b148061188157506001600160e01b03198216635b5e139f60e01b145b806104da57506301ffc9a760e01b6001600160e01b03198316146104da565b80806118b457506001600160a01b03821615155b15611975575f6118c38461131e565b90506001600160a01b038316158015906118ef5750826001600160a01b0316816001600160a01b031614155b801561190257506119008184611019565b155b1561192b5760405163a9fbf51f60e01b81526001600160a01b0384166004820152602401610463565b81156119735783856001600160a01b0316826001600160a01b03167f8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b92560405160405180910390a45b505b50505f90815260046020526040902080546001600160a01b0319166001600160a01b0392909216919091179055565b6119af838383611a90565b610648576001600160a01b0383166119dd57604051637e27328960e01b815260048101829052602401610463565b60405163177e802f60e01b81526001600160a01b038316600482015260248101829052604401610463565b611a128383611af1565b610648335f85858561161e565b6060611a2a8261131e565b505f611a4060408051602081019091525f815290565b90505f815111611a5e5760405180602001604052805f815250611a89565b80611a6884611b52565b604051602001611a799291906124ff565b6040516020818303038152906040525b9392505050565b5f6001600160a01b038316158015906118495750826001600160a01b0316846001600160a01b03161480611ac95750611ac98484611019565b806118495750505f908152600460205260409020546001600160a01b03908116911614919050565b6001600160a01b038216611b1a57604051633250574960e11b81525f6004820152602401610463565b5f611b2683835f611363565b90506001600160a01b03811615610648576040516339e3563760e11b81525f6004820152602401610463565b60605f611b5e83611be1565b60010190505f816001600160401b03811115611b7c57611b7c611cb8565b6040519080825280601f01601f191660200182016040528015611ba6576020820181803683370190505b5090508181016020015b5f19016f181899199a1a9b1b9c1cb0b131b232b360811b600a86061a8153600a8504945084611bb057509392505050565b5f8072184f03e93ff9f4daa797ed6e38ed64bf6a1f0160401b8310611c1f5772184f03e93ff9f4daa797ed6e38ed64bf6a1f0160401b830492506040015b6d04ee2d6d415b85acef81000000008310611c4b576d04ee2d6d415b85acef8100000000830492506020015b662386f26fc100008310611c6957662386f26fc10000830492506010015b6305f5e1008310611c81576305f5e100830492506008015b6127108310611c9557612710830492506004015b60648310611ca7576064830492506002015b600a83106104da5760010192915050565b634e487b7160e01b5f52604160045260245ffd5b5f5f6001600160401b03841115611ce557611ce5611cb8565b50604051601f19601f85018116603f011681018181106001600160401b0382111715611d1357611d13611cb8565b604052838152905080828401851015611d2a575f5ffd5b838360208301375f60208583010152509392505050565b5f82601f830112611d50575f5ffd5b611a8983833560208501611ccc565b5f5f60408385031215611d70575f5ffd5b8235915060208301356001600160401b03811115611d8c575f5ffd5b611d9885828601611d41565b9150509250929050565b6001600160e01b031981168114611080575f5ffd5b5f60208284031215611dc7575f5ffd5b8135611a8981611da2565b5f81518084528060208401602086015e5f602082860101526020601f19601f83011685010191505092915050565b602081525f611a896020830184611dd2565b5f60208284031215611e22575f5ffd5b5035919050565b80356001600160a01b0381168114611e3f575f5ffd5b919050565b5f5f60408385031215611e55575f5ffd5b611e5e83611e29565b946020939093013593505050565b5f5f5f60608486031215611e7e575f5ffd5b611e8784611e29565b9250611e9560208501611e29565b929592945050506040919091013590565b5f5f60408385031215611eb7575f5ffd5b82356001600160401b03811115611ecc575f5ffd5b611ed885828601611d41565b95602094909401359450505050565b5f60208284031215611ef7575f5ffd5b611a8982611e29565b5f5f5f5f5f60a08688031215611f14575f5ffd5b85356001600160401b03811115611f29575f5ffd5b611f3588828901611d41565b95505060208601356001600160401b03811115611f50575f5ffd5b611f5c88828901611d41565b9450506040860135925060608601356001600160401b03811115611f7e575f5ffd5b611f8a88828901611d41565b92505060808601356001600160401b03811115611fa5575f5ffd5b611fb188828901611d41565b9150509295509295909350565b5f60208284031215611fce575f5ffd5b81356001600160401b03811115611fe3575f5ffd5b61184984828501611d41565b602080825282518282018190525f918401906040840190835b81811015612026578351835260209384019390920191600101612008565b509095945050505050565b5f5f60408385031215612042575f5ffd5b61204b83611e29565b91506020830135801515811461205f575f5ffd5b809150509250929050565b5f5f5f5f6080858703121561207d575f5ffd5b61208685611e29565b935061209460208601611e29565b92506040850135915060608501356001600160401b038111156120b5575f5ffd5b8501601f810187136120c5575f5ffd5b6120d487823560208401611ccc565b91505092959194509250565b60e081525f6120f260e083018a611dd2565b8281036020840152612104818a611dd2565b905082810360408401526121188189611dd2565b6001600160a01b039790971660608401525050608081019390935260a083019190915260c0909101529392505050565b5f5f60408385031215612159575f5ffd5b61216283611e29565b915061217060208401611e29565b90509250929050565b602081525f825160e06020840152612195610100840182611dd2565b90506020840151601f198483030160408501526121b28282611dd2565b9150506040840151601f198483030160608501526121d08282611dd2565b91505060018060a01b036060850151166080840152608084015160a084015260a084015160c084015260c084015160e08401528091505092915050565b602080825260149082015273151bdad95b88191bd95cc81b9bdd08195e1a5cdd60621b604082015260600190565b5f81518060208401855e5f93019283525090919050565b5f611a89828461223b565b600181811c9082168061227157607f821691505b60208210810361228f57634e487b7160e01b5f52602260045260245ffd5b50919050565b5f5f83546122a28161225d565b6001821680156122b957600181146122ce576122fb565b60ff19831686528115158202860193506122fb565b865f5260205f205f5b838110156122f3578154888201526001909101906020016122d7565b505081860193505b509195945050505050565b5f612311828561223b565b9283525050602001919050565b5f6001820161233b57634e487b7160e01b5f52601160045260245ffd5b5060010190565b601f82111561064857805f5260205f20601f840160051c810160208510156123675750805b601f840160051c820191505b8181101561173f575f8155600101612373565b81516001600160401b0381111561239f5761239f611cb8565b6123b3816123ad845461225d565b84612342565b6020601f8211600181146123e5575f83156123ce5750848201515b5f19600385901b1c1916600184901b17845561173f565b5f84815260208120601f198516915b8281101561241457878501518255602094850194600190920191016123f4565b508482101561243157868401515f19600387901b60f8161c191681555b50505050600190811b01905550565b60c081525f61245260c0830189611dd2565b82810360208401526124648189611dd2565b9050866040840152828103606084015261247e8187611dd2565b6080840195909552505060a00152949350505050565b634e487b7160e01b5f52603260045260245ffd5b6001600160a01b03858116825284166020820152604081018390526080606082018190525f906124da90830184611dd2565b9695505050505050565b5f602082840312156124f4575f5ffd5b8151611a8981611da2565b5f61184961250d838661223b565b8461223b56fea2646970667358221220ec5692f96d1d270dc9c2c061988393c84d97f92e3bcc623597bccbb57a29d12d64736f6c634300081e0033

package/contracts/compile-contract.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+/**
+ * Contract Compilation Helper for NZIP
+ * 
+ * This script helps compile the NZIP-NFT.sol contract
+ * Usage: node compile-contract.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const readline = require('readline');
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+console.log('🔧 NZIP Contract Compilation Helper');
+console.log('===================================\n');
+
+const contractPath = path.join(__dirname, 'src/NZIP-NFT.sol');
+const deployPath = path.join(__dirname, 'deploy/deploy-public-contract.js');
+
+if (!fs.existsSync(contractPath)) {
+  console.log('❌ Contract file not found:', contractPath);
+  process.exit(1);
+}
+
+console.log('📋 Choose your compilation method:\n');
+console.log('1️⃣  Remix IDE (Online) - RECOMMENDED');
+console.log('2️⃣  Remix IDE (Step-by-Step Guide) - NEW!');
+console.log('3️⃣  Local Hardhat (Advanced)');
+console.log('4️⃣  View Deprecated Contract Info');
+console.log('5️⃣  View Contract Source Code');
+console.log('6️⃣  Exit\n');
+
+rl.question('Enter your choice (1-6): ', (choice) => {
+  console.log('');
+  
+  switch(choice.trim()) {
+    case '1':
+      showRemixInstructions();
+      break;
+    case '2':
+      showRemixGuide();
+      break;
+    case '3':
+      showHardhatInstructions();
+      break;
+    case '4':
+      showDeprecatedInfo();
+      break;
+    case '5':
+      showContractSource();
+      break;
+    case '6':
+      console.log('👋 Goodbye!');
+      rl.close();
+      return;
+    default:
+      console.log('❌ Invalid choice. Please run the script again and choose 1-6.');
+      rl.close();
+      return;
+  }
+  
+  rl.close();
+});
+
+function showRemixInstructions() {
+  console.log('🌐 Remix IDE Compilation (RECOMMENDED)');
+  console.log('======================================\n');
+  console.log('📋 Steps:');
+  console.log('1. Go to https://remix.ethereum.org');
+  console.log('2. Create new file: NZIP-NFT.sol');
+  console.log('3. Copy contract content (run with option 5 to see source)');
+  console.log('4. Install OpenZeppelin dependencies');
+  console.log('5. Compile with Solidity 0.8.19+');
+  console.log('6. Copy bytecode and ABI from compilation artifacts');
+  console.log('7. Update deployment script with compiled data\n');
+  
+  console.log('🎯 After compilation:');
+  console.log('• Update CONTRACT_BYTECODE in deploy-public-contract.js');
+  console.log('• Update CONTRACT_ABI in deploy-public-contract.js');
+  console.log('• Run: npm run deploy:public');
+}
+
+function showRemixGuide() {
+  console.log('📋 Remix IDE Step-by-Step Guide');
+  console.log('===============================\n');
+  console.log('For a detailed, interactive walkthrough of the entire Remix compilation process:');
+  console.log('');
+  console.log('🎯 Run this command:');
+  console.log('npm run remix-compile\n');
+  
+  console.log('✨ This dedicated guide will:');
+  console.log('• Walk you through each step interactively');
+  console.log('• Show you exactly what to do in Remix');
+  console.log('• Display the contract source when needed');
+  console.log('• Guide you through extracting bytecode and ABI');
+  console.log('• Help you update the deployment script');
+  console.log('• Prepare you for deployment\n');
+  
+  console.log('💡 Perfect for first-time users or when you need detailed guidance!');
+}
+
+function showHardhatInstructions() {
+  console.log('💻 Local Hardhat Compilation (Advanced)');
+  console.log('=======================================\n');
+  console.log('📋 Setup Steps:');
+  console.log('1. npm install --save-dev hardhat @nomiclabs/hardhat-ethers ethers @openzeppelin/contracts');
+  console.log('2. npx hardhat init');
+  console.log('3. Copy contract to contracts/ folder');
+  console.log('4. npx hardhat compile');
+  console.log('5. Extract bytecode and ABI from artifacts/\n');
+  
+  console.log('📁 Artifact Location:');
+  console.log('• Bytecode: artifacts/contracts/NZIP-NFT.sol/ZipFileNFT.json');
+  console.log('• Look for "bytecode" and "abi" fields in the JSON file\n');
+  
+  console.log('🎯 After compilation:');
+  console.log('• Update CONTRACT_BYTECODE in deploy-public-contract.js');
+  console.log('• Update CONTRACT_ABI in deploy-public-contract.js');
+  console.log('• Run: npm run deploy:public');
+}
+
+function showDeprecatedInfo() {
+  console.log('⚠️  Deprecated Contract Notice');
+  console.log('=============================\n');
+  console.log('Previous contract is now DEPRECATED:');
+  console.log('Address: 0xb78CB3bcC788fca38c731b1E9D70CF60b04CA015');
+  console.log('Network: Base Sepolia');
+  console.log('Status: ❌ DEPRECATED - Do not use\n');
+  
+  console.log('🚨 Why it\'s deprecated:');
+  console.log('• Had broken block hash storage (always returned 0)');
+  console.log('• Missing input validation');
+  console.log('• Lacked proper version tracking\n');
+  
+  console.log('✅ New contract fixes:');
+  console.log('• Removed unreliable block hash storage');
+  console.log('• Added comprehensive input validation');
+  console.log('• Version 2.0 with proper documentation');
+  console.log('• Improved error handling\n');
+  
+  console.log('📋 Action Required:');
+  console.log('You MUST compile and deploy a new contract!');
+}
+
+function showContractSource() {
+  console.log('📄 NZIP NFT Contract v2.0 Source Code');
+  console.log('=====================================\n');
+  console.log('Copy this code to your compilation environment:\n');
+  
+  try {
+    const contractContent = fs.readFileSync(contractPath, 'utf8');
+    console.log(contractContent);
+  } catch (err) {
+    console.log('❌ Error reading contract:', err.message);
+  }
+  
+  console.log('\n🎯 Next Steps:');
+  console.log('1. Copy the contract code above');
+  console.log('2. Use Remix IDE or Hardhat to compile');
+  console.log('3. Update deployment script with compiled bytecode/ABI');
+  console.log('4. Deploy with: npm run deploy:public');
+}