OnceQR

README.md

@@ -1,44 +1,255 @@
-# Monad Blitz Thailand submission process
+# OnceQR - Smart Contract Infrastructure
 
-**How to Submit Your Project**
+A comprehensive smart contract system for QR code-based NFT distribution with batch management, Merkle tree validation, and gas-efficient deployment using EIP-1167 minimal proxies.
 
-1. Visit the [monad-blitz-bangkok repo](https://github.com/monad-developers/monad-blitz-bangkok) and **fork** it.
+## 🌟 Overview
 
-![fork repo](https://raw.githubusercontent.com/addicola/monad-blitz-bangkok/refs/heads/main/images/fork-repository.png)
+OnceQR is a decentralized platform that enables businesses and creators to distribute NFTs through QR codes. The system supports batch creation, validation through Merkle proofs, and provides robust access controls for managing NFT campaigns.
 
-2. Enter your **project name** and a **one-line description**.
-   - Make sure you are forking the **main** branch.
-   - Then click **Create Fork**.
+### Key Features
 
-![fork detail](https://raw.githubusercontent.com/addicola/monad-blitz-bangkok/refs/heads/main/images/fork-detail.png)
+- **QR Code-Based NFT Distribution**: Mint NFTs by scanning QR codes
+- **Batch Management**: Organize NFT distributions into batches with Merkle tree validation
+- **Gas Efficient**: Uses EIP-1167 minimal proxies for ~90% gas savings on NFT contract deployments
+- **Multi-Token Support**: ERC721 and ERC1155 (Art & Stamp variants)
+- **Comprehensive Access Controls**: Multi-level pause and ban system
+- **Royalty Support**: Built-in ERC2981 royalty standard implementation
 
-3. In your fork, you can:
-   - Add your project code
-   - Create new branches
-   - Update the README with project info
-   - Make any other changes you need
+## 📁 Project Structure
 
-![example project](https://raw.githubusercontent.com/addicola/monad-blitz-bangkok/refs/heads/main/images/example-project.png)
+```
+contracts/
+├── BatchManager.sol          # Core batch and claiming logic
+├── BatchFactory.sol          # Factory for creating batches and NFT contracts
+├── Once721TemplateV2.sol     # ERC721 template for minimal proxy cloning
+├── Once1155TemplateV2.sol    # ERC1155 template for minimal proxy cloning
+└── OnceToken.sol            # ERC20 token for batch creation fees
 
-4. Once your project is ready for submission, open a **Pull Request (PR)**.
+scripts/
+├── full_deploy.js           # Complete deployment script
+├── continue_deploy.js       # Continue partial deployment
+└── verify_contracts.js     # Contract verification
 
-![pull requests](https://raw.githubusercontent.com/addicola/monad-blitz-bangkok/refs/heads/main/images/pull-requests.png)
+test/
+├── BatchManager.test.js     # Core functionality tests
+├── BatchFactory.test.js     # Factory contract tests
+├── Once721TemplateV2.test.js
+├── Once1155TemplateV2.test.js
+└── Legacies/               # Legacy V1 contract tests
 
-5. Ensure your PR is targeting the correct repo:
-   - **Base repo:** `monad-developers/monad-blitz-bangkok`
-   - Then click **Create Pull Request**.
+verify-args/                # Contract verification arguments
+```
 
-![create pull-request](https://raw.githubusercontent.com/addicola/monad-blitz-bangkok/refs/heads/main/images/crate-pull-request.png)
+## 🏗️ Architecture
 
-6. Add details to your PR:
-   - Use your **project name** as the PR title
-   - Write a **detailed description** of your project (include as much info as possible; you can also link to a demo video)
-   - Click **Create Pull Request**
+### Core Contracts
 
-![pull request detail](https://raw.githubusercontent.com/addicola/monad-blitz-bangkok/refs/heads/main/images/pull-request-detail.png)
+#### BatchManager
+The heart of the system that manages:
+- Batch creation and lifecycle
+- QR code claiming with Merkle proof validation
+- Access controls (System Admin, Batch Owner, Batch Admin)
+- Pause/ban mechanisms for security
 
-7. Finally, verify your PR:
-   - Double-check that it was created on the correct repo
-   - Make sure the **source** and **destination branches** are set properly
+#### BatchFactory
+Factory contract responsible for:
+- Creating new batches
+- Deploying NFT contracts using EIP-1167 minimal proxies
+- Managing template contracts and configurations
+- Gas-efficient contract creation with CREATE2
 
-![pull request review](https://raw.githubusercontent.com/addicola/monad-blitz-bangkok/refs/heads/main/images/pull-request-review.png)
+#### Template Contracts
+- **Once721TemplateV2**: ERC721 implementation with initializer pattern
+- **Once1155TemplateV2**: ERC1155 implementation with initializer pattern
+- Support pause/unpause, royalties (ERC2981), and role-based access
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- Node.js >= 16.0.0
+- npm or yarn
+- Hardhat
+
+### Installation
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd hardhat
+
+# Install dependencies
+npm install
+
+# Compile contracts
+npx hardhat compile
+```
+
+### Network Configuration
+
+The project is configured for Monad Testnet (Chain ID: 10143). Update `hardhat.config.js` for other networks.
+
+## 📋 Deployment
+
+### Full Deployment
+
+Deploy all contracts in the correct order:
+
+```bash
+npx hardhat run scripts/full_deploy.js --network monadTestnet
+```
+
+This will deploy:
+1. OnceToken (ERC20 for fees)
+2. BatchManager
+3. Template contracts (Once721TemplateV2, Once1155TemplateV2)
+4. BatchFactory
+
+### Contract Verification
+
+```bash
+npx hardhat run scripts/verify_contracts.js --network monadTestnet
+```
+
+## 🎯 Usage Examples
+
+### For Issuers (Creating Campaigns)
+
+```javascript
+// 1. Create batch parameters
+const params = {
+    nftType: 0, // ERC721
+    name: "My NFT Collection",
+    symbol: "MNC",
+    merkleRoot: "0x...", // Generated from QR codes
+    totalCodes: 1000,
+    expireTime: Math.floor(Date.now() / 1000) + (30 * 24 * 60 * 60), // 30 days
+    existingNFTContract: "0x0000000000000000000000000000000000000000", // Create new
+    royaltyRecipient: "0x...", // Royalty recipient address
+    royaltyFeeNumerator: 500, // 5% royalty
+    baseURI: "https://api.example.com/metadata/"
+};
+
+// 2. Create batch through BatchFactory
+const tx = await batchFactory.createBatch(params);
+const receipt = await tx.wait();
+
+// 3. Get batch ID and NFT contract address from events
+const event = receipt.events.find(e => e.event === 'BatchCreated');
+const { batchId, nftContract } = event.args;
+```
+
+### For End Users (Claiming NFTs)
+
+```javascript
+// 1. Scan QR code to get codeId
+const codeId = "ABC123DEF456"; // From QR code
+
+// 2. Get Merkle proof from backend
+const proof = await getProofFromBackend(codeId, batchId);
+
+// 3. Claim NFT
+const tx = await batchManager.claimCode(batchId, codeId, proof);
+await tx.wait();
+
+// NFT is now minted to user's wallet
+```
+
+### Administrative Functions
+
+```javascript
+// Pause a batch (Batch Admin or System Admin)
+await batchManager.pauseBatch(batchId, true);
+
+// Ban a user from a batch
+await batchManager.pauseWalletForBatch(batchId, userAddress, true);
+
+// Set new expiration time
+await batchManager.setBatchExpireTime(batchId, newExpireTime);
+```
+
+## 🔒 Security Features
+
+### Access Control Levels
+
+1. **System Admin**: Full system control, can pause everything
+2. **Batch Owner**: Controls their own batches
+3. **Batch Admin**: Delegated admin rights for specific batches
+
+### Pause Mechanisms
+
+- **Global Pause**: Stop entire system (System Admin only)
+- **Issuer Pause**: Disable all batches from specific issuer
+- **Batch Pause**: Disable specific batch
+- **Wallet Pause**: Ban specific wallet (global or per-batch)
+- **Code Pause**: Disable specific QR codes
+
+### Validation
+
+- Merkle proof validation for QR codes
+- Double-claiming prevention
+- Expiration time enforcement
+- Reentrancy protection
+
+## ⚡ Gas Optimization
+
+The system uses EIP-1167 minimal proxies for significant gas savings:
+
+| Operation | Traditional Deployment | Minimal Proxy |
+|-----------|----------------------|---------------|
+| Template Deploy | N/A | ~2M gas (one-time) |
+| NFT Contract | ~2M gas each | ~200K gas each |
+| **Savings** | - | **~90% gas reduction** |
+
+## 🧪 Testing
+
+Run the complete test suite:
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test file
+npx hardhat test test/BatchManager.test.js
+
+# Run tests with coverage
+npx hardhat coverage
+```
+
+Test coverage includes:
+- ✅ Batch creation and management
+- ✅ QR code claiming with Merkle proofs
+- ✅ Access control and pause mechanisms
+- ✅ NFT minting (ERC721 & ERC1155)
+- ✅ Gas optimization validation
+- ✅ Edge cases and security scenarios
+
+## 📊 Contract Addresses (Monad Testnet)
+
+```json
+{
+  "network": "monadTestnet (Chain ID: 10143)",
+  "contracts": {
+    "onceToken": "0x53Af2E544dc9b40c5f3a0D43A667EFFf943f2535",
+    "batchManager": "0x62C3ae5cF6F89FA1D2BB41b6a28cE2F15deF087D",
+    "once721Template": "0xA0b5571e8bfe8C03942e8bb2A50A41F7D8c9C850",
+    "once1155Template": "0xBbabd9568326cD5AF963F4682Ea6c9F1467EE581",
+    "batchFactory": "0x8B3247b9Aa9D7fd3c796F2d518F1C228A820CCb0"
+  }
+}
+```
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🆘 Support
+
+For technical support or questions:
+- Create an issue in this repository
+- Check existing documentation in `/contracts/README.md`
+- Review test files for usage examples
+
+## ⚠️ Disclaimer
+
+This smart contract system is provided as-is. Please conduct thorough testing and auditing before using in production environments. The developers are not responsible for any loss of funds or other damages.

projects/hardhat/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 meawpipat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.