@paulstinchcombe/gasless-nft-tx 0.4.3 → 0.4.5

package/README.md

@@ -20,6 +20,20 @@ A robust, production-ready TypeScript library that enables **gasless NFT transac
 -   **🛡️ Robust Error Handling**: Automatic retry and recovery mechanisms
 -   **🔮 Deterministic Addresses**: Predictable SimpleAccount addresses using CREATE2
 
+## ⚠️ Important: Update to v0.4.4+
+
+If you're deploying KAMI libraries and got "Contract artifact not found" errors, update immediately:
+
+```bash
+npm install @paulstinchcombe/gasless-nft-tx@^0.4.4
+```
+
+**Fixed:** KAMI artifacts now properly included in npm package. See [Migration Guide](./docs/MIGRATION_v0.4.4.md).
+
+### Next.js Users: Additional Step Required
+
+If using Next.js and still getting artifact errors after updating, see **[Next.js Artifacts Fix](./docs/NEXTJS_ARTIFACTS_FIX.md)** - you need to configure Next.js to copy artifacts to the build output.
+
 ## 🎊 What's New in v0.4.0 - Per-Token Pricing & Enhanced APIs!
 
 ### 🔥 Major API Improvements
@@ -342,6 +356,7 @@ pnpm run dev
 ### KAMI NFT Documentation
 
 -   🔴 **[API Migration Guide v0.4.0](./docs/KAMI_API_CHANGES_v0.4.0.md)** - **BREAKING CHANGES: Required for v0.3.x users!**
+-   ⚠️ **[Next.js Artifacts Fix](./docs/NEXTJS_ARTIFACTS_FIX.md)** - **REQUIRED for Next.js users!**
 -   🆕 **[Enhanced Mint Results Guide](./docs/MINT_RESULTS_GUIDE.md)** - **NEW: Get tokenId from mint operations!**
 -   🆕 **[Royalty System Guide](./docs/KAMI_ROYALTY_GUIDE.md)** - **NEW: Dual royalty system (mint vs transfer)**
 -   🎯 **[Custodial Zero-Gas](./docs/KAMI_CUSTODIAL_ZERO_GAS.md)** - **BEST: ZERO user gas for custodial wallets!**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@paulstinchcombe/gasless-nft-tx",
-	"version": "0.4.3",
+	"version": "0.4.5",
 	"description": "Library for gasless NFT transactions using SimpleAccount operations",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -36,6 +36,7 @@
 	},
 	"files": [
 		"dist/**/*",
+		"src/KAMI-NFTs/artifacts/**/*",
 		"README.md"
 	],
 	"engines": {

package/src/KAMI-NFTs/README.md

@@ -0,0 +1,361 @@
+# KAMI NFT Contracts
+
+This folder contains the Solidity contracts for the KAMI NFT system, along with their compiled artifacts.
+
+## Contracts
+
+### Main Contracts
+
+#### KAMI721C.sol
+
+Standard ERC721 contract with advanced features:
+
+-   Traditional one-at-a-time minting
+-   ERC20 payment token integration
+-   Platform commission system
+-   Programmable royalties (mint & transfer)
+-   Time-based rental system
+-   Transfer validation
+-   Pausable functionality
+-   Role-based access control
+
+**Standard**: ERC721, ERC721Enumerable, ERC2981, AccessControl, Pausable
+
+#### KAMI721AC.sol
+
+ERC721A-style contract with claiming features:
+
+-   One claim per address restriction
+-   Batch claiming (owner pays for all)
+-   Batch claiming (each recipient pays)
+-   All KAMI721C features included
+-   Optimized for airdrops and allowlists
+
+**Standard**: ERC721, ERC721Enumerable, ERC2981, AccessControl, Pausable
+
+#### KAMI1155C.sol
+
+Multi-token ERC1155 contract:
+
+-   Multiple token types in one contract
+-   Fungible and non-fungible tokens
+-   Batch minting and burning
+-   Per-token-type tracking
+-   All rental and royalty features
+-   Ideal for gaming and utility tokens
+
+**Standard**: ERC1155, ERC1155Supply, ERC2981, AccessControl, Pausable
+
+### Shared Libraries
+
+All three main contracts use these libraries to reduce code duplication and gas costs:
+
+#### libraries/KamiNFTCore.sol
+
+Core library providing:
+
+-   Data structure definitions (RoyaltyData, Rental, PlatformConfig, etc.)
+-   Storage slot management for proxy compatibility
+-   Role constants (OWNER_ROLE, PLATFORM_ROLE, RENTER_ROLE)
+-   Storage access functions
+-   Basic validation helpers
+
+#### libraries/KamiPlatform.sol
+
+Platform commission management:
+
+-   Initialize platform configuration
+-   Update commission percentage and address
+-   Distribute platform commission
+-   Validation (max 20% commission)
+
+#### libraries/KamiRoyalty.sol
+
+Royalty system management:
+
+-   Initialize royalty configuration
+-   Set global royalty percentage
+-   Set mint and transfer royalties
+-   Set token-specific royalties
+-   Distribute royalties automatically
+-   Get royalty receivers
+
+#### libraries/KamiRental.sol
+
+Token rental system:
+
+-   Rent tokens for specific durations
+-   End rentals early
+-   Extend rental periods
+-   Track rental status
+-   Validate rental operations
+-   Platform commission on rentals
+
+#### libraries/KamiTransfer.sol
+
+Transfer validation and sales:
+
+-   Validate transfers (rental protection)
+-   Process token sales
+-   Calculate transfer payments
+-   Distribute royalties on sales
+-   Track pending transfers
+-   Burn validation
+
+## Key Features
+
+### 🎨 Flexible Minting
+
+-   **KAMI721C**: Traditional minting
+-   **KAMI721AC**: Claiming mechanism
+-   **KAMI1155C**: Batch multi-token minting
+
+### 💰 Payment Integration
+
+-   All contracts accept ERC20 payment tokens (e.g., USDC)
+-   Configurable mint/claim prices
+-   Automatic payment distribution
+
+### 🏢 Platform Commission
+
+-   Configurable commission percentage (max 20%)
+-   Automatic commission on all paid operations
+-   Platform address can be updated
+
+### 👑 Programmable Royalties
+
+-   Global royalty percentage
+-   Mint royalties (distributed on minting)
+-   Transfer royalties (distributed on sales)
+-   Token-specific royalty overrides
+-   Multiple royalty receivers per token
+-   Automatic distribution
+
+### 🏠 Rental System
+
+-   Time-based token rentals
+-   Rental price configuration
+-   Extend rentals
+-   End rentals early
+-   Automatic role management (RENTER_ROLE)
+-   Transfer protection for rented tokens
+
+### 🛡️ Access Control
+
+-   **OWNER_ROLE**: Manage contract settings
+-   **PLATFORM_ROLE**: Receive commission payments
+-   **RENTER_ROLE**: Assigned to active renters
+
+### 🔐 Security Features
+
+-   Pausable in emergencies
+-   Transfer validation
+-   Rental protection (tokens can't be transferred while rented)
+-   Royalty enforcement
+-   Role-based permissions
+
+## Contract Interactions
+
+```
+User → KAMI721C/KAMI721AC/KAMI1155C
+              ↓
+         Libraries:
+         - KamiNFTCore (storage)
+         - KamiPlatform (commission)
+         - KamiRoyalty (royalties)
+         - KamiRental (rentals)
+         - KamiTransfer (sales)
+              ↓
+         Payment Token (USDC)
+              ↓
+    Distribution:
+    - Platform (commission)
+    - Royalty Receivers
+    - Token Owner
+```
+
+## Constructor Parameters
+
+### KAMI721C & KAMI721AC
+
+```solidity
+constructor(
+    address paymentToken_,           // ERC20 payment token
+    string memory name_,             // NFT collection name
+    string memory symbol_,           // NFT collection symbol
+    string memory baseTokenURI_,     // Base URI for metadata
+    uint256 initialMintPrice_,       // Initial mint/claim price
+    address platformAddress_,        // Platform commission receiver
+    uint96 platformCommissionPercentage_ // Commission % in basis points
+)
+```
+
+### KAMI1155C
+
+```solidity
+constructor(
+    address paymentToken_,           // ERC20 payment token
+    string memory baseTokenURI_,     // Base URI for metadata
+    uint256 initialMintPrice_,       // Initial mint price
+    address platformAddress_,        // Platform commission receiver
+    uint96 platformCommissionPercentage_ // Commission % in basis points
+)
+```
+
+## Royalty Configuration
+
+Royalties use basis points (1/100th of a percent):
+
+-   100 = 1%
+-   1000 = 10%
+-   10000 = 100%
+
+When setting royalty receivers, the feeNumerator values must sum to exactly 10000:
+
+```solidity
+RoyaltyData[] memory royalties = [
+    RoyaltyData({ receiver: address1, feeNumerator: 5000 }), // 50%
+    RoyaltyData({ receiver: address2, feeNumerator: 3000 }), // 30%
+    RoyaltyData({ receiver: address3, feeNumerator: 2000 })  // 20%
+];
+// Total: 10000 (100%) ✓
+```
+
+## Platform Commission Limits
+
+-   Minimum: 0 basis points (0%)
+-   Maximum: 2000 basis points (20%)
+-   Applied to: mints, claims, rentals, and sales
+
+## Rental Flow
+
+1. User calls `rentToken(tokenId, duration, rentalPrice)`
+2. Contract transfers payment from user to:
+    - Platform (commission)
+    - Token owner (remainder)
+3. Rental is created with start and end times
+4. User is granted RENTER_ROLE
+5. Token cannot be transferred while rented
+6. Rental can be extended or ended early
+7. RENTER_ROLE revoked when no active rentals
+
+## Sales Flow
+
+1. User calls `sellToken(to, tokenId, salePrice)`
+2. Token is transferred to buyer
+3. Contract processes payment:
+    - Platform commission
+    - Transfer royalties
+    - Seller receives remainder
+4. All payments handled automatically
+
+## Library Benefits
+
+Using shared libraries provides:
+
+-   **Reduced Gas**: No duplicate code in each contract
+-   **Consistency**: Same logic across all contracts
+-   **Maintainability**: Update logic in one place
+-   **Reusability**: Deploy once, use in many contracts
+
+## Deployment
+
+Libraries must be deployed before main contracts and linked during deployment. The TypeScript library handles this automatically.
+
+### Using TypeScript Library
+
+```typescript
+import { deployKAMI721C } from '../index';
+
+// Automatically handles library deployment and linking
+const deployment = await deployKAMI721C(signer, params);
+```
+
+### Manual Deployment (Advanced)
+
+1. Deploy all 5 libraries
+2. Link libraries in main contract bytecode
+3. Deploy main contract with linked bytecode
+
+## Artifacts
+
+The `artifacts/` folder contains compiled contract artifacts:
+
+-   ABI (Application Binary Interface)
+-   Bytecode
+-   Debug information
+-   Metadata
+
+These are generated by Hardhat/Foundry during compilation.
+
+## Dependencies
+
+### OpenZeppelin Contracts
+
+-   ERC721, ERC721Enumerable
+-   ERC1155, ERC1155Supply
+-   ERC2981 (Royalty Standard)
+-   ERC20, SafeERC20
+-   AccessControl
+-   Pausable
+-   Counters
+
+### Solidity Version
+
+-   `^0.8.24` (KAMI721C, KAMI721AC, KAMI1155C)
+-   `^0.8.20` (Libraries)
+
+## Testing
+
+Tests should cover:
+
+-   Deployment and initialization
+-   Minting/claiming
+-   Rentals (create, extend, end)
+-   Sales with royalty distribution
+-   Platform commission
+-   Role management
+-   Pause functionality
+-   Edge cases (rental protection, royalty sum validation, etc.)
+
+## Gas Optimization
+
+The contracts use several gas optimization techniques:
+
+-   Library usage (code reuse)
+-   Immutable variables where possible
+-   Efficient storage patterns
+-   Batch operations (KAMI1155C, KAMI721AC)
+-   Counter optimization
+
+## Security Considerations
+
+1. **Reentrancy**: Uses SafeERC20 for token transfers
+2. **Access Control**: Role-based permissions
+3. **Rental Protection**: Prevents transfer of rented tokens
+4. **Input Validation**: Extensive require statements
+5. **Pausable**: Emergency stop mechanism
+6. **Royalty Validation**: Ensures royalties sum to 100%
+7. **Commission Limits**: Platform commission capped at 20%
+
+## Future Enhancements
+
+Possible future additions:
+
+-   Rental marketplace
+-   Auction functionality
+-   Staking mechanisms
+-   Cross-chain bridging
+-   Upgradeable versions
+
+## Support
+
+For integration help, see:
+
+-   [TypeScript API Documentation](../../docs/KAMI_NFT_INTEGRATION.md)
+-   [Quick Start Guide](../../docs/KAMI_QUICK_START.md)
+-   [Complete Example](../../examples/kami-nft-complete-example.ts)
+
+## License
+
+MIT License

package/src/KAMI-NFTs/artifacts/contracts/KAMI1155C.sol/KAMI1155C.dbg.json

@@ -0,0 +1,4 @@
+{
+  "_format": "hh-sol-dbg-1",
+  "buildInfo": "../../build-info/5eb46d5ad8af8f68e7c4b12971657018.json"
+}